LLM 应用 API 迁移测试:实用计划
LLM 应用的 API 迁移测试不同于测试普通 REST API,因为相同的提示词不会两次返回相同的文本。你测试的是答案的属性,而不是精确字符串。
最后更新

总结
- 构建包含 50 到 200 个真实提示词的黄金集,使用基于规则的检查,而不是精确匹配期望。
- 固定 temperature 和 seed 以减少噪声,但永远不要期望文本完全相同。
- 记录旧路由和新路由上的延迟百分位数和每次请求的成本。
- 在发布开始前写下回滚触发器。
你实际在测试什么
对于经典 API,你可以逐字节比较响应。对于语言模型,这立即行不通。相反,确定你的产品依赖答案的哪些属性,并测试这些属性。
- 结构。 有效的 JSON、必需的键、带有正确参数的工具调用。
- 内容。 提及必要的事实,遵循格式,保持角色设定。
- 产品的安全性。 在需要回答时不拒绝,不泄露系统提示词。
- 运营指标。 延迟、错误率、速率限制行为、成本。
如果你仍然需要切换步骤本身,计划位于本网站的迁移指南中,你在此过程中遇到的故障在 常见 LLM 集成错误 中有所涵盖。本文涵盖验证。
构建黄金提示词集
从日志中提取 50 到 200 个真实提示词(先剥离个人数据)。涵盖常见路径、棘手案例以及之前出错的案例。将每个提示词存储为包含消息、参数和必须通过的检查的记录。
{
"id": "invoice-json-03",
"messages": [
{"role": "system", "content": "Extract fields. Reply with JSON only."},
{"role": "user", "content": "Invoice 4471 from Acme, total 1,250 EUR, due 2025-03-01"}
],
"json": true,
"required_keys": ["number", "vendor", "total"],
"must_contain": ["4471"]
}
按风险标记案例:函数调用、长上下文、流式输出、非英语、非常短和非常长的回答。当后续在生产环境中出现 bug 时,将其添加到集中。该集将演变为你的回归测试套件。
编写记录一切内容的测试框架
一个脚本应针对路由运行整个集合,应用检查并保存数据。使用 temperature=0 和固定的 seed 来减少波动。此 API 会透传这两个参数,但请将其视为减少噪声的手段,而非保证。
import json, time
from openai import OpenAI
client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")
PRICE_IN, PRICE_OUT = 0.15, 0.50 # USD per 1M tokens
def run(case):
t0 = time.perf_counter()
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=case["messages"],
temperature=0,
seed=42,
)
elapsed = time.perf_counter() - t0
resp = raw.parse()
text = resp.choices[0].message.content or ""
u = resp.usage
return {
"id": case["id"],
"text": text,
"seconds": elapsed,
"cost": (u.prompt_tokens * PRICE_IN + u.completion_tokens * PRICE_OUT) / 1e6,
"balance": raw.headers.get("X-Balance-USD"),
"request_id": raw.headers.get("X-Request-Id"),
}
保留每个失败案例的 X-Request-Id。这是你在向支持团队询问特定请求时引用的内容。
按规则而非字符串进行差异比对
应用每条记录中的检查。任何失败的项目都会进入一个简短列表,供人工阅读。
def check(case, text):
problems = []
if case.get("json"):
try:
obj = json.loads(text)
except ValueError:
return ["invalid json"]
for key in case.get("required_keys", []):
if key not in obj:
problems.append("missing key " + key)
for needle in case.get("must_contain", []):
if needle.lower() not in text.lower():
problems.append("missing text " + needle)
if len(text.strip()) < case.get("min_chars", 1):
problems.append("answer too short")
return problems
对于自由形式的回答,添加一个廉价长度区间(例如在旧回答的一半到两倍之间)以及一个用于标记拒绝短语的短列表。然后人工并排阅读 20 个输出。规则捕获回归;阅读捕获语气。两者都要做。
对于 JSON 输出,将 response_format 设置为 {"type":"json_object"} 并仍然进行验证,因为上述检查成本很低。
故意测试故障路径
正常路径提示词在几乎所有提供商上都能通过。故障是迁移造成损害的地方,因此在用户遇到之前故意引发它们。
- 密钥错误。 发送带有错误密钥的请求,并确认你的应用显示合理的消息且不会循环重试。
- 速率限制。 用完整密钥同时发起超过 8 个请求(试用密钥为超过 2 个),确认你的代码能处理带有
concurrency代码的 HTTP 429;如果超出每分钟上限,则处理带有rate_limited代码的 429。 - 临时过载。 带有
Retry-After: 5的 429 应导致等待五秒,而不是立即猛烈重试。 - 输入过大。 发送接近 100,000 token 上下文窗口和一个超出该窗口的提示词。你的应用应进行截断或摘要,而不是崩溃。
- 请求体过大。 限制为 8 MB。确认你自行拒绝更大的请求体。
- 流中断。 在流式传输过程中断开连接,并确认并发配额会恢复。
这些每一项都应有一个在 CI 中针对假服务器运行的自动化测试,以及一次针对真实服务器的手动测试。
检查流式输出和函数调用
流式输出和工具会改变响应的结构,因此基于纯文本构建的黄金数据集会遗漏它们。为每种情况添加测试用例。
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Look up an order by id",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Where is order A-1042?"}],
tools=tools,
tool_choice="auto",
)
calls = r.choices[0].message.tool_calls or []
assert calls and calls[0].function.name == "get_order_status"
print(calls[0].function.arguments)
断言检查调用是否存在,以及参数是否解析为你期望的 JSON。添加一个检查,确保第二个回合(将结果作为 role: "tool" 的消息发送)产生正常回答。对于流式输出,断言块已到达,最终用量出现,并且你的代码在流结束时停止读取。
跟踪每条路由的延迟和成本
在旧路由和新路由上运行测试集并比较相同的列:中位数和 95 百分位秒数、错误计数、token、成本。本文未提供任何提供商的延迟数据,因为你的数据将取决于你的提示词和网络。请自行测量。
新路由的成本是 token 数乘以费率,每 1M 输入 $0.15,每 1M 输出 $0.50。示例:200 个黄金提示词,平均 1,200 输入 token 和 300 输出 token。
- 输入:240,000 tokens × $0.15 / 1,000,000 = $0.036。
- 输出:60,000 tokens × $0.50 / 1,000,000 = $0.03。
- 一次完整运行:$0.066。
$0.50 试用额度可覆盖约七次此类运行。试用密钥允许 2 个并发请求和每分钟 60 个请求,因此 200 个提示词至少需要 3.5 分钟。失败或被拒的请求不收费。你也可以在每次调用后从 X-Balance-USD 标头读取余额,以确认你自己的计算。
影子流量与分阶段发布
一旦黄金集通过测试,将真实请求复制到新路由,但不显示答案。记录结果,并使用相同的检查项将其与真实响应进行比较。影子运行需要并发限制:完整密钥允许同时发起 8 个并发请求,因此应对镜像调用进行排队,而不是同时全部发出。
然后分步迁移真实用户,例如 5%、25%、50% 和 100%。在错误率、检查失败和投诉保持平稳之前,请保持每个阶段不变。
提前决定回滚规则
在迁移第一个用户之前写下阈值,以便在当下做出机械化的决策。
| 信号 | 触发条件示例 |
|---|---|
| 真实流量中的检查失败 | 超过约定比例的规则检查失败 |
| HTTP 429 或 5xx 比率 | 持续高于旧路由的基线 |
| 延迟 p95 | 超过产品的超时预算 |
| 每次请求成本 | 超过估算值且超出设定幅度 |
| 用户反馈 | 关于相同行为的集群 |
回滚应为配置更改,而非部署。在 100% 迁移后,保持旧路由的资金充足且配置完好至少几天。当你准备好运行测试时,获取 API 密钥 并领取试用,查看 定价 以进行更大规模的运行,并使用 文档 获取接口详情。
更多指南
常见问题
我需要多少个黄金提示词?
50 到 200 个真实提示词可覆盖大多数应用。质量比数量更重要,因此请包含那些棘手且之前出错的案例。
我可以使用精确匹配的差异比较输出吗?
不可靠。即使在 temperature 0 和固定种子下,也将输出视为变量,并测试规则,如有效的 JSON、关键事实和长度。
我如何在测试期间跟踪成本?
将 token 用量乘以每 1M 输入 $0.15 和每 1M 输出 $0.50,并监控 X-Balance-USD 标头以获取实际余额。
什么情况下应触发回滚?
首先定义阈值:失败的检查、429 或 5xx 比率、相对于超时阈值的延迟,以及相对于预估的成本。
获取 API 密钥
注册,复制密钥,更新基础 URL。设置完成。