Harness 与 Agent 工程 · 日志、监控与故障定位 · 2026-07-01

AI可观测性:Prompt、Tool Call、Trace、Token全链路追踪

AI系统为何时好时坏?从Prompt到Tool Call的全链路追踪,帮你精准定位问题,告别昂贵黑盒。

核心内容:

  1. AI系统监控的四大核心维度:Prompt、Tool Call、Trace、Token
  2. Prompt追踪的重要性与实现方法,实现问题精确定位
  3. 传统监控与AI可观测性的本质区别,构建完整监控体系

你的 AI 系统上线了,用户反馈「有时候好用,有时候不好用」。

你想排查问题,却发现:

这不是个例。这是 2026 年大多数 AI 系统的现状。

传统软件有成熟的监控体系(APM、日志、指标、链路追踪),但 AI 系统——特别是基于 LLM 的系统——有其独特的复杂性:

这就是为什么我们需要 AI 可观测性(AI Observability)。


什么是 AI 可观测性?

AI 可观测性不是简单的日志记录。它是理解 AI 系统内部状态和行为的完整能力。

类比传统软件:

AI 可观测性的 4 个核心维度:

  1. Prompt 追踪:记录和追踪所有 Prompt(包括动态生成的)
  2. Tool Call 追踪:监控 Agent 调用的所有外部工具
  3. Trace 链路追踪:完整的调用链路,从输入到输出
  4. 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 追踪的最佳实践

  1. 记录完整 Prompt:不要只记录用户输入,要记录最终发送给 LLM 的完整 Prompt(包括 system prompt、few-shot examples)

  2. 版本管理:Prompt 模板要有版本号,方便追踪哪个版本效果好

  3. A/B 测试追踪:在 metadata 中记录实验分组,方便后续分析

  4. 敏感信息脱敏:用户输入可能包含个人信息,记得脱敏后再记录


维度 2:Tool Call 追踪——你的 Agent 在「做」什么?

Agent 的工具调用链

2026 年的 AI Agent 不再是简单的「问答机器」。它们会:

一个 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 追踪的关键指标

  1. 成功率:工具调用的成功率应该 > 99%
  2. 延迟分布:P50、P95、P99 延迟,识别慢工具
  3. 错误类型分布:哪些工具最容易出错?
  4. 调用频率:哪些工具被调用最多?是否有优化空间?

工具调用的常见陷阱

陷阱 表现 解决方案
工具超时 Agent 卡在某个工具调用 设置超时 + 重试机制
工具幻觉 Agent 调用不存在的工具 工具注册表 + 严格校验
工具滥用 简单任务调用过多工具 优化工具选择逻辑
工具依赖 工具 A 失败导致工具 B 也失败 记录依赖关系 + 级联错误处理

维度 3:Trace 链路追踪——完整的「故事线」

什么是 Trace?

Trace 是一次完整用户请求的全部调用链路。

类比:

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 的核心价值

  1. 问题定位:用户说「响应太慢」,Trace 告诉你慢在哪个环节
  2. 性能优化:发现哪个 Span 耗时最长,针对性优化
  3. 成本分析:每次请求花了多少 Token,哪些 Prompt 最贵
  4. 质量评估:对比成功和失败的 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…

— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/LargeLanguageModel/2026070129568.html