#AI 应用应该记录哪些日志

传统 Web 应用记录日志，通常关注请求是否成功、接口耗时、错误堆栈和数据库查询。

AI 应用也需要这些，但远远不够。

当用户说“这次回答不对”“它突然变慢了”“为什么扣了这么多额度”“为什么模型忘了前文”，普通接口日志很难回答。因为 AI 输出不是一个确定性函数，它受模型、prompt、上下文、检索、工具、历史消息、采样参数和运行状态共同影响。

AI 应用的日志要能回答三个问题：

• 发生了什么？
• 为什么会这样？
• 下次如何改进？

这意味着日志不只是排错工具，也是成本管理、质量评估、安全审计和产品迭代的基础。

#AI 日志和普通日志有什么不同

普通接口通常可以用 request、response、status、latency 定位大部分问题。

AI 请求更复杂。一次看似简单的聊天回复，可能包含：

• 用户消息。
• 系统 prompt。
• 历史消息裁剪。
• 检索片段。
• 工具定义。
• 模型路由。
• Provider 调用。
• streaming delta。
• 工具调用和工具结果。
• token 用量。
• 内容安全判断。
• 用户反馈。

其中任何一环变化，都可能改变最终答案。

所以 AI 日志需要覆盖完整链路，而不是只记录最终文本。

这张图不是要求所有日志都放在一张表里，而是提醒我们：AI 可观测性是一条链路。只记录其中一段，就很难解释整体行为。

#第一类：请求与身份日志

每次 AI 请求都应该有稳定的 trace id 或 run id。

基础字段包括：

这些字段决定日志能不能串起来。

前端报一个 run id，后端应该能查到对应用户、会话、模型调用、token 用量和错误。没有统一 id，线上问题会变成“你把当时的问题再发我一遍”。

对前端来说，run id 也应该出现在错误上报和用户反馈里。用户点击“这条回答不好”时，不只是提交一段文本，而是提交这次生成的可追踪引用。

#第二类：模型调用日志

模型调用日志记录 Gateway 或 AI Runtime 实际调用了什么。

常见字段包括：

• provider。
• model。
• model policy。
• prompt version。
• temperature、top_p、max_tokens。
• response format。
• tools enabled。
• streaming enabled。
• fallback from。
• retry count。
• normalized error code。

这里的重点不是把 Provider 请求原样完整保存下来，而是保留足够复现和分析的结构化信息。

例如，当模型质量突然下降，你需要知道是不是模型版本换了、temperature 被改了、prompt version 更新了、fallback 到了更弱模型，还是输出格式约束被关闭了。

如果只记录“请求成功，耗时 8 秒”，基本没有分析价值。

#第三类：上下文日志

上下文是 AI 应用里最容易出问题、也最容易缺日志的部分。

一次模型调用到底看到了什么？它有没有看到用户刚上传的文件？有没有引用过期历史？检索结果是不是错的？系统 prompt 有没有被错误拼接？

上下文日志可以记录：

注意，上下文日志不一定要保存完整明文。很多产品不能把用户隐私、业务数据或文件内容原样写进日志。更稳妥的方式是保存引用、摘要、哈希、长度、token 数和脱敏后的片段。

如果需要保存完整 context snapshot，也应该放在受控存储里，并设置访问权限、保留周期和脱敏策略。

#第四类：Streaming 与运行时日志

AI Chat 的体验问题经常发生在生成过程中，而不是请求结束后。

你需要知道：

• run 什么时候开始。
• 首 token 什么时候出现。
• streaming 中间是否断开。
• 用户是否点击停止。
• 是否发生服务端超时。
• 是否有 delta 写入失败。
• 是否出现部分输出后失败。

关键指标包括：

• queue_time_ms：排队时间。
• first_token_ms：首 token 时间。
• generation_ms：生成耗时。
• total_latency_ms：总耗时。
• stream_event_count：streaming 事件数量。
• client_aborted：客户端是否中断。
• server_cancelled：服务端是否取消。

前端看到“卡住了”，背后可能是排队、Provider 慢、首 token 慢、网络断流、浏览器中断或渲染压力。没有运行时日志，很难区分。

#第五类：Token、成本和配额日志

AI 应用必须记录 token 和成本。

至少记录：

这些日志可以回答：

• 哪些功能最贵？
• 哪些用户或租户消耗异常？
• 成本上涨来自输入还是输出？
• 重试和失败浪费了多少？
• 哪个模型性价比更好？

对前端产品来说，成本日志还会变成额度 UI、套餐设计、用量报表和限制提示的基础。

#第六类：工具调用和外部动作日志

只要 AI 能调用工具，日志就必须更严格。

工具调用可能读取数据、写入系统、发送邮件、创建订单、修改配置。模型可以建议，但真实执行必须由系统负责审计。

工具日志应该记录：

• tool name。
• tool call id。
• run id。
• arguments。
• arguments redaction status。
• required permission。
• approval status。
• executor。
• external request id。
• result status。
• result summary。
• error code。

对于高风险工具，还要记录用户确认：

• 谁确认了。
• 什么时候确认。
• 确认前展示了什么内容。
• 最终执行了什么参数。

不要只在 prompt 里写“高风险操作要确认”。确认应该是系统流程，日志也要能证明它发生过。

#第七类：质量反馈日志

AI 应用上线后，质量改进不能只靠感觉。

用户反馈日志包括：

• thumbs up / thumbs down。
• 用户选择的原因。
• 用户是否点击重试。
• 用户是否编辑了 AI 输出。
• 用户是否复制、插入、采纳或删除结果。
• 用户是否继续追问。
• 人工标注的正确性。

这些反馈能帮助你建立评估集。

例如，一条差评回答可以关联 run id、context snapshot、model、prompt version 和用户修改后的最终文本。后续你可以用它做回归测试，验证 prompt 修改或模型升级是否真的改善了问题。

前端在这里很关键。反馈入口如果太重，用户不会填；如果只收一个“差评”，工程团队又很难知道哪里错。更好的方式是提供轻量反馈，并在必要时让用户选择原因，例如“不准确”“没理解上下文”“太啰嗦”“格式不对”“引用错误”。

#第八类：安全与审计日志

AI 应用可能处理敏感数据，也可能代表用户执行动作，所以安全日志不能缺。

需要关注：

• 权限校验结果。
• 数据脱敏结果。
• prompt injection 检测。
• 内容安全拦截。
• 敏感信息输出风险。
• 工具调用审批。
• 管理员或内部人员查看日志的行为。

一个容易忽视的点是：日志本身也可能变成敏感数据仓库。

如果你把用户输入、检索内容、工具结果、模型输出全部明文写入日志，那么日志系统就拥有了比业务数据库更混杂、更难管控的数据。AI 日志必须有脱敏、权限和保留周期。

#日志数据流设计

一个较完整的 AI 日志链路可以这样设计：

这里有两个实践建议。

第一，日志要结构化。不要只写自然语言字符串。模型、token、耗时、状态、错误码、功能入口、租户都应该是可查询字段。

第二，日志要分层存储。高频运行日志、长期分析指标、安全审计、完整上下文快照，不一定放在同一个系统里。它们的访问权限、保留时间和查询方式不同。

#前端工程师要关心哪些日志

前端不负责全部日志系统，但很多关键数据来自前端。

前端应该传：

• client request id。
• thread id 和 message id。
• 用户触发入口。
• 选中文本、页面对象或文件引用。
• abort、retry、regenerate 等用户操作。
• 用户反馈。
• 客户端错误和断流信息。

前端也应该消费：

• run id。
• run status。
• normalized error code。
• usage summary。
• fallback 或降级状态。
• source/citation 信息。

这样 UI 才能准确表达“正在生成”“工具执行中”“已取消”“可重试”“上下文过长”“额度不足”“基于哪些来源回答”。

AI 日志不是后端的内部事务。它最终会变成前端可见状态和用户信任的一部分。

#常见坑

坑一：只记录最终回答。

最终回答无法解释模型为什么这么回答。至少要记录模型、prompt version、上下文引用、token、耗时和状态。

坑二：完整明文记录所有 prompt 和上下文。

这样排查方便，但安全风险极高。日志要有脱敏、访问控制和保留周期。能存引用时，不要盲目存全文。

坑三：错误码不归一。

Provider 的原始错误不适合直接给前端和分析系统使用。应该映射成内部错误码，例如 rate_limited、context_too_long、quota_exceeded、provider_timeout、tool_failed。

坑四：没有记录失败和取消。

失败、取消、中断、超时往往比成功更有分析价值。只记录成功请求，会系统性低估成本和体验问题。

坑五：反馈和 run 脱节。

用户点了差评，但没有关联 run id、message id、prompt version 和 context，就很难把反馈转化为评估样例。

坑六：日志字段没有租户维度。

多租户产品如果缺少 tenant_id，后续成本分摊、权限隔离、异常排查和企业报表都会很麻烦。

坑七：日志太多但无法查询。

日志不是越多越好。没有结构化字段、索引、采样策略和仪表盘，海量日志只会增加存储成本。

#小结

AI 应用的日志要覆盖请求、身份、模型、上下文、运行时、token 成本、工具调用、质量反馈和安全审计。它不是简单的 debug 输出，而是 AI 系统可观测、可评估、可控成本和可合规的基础。

对前端工程师来说，日志的意义也不只是后端排查。run id、streaming 状态、错误码、引用来源、用量反馈和用户评价，都会直接进入产品体验。

当你能从一条用户反馈追溯到一次 run、一个 prompt 版本、一组上下文、一串工具调用和一份 token 成本时，AI 应用才真正具备持续改进的能力。