真实问题：请求成功了，却查不到它走了谁
多模型系统常见一个误区：业务日志只写 model=gpt、status=success，网关日志只写 path=/chat，账单日志又用另一套流水号。平时看起来没有问题，一旦出现延迟、输出差异、费用异常或备用路由触发，就很难把三段记录拼起来。
我更倾向于把一次开发者 AI 调用看成一条有父子关系的链路。用户请求生成一个 trace_id，网关、路由器、模型 provider 和业务写回各自记录同一个 trace_id；如果发生重试，就新建 attempt_id 并保留 parent_trace_id。这样“请求失败”和“某次尝试失败”不会混为一谈。
适用场景
这套日志设计适合多租户 AI API 接入、主备模型切换、CCSwitch 配置管理、Codex 接入后的工具调用，以及 AI 自动化办公中的批量任务。它尤其适合需要解释成本、延迟和输出差异的团队。记录路由证据并不等于保存完整提示词，敏感内容仍然应该脱敏或只保存摘要。
操作步骤：从入口到账单建立同一条线
- 在业务入口生成
trace_id，同时记录 tenant、project、environment、task_type 和 prompt_version。不要用用户手机号或完整提示词代替追踪 ID。 - 在路由层记录
route_profile、provider、base_url_name、requested_model和selected_model。如果路由发生降级，要写出原因和目标 profile。 - 在模型调用层记录
attempt_id、开始时间、首字时间、结束时间、输入输出 token、finish_reason 和错误类别。Key 只记录脱敏后的标识，不保存密钥原文。 - 在业务层记录 parser_status、write_status、callback_status 和 billing_ref。一次 200 只能证明某个调用返回，不代表整条任务完成。
- 用三条样本做回归：主路由成功、备用路由成功、所有路由失败。分别核对 trace_id 是否贯穿，并确认重试只增加 attempt_id，不会生成无法关联的新请求。
如果采用日志平台，查询条件优先使用 trace_id，再按 attempt_id 排序。没有集中日志时，也可以先把网关、应用和账单的脱敏 CSV 按 trace_id 合并。开发者 AI 调用的标签方法可参考 项目与环境归因，通用观测字段可对照 AI API 使用观测。
常见问题 / 避坑
第一，不要把 requested_model 当成 selected_model。前者是用户要求，后者才是实际命中。第二，不要用一次重试覆盖原记录，否则看不到路由切换和真实延迟。第三，不要为了排错把完整提示词、文件内容和 API Key 写入普通日志。第四，provider 名称要稳定，不能今天叫 default、明天叫 backup，最后又按人理解。
还有一个容易忽略的点：CCSwitch 配置可能在本地、网关和应用里各有一份。日志里必须记录配置版本或 profile_revision，否则只知道“调用了 CCSwitch”，却不知道当时使用的是哪版模型调用管理规则。需要查看基础入口时，可继续阅读 AI API 接入专题、CCSwitch 配置专题 和 Codex 接入专题。
检查清单
- 入口、网关、provider、业务写回和账单都能用 trace_id 关联。
- requested_model 与 selected_model 分开记录，降级有原因和目标 profile。
- 重试使用独立 attempt_id，并且能看到父请求关系。
- 日志保留延迟、token、finish_reason、错误类别和配置版本。
- 敏感提示词、文件内容、API Key 和内部地址已经脱敏。
- 主路由、备用路由、全失败三类样本都通过回归检查。
验收标准
随机抽一条调用记录，三分钟内应该能回答：谁发起、命中了哪个 provider、使用哪一版 profile、尝试了几次、消耗多少、在哪一层失败。若只能看到一个 200 或一个模型名，说明日志仍然不足。对于 AI 自动化办公和 Codex 接入任务，还要确认业务结果和模型返回可以分别追踪。
复盘时保留什么
每次更换路由策略、调整模型别名或修改 CCSwitch 配置时，保留一组脱敏样本和一份字段说明。复盘不必保存所有原文，重点是把 trace_id、路由选择、错误分类和费用结果串起来。这样模型调用管理从“感觉变慢了”变成可核对的事实，也方便后来的人判断问题来自网关、AI 模型接口还是业务层。
字段命名要保持稳定
日志字段不需要一次设计得很复杂，但名称必须固定。比如入口一直使用 trace_id，单次尝试一直使用 attempt_id，实际命中方一直使用 provider 和 selected_model。字段含义稳定后，查询、告警和费用报表才不会因为不同服务的叫法变化而失去可比性。调整字段时要保留旧字段一段时间，并用同一组脱敏样本验证新旧记录能否对应。
告警与检索要分开
告警只需要告诉值班人哪一层异常，检索才负责还原完整链路。可以按 provider、profile、错误类别和延迟分布设置聚合视图，再用 trace_id 回到单次请求。不要把每条原始响应都推成告警，也不要只保留聚合数字而删除样本。前者会让团队忽略真正问题，后者会让复盘没有证据。
发布前抽样
上线前抽三条记录做人工复核：一条主路由成功、一条备用路由成功、一条失败。确认每条都有 trace_id、attempt_id、provider、selected_model 和费用引用，且敏感内容已脱敏。抽样结果比只看总成功率更能说明路由日志是否真的可用。
延伸阅读
更多 AI API 接入、AI 模型接口和模型调用管理实践，可继续阅读永沃云枢在 https://ai.jn83.com 的专题内容。