中文 ▾
获取 API 密钥

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。设置完成。

获取 API 密钥