一、为什么大模型项目必须单独做日志系统？

普通 Java 后端日志，主要看：

1. 接口有没有报错
2. SQL 慢不慢
3. 服务有没有超时
4. 用户请求链路是否正常

但大模型应用不一样。它的问题不只是“接口挂了”，更常见的是：

1. 模型回答错了，但接口是 200
2. 用户说 AI 胡说八道，但后端日志看不出来
3. RAG 检索到了错误文档，模型照着错误内容回答
4. Prompt 改了一行，线上效果突然变差
5. Token 消耗暴涨，成本失控
6. 用户输入了敏感信息，日志里可能泄露隐私
7. Agent 调工具失败，但最终回答看起来像成功了
8. 同一个问题昨天答对，今天答错，不知道为什么

所以，大模型日志系统不能只记录：

requestId、userId、接口耗时、状态码

还要记录：

用户问题、Prompt版本、模型名称、检索结果、工具调用、Token消耗、模型输出、质量评分、人工反馈、安全拦截、成本明细

这就是大模型日志系统的核心价值：让 AI 应用从“黑盒”变成“可追踪、可复盘、可优化”的系统。

OpenTelemetry 也把可观测数据分为 traces、metrics、logs 三类，日志系统最好和链路追踪、指标监控一起设计，而不是孤立做一堆文本日志。

---

二、大模型日志系统的核心目标

2.1 第一目标：问题可追踪

用户投诉：

“你们 AI 回答错了。”

你不能只看接口日志说：

“接口没报错啊。”

你要能查到：

1. 用户原始问题是什么
2. 当时走的是 RAG、FAQ、工具调用，还是纯大模型
3. 当时使用的 Prompt 是哪个版本
4. 检索到了哪些知识库文档
5. 模型最终输入是什么
6. 模型最终输出是什么
7. 模型有没有触发安全策略
8. 工具调用有没有失败
9. 总耗时是多少
10. Token 和成本是多少

这才叫“可追踪”。

---

2.2 第二目标：质量可评估

大模型不是传统代码，不能只看是否报错。

传统接口：

成功 = 状态码 200
失败 = 状态码 500

大模型接口：

状态码 200，也可能回答错误
状态码 200，也可能答非所问
状态码 200，也可能幻觉严重
状态码 200，也可能泄露敏感信息

所以日志系统要支持后续分析：

1. 哪些问题命中率低
2. 哪些知识库召回效果差
3. 哪些 Prompt 版本效果下降
4. 哪些模型成本高但效果一般
5. 哪些用户问题经常触发兜底回答
6. 哪些业务场景最容易产生幻觉

Langfuse 这类 LLM 工程平台就把 trace、prompt 管理、实验、数据集、评估等能力放在一起，用来帮助团队调试、分析和迭代 LLM 应用。

---

2.3 第三目标：成本可控制

大模型调用成本和普通接口不一样。

普通接口成本主要看：

CPU、内存、数据库、带宽

大模型成本主要看：

输入 Token、输出 Token、模型单价、调用次数、重试次数、上下文长度

如果没有日志，你很难知道：

1. 哪个接口最烧钱
2. 哪个用户最烧钱
3. 哪个 Prompt 写得太长
4. 哪个 RAG 检索塞入了太多无用文档
5. 哪个 Agent 工具链反复调用模型
6. 哪个模型该降级为小模型

所以大模型日志系统必须记录 Token 和成本。

---

2.4 第四目标：安全可审计

大模型日志里可能包含：

1. 用户手机号
2. 身份证号
3. 邮箱
4. 合同内容
5. 公司内部文档
6. 客户隐私
7. 业务机密
8. Prompt 内部规则
9. API Key 或工具调用参数

所以日志系统必须做：

1. 脱敏
2. 权限控制
3. 数据留存周期
4. 敏感字段加密
5. 审计记录
6. 日志访问审批

否则日志系统本身就可能变成最大的安全风险。

---

三、大模型日志系统到底要记录什么？

3.1 请求基础日志

这一层和普通业务日志类似。

建议记录：

trace_id：全链路追踪ID
request_id：单次请求ID
session_id：会话ID
user_id：用户ID
tenant_id：租户ID
app_id：应用ID
channel：来源渠道，比如 Web、App、企业微信、钉钉
ip：请求IP
user_agent：客户端信息
timestamp：请求时间
env：环境，比如 dev、test、prod

其中最重要的是：

trace_id

因为一个大模型请求可能经过：

网关 -> 鉴权 -> 意图识别 -> RAG检索 -> Prompt组装 -> 模型调用 -> 工具调用 -> 结果后处理 -> 返回用户

没有 trace_id，后面排查会非常痛苦。

---

3.2 用户输入日志

要记录用户原始输入，但不能无脑明文保存。

建议记录：

raw_query：用户原始问题
query_hash：问题哈希
query_length：问题长度
language：语言
input_type：文本/语音/图片/文件
sensitive_hit：是否命中敏感信息
risk_level：风险等级

例如：

{
  "query": "帮我总结一下这个合同的违约责任",
  "query_length": 18,
  "input_type": "text",
  "sensitive_hit": true,
  "risk_level": "medium"
}

注意：如果是金融、医疗、政务、企业内部知识库场景，用户输入最好做脱敏或分级存储。

---

3.3 意图识别日志

如果系统前面有意图识别模块，一定要记录。

例如：

intent：识别出的意图
confidence：置信度
route：最终路由

示例：

{
  "intent": "knowledge_qa",
  "confidence": 0.87,
  "route": "RAG"
}

为什么重要？

因为很多线上问题不是模型回答错，而是路由错了。

例如用户问：

“帮我查一下订单物流。”

系统却把它识别成：

普通问答

然后没有调用物流工具，最后模型胡编了一个物流状态。

这种问题如果没有意图日志，很难定位。

---

3.4 Prompt 日志

Prompt 是大模型系统的“隐形代码”。

代码上线会记录版本，Prompt 也必须记录版本。

建议记录：

prompt_id：Prompt编号
prompt_version：Prompt版本
system_prompt：系统提示词
user_prompt：用户提示词
prompt_template：模板
variables：模板变量
final_prompt：最终拼接后的Prompt

但注意：final_prompt 不一定适合长期明文保存，因为里面可能包含用户隐私和企业知识库内容。

可以采用两种方式：

1. 开发测试环境保存完整 Prompt
2. 生产环境保存摘要、哈希、版本号和脱敏内容

例如：

{
  "prompt_id": "customer_service_qa",
  "prompt_version": "v12",
  "template_variables": {
    "role": "售后客服",
    "knowledge_count": 5
  },
  "prompt_hash": "a8f9xxx"
}

Prompt 管理和实验能力也是很多 LLM 可观测平台的重点功能。

---

3.5 模型调用日志

这是大模型日志系统最核心的一层。

建议记录：

provider：模型供应商
model_name：模型名称
model_version：模型版本
temperature：随机性参数
top_p：采样参数
max_tokens：最大输出长度
input_tokens：输入Token
output_tokens：输出Token
total_tokens：总Token
latency_ms：模型耗时
retry_count：重试次数
status：成功/失败
error_code：错误码
error_message：错误信息

示例：

{
  "provider": "openai",
  "model_name": "gpt-4.1",
  "temperature": 0.3,
  "input_tokens": 3120,
  "output_tokens": 680,
  "total_tokens": 3800,
  "latency_ms": 2650,
  "retry_count": 0,
  "status": "success"
}

这类日志可以帮助你分析：

1. 哪个模型慢
2. 哪个模型贵
3. 哪个模型失败率高
4. 哪些请求上下文太长
5. 哪些业务场景需要换小模型
6. 哪些场景需要缓存

---

3.6 RAG 检索日志

如果项目里用了知识库问答，RAG 日志一定要重点做。

建议记录：

query_rewrite：改写后的查询
retrieval_type：向量检索/关键词检索/混合检索
embedding_model：向量模型
top_k：召回数量
rerank_model：重排模型
retrieved_docs：召回文档
doc_id：文档ID
chunk_id：切片ID
score：相关性分数
final_context：最终塞给模型的上下文
hit_knowledge_base：命中的知识库

示例：

{
  "retrieval_type": "hybrid_search",
  "top_k": 10,
  "rerank_top_k": 5,
  "retrieved_docs": [
    {
      "doc_id": "contract_2025_001",
      "chunk_id": "chunk_32",
      "score": 0.86,
      "title": "售后服务政策"
    }
  ]
}

RAG 线上问题经常出在这里：

1. 用户问题没改写好
2. 向量召回没召到
3. 关键词检索漏召
4. 重排模型排序错误
5. 文档切片太碎
6. 文档版本过旧
7. 错误知识被塞进上下文
8. 模型没有严格依据知识库回答

所以 RAG 日志不是可选项，而是必选项。

---

3.7 Agent 工具调用日志

如果你的系统有 Agent，例如：

查订单
查库存
查天气
查数据库
调用搜索
调用计算器
调用业务接口

就必须记录工具调用日志。

建议记录：

tool_name：工具名称
tool_input：工具入参
tool_output：工具返回
tool_latency_ms：工具耗时
tool_status：成功/失败
tool_error：错误原因
tool_retry_count：重试次数

示例：

{
  "tool_name": "query_order_status",
  "tool_input": {
    "order_id": "202605060001"
  },
  "tool_output": {
    "status": "已发货"
  },
  "tool_latency_ms": 320,
  "tool_status": "success"
}

Agent 最大的问题是链路长。

一次用户请求可能变成：

模型判断意图 -> 调用工具A -> 模型分析结果 -> 调用工具B -> 模型生成回答

如果没有工具调用日志，失败时根本不知道是哪一步出问题。

---

3.8 模型输出日志

建议记录：

raw_output：模型原始输出
final_output：后处理后的输出
output_length：输出长度
finish_reason：结束原因
is_truncated：是否被截断
safety_hit：是否触发安全策略
refusal：是否拒答

示例：

{
  "finish_reason": "stop",
  "output_length": 580,
  "is_truncated": false,
  "safety_hit": false
}

模型输出日志可以帮助分析：

1. 是否答非所问
2. 是否输出过长
3. 是否经常被截断
4. 是否经常触发安全策略
5. 是否存在幻觉
6. 是否需要优化 Prompt

---

3.9 用户反馈日志

大模型系统一定要设计反馈入口。

例如：

点赞
点踩
复制
重新生成
追问
投诉
人工标注

建议记录：

feedback_type：反馈类型
feedback_reason：反馈原因
rating：评分
human_label：人工标签
comment：用户备注

示例：

{
  "feedback_type": "downvote",
  "feedback_reason": "答案不准确",
  "rating": 1
}

这类日志非常有价值。

因为它可以反向驱动：

1. Prompt 优化
2. 知识库补充
3. 评测集建设
4. 模型选型
5. 业务流程优化

---

3.10 质量评估日志

大模型系统不能只靠用户点踩来发现问题，还要做自动评估。

建议记录：

answer_relevance：回答相关性
faithfulness：是否忠于知识库
hallucination_risk：幻觉风险
toxicity：有害内容风险
format_score：格式是否符合要求
citation_score：引用是否准确

不用把它理解得太复杂。

通俗讲，就是给每次回答打几个标签：

有没有答到点？
有没有胡编？
有没有按照知识库回答？
格式有没有乱？
有没有风险内容？

Langfuse 文档中也强调，评估可以让团队用数据检查 LLM 应用行为，并在 Prompt 或应用变更后发现回归问题。

---

四、大模型日志系统的整体架构

4.1 推荐架构

可以设计成这样：

用户请求
  ↓
网关层
  ↓
业务服务
  ↓
日志埋点 SDK
  ↓
消息队列 Kafka / Pulsar / RocketMQ
  ↓
日志处理服务
  ↓
冷热分层存储
  ↓
检索分析平台
  ↓
监控告警 / 质量评估 / 成本看板

简单理解：

业务系统负责产生日志
消息队列负责削峰
日志处理服务负责清洗脱敏
存储系统负责保存
分析平台负责查询和看板
告警系统负责发现异常

---

4.2 为什么不要直接写数据库？

很多人一开始会这样做：

每次大模型请求结束后，直接 insert 到 MySQL

小流量可以，大流量不行。

原因：

1. 日志字段很多
2. Prompt 和输出内容很长
3. QPS 上来后数据库压力大
4. 查询维度复杂
5. 后续清洗、脱敏、归档麻烦
6. 影响主业务接口性能

更好的方式是：

业务服务异步写日志
日志进入消息队列
后台慢慢消费处理

这样即使日志系统短暂异常，也不会拖垮主业务。

---

五、日志系统应该怎么分层？

5.1 第一层：业务链路日志

回答的是：

“这个请求经历了哪些步骤？”

包括：

鉴权
意图识别
RAG检索
Prompt组装
模型调用
工具调用
输出后处理
安全审核
返回用户

适合用 Trace 来串起来。

---

5.2 第二层：模型调用日志

回答的是：

“模型到底怎么被调用的？”

包括：

模型名称
Prompt版本
输入Token
输出Token
耗时
状态
错误信息

---

5.3 第三层：知识库检索日志

回答的是：

“RAG为什么答错？”

包括：

检索词
召回文档
切片内容
相关性分数
重排结果
最终上下文

---

5.4 第四层：质量评估日志

回答的是：

“这次回答质量怎么样？”

包括：

是否相关
是否准确
是否幻觉
是否符合格式
是否引用正确
用户是否满意

---

5.5 第五层：成本日志

回答的是：

“这次请求花了多少钱？”

包括：

模型单价
输入Token
输出Token
总Token
缓存命中
重试次数
总成本

---

5.6 第六层：安全审计日志

回答的是：

“有没有安全风险？”

包括：

敏感词命中
隐私数据命中
越权访问
Prompt注入
违规输出
高风险工具调用
管理员查看日志记录

---

六、大模型日志字段设计模板

6.1 一条完整日志应该长什么样？

可以参考下面这个结构：

{
  "trace_id": "trace_20260506_001",
  "request_id": "req_abc123",
  "user_id": "u_10086",
  "tenant_id": "tenant_a",
  "app_id": "ai_customer_service",
  "timestamp": "2026-05-06T16:30:00+08:00",

  "input": {
    "query": "我的订单为什么还没发货？",
    "query_hash": "xxx",
    "language": "zh-CN",
    "sensitive_hit": false
  },

  "intent": {
    "name": "order_query",
    "confidence": 0.92,
    "route": "agent_tool"
  },

  "prompt": {
    "prompt_id": "order_agent_prompt",
    "prompt_version": "v3",
    "template_hash": "xxx"
  },

  "retrieval": {
    "enabled": false
  },

  "tools": [
    {
      "tool_name": "query_order_status",
      "status": "success",
      "latency_ms": 280
    }
  ],

  "llm": {
    "provider": "xxx",
    "model": "xxx-large",
    "temperature": 0.2,
    "input_tokens": 1200,
    "output_tokens": 300,
    "total_tokens": 1500,
    "latency_ms": 2100,
    "status": "success"
  },

  "output": {
    "finish_reason": "stop",
    "answer_length": 180,
    "safety_hit": false
  },

  "quality": {
    "auto_score": 0.86,
    "hallucination_risk": "low"
  },

  "cost": {
    "estimated_cost": 0.012,
    "currency": "USD"
  }
}

---

七、日志采集怎么做？

7.1 推荐使用统一 SDK 埋点

不要每个业务方自己乱打日志。

应该封装一个统一的日志 SDK。

例如：

llmLogger.startTrace();
llmLogger.recordIntent();
llmLogger.recordRetrieval();
llmLogger.recordPrompt();
llmLogger.recordModelCall();
llmLogger.recordToolCall();
llmLogger.recordOutput();
llmLogger.endTrace();

这样好处是：

1. 字段统一
2. 格式统一
3. 方便升级
4. 方便治理
5. 方便接入多个业务系统

---

7.2 日志采集要异步

不要这样：

模型返回 -> 同步写日志 -> 返回用户

应该这样：

模型返回 -> 投递日志事件 -> 立即返回用户
                    ↓
              后台异步处理

因为日志系统不能影响主流程。

尤其是大模型本身已经比较慢，如果日志再同步写数据库，用户体验会更差。

---

7.3 日志采集要支持失败降级

日志系统挂了，不能导致 AI 服务不可用。

正确做法：

日志写入失败 -> 本地缓冲 -> 限流丢弃非核心日志 -> 告警

核心原则：

业务优先，日志降级

但关键审计日志不能随便丢，要单独设计可靠通道。

---

八、日志存储怎么做？

8.1 热数据和冷数据分开

大模型日志通常很大。

建议：

近 7 天：热数据，方便快速查询
近 30 天：温数据，用于分析统计
超过 30/90 天：冷数据，归档存储

例如：

热数据：Elasticsearch / ClickHouse
冷数据：对象存储 / HDFS / S3

---

8.2 结构化字段和大文本分开

不要把所有内容都塞进一个大 JSON 里。

建议拆分：

结构化字段：request_id、user_id、model、tokens、cost、latency
大文本字段：prompt、context、answer、retrieved_chunks

结构化字段用于查询分析，大文本字段用于问题复盘。

---

8.3 敏感内容单独存储

例如：

用户原始问题
完整 Prompt
知识库上下文
模型完整输出
工具调用参数

这些内容应该：

1. 加密存储
2. 控制访问权限
3. 设置保留周期
4. 支持脱敏查看
5. 记录谁查看过

---

九、日志查询平台应该怎么做？

9.1 按用户查

客服或运营经常需要查：

某个用户刚刚问了什么？
AI 是怎么回答的？
为什么回答错？

所以要支持：

user_id
session_id
request_id
trace_id

查询。

---

9.2 按问题查

产品和算法同学常查：

哪些问题经常答错？
哪些问题经常触发兜底？
哪些问题用户经常点踩？

所以要支持：

query关键词
query_hash
intent
feedback_type
quality_score

查询。

---

9.3 按模型查

技术团队要看：

哪个模型效果好？
哪个模型成本高？
哪个模型延迟大？
哪个模型失败率高？

所以要支持：

model_name
provider
latency_ms
tokens
cost
error_code

查询。

---

9.4 按知识库查

RAG 场景要看：

哪个知识库命中多？
哪个文档经常被引用？
哪个文档导致错误回答？
哪些问题没有召回到内容？

所以要支持：

knowledge_base_id
doc_id
chunk_id
retrieval_score
rerank_score

查询。

---

十、日志看板应该做哪些？

10.1 调用量看板

核心指标：

总请求量
成功请求量
失败请求量
模型调用次数
工具调用次数
RAG调用次数
Agent调用次数

---

10.2 延迟看板

核心指标：

平均耗时
P95耗时
P99耗时
模型耗时
检索耗时
工具耗时
后处理耗时

不要只看平均值。

因为平均值容易骗人。

例如：

平均耗时 2 秒

但可能有 5% 用户等了 15 秒。

所以 P95、P99 很重要。

---

10.3 成本看板

核心指标：

总Token
输入Token
输出Token
平均单次成本
总成本
按用户成本
按租户成本
按模型成本
按应用成本

这块对老板和管理层非常有用。

---

10.4 质量看板

核心指标：

用户点赞率
用户点踩率
兜底率
拒答率
幻觉风险率
知识库命中率
工具调用成功率
答案相关性评分

---

10.5 安全看板

核心指标：

敏感输入次数
敏感输出次数
Prompt注入次数
越权访问次数
高风险工具调用次数
安全拦截次数

---

十一、大模型日志系统的告警怎么做？

11.1 技术告警

例如：

模型失败率 > 5%
平均延迟 > 5 秒
P99 延迟 > 20 秒
工具调用失败率 > 10%
RAG 检索失败率 > 10%
消息队列积压过高

---

11.2 成本告警

例如：

单小时 Token 消耗暴涨
某个用户成本异常
某个租户成本异常
某个 Prompt 版本导致 Token 翻倍
Agent 循环调用模型

---

11.3 质量告警

例如：

点踩率突然升高
兜底率突然升高
拒答率突然升高
幻觉风险突然升高
某个知识库命中率突然下降

---

11.4 安全告警

例如：

大量 Prompt 注入攻击
大量敏感信息输入
模型输出违规内容
用户越权查询知识库
管理员频繁查看敏感日志

---

十二、大模型日志系统和评测集怎么结合？

日志系统不是只用来查问题，还可以反哺评测集。

12.1 从线上日志沉淀真实问题

把线上问题分成：

高频问题
高风险问题
用户点踩问题
模型答错问题
召回失败问题
工具调用失败问题

这些都可以进入评测集。

---

12.2 从 badcase 生成测试样本

例如线上发现：

用户问“合同到期后能否自动续约？”

模型答错了。

就可以沉淀成评测样本：

问题：合同到期后能否自动续约？
标准答案：根据合同第 X 条，需双方书面确认后续约。
相关文档：合同第 X 条
错误类型：知识库召回错误 / 模型幻觉

---

12.3 Prompt 上线前跑评测

每次 Prompt 改版前，都可以跑一遍历史 badcase。

如果新 Prompt 导致：

准确率下降
幻觉率上升
格式错误变多
拒答率升高

就不要上线。

这就是日志系统和评测系统的闭环。

---

十三、常见坑

13.1 只记接口日志，不记 Prompt

这是最大的问题。

大模型应用里，Prompt 就像代码。

不记录 Prompt 版本，后面根本无法复盘。

---

13.2 只记最终答案，不记检索过程

RAG 答错时，很多人只看模型输出。

但真正问题可能在：

没召回
召回错
重排错
上下文拼错
知识库版本错

所以必须记录检索过程。

---

13.3 日志里保存太多敏感明文

这也是大坑。

大模型日志很容易包含隐私和机密。

一定要做：

脱敏
加密
权限
审计
保留周期

---

13.4 没有 trace_id

没有 trace_id，就无法串起完整链路。

最后排查时只能在不同日志文件里大海捞针。

---

13.5 没有成本字段

大模型项目最容易出现：

效果没提升多少，成本先爆了

所以 Token 和成本必须从第一天开始记录。

---

十四、简历里怎么写“大模型日志系统”？

如果你想写到简历里，可以这样写：

负责大模型应用日志与可观测体系建设，设计 Trace 级调用链路，覆盖用户输入、意图识别、RAG 检索、Prompt 版本、模型调用、Token 成本、工具调用、模型输出、用户反馈等关键节点；通过异步日志采集、敏感信息脱敏、冷热分层存储和质量看板，实现大模型问题追踪、成本分析、badcase 沉淀和线上效果评估，提升问题排查效率并支撑 Prompt 迭代和评测集建设。

再具体一点：

建设 LLM Trace 日志体系，打通 request_id / session_id / trace_id 全链路追踪，记录 Prompt 版本、模型参数、输入输出 Token、RAG 召回文档、重排分数、工具调用结果和用户反馈，支持按用户、模型、知识库、Prompt 版本维度进行问题定位和质量分析。

如果想体现业务价值：

基于线上日志沉淀 badcase，构建评测集和质量看板，定位 RAG 召回失败、Prompt 回归、模型幻觉和工具调用异常等问题，为 Prompt 优化、知识库治理和模型选型提供数据依据。

---

十五、总结

大模型日志系统不是简单的“打印几行日志”。

它应该是一套完整的 AI 可观测体系。

核心要做到：

一、请求可追踪
二、Prompt 可回溯
三、RAG 可分析
四、Agent 可复盘
五、Token 可计费
六、质量可评估
七、安全可审计
八、badcase 可沉淀
九、评测集可迭代
十、线上效果可持续优化

普通业务日志解决的是：

系统有没有挂？

大模型日志系统解决的是：

AI 为什么这么回答？
回答得好不好？
成本高不高？
有没有安全风险？
下次怎么优化？

真正成熟的大模型项目，一定不是只把模型接进来，而是要把：

日志系统 + 监控看板 + 质量评估 + 成本分析 + 安全审计 + badcase闭环

一起建设起来。

这样你的大模型应用才不是一个“会聊天的黑盒”，而是一个可以运营、可以优化、可以规模化落地的工程系统。