Haystack 集成指南使用 OpenRouterChatGenerator 打通多模型 Chat Completion【免费下载链接】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/haystackOpenRouter 是一个聚合多家大模型供应商的统一 API 平台本文基于 Haystack 官方参考文档完整讲解OpenRouterChatGenerator组件从安装、初始化参数、generation_kwargs生成参数、流式输出、推理内容reasoning提取到工具调用与 Pipeline 集成并深入源码剖析其底层实现机制。读完本文你将能够在 Haystack 应用中通过一个组件灵活调用 DeepSeek、Claude、GPT 等来自不同厂商的模型并自行切换供应商路由与模型回退策略。组件概览一个生成器接入全品类模型OpenRouterChatGenerator是 Haystack 的 OpenRouter 官方集成组件直接继承自核心库中的OpenAIChatGenerator基类实现见 haystack/components/generators/chat/openai.py因此它复用 OpenAI Chat Completion 的请求范式但将请求端点指向 OpenRouter 网关。通过它你可以使用openai/gpt-4o、anthropic/claude-sonnet-4.5、deepseek/deepseek-r1等任意在 OpenRouter 平台托管的模型而无需为每家厂商编写独立的客户端代码。该组件与 OpenRouter Chat Completion 端点完全兼容官方参考文档version-2.22 参考页归纳了它的三大特性流式输出支持可从 OpenRouter Chat Completion 端点接收流式响应逐 token 回调参数高度可定制OpenRouter Chat Completion 端点支持的所有参数都可透传推理内容提取对支持思考过程的模型如 DeepSeek R1、开启扩展思考的 Claude将推理/思考内容提取到ChatMessage的ReasoningContent字段中注意推理内容仅在非流式请求下捕获。输入输出统一采用 Haystack 的ChatMessage格式保证与ChatPromptBuilder、Agent 等生态组件无缝衔接。安装与前置条件使用该集成需要具备可用的 OpenRouter 订阅账户内需有足够额度和 API Key。官方使用指南OpenRouterChatGenerator 组件文档给出的安装方式为pip install openrouter-haystackAPI Key 有两种提供方式设置环境变量OPENROUTER_API_KEY组件默认从该变量读取初始化时通过api_key参数显式传入一个Secret。快速上手独立运行参考文档给出的最小示例——以 DeepSeek R1 为例同时演示如何访问推理内容与最终答案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) # Access reasoning content print(response[replies][0].text) # Access final answerrun()返回dict[str, list[ChatMessage]]唯一的键replies是模型生成回复的ChatMessage列表reply.text取正文reply.reasoning取推理内容reply.meta中则包含模型名、finish reason、token 用量等元信息。__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_keySecret环境变量OPENROUTER_API_KEYOpenRouter API Keymodelstropenai/gpt-5-mini使用的 OpenRouter 模型名streaming_callbackStreamingCallbackT \| NoneNone流式输出时每收到一个新 token 就调用一次的回调函数回调参数为StreamingChunkapi_base_urlstr \| Nonehttps://openrouter.ai/api/v1OpenRouter API 基础地址一般无需修改generation_kwargsdict \| NoneNone透传给 OpenRouter 端点的生成参数详见下文toolsToolsType \| NoneNone供模型准备调用的工具可接受Tool对象列表或一个Toolset实例timeoutfloat \| NoneNoneOpenRouter API 调用超时时间extra_headersdict \| NoneNone附加 HTTP 请求头可用于向 OpenRouter 平台提交 site URL / title以参与 openrouter.ai 的模型排行榜max_retriesint \| NoneNone内部错误后的最大重试次数未设置时读取OPENAI_MAX_RETRIES环境变量仍无则默认为 5http_client_kwargsdict \| NoneNone用于配置自定义httpx.Client/httpx.AsyncClient的关键字参数几点需要特别注意api_base_url直接决定了请求发往何处。从基类 OpenAIChatGenerator 的_client_kwargs可以看到api_base_url会被透传为 OpenAI SDK 客户端的base_url这正是套壳接入 OpenRouter 网关的关键机制。timeout与max_retries遵循同样的环境变量回退逻辑timeout未设置时读取OPENAI_TIMEOUT再缺省为 30 秒max_retries未设置时读取OPENAI_MAX_RETRIES再缺省为 5。extra_headers是 OpenRouter 特有的实用参数在排行榜参与场景中官方建议通过它附带站点信息。generation_kwargs透传全部 OpenRouter 生成参数generation_kwargs是组件最灵活的部分所有键值都会被直接发送到 OpenRouter 端点。参考文档明确列出以下常用参数参数说明max_tokens输出文本的最大 token 数上限temperature采样温度值越高模型越冒险创意类任务可尝试 0.9有明确答案的任务用 0即 argmax 采样top_p核采样nucleus sampling替代方案只考虑累计概率质量达到top_p的 token如 0.1 表示只考虑概率最高的前 10%stream是否流式返回部分进度开启后 token 以>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列表若直接传字符串会自动包装为一条 user 角色的ChatMessage。从基类源码看空消息列表会直接返回空replies不会发起请求。streaming_callback运行期流式回调优先级高于初始化时设置的回调基类通过select_streaming_callback完成选择。generation_kwargs运行期生成参数覆盖初始化值合并规则见上节。tools若设置则覆盖初始化时的tools可传Tool列表、Toolset或二者混合的列表。tools_strict是否启用工具调用的严格 Schema 约束。run_async与run参数、返回值完全一致供asyncio异步场景使用唯一区别是流式回调必须为协程。基类的 run 实现 展示了完整的调用链warm_up()初始化 OpenAI 客户端与预热工具→_normalize_messages()→ 选择流式回调 →_prepare_api_call()组装请求参数 → 调用client.chat.completions端点 → 对每个 choice 转换为ChatMessage→ 最后经_check_finish_reason()检查 finish reason 并附加到meta。to_dict()则将组件完整序列化为字典含api_key、model、generation_kwargs、tools等配合from_dict()即可实现组件的保存、加载与反序列化用于 Pipeline 的 YAML/JSON 配置持久化。推理内容ReasoningContent的底层机制推理内容提取是 OpenRouter 集成区别于普通 Chat Generator 的一大卖点。其数据模型位于核心库 haystack/dataclasses/chat_message.pyReasoningContent数据类表示模型产出的可选推理内容包含reasoning_text推理文本与extra供应商特有附加信息的字典两个字段ChatMessage通过reasonings属性返回消息中全部ReasoningContent并支持与TextContent、ToolCall、ImageContent等共存于同一条消息。这意味着当你使用 DeepSeek R1 这类先思考后作答的模型时思考链与最终答案被结构化地分开存放可以分别用于展示、记录或后续处理。需要再次强调的限制推理内容只在非流式请求中捕获如果启用了流式回调reasoning字段将不会被填充。流式输出流式输出让 token 边生成边返回显著降低首 token 延迟适合对话式 UI。启用方式是在初始化或run()时传入streaming_callback回调接收StreamingChunk参数。组件文档中的示例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])工具调用Tool 与 Toolset 灵活组合OpenRouterChatGenerator支持函数调用function callingtools参数接受灵活的配置形态见 组件文档的工具调用章节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, parameters..., function... ) news_tool Tool( namenews, descriptionGet latest news, parameters..., function... ) # 把相关工具归组为 toolset math_toolset Toolset([add_tool, subtract_tool, multiply_tool]) # 混合传参 generator OpenRouterChatGenerator( tools[math_toolset, weather_tool, news_tool] )基类在初始化时会通过_check_duplicate_tool_names检查工具重名warm_up()阶段则调用warm_up_tools预热工具元信息tools_strictTrue可让模型严格遵循工具定义中的parametersSchema代价是可能增加延迟。在 Pipeline 中编排使用OpenRouterChatGenerator最典型的位置是接在ChatPromptBuilder之后前者负责按模板组装消息后者负责调用模型。组件文档给出的完整示例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)借助 OpenRouter 的统一网关你甚至可以在不改动 Pipeline 拓扑的前提下仅通过更换model参数就在不同厂商的模型间切换方便做模型对比评测。高级用法供应商路由、多模态与平台排行组件文档中还展示了几个 OpenRouter 特有的高阶用法供应商路由 / 模型回退将model设为openrouter/auto由 OpenRouter 根据可用性、价格与延迟自动路由到合适的供应商模型实现透明回退相关路由偏好可通过generation_kwargs在初始化或运行时配置。多模态输入通过ChatMessage携带ImageContent直接传入图片即可调用具备视觉能力的模型from haystack.dataclasses import ChatMessage, ImageContent from haystack_integrations.components.generators.openrouter import ( OpenRouterChatGenerator, ) llm OpenRouterChatGenerator(modelanthropic/claude-sonnet-4.5) 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)排行榜站点信息利用extra_headers附带站点 URL 与标题参与 openrouter.ai 的平台排行。版本与兼容性说明本文内容以仓库内 version-2.22 参考文档 为准同时参考了当前 OpenRouterChatGenerator 组件指南。该集成以独立分发包openrouter-haystack形式发布具体组件源码维护在配套的 integrations 仓库中本仓库侧对应的基类实现为 haystack/components/generators/chat/openai.py推理内容数据模型见 haystack/dataclasses/chat_message.py。若使用其他 Haystack 版本请以对应版本的reference_versioned_docs/version-*文档为准各版本间参数与默认模型可能存在差异。【免费下载链接】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），仅供参考