OpenAIResponsesChatGenerator

OpenAIResponsesChatGenerator는 추론 모델을 지원하는 OpenAI의 Responses API로 채팅 완성을 가능하게 해 줘요.

항목	내용
파이프라인에서의 위치	ChatPromptBuilder 뒤
필수 init 변수	`api_key`: OpenAI API 키. `OPENAI_API_KEY` 환경 변수로 설정 가능.
필수 run 변수	`messages`: 채팅을 나타내는 `ChatMessage` 객체 리스트 또는 일반 문자열
출력 변수	`replies`: 생성된 응답을 담은 `ChatMessage` 객체 리스트
API 레퍼런스	Generators
GitHub 링크	https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/openai_responses.py
패키지명	`haystack-ai`

출처: 공식문서

개요 (Overview)

OpenAIResponsesChatGenerator는 OpenAI의 Responses API로 채팅 완성을 생성해요. OpenAI의 채팅 완성 및 추론 모델, 예컨대 gpt-4o-mini, gpt-4.1-mini, GPT-5 계열과 o-series 계열을 지원해요. 기본 모델은 gpt-5-mini예요.

Responses API는 추론 가능한 모델을 위해 설계됐으며, 추론 요약, 이전 응답 ID를 통한 다중 턴 대화, 구조화된 출력 같은 기능을 지원해요.

이 컴포넌트는 동작하려면 ChatMessage 객체 리스트가 필요해요. ChatMessage는 메시지, 역할(누가 생성했는지 — user, assistant, system), 선택적 메타데이터를 담는 데이터 클래스예요. 문자열이 넘어오면 user 역할을 가진 단일 ChatMessage가 담긴 리스트로 변환돼요. 예시는 usage 섹션을 참고하세요.

OpenAI Responses API에 유효한 파라미터는 generation_kwargs 파라미터로 초기화와 run() 메서드 양쪽에서 OpenAIResponsesChatGenerator에 직접 전달할 수 있어요. OpenAI API가 지원하는 파라미터에 대한 자세한 내용은 OpenAI Responses API 문서를 참고하세요.

OpenAIResponsesChatGenerator는 api_base_url init 파라미터로 OpenAI 모델의 커스텀 배포를 지원할 수 있어요.

인증 (Authentication)

OpenAIResponsesChatGenerator는 동작하려면 OpenAI 키가 필요해요. 기본적으로 OPENAI_API_KEY 환경 변수를 사용해요. 그렇지 않으면 Secret으로 api_key를 초기화 시 전달할 수 있어요.

from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.utils import Secret

generator = OpenAIResponsesChatGenerator(api_key=Secret.from_token("<your-api-key>"))

추론 지원 (Reasoning Support)

Responses API의 핵심 기능 하나는 추론 모델 지원이에요. generation_kwargs의 reasoning 파라미터로 추론 동작을 설정할 수 있어요.

from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage

client = OpenAIResponsesChatGenerator(
    generation_kwargs={"reasoning": {"effort": "medium", "summary": "auto"}},
)

messages = [
    ChatMessage.from_user(
        "What's the most efficient sorting algorithm for nearly sorted data?",
    ),
]
response = client.run(messages)
print(response)

reasoning 파라미터는 다음을 받아요.

effort: 추론 노력 수준 — "low", "medium", "high"
summary: 추론 요약 생성 방식 — "auto" 또는 "generate_summary": True/False

:::note OpenAI는 실제 추론 토큰을 반환하지 않지만, 활성화하면 요약을 볼 수 있어요. 자세한 내용은 OpenAI Reasoning 문서를 참고하세요. :::

다중 턴 대화 (Multi-turn Conversations)

Responses API는 previous_response_id로 다중 턴 대화를 지원해요. 이전 턴의 응답 ID를 전달해 대화 컨텍스트를 유지할 수 있어요.

from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage

client = OpenAIResponsesChatGenerator()

# First turn
messages = [ChatMessage.from_user("What's quantum computing?")]
response = client.run(messages)
response_id = response["replies"][0].meta.get("id")

# Second turn - reference previous response
messages = [ChatMessage.from_user("Can you explain that in simpler terms?")]
response = client.run(messages, generation_kwargs={"previous_response_id": response_id})

구조화된 출력 (Structured Output)

OpenAIResponsesChatGenerator는 generation_kwargs의 text_format과 text 파라미터로 구조화된 출력 생성을 지원해요.

text_format: 구조를 정의할 Pydantic 모델을 전달
text: JSON 스키마를 직접 전달

Pydantic 모델 사용하기:

from pydantic import BaseModel
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage


class BookInfo(BaseModel):
    title: str
    author: str
    year: int
    genre: str


client = OpenAIResponsesChatGenerator(
    model="gpt-4o",
    generation_kwargs={"text_format": BookInfo},
)

response = client.run(
    messages=[
        ChatMessage.from_user(
            "Extract book information: '1984 by George Orwell, published in 1949, is a dystopian novel.'",
        ),
    ],
)
print(response["replies"][0].text)

JSON 스키마 사용하기:

from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage

json_schema = {
    "format": {
        "type": "json_schema",
        "name": "BookInfo",
        "strict": True,
        "schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "author": {"type": "string"},
                "year": {"type": "integer"},
                "genre": {"type": "string"},
            },
            "required": ["title", "author", "year", "genre"],
            "additionalProperties": False,
        },
    },
}

client = OpenAIResponsesChatGenerator(
    model="gpt-4o",
    generation_kwargs={"text": json_schema},
)

response = client.run(
    messages=[
        ChatMessage.from_user(
            "Extract book information: '1984 by George Orwell, published in 1949, is a dystopian novel.'",
        ),
    ],
)
print(response["replies"][0].text)

:::info[모델 호환성과 제한 사항]

Pydantic 모델과 JSON 스키마 모두 GPT-4o부터 시작하는 최신 모델에서 지원돼요.
text_format과 text를 모두 제공하면 text_format이 우선하고 text에 전달된 JSON 스키마는 무시돼요.
구조화된 출력을 쓸 때는 스트리밍이 지원되지 않아요.
이전 모델은 {"type": "json_object"}를 통한 기본 JSON 모드만 지원해요. 자세한 내용은 OpenAI JSON mode 문서를 참고하세요.
완전한 정보는 OpenAI Structured Outputs 문서를 확인하세요. :::

툴 지원 (Tool Support)

OpenAIResponsesChatGenerator는 tools 파라미터로 함수 호출을 지원해요. 유연한 툴 설정을 받아들여요.

Haystack Tool 객체와 Toolset: Haystack Tool 객체나 Toolset 객체를 전달(둘 다 섞인 리스트 포함)
OpenAI/MCP 툴 정의: 미리 정의된 OpenAI 또는 MCP 툴 정의를 딕셔너리로 전달

같은 호출 안에서 Haystack 툴과 OpenAI/MCP 툴을 섞을 수는 없다는 점에 주의하세요. 둘 중 하나의 형식을 선택해야 해요.

from haystack.tools import Tool
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage


def get_weather(city: str) -> str:
    """Get weather information for a city."""
    return f"Weather in {city}: Sunny, 22°C"


weather_tool = Tool(
    name="get_weather",
    description="Get current weather for a city",
    function=get_weather,
    parameters={"type": "object", "properties": {"city": {"type": "string"}}},
)

generator = OpenAIResponsesChatGenerator(tools=[weather_tool])
messages = [ChatMessage.from_user("What's the weather in Paris?")]
response = generator.run(messages)

tools_strict 파라미터로 스키마의 엄격한 준수를 제어할 수 있어요. True로 설정하면(기본값은 False) 모델이 툴 스키마를 정확히 따르게 돼요. Responses API에는 이 파라미터와는 별개로 자체 강제성(enforcement) 메커니즘이 있다는 점을 참고하세요.

툴 사용에 대한 자세한 내용은 Tool 및 Toolset 문서를 참고하세요.

스트리밍 (Streaming)

생성됨에 따라 출력을 스트리밍할 수 있어요. streaming_callback에 콜백을 전달하세요. 내장 print_streaming_chunk를 사용하면 텍스트 토큰과 툴 이벤트(툴 호출 및 툴 결과)를 출력할 수 있어요.

from haystack.components.generators.utils import print_streaming_chunk

# Configure any `ChatGenerator` with a streaming callback
component = SomeChatGenerator(streaming_callback=print_streaming_chunk)

# Pass a list of messages:
# from haystack.dataclasses import ChatMessage
# component.run([ChatMessage.from_user("Your question here")])

:::info 스트리밍은 단일 응답에서만 동작해요. 프로바이더가 여러 후보를 지원한다면 n=1로 설정하세요. :::

StreamingChunk가 어떻게 동작하고 커스텀 콜백을 어떻게 작성하는지 더 알아보려면 Streaming Support 문서를 참고하세요.

기본적으로 print_streaming_chunk를 우선 사용하세요. 특정 전송(예: SSE/WebSocket)이나 커스텀 UI 포맷이 필요할 때만 커스텀 콜백을 작성하세요.

사용법 (Usage)

단독으로 쓰기

추론과 스트리밍으로 OpenAIResponsesChatGenerator를 단독 사용하는 예시예요.

from haystack.dataclasses import ChatMessage
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.components.generators.utils import print_streaming_chunk

client = OpenAIResponsesChatGenerator(
    streaming_callback=print_streaming_chunk,
    generation_kwargs={"reasoning": {"effort": "high", "summary": "auto"}},
)
response = client.run(
    [
        ChatMessage.from_user(
            "Solve this logic puzzle: If all roses are flowers and some flowers fade quickly, can we conclude that some roses fade quickly?",
        ),
    ],
)
print(response["replies"][0].reasoning)  # Access reasoning summary if available

파이프라인에서 쓰기

이 예시는 ChatPromptBuilder로 동적 프롬프트를 만들고, 추론을 활성화한 OpenAIResponsesChatGenerator로 복잡한 주제에 대한 설명을 생성하는 파이프라인이에요.

from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.dataclasses import ChatMessage
from haystack import Pipeline

prompt_builder = ChatPromptBuilder()
llm = OpenAIResponsesChatGenerator(
    generation_kwargs={"reasoning": {"effort": "low", "summary": "auto"}},
)

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

topic = "quantum computing"
messages = [
    ChatMessage.from_system(
        "You are a helpful assistant that explains complex topics clearly.",
    ),
    ChatMessage.from_user("Explain {{topic}} in simple terms"),
]
result = pipe.run(
    data={
        "prompt_builder": {
            "template_variables": {"topic": topic},
            "template": messages,
        },
    },
)

print(result)

OpenAIResponsesChatGenerator