72小时建立前端代码解构能力：HTML结构与JS执行上下文实战
2026/9/15 14:05:52
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/haystack
OpenRouter 是一个聚合多家大模型供应商的统一 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("What's Natural Language Processing?")] client = OpenRouterChatGenerator( model="deepseek/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_key | Secret | 环境变量OPENROUTER_API_KEY | OpenRouter API Key |
model | str | "openai/gpt-5-mini" | 使用的 OpenRouter 模型名 |
streaming_callback | StreamingCallbackT \| None | None | 流式输出时每收到一个新 token 就调用一次的回调函数，回调参数为StreamingChunk |
api_base_url | str \| None | "https://openrouter.ai/api/v1" | OpenRouter API 基础地址，一般无需修改 |
generation_kwargs | dict \| None | None | 透传给 OpenRouter 端点的生成参数（详见下文） |
tools | ToolsType \| None | None | 供模型准备调用的工具，可接受Tool对象列表或一个Toolset实例 |
timeout | float \| None | None | OpenRouter API 调用超时时间 |
extra_headers | dict \| None | None | 附加 HTTP 请求头；可用于向 OpenRouter 平台提交 site URL / title，以参与 openrouter.ai 的模型排行榜 |
max_retries | int \| None | None | 内部错误后的最大重试次数；未设置时读取OPENAI_MAX_RETRIES环境变量，仍无则默认为 5 |
http_client_kwargs | dict \| None | None | 用于配置自定义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]] 参数语义如下：
推理内容（ReasoningContent）的底层机制"推理内容提取"是 OpenRouter 集成区别于普通 Chat Generator 的一大卖点。其数据模型位于核心库 haystack/dataclasses/chat_message.py：
这意味着当你使用 DeepSeek R1 这类"先思考后作答"的模型时，思考链与最终答案被结构化地分开存放，可以分别用于展示、记录或后续处理。需要再次强调的限制：推理内容只在非流式请求中捕获，如果启用了流式回调， 流式输出流式输出让 token 边生成边返回，显著降低首 token 延迟，适合对话式 UI。启用方式是在初始化或 工具调用：Tool 与 Toolset 灵活组合
基类在初始化时会通过 在 Pipeline 中编排使用
借助 OpenRouter 的统一网关，你甚至可以在不改动 Pipeline 拓扑的前提下，仅通过更换 高级用法：供应商路由、多模态与平台排行组件文档中还展示了几个 OpenRouter 特有的高阶用法：
版本与兼容性说明本文内容以仓库内 version-2.22 参考文档 为准，同时参考了当前 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. 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 |