YouComWebSearch

You.com Search API를 사용해 웹을 검색하는 컴포넌트예요. 검색 결과를 Haystack Document 객체로 반환해요. 별도 설정 없이 시작할 수 있다는 점이 특징이에요.

파이프라인에서 가장 흔한 위치: ChatPromptBuilder 앞, 또는 인덱싱 파이프라인의 맨 앞 필수 init 변수: 없음. You.com의 키 없는(keyless) 무료 티어로 대체돼요. 더 높은 rate limit을 원하면 YOUDOTCOM_API_KEY(또는 api_key)를 설정하세요. 필수 run 변수: query — 검색 쿼리 문자열 출력 변수: documents — 검색 결과 콘텐츠를 담은 Haystack Document 리스트 / links — 결과 URL 문자열 리스트 API 레퍼런스: You.com Search API GitHub 링크: https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/youcom/src/haystack_integrations/components/websearch/youcom/youcom_websearch.py 패키지 이름: youcom-haystack

출처: 문서

본문

개요 (Overview)

YouComWebSearch에 쿼리를 주면 You.com Search API로 웹을 검색하고 관련 콘텐츠를 Haystack Document 객체로 반환해요. 출처 URL 리스트도 함께 반환해요.

대부분의 다른 웹 검색 컴포넌트와 달리 YouComWebSearch는 설정이 전혀 없이 동작해요. API 키가 없으면 You.com의 키 없는 무료 티어(IP당 rate limit 있음)로 검색하므로, 입문용 파이프라인은 어떤 설정도 없이 실행될 수 있어요. 키 기반 API를 쓰고 더 높은 한도를 원하면 YOUDOTCOM_API_KEY 환경 변수(또는 api_key)를 설정하세요.

keyless_fallback=False를 넘기면 키를 요구하고, 무료 티어로 조용히 전환하는 대신 YouComError로 빨리 실패해요. 키가 없을 때 오류로 표면화돼야 하는 프로덕션 파이프라인에서 유용해요.

검색은 이렇게 구성할 수 있어요:

top_k: 섹션(웹, 뉴스)당 반환할 최대 결과 수. You.com API의 count 파라미터에 매핑됨(1-100). freshness: 주어진 기간 내의 결과만 반환: "day", "week", "month", "year", 또는 "YYYY-MM-DDtoYYYY-MM-DD" 형식의 날짜 범위. country: 웹 결과의 지역적 초점을 결정하는 2글자 국가 코드(예: "US", "DE"). search_lang: 반환되는 웹 결과의 언어(BCP 47 형식, 예: "EN", "PT-BR"). You.com API의 language 파라미터에 매핑됨. safesearch: 콘텐츠 모더레이션 수준: "off", "moderate", "strict". extra_params: You.com Search API에 직접 전달하는 추가 쿼리 파라미터(예: {"include_domains": "nytimes.com,bbc.com"}). timeout: HTTP 요청의 타임아웃(초). 기본 10. max_retries: 일시적 실패 시 재시도 최대 횟수. 기본 3.

이 모든 것은 run()에 top_k를 전달해 단일 검색에 대해 오버라이드할 수 있어요.

YouComWebSearch는 run_async()를 통한 비동기 실행도 지원해요.

사용법 (Usage)

YouComWebSearch 컴포넌트를 쓰려면 youcom-haystack 패키지를 설치해요:

pip install youcom-haystack

단독으로 사용하기 (On its own)

YouComWebSearch가 쿼리로 웹을 검색하고 Document 리스트를 반환하는 빠른 예시예요. 시작하는 데 API 키가 필요 없어요.

from haystack_integrations.components.websearch.youcom import YouComWebSearch

web_search = YouComWebSearch(top_k=5)
query = "What is Haystack by deepset?"
response = web_search.run(query=query)
for doc in response["documents"]:
    print(doc.content)

더 높은 rate limit의 키 기반 API를 사용하고, 키가 없을 때 무료 티어로 전환하는 대신 바로 실패하려면:

from haystack_integrations.components.websearch.youcom import YouComWebSearch
from haystack.utils import Secret

web_search = YouComWebSearch(
    api_key=Secret.from_env_var("YOUDOTCOM_API_KEY"),
    keyless_fallback=False,
    top_k=5,
)

파이프라인 안에서 사용하기 (In a pipeline)

YouComWebSearch로 웹에서 답을 찾는 RAG(Retrieval-Augmented Generation) 파이프라인 예시예요.

from haystack import Pipeline
from haystack.utils import Secret
from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack_integrations.components.websearch.youcom import YouComWebSearch
from haystack.dataclasses import ChatMessage

web_search = YouComWebSearch(top_k=3)
prompt_template = [
    ChatMessage.from_system("You are a helpful assistant."),
    ChatMessage.from_user(
        "Given the information below:\n"
        "{% for document in documents %}{{ document.content }}\n{% endfor %}\n"
        "Answer the following question: {{ query }}.\nAnswer:",
    ),
]
prompt_builder = ChatPromptBuilder(
    template=prompt_template,
    required_variables={"query", "documents"},
)
llm = OpenAIChatGenerator(
    api_key=Secret.from_env_var("OPENAI_API_KEY"),
)
pipe = Pipeline()
pipe.add_component("search", web_search)
pipe.add_component("prompt_builder", prompt_builder)
pipe.add_component("llm", llm)
pipe.connect("search.documents", "prompt_builder.documents")
pipe.connect("prompt_builder.prompt", "llm.messages")

query = "What is Haystack by deepset?"
result = pipe.run(data={"search": {"query": query}, "prompt_builder": {"query": query}})
print(result["llm"]["replies"][0].text)

YouComWebSearch