用一个 base URL 把 Haystack 的 OpenAIChatGenerator 接到 Router One

安装 haystack-ai 并设置凭证

使用 Python 3.10 或更新版本，安装 haystack-ai：OpenAIChatGenerator 和它调用的 OpenAI Python SDK 都在核心包里，本指南不需要额外的集成包。下面是 macOS/Linux 的 shell 示例，运行前替换两个占位符：一把 Router One Key，以及当前目录中支持 Chat Completions 的精确模型 ID。ROUTER_ONE_* 是本示例自己定义并显式读取的变量名；generator 拿到的是专属 Secret，所以不需要设置 OPENAI_API_KEY。运行 Python 文件时沿用同一环境。

python -m pip install haystack-ai
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL_ID="<exact-model-id-from-/models>"

把 Haystack 配置到 Router One base URL

保存为 haystack_router_one.py，再运行 python haystack_router_one.py。Secret.from_env_var("ROUTER_ONE_API_KEY") 替换了 generator 默认的 OPENAI_API_KEY Secret，在构造 generator 时解析；变量缺失会抛出点名该变量的 ValueError。model 原样传入目录里的模型 ID，若 ID 自带 provider 前缀也要保留。api_base_url 填带 /v1 的 base URL，generator 内部的 OpenAI 客户端会自行拼接 /chat/completions，所以每次 run() 就是一个 POST /v1/chat/completions。第一次 run() 发送一条用户 ChatMessage，从 replies[0].text 读取回复文本；Haystack 3.0 起也可以直接传一个字符串。第二次 run() 复用同一个 generator，加上 streaming_callback=print_streaming_chunk，每个 chunk 到达时立即打印；这个回调也可以在构造 generator 时设置。两次调用只差这一点，行为不同就能定位到流式本身。

import os

from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.generators.utils import print_streaming_chunk
from haystack.dataclasses import ChatMessage
from haystack.utils import Secret

llm = OpenAIChatGenerator(
    api_key=Secret.from_env_var("ROUTER_ONE_API_KEY"),
    model=os.environ["ROUTER_ONE_MODEL_ID"],
    api_base_url="https://api.router.one/v1",
)

# 1. One plain Chat Completions request; the reply is a ChatMessage
result = llm.run(messages=[ChatMessage.from_user("Reply with one short greeting.")])
print(result["replies"][0].text)

# 2. The same generator, streaming: chunks print as they arrive
llm.run(
    messages=[ChatMessage.from_user("Count from 1 to 5, one number per line.")],
    streaming_callback=print_streaming_chunk,
)

Haystack 的哪个调用发出哪种请求

Haystack 的组件不共用一个客户端：每个 generator 实例各自带着 api_key、model 和 api_base_url，Agent、LLM 这类包装组件接收的是 generator 实例而不是 URL。下表按本指南这个 generator 的各项功能，说明到达网关的请求是什么，以及使用前要在模型详情页确认的能力。

网关不提供什么，以及怎样给一次 pipeline 运行设预算

一条 Haystack RAG pipeline 串起 embedder、document store、retriever、ChatPromptBuilder 和 generator，其中只有 generator 的请求会到达 Router One。OpenAITextEmbedder 和 OpenAIDocumentEmbedder 调用的是 embeddings API，网关没有这个端点，把它们的 api_base_url 指向 Router One 不可能成功。向量化改用本地 sentence-transformers embedder（pip install sentence-transformers-haystack，这些组件在 Haystack 3.0 移出了核心包），或换用其他 embedding 服务商及其自己的 Key，并保证索引和查询用同一个 embedding 模型。cross-encoder ranker 和 document store 同样运行在你的进程里或各自的服务上。此外，一次 pipeline 运行可能产生多次模型请求：generator 内部的 OpenAI 客户端会对连接错误以及 408、409、429、5xx 响应重试，上限是 max_retries（Haystack 默认 5，也可用 OPENAI_MAX_RETRIES 设置）；Agent 每一步都会再调一次 generator；FallbackChatGenerator 遇到任何异常就切到下一个 generator。每一次到达网关的尝试在 Dashboard → Logs 里都是独立请求，有各自的 request_id、Trace 和费用。给 pipeline 单独建一把设了 maxSpend 的 Key，批处理任务调低 max_retries，限制 max_agent_steps，并用 Agent 输出的 token_usage 和 step_count 与 Logs 对账。默认 30 秒超时（OPENAI_TIMEOUT）对慢模型可以用 timeout= 调高。Router One 只记录模型调用元数据，不执行你的工具、不存文档，也不保存 pipeline 状态。

Haystack 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Haystack 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

Haystack 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在 trace 里验证 Haystack 的调用

先在 Haystack 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题