Haystack OpenRouterChatGenerator 实战指南跨厂商模型统一接入、流式输出与推理内容解析【免费下载链接】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导读OpenRouterChatGenerator是 Haystack 生态中用于接入 OpenRouter 平台的聊天生成组件它通过 OpenRouter 的 Chat Completions 端点让你在同一个组件里调用来自 OpenAI、Anthropic、DeepSeek 等多家厂商的模型如openai/gpt-4o-mini、anthropic/claude-3.5-sonnet、deepseek/deepseek-r1从而规避供应商锁定并享受模型路由与故障回退能力。读完本文你将掌握该组件的安装、初始化参数、run/run_async调用方式、流式回调、工具调用Tool/Toolset、结构化输出与推理reasoning内容提取并能把它接入 Haystack 管线与ChatPromptBuilder协同工作。一、组件定位继承自 OpenAIChatGenerator 的跨厂商生成器从 API 参考文档docs-website/reference_versioned_docs/version-2.23/integrations-api/openrouter.md可以看出OpenRouterChatGenerator的基类是OpenAIChatGeneratorBases:OpenAIChatGenerator。这意味着它复用了 OpenAI Chat Completions 协议的客户端逻辑只是把请求端点指向 OpenRouter 的聚合网关。在 Haystack 源码中基类实现位于 haystack/components/generators/chat/openai.py组件通过component装饰器注册输入输出统一使用ChatMessage格式run内部先调用self.warm_up()完成客户端初始化openai.py再经_prepare_api_call组装请求参数后调用self.client.chat.completions端点流式与工具调用等能力全部由基类提供OpenRouter 集成在此基础上仅调整api_base_url与厂商特有参数。核心能力一览能力说明主兼容端点OpenRouter Chat Completions 端点https://openrouter.ai/api/v1流式输出支持逐 token 回调模型路由下可用openrouter/auto自动选择模型高度可定制generation_kwargs支持 OpenRouter 端点全部参数推理内容提取对 DeepSeek R1、Claude extended thinking 等模型的 reasoning/thinking 内容存入ChatMessage的ReasoningContent字段仅非流式请求可捕获多模态输入通过ImageContent传入图片配合支持视觉的模型完成图文问答工具调用支持Tool列表、Toolset以及二者混用的灵活配置异步支持提供run_async供 async 场景调用二、安装与初始化2.1 安装集成包OpenRouter 是独立集成包需单独安装见 openrouterchatgenerator.mdxpip install openrouter-haystack使用前需要在 OpenRouter 平台开通账号并充值足够的 credits获取 API key。2.2 配置 API KeySecret 机制API Key 有两种提供方式环境变量直接导出OPENROUTER_API_KEY初始化参数传入Secret对象例如Secret.from_token(...)。组件默认从环境变量读取源码签名中api_key: Secret Secret.from_env_var(OPENROUTER_API_KEY)。Haystack 的Secret抽象见 haystack/utils 目录下 Secret 实现支持环境变量、token 等来源序列化时不会把密钥明文写入字典保障安全。2.3__init__完整签名与参数解析__init__( *, api_key: Secret Secret.from_env_var(OPENROUTER_API_KEY), model: str openai/gpt-5-mini, streaming_callback: StreamingCallbackT | None None, api_base_url: str | None https://openrouter.ai/api/v1, generation_kwargs: dict[str, Any] | None None, tools: ToolsType | None None, timeout: float | None None, extra_headers: dict[str, Any] | None None, max_retries: int | None None, http_client_kwargs: dict[str, Any] | None None ) - None各参数详解参数类型默认值说明api_keySecretOPENROUTER_API_KEY环境变量OpenRouter API 密钥modelstropenai/gpt-5-mini使用的模型 IDOpenRouter 格式为厂商/模型如deepseek/deepseek-r1streaming_callbackStreamingCallbackT \| NoneNone收到新 token 时触发的回调回调参数为StreamingChunkapi_base_urlstr \| Nonehttps://openrouter.ai/api/v1OpenRouter API 基地址generation_kwargsdict \| NoneNone透传给 OpenRouter 端点的生成参数见 2.4toolsToolsType \| NoneNoneTool对象列表或单个Toolset供模型准备函数调用timeoutfloat \| NoneNoneAPI 调用超时秒extra_headersdict \| NoneNone附加 HTTP 请求头可用于提交 site URL/标题提升 openrouter.ai 上的排名展示max_retriesint \| NoneNone内部错误后最大重试次数未设置时取OPENAI_MAX_RETRIES环境变量否则默认 5http_client_kwargsdict \| NoneNone配置自定义httpx.Client/httpx.AsyncClient的关键字参数说明从基类源码 openai.py 可以确认timeout与max_retries未显式设置时会回退到OPENAI_TIMEOUT默认 30 秒与OPENAI_MAX_RETRIES默认 5环境变量OpenRouter 集成继承了这套默认值逻辑。2.4generation_kwargs支持的常见参数generation_kwargs中的参数会被原样透传给 OpenRouter 端点。参考文档明确列出的常用项参数作用max_tokens输出文本的最大 token 数temperature采样温度。值越高模型越“冒险”创意场景可试 0.9答案确定型任务用 0argmax 采样top_p核采样nucleus sampling概率质量。0.1 表示只考虑累计概率前 10% 的 tokenstream是否流式返回部分进度。为真时以 SSE 形式逐 token 推送以data: [DONE]结束safe_prompt是否在所有对话前注入安全提示random_seed随机采样种子reasoning配置推理/思考 token 的字典如{effort: high}或{max_tokens: 2000}。仅非流式请求能捕获推理内容response_formatJSON Schema 或 Pydantic 模型强制约束模型输出结构这些参数既可以在初始化时传入也可以在run时传入见下文后者按 key 覆盖前者。三、run与run_async调用方式详解3.1run签名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输入消息列表。ChatMessage是 Haystack 统一的消息结构定义于 haystack/dataclasses/chat_message.py若直接传入str会被自动包装成 role 为user的单条消息。streaming_callback本次调用专用的流式回调优先于初始化时的回调。generation_kwargs本次调用的生成参数与初始化参数按 key 合并本次传入的优先源码见 openai.py 的{**self.generation_kwargs, **(generation_kwargs or {})}。tools本次调用的工具配置设置后覆盖初始化时传入的tools。tools_strict是否启用工具调用的严格 schema 约束。开启后模型将严格遵循工具定义中的parametersschema可能增加延迟可避免返回畸形 JSON 参数基类在 openai.py 对解析失败的 tool call 会告警并跳过。返回值字典键为replies值为ChatMessage列表包含模型生成的回复。3.2 基本用法示例from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) client OpenRouterChatGenerator() response client.run([ChatMessage.from_user(What are Agentic Pipelines? Be brief.)]) print(response[replies][0].text)3.3 使用推理模型并读取思考过程以deepseek/deepseek-r1为例通过reasoning参数配置推理强度并从返回消息中分别读取思考内容与最终答案from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) from haystack.dataclasses import ChatMessage messages [ChatMessage.from_user(Whats Natural Language Processing?)] client OpenRouterChatGenerator( modeldeepseek/deepseek-r1, generation_kwargs{reasoning: {effort: high}}, ) response client.run(messages) print(response[replies][0].reasoning) # 访问推理内容 print(response[replies][0].text) # 访问最终答案底层机制ChatMessage的消息体由多种内容片段组成其中ReasoningContent负责承载模型的思考文本见 chat_message.py。消息上暴露了reasoning/reasonings属性chat_message.py序列化时以reasoning键存储chat_message.py。需要提醒的是推理内容只在非流式请求中捕获在把ChatMessage转回 OpenAI 格式时推理内容会被忽略OpenAI Chat Completions API 不支持该字段见 chat_message.py因此历史消息回传时需自行处理。3.4run_async异步调用run_async( 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]]run_async是run的异步版本签名与返回结构完全一致。差异点异步场景下streaming_callback必须是协程async 函数从基类源码看openai.py它使用AsyncOpenAI客户端与async for消费流并在任务被取消时通过asyncio.shield确保流被正确关闭openai.py。使用示例import asyncio from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator async def main(): client OpenRouterChatGenerator(modelopenai/gpt-4o-mini) response await client.run_async([ChatMessage.from_user(Hello!)]) print(response[replies][0].text) asyncio.run(main())3.5to_dict序列化to_dict() - dict[str, Any]将组件序列化为字典便于保存到 YAML/JSON 或经 Haystack 管线序列化机制default_to_dict/default_from_dict持久化与重建。序列化时streaming_callback会经serialize_callable转为可反序列化的引用名tools会经serialize_tools_or_toolset处理generation_kwargs中的 Pydanticresponse_format会被转换为 OpenAI JSON Schema 格式见 openai.py。四、流式输出与模型路由4.1 流式输出传入streaming_callback即可开启流式每个新 token 会以StreamingChunk形式回调chunk 内含content、meta等字段。结合openrouter/auto模型路由可以让 OpenRouter 自动挑选可用模型from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) client OpenRouterChatGenerator( modelopenrouter/auto, streaming_callbacklambda chunk: print(chunk.content, end, flushTrue), ) response client.run([ChatMessage.from_user(What are Agentic Pipelines? Be brief.)]) # 检查实际使用的模型 print(\n\n Model used: , response[replies][0].meta[model])流式场景下实际选中模型会出现在回复ChatMessage的meta[model]中这在openrouter/auto路由模式下非常有用——你可以确认最终由哪个厂商模型作答。底层实现上基类会把每个流式 chunk 转换为StreamingChunk并逐块回调openai.py同时把finish_reason映射为 Haystack 的标准枚举stop/length/content_filter/tool_calls。4.2 多模态输入OpenRouter 上的多模态模型如anthropic/claude-3-5-sonnet可通过ImageContent直接传入图片from haystack.dataclasses import ChatMessage, ImageContent from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) llm OpenRouterChatGenerator(modelanthropic/claude-3-5-sonnet) image ImageContent.from_file_path(apple.jpg) user_message ChatMessage.from_user( content_parts[What does the image show? Max 5 words., image], ) response llm.run([user_message])[replies][0].text print(response) # 示例输出: Red apple on straw.ChatMessage.from_user的content_parts参数支持str、TextContent、ImageContent、FileContent的序列见 chat_message.py图片会以 base64 编码随请求发送。五、工具调用Tool 与 Toolset 的灵活组合OpenRouterChatGenerator通过tools参数支持函数调用可接受三种配置形态Tool对象列表把独立工具逐个传入单个Toolset把一个已分组的工具集整体传入混合模式在同一个列表中同时混用多个Toolset与独立Tool。from haystack.tools import Tool, Toolset from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator # 创建独立工具 weather_tool Tool(nameweather, descriptionGet weather info, ...) news_tool Tool(namenews, descriptionGet latest news, ...) # 把相关工具分组为 toolset math_toolset Toolset([add_tool, subtract_tool, multiply_tool]) # 混合传入 toolset 与独立工具 generator OpenRouterChatGenerator( tools[math_toolset, weather_tool, news_tool] # Toolset 与 Tool 混用 )这种设计让你既能按领域组织工具如数学计算工具集又能随时加入零散的独立工具。底层实现中基类会先flatten_tools_or_toolsets摊平工具再执行_check_duplicate_tool_names重名校验openai.py若开启tools_strictTrue还会递归改写工具 JSON Schema设置additionalProperties: false并补齐required确保模型严格按 schema 返回参数见_make_schema_strictopenai.py。注意Tool与Toolset的具体定义、工具序列化细节可参考 haystack/tools 目录及官方 Tool/Toolset 文档。六、接入 Haystack 管线与 ChatPromptBuilder 组合OpenRouterChatGenerator最常见的管线位置是ChatPromptBuilder 之后见 openrouterchatgenerator.mdx由 builder 组装ChatMessage模板生成器负责调用模型from haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) prompt_builder ChatPromptBuilder() llm OpenRouterChatGenerator(modelopenai/gpt-4o-mini) pipe Pipeline() pipe.add_component(builder, prompt_builder) pipe.add_component(llm, llm) pipe.connect(builder.prompt, llm.messages) messages [ ChatMessage.from_system(Give brief answers.), ChatMessage.from_user(Tell me about {{city}}), ] response pipe.run( data{builder: {template: messages, template_variables: {city: Berlin}}}, ) print(response)要点ChatMessage.from_system/from_user分别构造系统提示与用户提问定义见 chat_message.py模板中的{{city}}由template_variables注入管线中该组件只依赖messages输入、产出replies输出接口契约清晰可替换为任何其他 Chat Generator详见 生成器总览 中各类 Generator 的 Streaming 支持对比。七、常见问题与使用建议推理内容拿不到检查是否开启了流式——reasoning内容只在非流式请求中捕获流式场景请改用meta信息或关闭streaming_callback获取思考文本。openrouter/auto路由下如何知道用了哪个模型从response[replies][0].meta[model]读取。工具参数格式不稳设置tools_strictTrue让模型严格遵循 JSON Schema降低畸形参数概率。想为某个调用单独覆盖参数在run时传generation_kwargs它会按 key 覆盖初始化时的同名参数。超时与重试调优通过timeout、max_retries参数或全局设置OPENAI_TIMEOUT、OPENAI_MAX_RETRIES环境变量。OpenRouter 排名展示使用extra_headers提交站点 URL/标题信息。八、延伸阅读组件 API 参考docs-website/reference_versioned_docs/version-2.23/integrations-api/openrouter.md组件使用指南含更多代码示例openrouterchatgenerator.mdx基类实现客户端初始化、流式转换、工具 schema 处理haystack/components/generators/chat/openai.pyChatMessage与ReasoningContent数据结构haystack/dataclasses/chat_message.py生成器家族对比各厂商 Chat Generator 与流式支持矩阵生成器总览【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Haystack OpenRouterChatGenerator 实战指南：跨厂商模型统一接入、流式输出与推理内容解析
Haystack OpenRouterChatGenerator 实战指南跨厂商模型统一接入、流式输出与推理内容解析【免费下载链接】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导读OpenRouterChatGenerator是 Haystack 生态中用于接入 OpenRouter 平台的聊天生成组件它通过 OpenRouter 的 Chat Completions 端点让你在同一个组件里调用来自 OpenAI、Anthropic、DeepSeek 等多家厂商的模型如openai/gpt-4o-mini、anthropic/claude-3.5-sonnet、deepseek/deepseek-r1从而规避供应商锁定并享受模型路由与故障回退能力。读完本文你将掌握该组件的安装、初始化参数、run/run_async调用方式、流式回调、工具调用Tool/Toolset、结构化输出与推理reasoning内容提取并能把它接入 Haystack 管线与ChatPromptBuilder协同工作。一、组件定位继承自 OpenAIChatGenerator 的跨厂商生成器从 API 参考文档docs-website/reference_versioned_docs/version-2.23/integrations-api/openrouter.md可以看出OpenRouterChatGenerator的基类是OpenAIChatGeneratorBases:OpenAIChatGenerator。这意味着它复用了 OpenAI Chat Completions 协议的客户端逻辑只是把请求端点指向 OpenRouter 的聚合网关。在 Haystack 源码中基类实现位于 haystack/components/generators/chat/openai.py组件通过component装饰器注册输入输出统一使用ChatMessage格式run内部先调用self.warm_up()完成客户端初始化openai.py再经_prepare_api_call组装请求参数后调用self.client.chat.completions端点流式与工具调用等能力全部由基类提供OpenRouter 集成在此基础上仅调整api_base_url与厂商特有参数。核心能力一览能力说明主兼容端点OpenRouter Chat Completions 端点https://openrouter.ai/api/v1流式输出支持逐 token 回调模型路由下可用openrouter/auto自动选择模型高度可定制generation_kwargs支持 OpenRouter 端点全部参数推理内容提取对 DeepSeek R1、Claude extended thinking 等模型的 reasoning/thinking 内容存入ChatMessage的ReasoningContent字段仅非流式请求可捕获多模态输入通过ImageContent传入图片配合支持视觉的模型完成图文问答工具调用支持Tool列表、Toolset以及二者混用的灵活配置异步支持提供run_async供 async 场景调用二、安装与初始化2.1 安装集成包OpenRouter 是独立集成包需单独安装见 openrouterchatgenerator.mdxpip install openrouter-haystack使用前需要在 OpenRouter 平台开通账号并充值足够的 credits获取 API key。2.2 配置 API KeySecret 机制API Key 有两种提供方式环境变量直接导出OPENROUTER_API_KEY初始化参数传入Secret对象例如Secret.from_token(...)。组件默认从环境变量读取源码签名中api_key: Secret Secret.from_env_var(OPENROUTER_API_KEY)。Haystack 的Secret抽象见 haystack/utils 目录下 Secret 实现支持环境变量、token 等来源序列化时不会把密钥明文写入字典保障安全。2.3__init__完整签名与参数解析__init__( *, api_key: Secret Secret.from_env_var(OPENROUTER_API_KEY), model: str openai/gpt-5-mini, streaming_callback: StreamingCallbackT | None None, api_base_url: str | None https://openrouter.ai/api/v1, generation_kwargs: dict[str, Any] | None None, tools: ToolsType | None None, timeout: float | None None, extra_headers: dict[str, Any] | None None, max_retries: int | None None, http_client_kwargs: dict[str, Any] | None None ) - None各参数详解参数类型默认值说明api_keySecretOPENROUTER_API_KEY环境变量OpenRouter API 密钥modelstropenai/gpt-5-mini使用的模型 IDOpenRouter 格式为厂商/模型如deepseek/deepseek-r1streaming_callbackStreamingCallbackT \| NoneNone收到新 token 时触发的回调回调参数为StreamingChunkapi_base_urlstr \| Nonehttps://openrouter.ai/api/v1OpenRouter API 基地址generation_kwargsdict \| NoneNone透传给 OpenRouter 端点的生成参数见 2.4toolsToolsType \| NoneNoneTool对象列表或单个Toolset供模型准备函数调用timeoutfloat \| NoneNoneAPI 调用超时秒extra_headersdict \| NoneNone附加 HTTP 请求头可用于提交 site URL/标题提升 openrouter.ai 上的排名展示max_retriesint \| NoneNone内部错误后最大重试次数未设置时取OPENAI_MAX_RETRIES环境变量否则默认 5http_client_kwargsdict \| NoneNone配置自定义httpx.Client/httpx.AsyncClient的关键字参数说明从基类源码 openai.py 可以确认timeout与max_retries未显式设置时会回退到OPENAI_TIMEOUT默认 30 秒与OPENAI_MAX_RETRIES默认 5环境变量OpenRouter 集成继承了这套默认值逻辑。2.4generation_kwargs支持的常见参数generation_kwargs中的参数会被原样透传给 OpenRouter 端点。参考文档明确列出的常用项参数作用max_tokens输出文本的最大 token 数temperature采样温度。值越高模型越“冒险”创意场景可试 0.9答案确定型任务用 0argmax 采样top_p核采样nucleus sampling概率质量。0.1 表示只考虑累计概率前 10% 的 tokenstream是否流式返回部分进度。为真时以 SSE 形式逐 token 推送以data: [DONE]结束safe_prompt是否在所有对话前注入安全提示random_seed随机采样种子reasoning配置推理/思考 token 的字典如{effort: high}或{max_tokens: 2000}。仅非流式请求能捕获推理内容response_formatJSON Schema 或 Pydantic 模型强制约束模型输出结构这些参数既可以在初始化时传入也可以在run时传入见下文后者按 key 覆盖前者。三、run与run_async调用方式详解3.1run签名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输入消息列表。ChatMessage是 Haystack 统一的消息结构定义于 haystack/dataclasses/chat_message.py若直接传入str会被自动包装成 role 为user的单条消息。streaming_callback本次调用专用的流式回调优先于初始化时的回调。generation_kwargs本次调用的生成参数与初始化参数按 key 合并本次传入的优先源码见 openai.py 的{**self.generation_kwargs, **(generation_kwargs or {})}。tools本次调用的工具配置设置后覆盖初始化时传入的tools。tools_strict是否启用工具调用的严格 schema 约束。开启后模型将严格遵循工具定义中的parametersschema可能增加延迟可避免返回畸形 JSON 参数基类在 openai.py 对解析失败的 tool call 会告警并跳过。返回值字典键为replies值为ChatMessage列表包含模型生成的回复。3.2 基本用法示例from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) client OpenRouterChatGenerator() response client.run([ChatMessage.from_user(What are Agentic Pipelines? Be brief.)]) print(response[replies][0].text)3.3 使用推理模型并读取思考过程以deepseek/deepseek-r1为例通过reasoning参数配置推理强度并从返回消息中分别读取思考内容与最终答案from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) from haystack.dataclasses import ChatMessage messages [ChatMessage.from_user(Whats Natural Language Processing?)] client OpenRouterChatGenerator( modeldeepseek/deepseek-r1, generation_kwargs{reasoning: {effort: high}}, ) response client.run(messages) print(response[replies][0].reasoning) # 访问推理内容 print(response[replies][0].text) # 访问最终答案底层机制ChatMessage的消息体由多种内容片段组成其中ReasoningContent负责承载模型的思考文本见 chat_message.py。消息上暴露了reasoning/reasonings属性chat_message.py序列化时以reasoning键存储chat_message.py。需要提醒的是推理内容只在非流式请求中捕获在把ChatMessage转回 OpenAI 格式时推理内容会被忽略OpenAI Chat Completions API 不支持该字段见 chat_message.py因此历史消息回传时需自行处理。3.4run_async异步调用run_async( 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]]run_async是run的异步版本签名与返回结构完全一致。差异点异步场景下streaming_callback必须是协程async 函数从基类源码看openai.py它使用AsyncOpenAI客户端与async for消费流并在任务被取消时通过asyncio.shield确保流被正确关闭openai.py。使用示例import asyncio from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator async def main(): client OpenRouterChatGenerator(modelopenai/gpt-4o-mini) response await client.run_async([ChatMessage.from_user(Hello!)]) print(response[replies][0].text) asyncio.run(main())3.5to_dict序列化to_dict() - dict[str, Any]将组件序列化为字典便于保存到 YAML/JSON 或经 Haystack 管线序列化机制default_to_dict/default_from_dict持久化与重建。序列化时streaming_callback会经serialize_callable转为可反序列化的引用名tools会经serialize_tools_or_toolset处理generation_kwargs中的 Pydanticresponse_format会被转换为 OpenAI JSON Schema 格式见 openai.py。四、流式输出与模型路由4.1 流式输出传入streaming_callback即可开启流式每个新 token 会以StreamingChunk形式回调chunk 内含content、meta等字段。结合openrouter/auto模型路由可以让 OpenRouter 自动挑选可用模型from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) client OpenRouterChatGenerator( modelopenrouter/auto, streaming_callbacklambda chunk: print(chunk.content, end, flushTrue), ) response client.run([ChatMessage.from_user(What are Agentic Pipelines? Be brief.)]) # 检查实际使用的模型 print(\n\n Model used: , response[replies][0].meta[model])流式场景下实际选中模型会出现在回复ChatMessage的meta[model]中这在openrouter/auto路由模式下非常有用——你可以确认最终由哪个厂商模型作答。底层实现上基类会把每个流式 chunk 转换为StreamingChunk并逐块回调openai.py同时把finish_reason映射为 Haystack 的标准枚举stop/length/content_filter/tool_calls。4.2 多模态输入OpenRouter 上的多模态模型如anthropic/claude-3-5-sonnet可通过ImageContent直接传入图片from haystack.dataclasses import ChatMessage, ImageContent from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) llm OpenRouterChatGenerator(modelanthropic/claude-3-5-sonnet) image ImageContent.from_file_path(apple.jpg) user_message ChatMessage.from_user( content_parts[What does the image show? Max 5 words., image], ) response llm.run([user_message])[replies][0].text print(response) # 示例输出: Red apple on straw.ChatMessage.from_user的content_parts参数支持str、TextContent、ImageContent、FileContent的序列见 chat_message.py图片会以 base64 编码随请求发送。五、工具调用Tool 与 Toolset 的灵活组合OpenRouterChatGenerator通过tools参数支持函数调用可接受三种配置形态Tool对象列表把独立工具逐个传入单个Toolset把一个已分组的工具集整体传入混合模式在同一个列表中同时混用多个Toolset与独立Tool。from haystack.tools import Tool, Toolset from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator # 创建独立工具 weather_tool Tool(nameweather, descriptionGet weather info, ...) news_tool Tool(namenews, descriptionGet latest news, ...) # 把相关工具分组为 toolset math_toolset Toolset([add_tool, subtract_tool, multiply_tool]) # 混合传入 toolset 与独立工具 generator OpenRouterChatGenerator( tools[math_toolset, weather_tool, news_tool] # Toolset 与 Tool 混用 )这种设计让你既能按领域组织工具如数学计算工具集又能随时加入零散的独立工具。底层实现中基类会先flatten_tools_or_toolsets摊平工具再执行_check_duplicate_tool_names重名校验openai.py若开启tools_strictTrue还会递归改写工具 JSON Schema设置additionalProperties: false并补齐required确保模型严格按 schema 返回参数见_make_schema_strictopenai.py。注意Tool与Toolset的具体定义、工具序列化细节可参考 haystack/tools 目录及官方 Tool/Toolset 文档。六、接入 Haystack 管线与 ChatPromptBuilder 组合OpenRouterChatGenerator最常见的管线位置是ChatPromptBuilder 之后见 openrouterchatgenerator.mdx由 builder 组装ChatMessage模板生成器负责调用模型from haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) prompt_builder ChatPromptBuilder() llm OpenRouterChatGenerator(modelopenai/gpt-4o-mini) pipe Pipeline() pipe.add_component(builder, prompt_builder) pipe.add_component(llm, llm) pipe.connect(builder.prompt, llm.messages) messages [ ChatMessage.from_system(Give brief answers.), ChatMessage.from_user(Tell me about {{city}}), ] response pipe.run( data{builder: {template: messages, template_variables: {city: Berlin}}}, ) print(response)要点ChatMessage.from_system/from_user分别构造系统提示与用户提问定义见 chat_message.py模板中的{{city}}由template_variables注入管线中该组件只依赖messages输入、产出replies输出接口契约清晰可替换为任何其他 Chat Generator详见 生成器总览 中各类 Generator 的 Streaming 支持对比。七、常见问题与使用建议推理内容拿不到检查是否开启了流式——reasoning内容只在非流式请求中捕获流式场景请改用meta信息或关闭streaming_callback获取思考文本。openrouter/auto路由下如何知道用了哪个模型从response[replies][0].meta[model]读取。工具参数格式不稳设置tools_strictTrue让模型严格遵循 JSON Schema降低畸形参数概率。想为某个调用单独覆盖参数在run时传generation_kwargs它会按 key 覆盖初始化时的同名参数。超时与重试调优通过timeout、max_retries参数或全局设置OPENAI_TIMEOUT、OPENAI_MAX_RETRIES环境变量。OpenRouter 排名展示使用extra_headers提交站点 URL/标题信息。八、延伸阅读组件 API 参考docs-website/reference_versioned_docs/version-2.23/integrations-api/openrouter.md组件使用指南含更多代码示例openrouterchatgenerator.mdx基类实现客户端初始化、流式转换、工具 schema 处理haystack/components/generators/chat/openai.pyChatMessage与ReasoningContent数据结构haystack/dataclasses/chat_message.py生成器家族对比各厂商 Chat Generator 与流式支持矩阵生成器总览【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
