Haystack Generators API 深度指南從 OpenAIChatGenerator 到 Fallback 容災(zāi)的完整生成器家族【免費下載鏈接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.項目地址: https://gitcode.com/GitHub_Trending/ha/haystack本篇技術(shù)指南以 Haystack 倉庫中的 generators_api.md 為骨架系統(tǒng)講解haystack.components.generators下的全部生成器組件OpenAIChatGenerator、AzureOpenAIChatGenerator、OpenAIResponsesChatGenerator、AzureOpenAIResponsesChatGenerator、FallbackChatGenerator、LLM、MockChatGenerator與OpenAIImageGenerator以及流式輸出工具print_streaming_chunk。讀完本文你將掌握每個組件的完整初始化參數(shù)、generation_kwargs傳參方式、流式與異步運行、序列化與生命周期管理并能基于源碼理解其底層實現(xiàn)與容災(zāi)語義直接用于構(gòu)建生產(chǎn)級 RAG 與 Agent 流水線。一、生成器組件家族總覽Haystack 的生成器Generators是一類負責調(diào)用大語言模型完成生成的 Pipeline 組件統(tǒng)一位于 haystack/components/generators 目錄其中聊天類生成器集中在 haystack/components/generators/chat 子目錄組件源碼文件定位OpenAIChatGeneratorchat/openai.py調(diào)用 OpenAI Chat Completions API 的通用聊天生成器AzureOpenAIChatGeneratorchat/azure.py基于 Azure OpenAI 部署的聊天生成器繼承OpenAIChatGeneratorOpenAIResponsesChatGeneratorchat/openai_responses.py調(diào)用 OpenAI Responses APIgpt-5 / o 系列AzureOpenAIResponsesChatGeneratorchat/azure_responses.pyAzure 上的 Responses API繼承OpenAIResponsesChatGeneratorFallbackChatGeneratorchat/fallback.py多生成器順序容災(zāi)包裝器LLMchat/llm.py簡化版 Agent僅做文本生成、不帶工具MockChatGeneratorchat/mock.py無需外部 API 的確定性模擬生成器OpenAIImageGeneratoropenai_image_generator.py圖像生成gpt-image-2等print_streaming_chunkutils.py流式回調(diào)工具函數(shù)所有聊天生成器均以 ChatMessage 作為輸入輸出格式并實現(xiàn)同步run與異步run_async雙入口。源碼中聊天生成器的協(xié)議約束定義在 chat/types/protocol.py。二、OpenAIChatGenerator最通用的 OpenAI 聊天生成器OpenAIChatGenerator使用 OpenAI 大語言模型完成聊天補全兼容 gpt-4 與 gpt-5 系列模型支持流式響應(yīng)。它的類定義、SUPPORTED_MODELS與 docstring 可在 chat/openai.py 中核對。2.1 基礎(chǔ)用法from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage messages [ChatMessage.from_user(Whats Natural Language Processing?)] client OpenAIChatGenerator() response client.run(messages) print(response)輸出示例{replies: [ChatMessage(_roleChatRole.ASSISTANT: assistant, _content [TextContent(textNatural Language Processing (NLP) is a branch of artificial intelligence that focuses on enabling computers to understand, interpret, and generate human language in a way that is meaningful and useful.)], _nameNone, _meta{model: gpt-5-mini, index: 0, finish_reason: stop, usage: {prompt_tokens: 15, completion_tokens: 36, total_tokens: 51}}) ] }2.2 支持的模型列表組件通過類變量SUPPORTED_MODELS聲明當前支持的非窮盡模型清單SUPPORTED_MODELS: list[str] [ gpt-5-mini, gpt-5-nano, gpt-5, gpt-5.1, gpt-5.2, gpt-5.2-pro, gpt-5.4, gpt-5-pro, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo, ]2.3 初始化參數(shù)詳解OpenAIChatGenerator( api_key: Secret Secret.from_env_var(OPENAI_API_KEY), model: str gpt-5-mini, streaming_callback: StreamingCallbackT | None None, api_base_url: str | None None, organization: str | None None, generation_kwargs: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None, tools: ToolsType | None None, tools_strict: bool False, http_client_kwargs: dict[str, Any] | None None, )api_keyOpenAI API Key默認從環(huán)境變量OPENAI_API_KEY解析也可在初始化時直接傳入Secret對象。model模型名稱默認gpt-5-mini。streaming_callback流式回調(diào)函數(shù)每個新 token 到達時被調(diào)用參數(shù)為StreamingChunk。api_base_url可選的基礎(chǔ) URL用于自建網(wǎng)關(guān)或代理場景。organization組織 ID默認None。timeoutOpenAI 客戶端調(diào)用超時。未設(shè)置時回退到OPENAI_TIMEOUT環(huán)境變量再缺省為 30 秒。max_retries內(nèi)部錯誤后的最大重試次數(shù)。未設(shè)置時回退到OPENAI_MAX_RETRIES環(huán)境變量再缺省為 5。toolsTool與/或Toolset對象列表供模型準備函數(shù)調(diào)用。tools_strict是否啟用工具調(diào)用的嚴格 schema 遵循設(shè)為True時模型會嚴格按parameters字段定義的 schema 輸出但可能增加延遲。http_client_kwargs用于配置自定義httpx.Client或httpx.AsyncClient的關(guān)鍵字參數(shù)。2.4 generation_kwargs透傳給 OpenAI 的參數(shù)通道組件允許通過**generation_kwargs在初始化或運行時向 OpenAI 端點透傳任意參數(shù)與openai.ChatCompletion.create兼容。核心參數(shù)及語義參數(shù)作用max_completion_tokens生成 token 數(shù)上限包含可見輸出 token 與推理reasoningtokentemperature采樣溫度越高越冒險0.9 適合創(chuàng)意場景0 為 argmax 采樣適合有確定答案的場景top_p核采樣只考慮概率質(zhì)量累計到 top_p 的 token如 0.1 表示只取概率最高的前 10%n每個 prompt 生成的補全數(shù)例如 3 個 prompt、n2 時共生成 6 個補全stop一個或多個停止序列LLM 遇到后停止生成presence_penalty對已出現(xiàn) token 的懲罰值越大越不易重復frequency_penalty對已生成 token 的懲罰值越大越不易重復logit_bias對特定 token 施加 logit 偏置鍵為 token值為偏置量response_formatJSON Schema 或 Pydantic 模型強制模型輸出結(jié)構(gòu)除非返回工具調(diào)用關(guān)于response_format結(jié)構(gòu)化輸出有兩點限制需要留意GPT-4o 起的新模型支持 Pydantic 模型與 JSON Schema舊模型只能使用基礎(chǔ)的{type: json_object}JSON 模式流式結(jié)構(gòu)化輸出時response_format必須是 JSON Schema 而非 Pydantic 模型。2.5 運行時透傳與優(yōu)先級合并run方法簽名run( messages: list[ChatMessage] | str, streaming_callback: StreamingCallbackT | None None, generation_kwargs: dict[str, Any] | None None, *, tools: ToolsType | None None, tools_strict: bool | None None, ) - dict[str, list[ChatMessage]]messages聊天歷史若傳入字符串會自動轉(zhuǎn)換為包含單個 user 角色的ChatMessage列表。generation_kwargs運行期參數(shù)按 key 與初始化時的generation_kwargs合并——運行期傳入的 key 優(yōu)先初始化獨有 key 保留。tools / tools_strict運行期傳入會覆蓋初始化設(shè)置。返回值僅含replies鍵生成的ChatMessage列表。異步版本run_async與run參數(shù)、返回值一致可用于await異步回調(diào)優(yōu)先同步回調(diào)會被接受但會在事件循環(huán)上同步執(zhí)行可能阻塞事件循環(huán)。2.6 生命周期與序列化組件實現(xiàn)了完整的生命周期接口warm_up/warm_up_async負責預(yù)熱工具并初始化同步/異步 OpenAI 客戶端異步客戶端在服務(wù)事件循環(huán)上初始化close/close_async負責釋放客戶端to_dict/from_dict用于流水線序列化與反序列化。三、AzureOpenAIChatGeneratorAzure 部署形態(tài)AzureOpenAIChatGenerator繼承OpenAIChatGenerator通過 Azure OpenAI 服務(wù)調(diào)用模型gpt-4 類型支持流式響應(yīng)同樣以ChatMessage作為輸入輸出。其 Azure 特有參數(shù)是azure_endpoint、api_version、azure_deployment、azure_ad_token與azure_ad_token_provider。3.1 用法示例from haystack.components.generators.chat import AzureOpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack.utils import Secret messages [ChatMessage.from_user(Whats Natural Language Processing?)] client AzureOpenAIChatGenerator( azure_endpointYour Azure endpoint e.g. https://your-company.azure.openai.com/, api_keySecret.from_token(your-api-key), azure_deploymentthis is a model name, e.g. gpt-4.1-mini) response client.run(messages) print(response)輸出示例{replies: [ChatMessage(_roleChatRole.ASSISTANT: assistant, _content[TextContent(text Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on enabling computers to understand, interpret, and generate human language in a way that is useful.)], _nameNone, _meta{model: gpt-4.1-mini, index: 0, finish_reason: stop, usage: {prompt_tokens: 15, completion_tokens: 36, total_tokens: 51}})] }3.2 初始化參數(shù)AzureOpenAIChatGenerator( azure_endpoint: str | Secret | None None, api_version: str | Secret | None 2024-12-01-preview, azure_deployment: str | None gpt-4.1-mini, api_key: Secret | None Secret.from_env_var(AZURE_OPENAI_API_KEY, strictFalse), azure_ad_token: Secret | None Secret.from_env_var(AZURE_OPENAI_AD_TOKEN, strictFalse), organization: str | None None, streaming_callback: StreamingCallbackT | None None, timeout: float | None None, max_retries: int | None None, generation_kwargs: dict[str, Any] | None None, default_headers: dict[str, str] | None None, tools: ToolsType | None None, tools_strict: bool False, *, azure_ad_token_provider: AzureADTokenProvider | AsyncAzureADTokenProvider | None None, http_client_kwargs: dict[str, Any] | None None, ) - Noneazure_endpoint已部署模型的端點例如https://example-resource.azure.openai.com/。可以傳Secret如Secret.from_env_var(AZURE_OPENAI_ENDPOINT)在運行時從環(huán)境變量解析便于在不同環(huán)境開發(fā)/生產(chǎn)間切換端點而無需修改序列化的流水線。api_versionAPI 版本默認2024-12-01-preview同樣支持Secret方式從AZURE_OPENAI_API_VERSION解析。azure_deployment模型部署名通常就是模型名。api_key認證用的 API Key默認從AZURE_OPENAI_API_KEY讀取strictFalse未設(shè)置不報錯。azure_ad_tokenAzure Active DirectoryEntra IDtoken默認從AZURE_OPENAI_AD_TOKEN讀取。azure_ad_token_provider返回 Azure AD token 的函數(shù)支持同步/異步每次請求都會被調(diào)用。default_headers為 AzureOpenAI 客戶端設(shè)置的默認請求頭。其余timeout、max_retries、generation_kwargs、tools、tools_strict、http_client_kwargs語義與OpenAIChatGenerator一致。組件同樣聲明SUPPORTED_MODELS非窮盡清單覆蓋 gpt-5.4 系列、gpt-4.1/gpt-4o 系列、o1/o3/o4-mini、codex-mini、gpt-oss-120b、computer-use-preview 等并實現(xiàn)warm_up、warm_up_async、close、close_async、to_dict、from_dict。四、OpenAIResponsesChatGenerator新一代 Responses APIOpenAIResponsesChatGenerator通過 OpenAI Responses API 完成聊天面向 gpt-4 與 o 系列模型支持流式響應(yīng)。與 Chat Completions 路徑不同它透傳openai.Responses.create支持的參數(shù)。4.1 用法示例from haystack.components.generators.chat import OpenAIResponsesChatGenerator from haystack.dataclasses import ChatMessage messages [ChatMessage.from_user(Whats Natural Language Processing?)] client OpenAIResponsesChatGenerator(generation_kwargs{reasoning: {effort: low, summary: auto}}) response client.run(messages) print(response)4.2 支持的模型SUPPORTED_MODELS覆蓋 gpt-5 系列g(shù)pt-5-mini / nano / 5 / 5.1 / 5.2 / 5.4 / 5-pro 等、gpt-4.1 系列、gpt-4o 系列以及 o1 / o1-mini / o1-pro / o3 / o3-mini / o3-pro / o4-mini。4.3 初始化與 generation_kwargs 進階參數(shù)初始化參數(shù)與OpenAIChatGenerator大體一致區(qū)別在于tools接受ToolsType | list[dict] | None既可以傳 Haystack 的Tool/Toolset混合列表也可以直接傳 OpenAI/MCP 工具定義字典二者不能混用。另外 Responses API 下工具調(diào)用默認就是 strict 的。Responses 路徑的generation_kwargs支持以下進階參數(shù)temperature / top_p采樣溫度與核采樣語義同前。previous_response_id上一響應(yīng)的 ID用于構(gòu)建多輪對話。text_formatPydantic 模型強制響應(yīng)結(jié)構(gòu)結(jié)構(gòu)化輸出。若同時提供text_format與texttext_format優(yōu)先text中的 JSON Schema 被忽略。textJSON Schema強制響應(yīng)結(jié)構(gòu)。reasoning推理參數(shù)字典包含summary推理摘要effort推理投入程度可取值low、medium、highgenerate_summary是否生成推理摘要mode推理模式可取值standard、proGPT-5.6 起支持。注意OpenAI 不會返回推理 token但啟用摘要后可查看摘要。include指定額外輸出數(shù)據(jù)支持web_search_call.action.sources網(wǎng)頁搜索來源、code_interpreter_call.outputs代碼執(zhí)行輸出、computer_call_output.output.image_url、file_search_call.results、message.input_image.image_url、message.output_text.logprobs、reasoning.encrypted_content加密推理 token用于無狀態(tài)多輪對話場景等取值。run/run_async的generation_kwargs同樣按 key 與初始化參數(shù)合并運行期優(yōu)先。五、AzureOpenAIResponsesChatGeneratorAzure 上的 Responses APIAzureOpenAIResponsesChatGenerator繼承OpenAIResponsesChatGenerator通過 Azure 端點使用 Responses API面向 gpt-5 與 o 系列模型。5.1 用法示例from haystack.components.generators.chat import AzureOpenAIResponsesChatGenerator from haystack.dataclasses import ChatMessage messages [ChatMessage.from_user(Whats Natural Language Processing?)] client AzureOpenAIResponsesChatGenerator( azure_endpointhttps://example-resource.azure.openai.com/, generation_kwargs{reasoning: {effort: low, summary: auto}} ) response client.run(messages) print(response)5.2 初始化參數(shù)AzureOpenAIResponsesChatGenerator( *, api_key: Secret | Callable[[], str] | Callable[[], Awaitable[str]] Secret.from_env_var(AZURE_OPENAI_API_KEY, strictFalse), azure_endpoint: str | None None, azure_deployment: str gpt-5-mini, streaming_callback: StreamingCallbackT | None None, organization: str | None None, generation_kwargs: dict[str, Any] | None None, timeout: float | None None, max_retries: int | None None, tools: ToolsType | None None, tools_strict: bool False, http_client_kwargs: dict[str, Any] | None None, ) - Noneapi_key是它的特色參數(shù)支持三種形態(tài)包含 API Key 的Secret對象包含 Azure AD token 的Secret對象返回 Azure AD token 的函數(shù)同步Callable[[], str]或異步Callable[[], Awaitable[str]]。默認模型部署為gpt-5-mini其余參數(shù)streaming_callback、timeout、max_retries、generation_kwargs、tools、tools_strict、http_client_kwargs與基類一致。六、FallbackChatGenerator多生成器順序容災(zāi)FallbackChatGenerator是一個包裝器組件按順序嘗試多個聊天生成器透明轉(zhuǎn)發(fā)所有參數(shù)返回第一個成功的結(jié)果任一生成器拋出異常即觸發(fā)切換若全部失敗則拋出帶細節(jié)的RuntimeError。實現(xiàn)位于 chat/fallback.py。6.1 觸發(fā)條件與超時語義故障切換對任何異常自動觸發(fā)包括超時錯誤如果生成器實現(xiàn)了超時并拋出異常限流錯誤429認證錯誤401上下文長度錯誤400服務(wù)端錯誤500其他任何異常。超時執(zhí)行完全委托給底層生成器因此容災(zāi)要正常工作底層生成器需滿足三點初始化支持timeout參數(shù)將超時實現(xiàn)為總墻鐘時間流式與非流式共享同一截止時間超時時拋出超時異常如TimeoutError、asyncio.TimeoutError、httpx.TimeoutException。對基于 HTTP 的 LLM 提供商單個超時值如timeout30通常作用于連接建立、讀取、寫入、連接池等所有階段流式響應(yīng)的讀取超時指 chunk 之間的最大間隔非流式則是收到完整響應(yīng)的時限。6.2 用法與輸出結(jié)構(gòu)from haystack.components.generators.chat import FallbackChatGenerator from haystack.components.generators.chat import OpenAIChatGenerator generator FallbackChatGenerator( chat_generators[ OpenAIChatGenerator(modelgpt-5-mini, timeout10), OpenAIChatGenerator(modelgpt-4.1-mini, timeout15), ] ) result generator.run(messages)run/run_async接受messages、generation_kwargs、tools、streaming_callback四個參數(shù)返回replies第一個成功生成器的ChatMessage列表meta執(zhí)行元數(shù)據(jù)包括successful_chat_generator_index、successful_chat_generator_class、total_attempts、failed_chat_generators失敗生成器類名列表以及成功生成器自身附帶的元數(shù)據(jù)。6.3 源碼級行為細節(jié)從 fallback.py 的實現(xiàn)可以看到初始化時校驗chat_generators必須是非空列表否則拋ValueErrorto_dict會遞歸序列化嵌套生成器component_to_dictfrom_dict通過deserialize_component_inplace還原warm_up/close對每個底層生成器逐一委托異步版本在缺少warm_up_async/close_async時會回退到同步方法每次嘗試都用_trace_chat_generator_run打開獨立 tracing span記錄輸入輸出。對應(yīng)的單元測試見 test/components/generators/chat/test_fallback.py其中明確覆蓋了 429 限流、401 認證、400 請求、500 服務(wù)端錯誤等觸發(fā)場景以及超時處理同步/異步與序列化 roundtrip。七、LLM去掉工具化的極簡 AgentLLM繼承自Agentchat/llm.py是一個簡化版 Agent專注文本生成、不攜帶工具處理消息并返回模型單次響應(yīng)。7.1 用法示例from haystack.components.generators.chat import LLM from haystack.components.generators.chat import OpenAIChatGenerator llm LLM( chat_generatorOpenAIChatGenerator(), system_promptYou are a helpful translation assistant., user_promptSummarize the following document: {{ document }}, required_variables[document], ) result llm.run(documentThe weather is lovely today and the sun is shining. ) print(result[last_message].text)7.2 初始化參數(shù)LLM( *, chat_generator: ChatGenerator, system_prompt: str | None None, user_prompt: str | None None, required_variables: list[str] | Literal[*] *, streaming_callback: StreamingCallbackT | None None, ) - Nonechat_generator底層聊天生成器實例LLM不直接發(fā) API 請求而是完全委托給它。system_prompt系統(tǒng)提示詞可以是普通字符串模板或 Jinja2 消息模板。user_prompt用戶提示詞會追加到運行時傳入的消息之后同樣支持模板變量。若包含模板變量如{{ variable_name }}變量名自動成為組件的輸入若省略或沒有模板變量則運行時必須提供messages。required_variables必須作為user_prompt/system_prompt輸入提供的變量列表若列為必填的變量未提供則拋異常設(shè)為*表示 prompt 中所有變量都必填默認值。僅在 prompt 含模板變量時生效。streaming_callback流式回調(diào)。約束若user_prompt含模板變量但required_variables是空列表初始化會拋ValueError。7.3 源碼級行為從 chat/llm.py 的實現(xiàn)可看出其關(guān)鍵機制根據(jù)user_prompt是否有模板變量通過component.set_input_type動態(tài)決定messages是必填還是可選輸入由于LLM永不使用工具且只運行一步基類Agent聲明的step_count與tool_call_counts輸出被移除僅暴露messages、last_message、token_usage三個輸出run/run_async接受streaming_callback、generation_kwargs與用于填充模板變量的**kwargs返回messages本次運行全部消息、last_message最后一條消息與token_usage若生成器未返回用量數(shù)據(jù)則為空generation_kwargs按 key 與初始化時配置合并運行期優(yōu)先。對應(yīng)的行為驗證見 test/components/generators/chat/test_llm.py包括is_subclass_of_agent、prompt 無變量時messages必填、required_variables為空拋錯、to_dict/from_dictroundtrip以及test_rag_pipeline驗證其在 RAG 流水線中的可用性。八、MockChatGenerator零成本確定性的測試替身MockChatGenerator是一個不調(diào)用任何外部 API、直接返回預(yù)定義響應(yīng)的生成器可作為真實生成器如OpenAIChatGenerator在測試、冒煙測試與快速原型中的直接替代品。它實現(xiàn)了與真實生成器相同的run、run_async、流式與序列化接口完全確定且零成本。實現(xiàn)見 chat/mock.py。8.1 四種響應(yīng)模式固定響應(yīng)Fixed response傳入單個字符串或ChatMessage每次調(diào)用返回相同回復。作為ChatMessage傳入時角色必須是assistant。循環(huán)響應(yīng)Cycling responses傳入字符串與/或ChatMessage的列表每次調(diào)用按順序返回下一項耗盡后回到開頭。適合驅(qū)動多步流程如 Agent第一次調(diào)用返回工具調(diào)用后續(xù)調(diào)用返回最終答案。動態(tài)響應(yīng)Dynamic response傳入response_fn可調(diào)用對象接收輸入消息并返回回復若該函數(shù)接受第二個位置參數(shù)還會收到run傳入的toolsToolsType或None回復可依賴運行時工具 schema便于演練工具集變化的 Agent。回顯Echo默認不做任何配置時回顯最后一條含文本內(nèi)容的消息文本開箱即用。傳入ChatMessage對象而非純字符串可以返回工具調(diào)用或推理內(nèi)容方便在不使用真實模型的情況下演練工具調(diào)用流水線。8.2 用法示例from haystack.components.generators.chat import MockChatGenerator from haystack.dataclasses import ChatMessage, ToolCall # 固定響應(yīng) generator MockChatGenerator(responsesHello, this is a mock response.) result generator.run([ChatMessage.from_user(Hi!)]) print(result[replies][0].text) # Hello, this is a mock response. # 循環(huán)響應(yīng)驅(qū)動 Agent 式循環(huán) generator MockChatGenerator( responses[ ChatMessage.from_assistant(tool_calls[ToolCall(tool_namesearch, arguments{query: Haystack})]), Here is the final answer., ] ) # 動態(tài)、感知工具的響應(yīng)根據(jù) run() 傳入的 tools 構(gòu)造工具調(diào)用 def call_first_tool(messages, tools): if not tools: return No tools available. return ChatMessage.from_assistant( tool_calls[ToolCall(tool_nametools[0].name, arguments{})] ) generator MockChatGenerator(response_fncall_first_tool)8.3 初始化參數(shù)與約束MockChatGenerator( responses: str | ChatMessage | Sequence[str | ChatMessage] | None None, *, response_fn: ResponseFn | None None, model: str mock-model, meta: dict[str, Any] | None None, streaming_callback: StreamingCallbackT | None None, ) - Noneresponses與response_fn互斥同時提供、responses為空列表、或傳入非assistant角色的ChatMessage都會拋ValueErrormodel寫入響應(yīng)元數(shù)據(jù)的模型名純展示用途不會真正加載模型meta并入每個返回ChatMessage的元數(shù)據(jù)單個響應(yīng)ChatMessage自身元數(shù)據(jù)優(yōu)先streaming_callback根據(jù)預(yù)定義響應(yīng)重構(gòu)StreamingChunk并觸發(fā)回調(diào)讓 mock 無需真實模型即可演練流式代碼路徑為保證可序列化response_fn需傳具名函數(shù)lambda 與嵌套函數(shù)無法序列化。run/run_async的簽名刻意鏡像OpenAIChatGenerator.run使其可作為位置參數(shù)式的直接替身generation_kwargs與tools_strict僅為接口兼容而被接受并忽略tools只傳給接受第二個參數(shù)的response_fn。warm_up是空操作僅為接口兼容。九、OpenAIImageGenerator圖像生成OpenAIImageGenerator使用 OpenAI 圖像生成模型默認gpt-image-2根據(jù)文本 prompt 生成圖像實現(xiàn)見 openai_image_generator.py。9.1 用法示例from haystack.components.generators import OpenAIImageGenerator image_generator OpenAIImageGenerator() response image_generator.run(Show me a picture of a black cat.) print(response)9.2 初始化參數(shù)OpenAIImageGenerator( model: str gpt-image-2, quality: Literal[auto, high, medium, low] auto, size: Literal[1024x1024, 1024x1536, 1536x1024, auto] 1024x1024, response_format: Literal[b64_json] b64_json, api_key: Secret Secret.from_env_var(OPENAI_API_KEY), api_base_url: str | None None, organization: str | None None, timeout: float | None None, max_retries: int | None None, http_client_kwargs: dict[str, Any] | None None, ) - Nonemodel圖像生成模型名默認gpt-image-2。quality圖像質(zhì)量可取auto、high、medium、low。源碼中傳入非法值時會有警告日志并回退到auto見 openai_image_generator.py。size圖像尺寸1024x1024、1024x1536、1536x1024或autogpt-image-2還支持任意尺寸。response_format僅保留向后兼容實際被忽略始終返回 base64 編碼圖像非法值會產(chǎn)生警告日志。api_key / api_base_url / organization / timeout / max_retries / http_client_kwargs語義與聊天生成器一致。run/run_async接受prompt并可用size、quality覆蓋初始化配置response_format忽略返回包含 base64 編碼圖像列表與revised promptOpenAI 修訂后的 prompt若存在的字典。十、print_streaming_chunk現(xiàn)成的流式輸出回調(diào)print_streaming_chunk是一個開箱即用的流式回調(diào)函數(shù)定義于 utils.py可作為streaming_callback直接傳入各生成器。其行為包括到達新內(nèi)容塊起點時輸出換行分隔打印工具調(diào)用元數(shù)據(jù)函數(shù)名與參數(shù)邊到達邊打印工具調(diào)用結(jié)果可用時打印結(jié)果打印流式文本內(nèi)容本身所有輸出直接寫 stdout 并立即 flush保證流式過程實時可見。此外utils.py 中的_trace_chat_generator_run上下文管理器會在內(nèi)部調(diào)用生成器的組件如 rankers、extractors、evaluators周圍打開haystack.chat_generator.runtracing span把 LLM token 用量重新暴露給 tracer——這正是 Fallback 等包裝組件能記錄每次嘗試 trace 的底層機制。十一、實戰(zhàn)組合建議單模型聊天場景直接使用OpenAIChatGenerator把采樣參數(shù)固化在初始化generation_kwargs運行期按需覆蓋。企業(yè) Azure 場景用AzureOpenAIChatGenerator/AzureOpenAIResponsesChatGenerator配合AZURE_OPENAI_API_KEY、AZURE_OPENAI_AD_TOKEN、AZURE_OPENAI_ENDPOINT等環(huán)境變量實現(xiàn)環(huán)境切換需要 AD 認證時用azure_ad_token_provider。需要推理能力的新模型選擇 Responses API 路徑OpenAIResponsesChatGenerator/ Azure 版本通過generation_kwargs[reasoning]控制 effort 與摘要通過include收集網(wǎng)頁搜索來源等附加輸出。生產(chǎn)高可用用FallbackChatGenerator包裝多個提供商/模型形成超時、限流、認證錯誤的自動容災(zāi)鏈并借助meta中的failed_chat_generators觀測切換過程。無工具文本生成用LLM組件獲得 Agent 的模板能力系統(tǒng)/用戶提示詞模板 必填變量校驗卻無需工具管理。測試與原型用MockChatGenerator的四種模式模擬固定回復、Agent 多步循環(huán)與工具調(diào)用讓 CI 與冒煙測試完全確定、零成本對應(yīng)測試可見 test/components/generators/chat/test_mock.py。所有生成器都支持同步run與異步run_async雙入口均可無縫接入 Pipeline 或 Agent 工作流統(tǒng)一的to_dict/from_dict接口保證了組件在序列化流水線YAML/JSON中的可移植性。完整的 API 參考文檔保存在 docs-website/reference/haystack-api/generators_api.md可按組件模塊逐個查閱。【免費下載鏈接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.項目地址: https://gitcode.com/GitHub_Trending/ha/haystack創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考