新模型上架了吗：用代码而不是文档页验证可用性

为什么不能只看文档页

聚合类 API 站的模型清单通常来自上游供应商和各贡献者的 key。文档页的更新是人工或半自动的，可能滞后于实际可用状态。你真正关心的问题是：此刻用我这个 API key，能不能成功调用某个 model ID？ 这个问题只有发一次真实请求才能回答。

探测脚本的目标不是压测，也不是评估效果，而是用尽可能低的成本确认“这个 model ID 走不通得通”。

设计探测请求

一次最小化的探测调用应满足几个条件：

• max_tokens 设成 1（或你接口支持的最小值），只消费一个输出 token。
• prompt 固定且极短，比如一个字符或一个句号，避免输入 token 影响成本。
• 不开流式，直接拿完整响应，方便判断。
• 明确超时，避免卡住你的探测流程。
• 只做一次调用，不做重试循环——探测阶段一次失败就标记为不可用。

伪代码大致如下：

def probe(client, model_id):
    try:
        resp = client.chat.completions.create(
            model=model_id,
            messages=[{"role": "user", "content": "."}],
            max_tokens=1,
            timeout=15,
        )
        return {"ok": True, "model": model_id}
    except Exception as e:
        return {"ok": False, "model": model_id, "err": type(e).__name__}

关键是只判断成功或失败，不去解析返回内容是否“正确”。探测阶段不关心答案质量。

区分不同的失败类型

把所有失败一视同仁会掩盖问题。至少要把这几类分开：

• 404 / model not found：这个 model ID 在当前网关不存在或未映射。
• 401 / 403：key 无效、无权限，或者这个模型不在你 key 的可用范围里。
• 429：限流。可能是该模型瞬时拥塞，不代表永久不可用，可以稍后再探。
• 5xx：上游故障。同样是暂时状态，不要立刻从生产清单里剔除。
• 超时：网络或上游响应慢，需要区分是偶发还是稳定。

只有 404 / 明确的不存在类错误，才适合直接判死刑。其余错误应标记为“待复测”。

把探测逻辑接进生产管线

探测脚本单独跑一次只能反映某个时刻的状态。要让它长期有用，需要接进你的调用链路：

1. 维护一份候选 model ID 清单，和你业务上真正会用到的模型对齐，不要探测清单外的 ID。
2. 在配置加载阶段做一次探测，把结果写入本地缓存（比如 JSON 或内存）。启动时就过滤掉当前不可用的 model。
3. 周期性后台复测，把标记为“待复测”的模型重新探一遍，恢复可用的就加回来。周期不要设太密，避免无意义的 token 消耗。
4. 失败时降级到备选模型，而不是把错误直接抛给用户。比如同一任务有多个候选模型，按优先级依次尝试。
5. 记录探测日志：时间、model ID、成功/失败、错误类型。出问题时这是唯一能回溯的依据。

成本几乎可以忽略

每次探测只花一个输出 token 和极少量输入 token。哪怕按量计费（本站用户按官方价 ×1.3 扣费），单次探测的金额也在可忽略量级。真正的成本是探测频率——如果你把周期设成一分钟一次、又探测几十个模型，累积起来才会显得明显。把频率控制在合理区间即可。

几个容易踩的坑

• 不要在探测里解析业务结果。探测只回答“通不通”。
• 不要用带副作用的 prompt，比如要求写文件、触发工具调用。探测请求应该是纯文本、纯 completions。
• 不要把探测结果当成模型能力的评价。一个模型能返回一个 token，不代表它适合你的任务。
• 上游 model ID 命名可能随时变。探测失败先怀疑 ID 写法，其次再怀疑可用性。
• 聚合站的模型清单和上游直连的清单不一定一致，以你实际调用网关返回的结果为准。

小结

文档页是给人看的，探测脚本是给管线看的。用一次一 token 的调用确认可用性，把结果接进启动检查和后台复测，你就能在新模型上架、旧模型下线、上游抖动这些情况发生时，第一时间知道该怎么路由请求，而不是等用户报错。