ParallelChatGenerator

ParallelChatGenerator

ParallelChatGenerator는 Parallel Responses API를 사용해 실시간 웹 리서치에 근거한 채팅 완성(chat completion)을 가능하게 해주는 컴포넌트예요. 답변마다 인용(citation)이 딸려 나오니 검색 파이프라인을 별도로 짤 필요가 없죠.

출처: 문서

본문

개요

ParallelChatGenerator는 OpenAIResponsesChatGenerator 위에 구축되어 있으며, Parallel Responses API(POST /v1/responses)와 통신해요. 이 API는 OpenAI Responses 호환 인터페이스를 사용하죠.

기본 모델은 단 하나, parallel만 지원해요. 모든 답변은 실시간 웹 리서치에 근거하며 인용이 포함되기 때문에, 별도로 연결할 리트리벌 단계가 없어요.

reasoning.effort 파라미터가 리서치 단계(티어)를 결정해요:

• low — 대략 5~10초
• medium — 대략 15~20초 (기본값)
• high — 대략 30~60초

ParallelChatGenerator는 동작하려면 Parallel API 키가 필요해요. 기본적으로 PARALLEL_API_KEY 환경 변수를 사용하죠.

이 컴포넌트는 동작을 위해 ChatMessage 객체 목록을 받아요. ChatMessage는 메시지, 역할(예: user, assistant, system), 그리고 선택적 메타데이터를 담는 데이터 클래스예요. 사용 예시는 사용법 섹션을 보세요.

Parallel Responses API가 지원하는 어떤 파라미터든 generation_kwargs 파라미터로 초기화 시 또는 run() 메서드에서 전달할 수 있어요. 웹 근거(grounding)가 모델에 내장되어 있기 때문에, 툴 호출과 샘플링 파라미터(tools, temperature, top_p 등)는 SDK 호환성을 위해 받아들이지만 API에서 조용히 무시해요. 이 파라미터들을 초기화 시 전달하면 컴포넌트가 경고 로그를 남겨요. 전체 목록은 OpenAI 호환성 페이지를 참고하세요.

단 한 번의 호출로 실시간 리서치가 돌아가기 때문에, timeout 기본값은 OpenAI 클라이언트에서 물려받은 30초가 아니라 120초예요. high 티어를 처리할 여유를 남겨두는 거죠.

설치

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

pip install parallel-haystack
export PARALLEL_API_KEY="YOUR_PARALLEL_API_KEY"

사용법

단독으로 사용하기

from haystack.dataclasses import ChatMessage
from haystack_integrations.components.generators.parallel import ParallelChatGenerator

chat_generator = ParallelChatGenerator(
    generation_kwargs={"reasoning": {"effort": "low"}}
)

response = chat_generator.run(
    [ChatMessage.from_user("What did Parallel Web Systems announce this year?")],
)
print(response["replies"][0].text)

스트리밍과 함께 사용하기 — streaming_callback에 아무 callable이나 전달하거나, 내장된 print_streaming_chunk를 쓰면 돼요:

from haystack.dataclasses import ChatMessage
from haystack.components.generators.utils import print_streaming_chunk
from haystack_integrations.components.generators.parallel import ParallelChatGenerator

chat_generator = ParallelChatGenerator(
    streaming_callback=print_streaming_chunk,
    generation_kwargs={"reasoning": {"effort": "low"}},
)

response = chat_generator.run(
    [ChatMessage.from_user("What did Parallel Web Systems announce this year?")],
)

파이프라인에서 사용하기

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

prompt_builder = ChatPromptBuilder(
    template=[
        ChatMessage.from_system("You are a helpful assistant."),
        ChatMessage.from_user("Tell me about {{topic}}"),
    ],
    required_variables="*",
)
llm = ParallelChatGenerator(
    api_key=Secret.from_env_var("PARALLEL_API_KEY"),
    generation_kwargs={"reasoning": {"effort": "low"}},
)

pipe = Pipeline()
pipe.add_component("prompt_builder", prompt_builder)
pipe.add_component("llm", llm)
pipe.connect("prompt_builder.prompt", "llm.messages")

result = pipe.run(
    data={"prompt_builder": {"topic": "large language models"}},
)
print(result["llm"]["replies"][0].text)

더 알아보기 (Learn more)

• Parallel Responses API quickstart
• OpenAI 호환성 페이지
• API reference: Integrations
• GitHub: chat_generator.py