你的 AI 系统上线了,用户反馈「有时候好用,有时候不好用」。
你想排查问题,却发现:
- Prompt 是什么?不知道,没记录
- 调了哪些工具?不知道,没日志
- 完整调用链路?不知道,黑盒
- Token 花了多少钱?月底账单才知道
这不是个例。这是 2026 年大多数 AI 系统的现状。
传统软件有成熟的监控体系(APM、日志、指标、链路追踪),但 AI 系统——特别是基于 LLM 的系统——有其独特的复杂性:
- 不确定性:同样的输入,可能产生不同的输出
- 多步骤:一个用户请求可能触发 10+ 次 LLM 调用
- 工具链:Agent 会调用外部 API、数据库、搜索引擎
- 成本不透明:Token 消耗、API 调用费用难以预估
这就是为什么我们需要 AI 可观测性(AI Observability)。
什么是 AI 可观测性?
AI 可观测性不是简单的日志记录。它是理解 AI 系统内部状态和行为的完整能力。
类比传统软件:
- 传统 APM:监控 HTTP 请求 → 数据库查询 → 响应
- AI 可观测性:监控用户输入 → Prompt → LLM 调用 → Tool Call → 多轮推理 → 最终输出
AI 可观测性的 4 个核心维度:
- Prompt 追踪:记录和追踪所有 Prompt(包括动态生成的)
- Tool Call 追踪:监控 Agent 调用的所有外部工具
- Trace 链路追踪:完整的调用链路,从输入到输出
- Token 追踪:Token 消耗、成本、延迟的实时监控这 4 个维度缺一不可。缺任何一个,你的 AI 系统就是一个「昂贵的黑盒」。
维度 1:Prompt 追踪——你的 AI 在「想」什么?
为什么 Prompt 追踪如此重要?
一个典型的 AI 应用,一次用户请求可能生成多个 Prompt:
用户输入:"帮我写一封邮件" ↓ Prompt 1: 意图识别(判断用户想做什么) ↓ Prompt 2: 上下文检索(从知识库找相关信息) ↓ Prompt 3: 邮件生成(根据意图和上下文生成邮件) ↓ Prompt 4: 质量检查(检查邮件是否符合要求) ↓ 最终输出:一封完整的邮件如果最终输出的邮件有问题,你如何定位是哪个 Prompt 出了问题?
没有 Prompt 追踪,你只能猜测。有了 Prompt 追踪,你可以精确定位。
Prompt 追踪的核心要素
每个 Prompt 应该记录:
prompt_trace: id: "prompt_abc123" # 唯一标识 timestamp: "2026-06-18T10:23:45Z" parent_id: "trace_xyz789" # 所属的 Trace ID
Prompt 内容
system_prompt: "你是一个专业的邮件助手..." user_prompt: "用户原始输入" full_prompt: "最终发送给 LLM 的完整 Prompt"
模型调用
model: "gpt-5.5" temperature: 0.7 max_tokens: 2000
LLM 响应
response: "LLM 的完整输出" finish_reason: "stop" # 或 "length"、"content_filter"
性能指标
latency_ms: 1234 tokens_input: 850 tokens_output: 420
上下文
metadata: user_id: "user_12345" session_id: "session_67890" feature_flag: "new_email_template_v2"
实战:用 Langfuse 实现 Prompt 追踪
Langfuse 是目前最流行的开源 AI 可观测性平台。下面是一个完整的示例:
from langfuse import Langfuse from openai import OpenAI
初始化
langfuse = Langfuse( public_key="pk-lf-...", secret_key="sk-lf-...", host="https://cloud.langfuse.com" ) openai = OpenAI()
def generate_email(user_input: str, user_id: str):
创建 Trace
trace = langfuse.trace( name="email_generation", user_id=user_id, metadata={"source": "web"} )
追踪 Prompt 1: 意图识别
span1 = trace.span(name="intent_detection") intent_prompt = f"判断用户意图:{user_input}"
response1 = openai.chat.completions.create( model="gpt-5.5", messages=[{"role": "user", "content": intent_prompt}] )
span1.end( output=response1.choices[0].message.content, metadata={ "tokens_input": response1.usage.prompt_tokens, "tokens_output": response1.usage.completion_tokens } )
intent = response1.choices[0].message.content
追踪 Prompt 2: 邮件生成
span2 = trace.span(name="email_drafting") email_prompt = f"根据意图 '{intent}' 生成邮件"
response2 = openai.chat.completions.create( model="gpt-5.5", messages=[{"role": "user", "content": email_prompt}] )
span2.end( output=response2.choices[0].message.content, metadata={ "tokens_input": response2.usage.prompt_tokens, "tokens_output": response2.usage.completion_tokens } )
email = response2.choices[0].message.content
记录最终输出
trace.update( output=email, metadata={"total_spans": 2} )
return email
Prompt 追踪的最佳实践
-
记录完整 Prompt:不要只记录用户输入,要记录最终发送给 LLM 的完整 Prompt(包括 system prompt、few-shot examples)
-
版本管理:Prompt 模板要有版本号,方便追踪哪个版本效果好
-
A/B 测试追踪:在 metadata 中记录实验分组,方便后续分析
-
敏感信息脱敏:用户输入可能包含个人信息,记得脱敏后再记录
维度 2:Tool Call 追踪——你的 Agent 在「做」什么?
Agent 的工具调用链
2026 年的 AI Agent 不再是简单的「问答机器」。它们会:
- 搜索互联网获取实时信息
- 调用 API 查询数据库
- 执行代码进行计算
- 操作浏览器完成复杂任务
一个 Agent 任务可能调用 5-20 个工具。如果没有追踪,你根本不知道它在做什么。
Tool Call 追踪的核心要素
tool_call_trace: id: "tool_call_def456" timestamp: "2026-06-18T10:23:46Z" parent_id: "span_abc123" # 所属的 Span
工具信息
tool_name: "web_search" tool_version: "2.1.0"
调用参数
input: query: "2026年AI市场规模" num_results: 5 date_range: "last_month"
工具响应
output: success: true results: [ {"title": "...", "url": "...", "snippet": "..."},
... 更多结果
] result_count: 5
性能指标
latency_ms: 890 retries: 0
错误信息(如果有)
error: null
上下文
metadata: cache_hit: false rate_limited: false
实战:追踪 Agent 的工具调用
from langfuse import Langfuse from typing import Callable, Any
langfuse = Langfuse()
def tracked_tool_call(trace, tool_name: str, func: Callable, **kwargs): """装饰器:自动追踪工具调用"""
创建 Span
span = trace.span( name=f"tool_call:{tool_name}", input=kwargs )
try:
执行工具
result = func(**kwargs)
记录成功
span.end( output=result, metadata={"success": True} )
return result
except Exception as e:
记录失败
span.end( output=None, metadata={ "success": False, "error_type": type(e).name, "error_message": str(e) } ) raise
使用示例
def search_web(query: str, num_results: int = 5):
实际的搜索逻辑
return {"results": [...], "count": num_results}
在 Agent 中调用
trace = langfuse.trace(name="research_agent")
results = tracked_tool_call( trace, "web_search", search_web, query="AI market size 2026", num_results=5 )
Tool Call 追踪的关键指标
- 成功率:工具调用的成功率应该 > 99%
- 延迟分布:P50、P95、P99 延迟,识别慢工具
- 错误类型分布:哪些工具最容易出错?
- 调用频率:哪些工具被调用最多?是否有优化空间?
工具调用的常见陷阱
| 陷阱 | 表现 | 解决方案 |
|---|---|---|
| 工具超时 | Agent 卡在某个工具调用 | 设置超时 + 重试机制 |
| 工具幻觉 | Agent 调用不存在的工具 | 工具注册表 + 严格校验 |
| 工具滥用 | 简单任务调用过多工具 | 优化工具选择逻辑 |
| 工具依赖 | 工具 A 失败导致工具 B 也失败 | 记录依赖关系 + 级联错误处理 |
维度 3:Trace 链路追踪——完整的「故事线」
什么是 Trace?
Trace 是一次完整用户请求的全部调用链路。
类比:
- 传统软件:一个 HTTP 请求 → 多个微服务调用 → 数据库查询 → 响应
- AI 系统:一个用户输入 → 多个 Prompt → 多次 LLM 调用 → 多个 Tool Call → 最终输出
Trace 让你看到完整的「故事线」,而不是零散的片段。
Trace 的层级结构
Trace: 用户请求 "帮我分析这个 CSV 文件" ├── Span 1: 意图识别 │ ├── LLM Call: GPT-5.5 (234ms, 850 tokens) │ └── Output: "用户想分析 CSV 数据" ├── Span 2: 文件读取 │ ├── Tool Call: file_reader (45ms) │ └── Output: CSV 内容 (1000 行) ├── Span 3: 数据分析 │ ├── LLM Call: GPT-5.5 (1.2s, 2100 tokens) │ ├── Tool Call: python_executor (890ms) │ └── Output: 统计结果 + 图表 ├── Span 4: 报告生成 │ ├── LLM Call: GPT-5.5 (1.8s, 3200 tokens) │ └── Output: 完整分析报告 └── Span 5: 结果格式化 ├── LLM Call: GPT-5.5 (456ms, 1200 tokens) └── Output: 最终响应
总计:4 次 LLM 调用,2 次工具调用,总延迟 4.6s,总 Token 7350
Trace 的核心价值
- 问题定位:用户说「响应太慢」,Trace 告诉你慢在哪个环节
- 性能优化:发现哪个 Span 耗时最长,针对性优化
- 成本分析:每次请求花了多少 Token,哪些 Prompt 最贵
- 质量评估:对比成功和失败的 Trace,找出差异
实战:构建完整的 Trace
from langfuse import Langfuse import time
langfuse = Langfuse()
def analyze_csv(user_input: str, file_path: str, user_id: str):
创建 Trace
trace = langfuse.trace( name="csv_analysis", user_id=user_id, metadata={ "input": user_input, "file_path": file_path } )
start_time = time.time()
Span 1: 意图识别
with trace.span(name="intent_detection") as span1: intent = detect_intent(user_input) span1.update(output=intent)
Span 2: 文件读取
with trace.span(name="file_reading") as span2: csv_data = read_csv_file(file_path) span2.update( output={"rows": len(csv_data), "columns": len(csv_data.columns)}, metadata={"file_size_mb": get_file_size(file_path)} )
Span 3: 数据分析
with trace.span(name="data_analysis") as span3: analysis_prompt = f"分析以下数据:\n{csv_data.head()}" analys…