ParallelWebSearch

ParallelWebSearch

Parallel Search API를 사용해 웹을 검색하는 컴포넌트예요. 검색 결과를 LLM에 최적화된 발췌문 형태로 Haystack Document 객체로 돌려받을 수 있죠.

출처: 문서

본문

개요

ParallelWebSearch에 쿼리를 주면 Parallel Search API를 사용해 웹을 검색하고, LLM에 최적화된 발췌문을 Haystack Document 객체로 반환해요. 동시에 소스 URL 목록과 검색 세션 식별자도 돌려주죠.

반환되는 각 Document는 결과의 발췌문이 이어진 값을 content로 담고, meta 딕셔너리에는 title과 url 필드, 비어 있지 않을 때의 excerpts, 그리고 API가 제공하면 publish_date를 담아요.

ParallelWebSearch는 동작하려면 Parallel API 키가 필요해요. 기본적으로 PARALLEL_API_KEY 환경 변수에서 읽어오고, 초기화 시 api_key를 직접 전달할 수도 있어요.

top_k 파라미터는 반환할 최대 결과 수를 제어해요(기본값 10). API의 advanced_settings.max_results 파라미터에 매핑되죠.

search_params를 사용해 검색 결과를 다듬을 수 있는데, mode, objective, max_chars_total, session_id, advanced_settings(중첩된 source_policy 도메인·날짜 필터, fetch_policy, excerpt_settings, location, max_results) 같은 키를 지원해요. 이것들은 초기화 시 또는 run() 호출 시 설정할 수 있어요. run()에 search_params를 전달하면 초기화 시의 딕셔너리 전체를 교체하므로 개별 키를 병합하지 않아요. 명시적인 advanced_settings.max_results는 top_k보다 우선해요. Search API는 지연·품질이 증가하는 순서로 turbo, fast, basic, advanced 네 가지 모드를 제공해요. 전체 파라미터 목록은 Parallel Search API reference를 참고하세요.

같은 작업에 속한 검색은 세션을 공유할 수 있어요. session_id 출력은 search_params로 보냈든 API가 생성했든, API가 사용한 식별자를 담아요. 이를 후속 검색에 전달하면 더 나은 맥락 결과를 얻을 수 있죠.

ParallelWebSearch는 동기(run())와 비동기(run_async()) 동작을 모두 지원해요.

설치

예제를 실행하기 전에 통합 패키지를 설치하고 Parallel API 키를 설정하세요:

pip install parallel-haystack
export PARALLEL_API_KEY="YOUR_PARALLEL_API_KEY"

사용법

단독으로 사용하기

from haystack.utils import Secret
from haystack_integrations.components.websearch.parallel import ParallelWebSearch

web_search = ParallelWebSearch(
    api_key=Secret.from_env_var("PARALLEL_API_KEY"),
    top_k=5,
)

result = web_search.run(query="What is Haystack by deepset?")
for doc in result["documents"]:
    print(doc.content)
    print(doc.meta["url"])

더 빠른 검색 모드와 도메인 필터를 함께 쓰려면:

from haystack.utils import Secret
from haystack_integrations.components.websearch.parallel import ParallelWebSearch

web_search = ParallelWebSearch(
    api_key=Secret.from_env_var("PARALLEL_API_KEY"),
    top_k=5,
    search_params={
        "mode": "turbo",
        "advanced_settings": {"source_policy": {"include_domains": ["arxiv.org"]}},
    },
)

result = web_search.run(query="Latest retrieval-augmented generation research")
for doc in result["documents"]:
    print(doc.meta["title"], doc.meta["url"])

관련 검색 사이에서 세션을 재사용하려면:

from haystack.utils import Secret
from haystack_integrations.components.websearch.parallel import ParallelWebSearch

web_search = ParallelWebSearch(api_key=Secret.from_env_var("PARALLEL_API_KEY"))

first = web_search.run(query="What is Haystack by deepset?")
second = web_search.run(
    query="Who maintains Haystack?",
    search_params={"session_id": first["session_id"]},
)
print(second["links"])

파이프라인에서 사용하기

이 파이프라인은 검색 발췌문을 프롬프트에 넘겨 답변을 생성해요. ParallelChatGenerator는 자체 웹 리서치도 수행하므로, 그 답변이 제공된 발췌문에만 제한되지는 않아요.

from haystack import Pipeline
from haystack.utils import Secret
from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
from haystack.dataclasses import ChatMessage
from haystack_integrations.components.generators.parallel import ParallelChatGenerator
from haystack_integrations.components.websearch.parallel import ParallelWebSearch

web_search = ParallelWebSearch(
    api_key=Secret.from_env_var("PARALLEL_API_KEY"),
    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 = ParallelChatGenerator(
    api_key=Secret.from_env_var("PARALLEL_API_KEY"),
    generation_kwargs={"reasoning": {"effort": "low"}},
)

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)

더 알아보기 (Learn more)

• Parallel Search API reference
• API reference: Integrations
• GitHub: parallel_websearch.py