通过 dspy.LM、openai/ 前缀和一个 api_base 把 DSPy 接到 Router One

安装 dspy 并设置凭证

使用 Python 3.10 或更新版本：PyPI 上的包元数据要求 >=3.10 且 <3.15，DSPy 的安装页也写明它适用于 Python 3.10+ 环境。官方给出的安装方式是 pip install dspy（或 uv add dspy）；litellm 和 openai 包都是它声明的依赖，接 OpenAI 兼容端点不需要再装别的。pip 会装最新的正式版，本指南核对时是 3.3.1；3.4.0b1 是预发布版，不特别指定 pip 不会装。下面是 macOS/Linux 的 shell 示例，运行前替换两个占位符：一把 Router One Key，以及当前目录中某个聊天模型的精确 ID。ROUTER_ONE_* 是本示例自己定义并显式读取的变量名；Key 直接作为 api_key 传给 dspy.LM，所以不需要设置 OPENAI_API_KEY，而且即使环境里设了 OPENAI_API_KEY 或 OPENAI_API_BASE，生效的仍是 api_key 和 api_base 这两个参数。运行 Python 文件时沿用同一环境。

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

把 DSPy 配置到 Router One base URL

保存为 program.py，再运行 python program.py。dspy.LM 接收 LiteLLM 风格的 provider/model 字符串，第一段必须是 openai/：LiteLLM 文档把这个前缀定义为「调用 OpenAI /chat/completions 端点」的指令，而字符串只在第一个斜杠处切分一次，openai/ 之后的内容会原样作为请求里的 model 字段发出。示例用 ROUTER_ONE_MODEL_ID 拼出它，所以 openai/gpt-5.5 这样的 GPT 系列 ID 写成 openai/openai/gpt-5.5，Claude 的 ID 写成 openai/anthropic/claude-sonnet-5。api_base 填带 /v1 的 base URL，后面不加任何路径；底层的 OpenAI 客户端会自己补上 /chat/completions。api_key 填 Router One Key。model_type='chat' 本来就是默认值，写出来只是为了把端点说清楚。cache=False 是为头几次运行准备的：DSPy 默认把响应缓存在内存和硬盘里，不关掉的话，同一个文件第二次运行会直接由本地回答，不发出任何请求。dspy.configure(lm=lm, track_usage=True) 把这个 LM 设为所有模块的默认模型，并打开 token 统计，result.get_lm_usage() 会按模型字符串返回统计结果。dspy.Predict 为签名 question -> answer 发出一次请求；dspy.ChainOfThought 多一个 reasoning 输出字段，仍然是一次请求；dspy.ReAct 每轮迭代发一次请求，最后再发一次提取最终答案，而 add 函数在你的进程里执行。在 3.3.1 里 temperature 和 max_tokens 默认为 None，不会写进请求，所以生效的是模型自己的默认值。dspy.inspect_history(n=1) 打印 DSPy 实际发出的最后一次提示词和回复，lm.history 为每次调用保留一条带 usage 的记录：

import os

import dspy

# openai/ selects the OpenAI Chat Completions route; the rest of the string is sent
# unchanged as the model field (openai/openai/gpt-5.5 for a GPT-family ID).
lm = dspy.LM(
    "openai/" + os.environ["ROUTER_ONE_MODEL_ID"],
    api_base="https://api.router.one/v1",  # ends in /v1, nothing after it
    api_key=os.environ["ROUTER_ONE_API_KEY"],
    model_type="chat",  # POST /v1/chat/completions
    cache=False,  # first runs: every call reaches the gateway and shows up in Logs
)
dspy.configure(lm=lm, track_usage=True)

# 1. One Predict call is one request
qa = dspy.Predict("question -> answer")
result = qa(question="What is the capital of France?")
print(result.answer, result.get_lm_usage())

# 2. ChainOfThought adds a reasoning output field; still one request
cot = dspy.ChainOfThought("question -> answer")
print(cot(question="What is 17 * 23?").answer)


# 3. ReAct: one request per iteration plus one that extracts the answer; the tool runs in your process
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b


agent = dspy.ReAct("question -> answer", tools=[add], max_iters=5)
print(agent(question="What is 1234 + 4321?").answer)

# The last call as DSPy sent it, and the per-call records DSPy keeps
dspy.inspect_history(n=1)
print(len(lm.history), lm.history[-1]["usage"])

DSPy 的哪个设置发出哪种请求

连接信息由 dspy.LM 携带，每个请求长什么样则由模块和 adapter 决定。下表按本指南涉及的设置，给出该填的值、它产生的请求，以及使用前要确认的事项。

给一次优化器运行定预算，并与 Logs 对账

DSPy 程序在推理时只是少量请求，花费集中在 compile()。优化器会在训练集和验证集上把你的程序反复运行很多遍：DSPy 的 FAQ 给出过一次 BootstrapFewShotWithRandomSearch 编译的数字，大约 3,200 次 API 调用、270 万输入 token 和 15.6 万输出 token，优化器选择指南也提醒 MIPROv2 和 GEPA 的 compile() 开销很大。预算开关都在客户端，数的是工作量而不是钱：MIPROv2 的 auto（默认 light，其次是 medium 和 heavy）对应 6、12 或 18 个候选，并把验证集上限定为 100、300 或 1,000 条；GEPA 要求在 auto、max_full_evals、max_metric_calls 三者中恰好设置一个，并在开始前把预计的指标调用次数写进日志。GEPA 的 reflection_lm 和 MIPROv2 的 prompt_model 是独立的 dspy.LM 对象，给它们同样的 openai/ 前缀和 api_base；想把生成提示词的花费和任务本身的花费分开，就再给它们单独一把 Key。并发来自 num_threads：dspy.Evaluate 和各优化器没有显式设置时会用 dspy.settings.num_threads，默认值是 8，所以一次评测中最多同时有 8 个请求在途。如果 Key 的 rateLimit 低于这个突发量，网关会返回 429，DSPy 在重试之后抛出 dspy.LMRateLimitError；这时应该调低 num_threads 或调高 Key 的 rateLimit，而不是增加重试。重试会放大请求数：num_retries 默认是 3，在本地 mock 服务器上，DSPy 3.3.1 搭配 LiteLLM 1.101 对返回 429 或 500 的请求一共发送了 7 次，对返回 400、401、402 或 404 的请求一共发送了 4 次，然后才抛出异常；num_retries=0 时只发送一次。每一次真正到达网关的尝试在 Dashboard → Logs 里都是独立请求，有各自的 request_id。给每个程序、以及每一次你想封顶的编译运行，单独建一把设了 maxSpend 的 Key：触到上限后，下一次调用返回 HTTP 402，DSPy 抛出 dspy.LMBillingError，并行执行器在失败样本数达到 max_errors（默认 10）后停止，消息为 Execution cancelled due to errors or interruption，钱包和其他 Key 不受影响。只要 cache=True，Logs 里的行数就会少于代码里的调用次数：完全相同的请求，包括整次重复的编译，都会从硬盘重放；而且缓存键不包含 api_key 和 api_base，同一个模型字符串在别的端点上缓存过的回答也会被重放。get_lm_usage() 是 DSPy 对 API 报告用量的统计，缓存命中的调用为空；lm.history 里的 cost 字段是 LiteLLM 按它自己的价格表估算的，遇到它不认识的 ID 可能是 None。费用以 Logs 记录为准：按 Key、时间、精确模型和 token 数对账，报障时保留 request_id。Router One 只服务模型请求并记录 Trace；优化器、指标、工具和缓存都在你的进程里运行。

Embedding 和微调留在网关之外

dspy.Embedder 既接受托管模型的字符串，也接受一个 Python 可调用对象。openai/text-embedding-3-small 这样的托管字符串会走 LiteLLM 的 embedding 调用，配上 Router One 的 api_base 就是 POST /v1/embeddings，而网关不提供这个端点，所以调用会以 404 失败，LiteLLM 抛出的是 NotFoundError。Embedding 要走另一条路：Embedder 的参考文档给出了把本地 sentence-transformers 模型作为可调用对象传入的写法 dspy.Embedder(model.encode)；其他服务商的托管 embedding 模型，则用那家自己的 Key 和 api_base。dspy.retrievers.Embeddings 把 embedder 作为参数接收，所以 RAG 程序可以用本地或第三方 embedder 做检索，只把生成调用通过 dspy.LM 发到 Router One。这两个对象互不相干：dspy.configure(lm=...) 不会影响 embedder，embedder 的请求也不会出现在 Logs 里。训练也是同样的边界：BootstrapFinetune 这类训练权重的优化器需要微调 API，Router One 不提供；而提示词优化器（BootstrapFewShot、MIPROv2、GEPA）只需要聊天调用。

DSPy 该填哪个模型 ID？

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

DSPy 用的是哪种 API 协议？

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

在 trace 里验证 DSPy 的调用

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

常见问题