AI 应用上线后怎么排查问题？日志与可观测性应该这样设计

关注

原创最新推荐文章于 2026-08-22 14:41:04 发布 594 阅读 AI 写同款· GEO 优化 ›

AI记账App从开发到上线：测试、部署与运维全链路实战在软件工程领域，测试与部署是保障应用从开发环境走向生产环境稳定运行的核心环节。其原理在于通过系统化的质量保障体系，模拟真实场景验证功能、性能与可靠性。对于AI驱动的应用而言，这一过程的技术价值尤为突出，它直接决定了模型能力能否在实际业务中有效转化。特别是在智能记账、文本分类等场景中，涉及账单识别、金额提取等复杂NLP任务时，全面的测试策略和稳健的部署流程是避免线上事故的关键。本文以AI记账App为例，深入探讨了如何构建涵盖单元测试、集成测试、压力测试的多层次防线，并详细介绍了使用Docker容器化与GitH 阅读详情

上一篇文章讨论了 Memory。

Memory 让 AI 应用可以在可控范围内延续上下文。

但当一个 AI 应用真的上线后，仅仅能记住上下文还不够。

它还必须能被排查、被追踪、被复盘。

因为线上问题一定会出现。

模型可能回答异常。

Prompt 可能被错误拼接。

RAG 可能检索不到正确内容。

Tool 可能调用失败。

Workflow 可能卡在某个节点。

Agent 可能重复执行无效步骤。

Token 成本可能突然升高。

用户输入可能触发边界情况。

如果没有日志和可观测性，开发者只能靠猜。

而 AI 应用最怕的就是靠猜排查问题。

所以，从 Demo 走向工程化，日志与可观测性是必须补上的一层能力。

一、AI 应用的问题不只是代码报错

传统后端系统排查问题，通常关注：

接口是否报错。
数据库是否异常。
响应时间是否过长。
服务器资源是否不足。
异常栈在哪里。

这些在 AI 应用里仍然重要。

但 AI 应用的问题更多。

例如：

模型没有报错，但回答质量很差。

接口返回 200，但用户觉得结果不对。

Tool 调用成功了，但用了错误参数。

RAG 检索返回了内容，但不是用户真正需要的内容。

Agent 执行完了，但路径明显绕远了。

Workflow 没有崩溃，但某个节点输出不合理。

Token 消耗没有报警，但单次请求成本比预期高很多。

这些问题不是普通异常栈能解释的。

它们需要更细的链路记录。

也需要专门面向 AI 应用的观测指标。

二、为什么 print 日志不够

很多 Demo 项目会这样写日志：

print("start workflow")
print("call llm")
print("result:", result)

这在本地调试阶段还可以。

但上线后远远不够。

首先，print 没有结构。

你很难按用户、请求、模型、任务、错误类型去检索。

其次，print 很难串联链路。

一次用户请求可能包含多次模型调用、多次 Tool 调用、多次检索和多个 Workflow 节点。

如果没有统一 trace_id，很难知道这些日志属于同一次请求。

第三，print 容易泄露敏感信息。

开发阶段随手打印 Prompt、用户输入、接口参数，线上可能就会把隐私或密钥打进日志。

第四，print 不适合统计。

你很难从一堆文本中稳定统计模型耗时、Token 成本、失败率和工具调用次数。

所以，AI 应用需要结构化日志。

不是多打几行 print。

三、一次 AI 请求应该有 trace_id

AI 应用的调用链通常比较长。

例如一次问答请求可能是：

用户请求
  ↓
解析输入
  ↓
加载 Memory
  ↓
RAG 检索
  ↓
构造 Prompt
  ↓
调用 LLM
  ↓
判断是否调用 Tool
  ↓
执行 Tool
  ↓
再次调用 LLM
  ↓
返回结果

如果每一步日志没有关联，排查问题会非常痛苦。

所以每次请求都应该生成一个 trace_id。

例如：

trace_id = "req_20260711_100001_xxxx"

后续所有日志都带上这个 trace_id：

{
  "trace_id": "req_20260711_100001_xxxx",
  "event": "llm_call_start",
  "model": "deepseek-chat",
  "workflow": "rag_workflow"
}

这样排查问题时，就能把一次请求下的所有事件串起来。

trace_id 是可观测性的基础。

没有 trace_id，日志只是散落的碎片。

四、请求日志应该记录什么

请求日志是入口层日志。

它回答的是：

谁在什么时候发起了什么类型的请求，最终结果如何。

请求日志可以记录：

trace_id：请求链路 ID。
user_id：用户 ID 或匿名 ID。
endpoint：接口路径或入口名称。
method：请求方法。
request_type：请求类型。
status：成功或失败。
latency_ms：总耗时。
created_at：请求时间。
error_code：错误码。

例如：

{
  "trace_id": "req_001",
  "event": "request_finished",
  "endpoint": "/chat",
  "status": "success",
  "latency_ms": 3420
}

请求日志不一定要记录完整用户输入。

很多时候只需要记录输入长度、类型、是否命中某类规则。

如果必须记录输入，也要做脱敏和权限控制。

五、模型调用日志应该记录什么

模型调用是 AI 应用最核心、也最容易出问题的地方。

模型调用日志应该至少记录：

trace_id：请求链路 ID。
provider：模型供应商。
model：模型名称。
prompt_version：Prompt 版本。
input_tokens：输入 token。
output_tokens：输出 token。
total_tokens：总 token。
latency_ms：模型耗时。
status：成功或失败。
error_type：错误类型。
retry_count：重试次数。

例如：

{
  "trace_id": "req_001",
  "event": "llm_call_finished",
  "provider": "openai",
  "model": "gpt-4.1",
  "prompt_version": "qa_v3",
  "input_tokens": 1200,
  "output_tokens": 360,
  "latency_ms": 2100,
  "status": "success"
}

这里有一个重点：

不要默认把完整 Prompt 和完整 Response 全部写进普通日志。

因为里面可能包含用户隐私、业务数据或敏感上下文。

更合理的做法是：

默认记录结构化元数据。
必要时记录脱敏后的摘要。
调试环境可以打开详细日志。
生产环境详细日志需要权限和保留周期。

六、Token 成本必须可观测

AI 应用和传统后端最大的不同之一，是模型调用有直接成本。

一次请求消耗多少 token，可能直接影响账单。

如果没有 Token 统计，很难发现成本异常。

需要观察的指标包括：

单次请求平均 token。
单个用户 token 消耗。
单个 Workflow token 消耗。
单个模型 token 消耗。
每日总 token。
输入 token 和输出 token 比例。
重试导致的额外 token。

例如某个 Workflow 改版后，平均输入 token 从 1000 增加到 8000。

接口仍然正常。

用户也可能没有马上反馈。

但成本已经明显异常。

所以 Token 不是附属信息。

它应该是 AI 应用的核心指标。

七、Tool 调用日志应该记录什么

Tool 调用让 Agent 具备行动能力。

但 Tool 也是风险点。

每一次 Tool 调用都应该可追踪。

Tool 调用日志可以记录：

trace_id：请求链路 ID。
tool_name：工具名称。
tool_version：工具版本。
permission_level：权限级别。
arguments_schema：参数结构。
latency_ms：执行耗时。
status：成功或失败。
error_type：错误类型。
result_size：结果大小。

例如：

{
  "trace_id": "req_001",
  "event": "tool_call_finished",
  "tool_name": "search_docs",
  "permission_level": "read_only",
  "latency_ms": 320,
  "status": "success"
}

注意，不要随意记录完整参数。

比如文件路径、用户输入、业务 ID、接口返回，都可能包含敏感信息。

更稳妥的做法是记录参数结构和脱敏后的关键字段。

Tool 日志的目标不是把所有内容打出来。

而是让开发者能知道工具有没有被调用、调用是否成功、耗时多少、失败在哪里。

八、RAG 检索也需要日志

RAG 系统里，模型回答不好，问题不一定在模型。

很可能是检索阶段出了问题。

例如：

没有检索到内容。
检索到了错误文档。
top_k 设置不合理。
相似度分数太低。
文档切片质量差。
过滤条件写错。

所以 RAG 检索也需要日志。

可以记录：

trace_id：请求链路 ID。
query_length：查询长度。
collection：知识库名称。
top_k：召回数量。
hit_count：命中数量。
score_range：相似度范围。
latency_ms：检索耗时。
rerank_used：是否使用重排。

例如：

{
  "trace_id": "req_001",
  "event": "retrieval_finished",
  "collection": "product_docs",
  "top_k": 5,
  "hit_count": 5,
  "latency_ms": 180
}

如果需要记录命中文档，也建议记录文档 ID、chunk ID 和分数。

不要默认记录完整原文内容。

九、Workflow 节点状态要能追踪

复杂 AI 应用通常不是一次模型调用。

它可能包含多个 Workflow 节点。

例如：

load_memory
retrieve_docs
build_prompt
call_llm
parse_answer
call_tool
finalize_response

每个节点都应该有开始、结束、失败日志。

例如：

{
  "trace_id": "req_001",
  "event": "workflow_node_finished",
  "workflow": "rag_workflow",
  "node": "retrieve_docs",
  "status": "success",
  "latency_ms": 210
}

这样当用户说结果慢时，可以看到慢在检索、模型、Tool，还是最终处理。

当结果错误时，也可以看是哪个节点开始偏离。

Workflow 可观测性的关键，是把黑盒流程拆成可追踪节点。

十、Agent step 也要能复盘

Agent 的问题往往更难排查。

因为 Agent 不是固定流程。

它可能根据上下文动态决定下一步。

所以 Agent step 需要记录。

可以记录：

trace_id：请求链路 ID。
agent_name：Agent 名称。
step_index：步骤序号。
thought_type：步骤类型。
selected_tool：选择的工具。
decision_status：决策状态。
latency_ms：步骤耗时。

例如：

{
  "trace_id": "req_001",
  "event": "agent_step",
  "agent_name": "research_agent",
  "step_index": 3,
  "selected_tool": "search_docs",
  "decision_status": "tool_call"
}

这里要注意：

不一定要记录完整推理过程。

很多场景只需要记录可审计的决策摘要。

例如选择了哪个 Tool、为什么进入某个分支、当前步骤是否成功。

这样既能复盘，又能降低敏感信息和冗余日志风险。

十一、错误日志要分层

AI 应用错误不能只分成成功和失败。

更合理的做法是分层。

例如：

config_error：配置错误。
llm_error：模型调用错误。
retrieval_error：检索错误。
tool_error：工具调用错误。
workflow_error：流程错误。
validation_error：参数校验错误。
permission_error：权限错误。
rate_limit_error：限流错误。
timeout_error：超时错误。

这样做的好处是：

报警更准确。

统计更清楚。

排查路径更短。

例如都是失败，但模型限流和 Tool 参数错误完全是两类问题。

前者可能要调整重试、降级或额度。

后者可能要修 schema、Prompt 或参数校验。

错误日志越清晰，线上恢复越快。

十二、日志必须脱敏

日志不是越详细越好。

尤其是 AI 应用，输入输出里很容易包含敏感信息。

不能直接记录的内容包括：

API Key。
Token。
密码。
验证码。
身份证号。
手机号。
邮箱。
支付信息。
用户隐私内容。
原始大文件全文。

所以需要 Redactor，也就是脱敏模块。

例如：

class Redactor:
    def redact(self, text: str) -> str:
        text = self.mask_api_keys(text)
        text = self.mask_phone_numbers(text)
        text = self.mask_emails(text)
        return text

在写日志之前先脱敏。

在保存 Prompt 或 Response 之前也要脱敏。

日志系统不能成为隐私泄露的入口。

十三、AI Scaffold 里的可观测性模块

在 AI Scaffold 中，可以把可观测性作为独立模块。

项目结构可以这样设计：

app/
├── observability/
│   ├── __init__.py
│   ├── logger.py
│   ├── tracing.py
│   ├── metrics.py
│   ├── events.py
│   ├── redactor.py
│   └── exporters.py
├── llm/
│   └── client.py
├── tools/
│   └── registry.py
├── workflows/
│   └── rag_workflow.py
├── agents/
│   └── assistant_agent.py
└── config/
    └── settings.py

其中：

logger.py 负责结构化日志。

tracing.py 负责 trace_id 和链路追踪。

metrics.py 负责统计指标。

events.py 定义 AI 应用里的事件类型。

redactor.py 负责敏感信息脱敏。

exporters.py 负责对接外部日志平台或监控系统。

LLM、Tool、Workflow、Agent 都不应该各写一套日志逻辑。

它们应该统一发事件。

由 observability 模块负责记录、脱敏和导出。