做大模型 API 日志分析，不能只盯着“请求成功了没有”这一件事。真实业务里，很多问题并不会表现得那么直接。比如接口明明没有报错，但回复质量突然变差；调用量看起来没涨多少，Token 成本却明显上去了；用户说“很慢”，后端日志里却只有一个总耗时；还有一种更麻烦的情况，为了方便排查问题，把完整 Prompt 都记了下来，结果反而带来了隐私和合规风险。

所以，大模型 API 的日志记录重点，并不是把所有东西都存下来。更合理的做法，是围绕排障、性能、成本、质量、安全和业务归因，设计一套能分析、能追踪、能审计，同时风险可控的字段体系。不管你用的是 OpenAI、Claude、DeepSeek、通义千问、智谱、火山方舟、自建 vLLM，还是通过第三方 Claude API 兼容接入服务平台来调用模型，底层思路其实差不多：关键元数据要记清楚，原始内容要谨慎处理。

一、大模型 API 日志分析到底要回答哪些问题？

在设计日志字段之前，最好先想清楚：这些日志将来到底要帮我们解决什么问题。否则很容易走向两个极端。一种是只记录 HTTP 状态码，线上一出问题根本定位不了；另一种是把 Prompt、Response、文件内容全部落盘，短期调试是方便了，但安全风险也被一起放大了。

一套真正可用的大模型 API 日志，至少要能回答下面几类问题。

第一，这次调用是谁发起的。也就是说，它来自哪个应用、哪个用户、哪个租户、哪个接口，或者哪条业务线。

第二，调用的是哪个模型。供应商是谁，模型名称和版本是什么，中间有没有发生 fallback，这些都很关键。

第三，失败或超时到底因为什么。是被限流了，还是鉴权失败？是上下文太长，还是内容安全策略拦截？又或者只是网络抖动。

第四，成本为什么上涨。输入 Token、输出 Token、重试次数、缓存命中情况，以及模型单价有没有变化，都需要能追踪。

第五，回答质量为什么变差。很多时候问题不在模型本身，而是 Prompt 版本、模型版本、参数配置、RAG 检索结果发生了变化。

另外，还要看有没有安全和合规风险。比如是否包含敏感信息，是否触发了安全策略，日志本身有没有完成脱敏。

换句话说，大模型日志不能简单照搬传统 API 日志字段。除了常规的请求状态、耗时和错误码，还要覆盖 Token、Prompt、模型版本、流式响应、RAG、Agent、内容安全等大模型特有的信息。

二、最小必记字段清单：没有这些很难排查问题

如果业务刚上线，没必要一开始就把日志体系做得特别复杂。但至少要先记录一组“最小可用字段”。这些字段不一定能解决所有问题，不过能保证故障发生时，你还有基本的分析能力。

字段	是否必记	用途
request_id	必记	标识单次模型 API 调用
trace_id	必记	串联前端、后端、网关、模型调用链路
timestamp	必记	按时间分析错误、延迟和成本
app_id / service_name	必记	区分调用来源
user_id_hash / tenant_id_hash	必记但需脱敏	用于用户、租户和业务归因
provider	必记	区分 OpenAI、Claude、DeepSeek、通义等供应商
model	必记	分析不同模型的成本、质量和错误率
endpoint	必记	区分 chat、embedding、rerank、image、audio 等接口
status	必记	success、failed、timeout、cancelled
status_code	必记	HTTP 或供应商返回状态码
error_code	失败时必记	分析限流、鉴权、超长、拦截等问题
latency_ms	必记	统计接口耗时
prompt_tokens	必记	分析输入成本和上下文长度
completion_tokens	必记	分析输出成本和回答长度
total_tokens	必记	做成本汇总
retry_count	必记	识别隐藏成本和不稳定调用
finish_reason	必记	判断正常结束、长度截断、内容过滤、工具调用等情况
redaction_status	必记	确认日志是否已经脱敏

举个例子，如果只有 status_code，却没有 error_code，就很难判断失败到底是限流还是上下文超长。只有 latency_ms，但没有 trace_id，你也很难知道慢在应用层、网关层，还是模型供应商那一侧。再比如，只记录了 total_tokens，却没有用户或租户标识，那么成本就无法准确归因。

三、成本分析必须记录的信息

大模型 API 和普通 HTTP API 最大的区别之一，就是它的成本通常和 Token、模型类型、重试次数、缓存命中情况强相关。如果日志里没有成本相关字段，后面很难解释“为什么这个月费用突然涨了”。

成本分析时，建议重点记录这些信息：

字段	用途
prompt_tokens	分析输入长度和上下文膨胀
completion_tokens	分析输出长度和生成成本
total_tokens	按请求、用户、租户、接口汇总成本
estimated_cost	做成本看板和预算告警，金额口径要按实际计费规则计算
model	不同模型的成本结构可能完全不同
cache_hit	判断缓存是否降低了重复请求成本
retry_count	识别失败重试带来的隐性成本
fallback_model	分析降级或切换模型之后的成本变化
batch_size	在 Embedding、批量任务场景下用于均摊分析
business_unit / project_id	把费用归因到业务线或项目

实际分析时，经常会遇到这些问题：哪个接口最消耗 Token？哪个租户成本最高？是不是因为失败重试，导致实际调用次数翻倍？有没有大量相似的高频请求可以做缓存？某次 Prompt 改版之后，输入上下文是不是明显变长了？这些问题都离不开成本字段的支撑。

四、性能与稳定性必须记录的信息

大模型 API 的“慢”，不一定只体现在总耗时上。对于流式响应来说，用户更关心第一个 Token 什么时候出现；对于 Agent 来说，慢可能卡在工具调用；对于 RAG 来说，问题也可能出在检索或重排阶段。

建议按下面这些问题来记录字段：

问题	应看字段
请求整体慢	latency_ms、trace_id
首字慢	ttft_ms
经常超时	timeout_ms、error_code、retry_count
流式输出中断	streaming、stream_interrupted、client_cancelled
供应商不稳定	provider、status_code、provider_request_id
限流频繁	error_code、rate_limit_type、retry_after_ms
fallback 频繁	fallback_model、fallback_reason

这里尤其要注意 ttft_ms，也就是 Time To First Token，表示首个 Token 返回的时间。在流式输出场景里，它非常重要。即使总耗时不算高，只要 ttft_ms 很高，用户也会明显感觉“卡住了”。同样，如果 retry_count 很高，表面看成功率还不错，但稳定性和成本其实已经变差了。

五、回答质量分析必须记录的信息

大模型应用的质量问题，很多时候不能简单归结为“模型变差了”。更常见的原因是 Prompt 改了，模型版本换了，参数调整了，检索结果不一样了，工具调用失败了，或者安全策略把部分内容拦掉了。

做质量分析时，建议记录这些字段：

字段	用途
prompt_template_id	定位使用了哪个 Prompt 模板
prompt_template_version	对比 Prompt 改版前后的效果
system_prompt_version	分析系统指令变化带来的影响
model_version	排查模型升级或切换造成的差异
temperature / top_p	分析输出稳定性
max_tokens	判断是否因为长度限制被截断
finish_reason	判断 stop、length、content_filter、tool_calls 等结果
rag_query_id	关联检索请求
retrieved_doc_ids	分析答案是否命中了正确知识
similarity_scores / rerank_scores	判断召回和重排质量
user_feedback	记录点赞、点踩、投诉等反馈
quality_label	标注 badcase 类型，方便后续复盘

需要特别强调的是，质量分析并不等于要全量记录原始 Prompt。更推荐的方式，是记录 Prompt 模板 ID、版本、变量类型、摘要、风险标签和 Token 数。确实需要看原文时，也应该在受控条件下做采样，并且记录脱敏后的内容，而不是默认明文落盘。

六、安全与合规：哪些内容不能明文记录？

大模型 API 日志最容易踩坑的地方，就是为了排查问题，把用户输入、模型输出、文件内容、知识库片段全部写进日志。短期看，这样确实方便调试；但从长期看，很可能造成日志的二次泄露，风险非常高。

生产环境里，默认不建议明文记录这些内容：

• API Key、Access Token、Authorization Header；
• Cookie、Session、数据库连接串、内部系统凭证；
• 身份证、手机号、银行卡、邮箱、地址等个人敏感信息；
• 包含商业秘密、合同、病历、财务数据的完整 Prompt；
• 模型完整输出，尤其是涉及隐私或敏感推理结果的内容；
• 文件原文、知识库原文、数据库查询结果；
• 未脱敏的多轮用户对话历史。

更安全的做法，是把原始内容转换成可分析但不暴露隐私的形式：

原始内容	推荐记录方式
用户 ID	user_id_hash
手机号	脱敏后保留后四位
Prompt 原文	prompt_template_id、变量类型、摘要、Token 数
Response 原文	输出长度、分类标签、风险标签、质量评分
文件内容	文件 ID、文档 ID、片段 ID，不记录原文
敏感命中	safety_flag、risk_category、redaction_status

如果确实必须记录原文，也应该限制在调试环境，或者采用低比例采样。同时要配合脱敏、截断、加密、访问审批、保留周期控制和日志访问审计。简单说，原文日志不是不能有，但绝不能随意有。

七、不同场景下的扩展字段

不同类型的大模型应用，日志字段不应该完全一样。最小字段解决的是基础排障问题，而扩展字段则要服务具体业务场景。

场景	额外建议记录
Chatbot	session_id、turn_index、intent_label、user_feedback
RAG 问答	rag_query_id、top_k、retrieved_doc_ids、similarity_scores、rerank_scores
Agent	tool_call_id、tool_name、tool_status、tool_latency_ms、plan_step_id
Embedding	input_length、embedding_dim、batch_size、index_name
多模型网关	route_policy、provider、fallback_model、fallback_reason
流式输出	ttft_ms、stream_interrupted、client_cancelled
企业多租户	tenant_id_hash、quota_id、department_id、project_id
内容安全	safety_flag、risk_category、policy_action、review_status

比如在 RAG 场景里，只记录最终回答显然不够。你还得能关联到检索 query、召回文档和重排结果，否则很难判断答案错在生成阶段，还是知识没召回。Agent 场景也是一样，只看最终模型调用没有太大意义，还要记录工具调用链路，这样才能判断失败到底来自模型推理，还是工具执行。

八、推荐日志格式示例

成功调用日志示例

{
  "timestamp": "2026-01-15T10:21:33.120Z",
  "request_id": "req_abc123",
  "trace_id": "trace_789",
  "app_id": "customer-support-bot",
  "tenant_id_hash": "tnt_9f2a",
  "provider": "deepseek",
  "model": "deepseek-chat",
  "endpoint": "/v1/chat/completions",
  "status": "success",
  "latency_ms": 1280,
  "ttft_ms": 320,
  "prompt_tokens": 842,
  "completion_tokens": 316,
  "total_tokens": 1158,
  "estimated_cost": 0.0021,
  "prompt_template_id": "support_reply",
  "prompt_template_version": "v3.2",
  "temperature": 0.7,
  "finish_reason": "stop",
  "cache_hit": false,
  "redaction_status": "masked"
}

失败调用日志示例

{
  "timestamp": "2026-01-15T10:23:10.502Z",
  "request_id": "req_def456",
  "trace_id": "trace_790",
  "app_id": "internal-agent",
  "provider": "model-provider-a",
  "model": "chat-model",
  "endpoint": "/v1/chat/completions",
  "status": "failed",
  "status_code": 429,
  "error_code": "rate_limit_exceeded",
  "error_message_sanitized": "request rate limit exceeded",
  "latency_ms": 860,
  "timeout_ms": 30000,
  "retry_count": 2,
  "fallback_model": "backup-chat-model",
  "provider_request_id": "prv_xxx",
  "redaction_status": "masked"
}

上面示例里的金额、模型名和错误码，只是为了展示结构。实际使用时，字段含义还是要以所接入模型服务或网关的返回为准。如果是通过第三方 Claude API 兼容接入服务平台调用 Claude 相关能力，也建议把兼容接入方式、供应商标识、线路、请求 ID、错误码和脱敏状态都记录清楚。至于具体服务能力、价格和规则，则应以平台最新说明为准，不要在日志设计里默认它们永远稳定、永远不限速。

九、从日志中建立哪些看板和告警？

字段记录下来之后，不能只是堆在日志系统里，还要把它们变成可观察的指标。比较实用的看板至少包括这些：

• 调用量趋势：按应用、接口、模型、租户拆分。
• 成功率与错误率：关注失败、超时、取消、内容拦截。
• 错误码 Top N：快速识别限流、鉴权、上下文超长等高频问题。
• P50/P90/P99 延迟：区分平均体验和长尾问题。
• 首 Token 延迟：重点观察流式响应体验。
• Token 消耗趋势：按用户、租户、业务线和模型统计。
• 成本趋势：结合模型、Token、重试、缓存命中情况分析。
• fallback 触发率：判断主模型或主线路是否稳定。
• 缓存命中率：评估缓存策略是否真的有效。
• Prompt 版本效果对比：结合反馈、badcase 和人工评分分析。
• RAG 召回命中率：观察检索质量是否影响回答效果。
• 内容安全拦截率：识别高风险输入和输出场景。

告警也不要只盯着接口 5xx。对大模型应用来说，Token 突然激增、P99 延迟明显恶化、重试率升高、fallback 异常增加、内容安全拦截率突增，往往比单次错误更值得警惕。

十、大模型 API 日志记录 Checklist

1. 最小可用版

适合刚上线，或者流量还不大的应用：

• request_id、trace_id、timestamp
• app_id、user_id_hash 或 tenant_id_hash
• provider、model、endpoint
• status、status_code、error_code
• latency_ms、retry_count
• prompt_tokens、completion_tokens、total_tokens
• finish_reason、redaction_status

2. 生产推荐版

适合已经有稳定流量，并且开始关注成本和质量的业务：

• 增加 estimated_cost、cache_hit、fallback_model
• 增加 ttft_ms、timeout_ms、provider_request_id
• 增加 prompt_template_id、prompt_template_version
• 增加 model_version、temperature、top_p、max_tokens
• 增加 user_feedback、quality_label
• 按应用、模型、租户建立成本和稳定性看板

3. 企业审计版

适合金融、医疗、政企、客服等对合规要求较高的场景：

• 增加 safety_flag、risk_category、policy_action
• 增加 redaction_status、data_classification
• 增加日志访问人、查看时间、导出记录
• 区分调试日志、调用日志、审计日志和安全日志
• 设置日志保留周期、加密存储和访问审批
• 对 Prompt、Response、文件内容默认做脱敏、截断或采样

总的来说，大模型 API 日志分析的核心不是“记得越多越好”，而是“围绕目标去记录”。排障需要 request_id、trace_id 和错误码；成本分析离不开 Token、模型、重试和缓存；质量复盘要看 Prompt 版本、模型版本、参数和用户反馈；安全合规则要关注脱敏状态、风险标签和访问审计。把这些字段提前设计清楚，后面无论是做 API 日志记录、成本分析、质量复盘，还是合规审计，都会少走很多弯路。