LLM 应用为什么必须有 trace:一次对话里的五次模型调用

举报
yd_232401777 发表于 2026/11/01 07:41:23 2026/11/01
【摘要】 用日志排查 LLM 应用,很快就会撞墙:一次用户提问背后可能是五次模型调用、三次检索、两个工具,日志里全是散落的行,你分不清哪一行属于哪一次请求。更麻烦的是延迟和成本——你知道总耗时 8 秒,但不知道这 8 秒里检索占多少、首 token 占多少、工具占多少。这篇讲 trace 该怎么埋:span 怎么切、属性怎么记、采样为什么不能用固定比例、prompt 到底该不该存。

前言

一个 Agent 应用最开始的日志大概长这样:

[INFO] 收到请求 q="帮我查下上周的销售数据"
[INFO] 检索命中 5 条
[INFO] 调用模型 model=gpt-4o tokens=1200
[INFO] 工具调用 query_db
[INFO] 调用模型 model=gpt-4o tokens=2400
[INFO] 返回

单用户测试时够用。一旦并发上来,这堆日志就废了——20 个用户同时在问,日志交错在一起,你没法把"检索命中 5 条"和"调用模型 tokens=1200"对应到同一个请求上。

更根本的问题是:日志是扁平的,而 LLM 应用天然是树状的。

一次提问会展开成一棵调用树:

用户请求
├── 改写查询(LLM 调用 1)
├── 向量检索
│   └── embedding 调用
├── 重排(LLM 或 cross-encoder)
├── 生成回答(LLM 调用 2)
│   ├── 工具调用:查数据库
│   └── 生成回答(LLM 调用 3,带工具结果)
└── 后处理

要回答"这次为什么慢""这次为什么贵",必须有这棵树。日志给不了,trace 可以。

一、span 该怎么切

切 span 的原则只有一条:一个 span 对应一次你可能想单独度量的操作。

对 LLM 应用,粒度大致是这样:

层级span 名代表什么关键看什么
根invoke_agent一次完整的用户请求端到端耗时、是否成功
中层chat一次模型调用首 token 延迟、token 数、模型名
中层retrieve一次检索召回条数、耗时、索引名
中层execute_tool一次工具调用工具名、是否失败、耗时
叶embeddings一次向量化条数、维度、耗时

关键在于中层 span 必须能反映"决策点"。比如一个 Agent 一次请求里调了 5 次 LLM(思考→调工具→再思考→再调工具→总结),那就该有 5 个 chat span,而不是一个把 5 次都盖住的 span。否则你没法回答"是第几次调用慢"。

同理,检索如果是"多路召回再融合",每一路都应该有独立 span——这样才知道是哪一路拖慢了整体。

二、属性记什么:对齐语义约定,别自己发明名字

OpenTelemetry 有一套 GenAI 语义约定(semantic conventions),专门规定 LLM 相关的属性和 span 名。主要属性:

属性含义例子
gen_ai.operation.name操作类型chat / embeddings / execute_tool
gen_ai.provider.name模型提供方openai / anthropic / huaweicloud
gen_ai.request.model请求的模型gpt-4o-mini
gen_ai.response.model实际响应的模型gpt-4o-mini-2024-07-18
gen_ai.usage.input_tokens输入 token1200
gen_ai.usage.output_tokens输出 token340
gen_ai.response.finish_reasons结束原因["stop"]

为什么要用约定名而不是自己起名:因为你迟早要接现成的观测平台(Langfuse、Phoenix、或者华为云 APM 这类)。用了约定名,面板、聚合、告警都能直接用;自己起 llm.tokens_in 这种名字,等于每次换平台都要重写一遍查询。

⚠️ 需要说明的是,这套语义约定目前仍在演进。比如早期的 gen_ai.system 后来被建议改为 gen_ai.provider.name。实际落地时以你使用的 SDK 版本为准,别硬抄网上过期的文档。

除了约定属性,下面几个是业务侧的必需项:

属性为什么必须
session.id把多轮对话串起来,看"第 3 轮为什么效果变差"
user.id(脱敏后)定位"只有某个用户出问题"这类反馈
agent.name多 Agent 系统里区分是哪个 Agent
retrieval.top_k / retrieval.hit_count检索效果出问题时,这是第一个要看的数

三、采样的坑:按比例采样会把证据丢掉

观测平台都按采样存数据,成本考虑。而默认的固定比例采样,在 LLM 应用里是错的。

原因:出问题的请求往往只占极少数。固定采 10%,意味着 90% 的失败链路你看不到。而失败链路恰恰是你唯一想看的东西。

正确做法是 tail sampling(尾部采样):先全量接收 span,等一条 trace 结束后再决定要不要丢。

典型策略:

policies:
  - type: status_code          # 出错的全留
    status_code: { status_codes: [ERROR] }
  - type: latency              # 慢的留(比如 > 5s)
    latency: { threshold_ms: 5000 }
  - type: string_attribute     # 特定用户/会话全留
    string_attribute: { key: user.id, values: ["u_debug"] }
  - type: probabilistic        # 剩下的按比例采
    probabilistic: { sampling_percentage: 5 }

顺序有意义:先保住异常,再对正常流量降采样。

代价是需要在收集端缓存整条 trace 一段时间(等它结束),内存开销比 head sampling 大。对 LLM 应用来说这笔开销值得——它换来了"每次事故都有完整现场"。

四、prompt 和 completion 到底存不存

这是落地时最纠结的问题。

存的好处:能复现。"用户说回答不对",你打开 trace 看到当时的 prompt 和模型输出,三分钟定位。不存的话只能猜。

存的代价:

代价具体影响
体积一条 trace 可能几十 KB 到几百 KB,存储成本是普通 API 的十倍以上
合规prompt 里可能有用户隐私、内部数据,存下来就受数据留存政策约束
泄露观测平台往往权限更松,等于多了一个数据出口

三条可选的折中路线:

路线 A:只存摘要。记录 prompt_hash、字符数、token 数、前 200 字符。能做基线对比("这条 prompt 最近变长了"),但不能复现内容。

路线 B:按开关存。生产默认不存,出问题时打开采样率 100% 重跑一段时间。需要能快速改配置。

路线 C:加密存 + 短留存。加密入库,保留 7 天,只给值班人解密权限。

实践中比较合理的组合:结构化摘要常存(路线 A)+ 内容在异常时存(配合 tail sampling 的错误策略)。正常请求只留元数据,出错的请求把完整 prompt 留下来。这样存储成本可控,而真正需要看的场景都有数据。

五、埋点代码

下面是一段手动埋点的骨架,用 Python + OpenTelemetry。核心是父子关系靠 context 自动传播,不要手动指定 parent。

import json
from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

tracer = trace.get_tracer("agent.llm")


def hash_short(text: str) -> str:
    import hashlib
    return hashlib.sha256(text.encode()).hexdigest()[:16]


def invoke_agent(question: str, session_id: str, user_id: str):
    with tracer.start_as_current_span("invoke_agent") as span:
        span.set_attribute("gen_ai.operation.name", "invoke_agent")
        span.set_attribute("session.id", session_id)
        span.set_attribute("user.id", user_id)       # 传进来之前先脱敏

        try:
            rewritten = rewrite_query(question, session_id)
            docs = retrieve(rewritten, top_k=5)
            answer = generate(question, docs, session_id)
            span.set_status(Status(StatusCode.OK))
            return answer
        except Exception as e:
            span.set_status(Status(StatusCode.ERROR, str(e)[:200]))
            span.record_exception(e)
            raise


def chat(messages, model, temperature=0.2, stream=False):
    with tracer.start_as_current_span("chat") as span:
        span.set_attribute("gen_ai.operation.name", "chat")
        span.set_attribute("gen_ai.provider.name", "openai")
        span.set_attribute("gen_ai.request.model", model)
        span.set_attribute("gen_ai.request.temperature", temperature)
        span.set_attribute("llm.stream", stream)

        # 默认只记摘要;需要复现时打开内容记录
        prompt_text = json.dumps(messages, ensure_ascii=False)
        span.set_attribute("llm.prompt.hash", hash_short(prompt_text))
        span.set_attribute("llm.prompt.chars", len(prompt_text))
        if RECORD_CONTENT:                            # 配置开关
            span.set_attribute("llm.prompt.preview", prompt_text[:1000])

        resp = _real_chat_call(messages, model, temperature, stream)

        span.set_attribute("gen_ai.response.model", resp.model)
        span.set_attribute("gen_ai.usage.input_tokens", resp.usage.input_tokens)
        span.set_attribute("gen_ai.usage.output_tokens", resp.usage.output_tokens)
        span.set_attribute("gen_ai.response.finish_reasons", [resp.finish_reason])
        return resp


def retrieve(query: str, top_k: int = 5):
    with tracer.start_as_current_span("retrieve") as span:
        span.set_attribute("gen_ai.operation.name", "retrieve")
        span.set_attribute("retrieval.query", query[:200])
        span.set_attribute("retrieval.top_k", top_k)

        docs = _vector_search(query, top_k)

        span.set_attribute("retrieval.hit_count", len(docs))
        span.set_attribute("retrieval.index", "kb_v3")
        # 记录分数分布,判断"召回质量"而不只是"召回数量"
        if docs:
            span.set_attribute("retrieval.top_score", round(docs[0].score, 4))
            span.set_attribute("retrieval.min_score", round(docs[-1].score, 4))
        return docs


def execute_tool(name: str, args: dict):
    with tracer.start_as_current_span("execute_tool") as span:
        span.set_attribute("gen_ai.operation.name", "execute_tool")
        span.set_attribute("tool.name", name)
        span.set_attribute("tool.args.hash", hash_short(json.dumps(args, sort_keys=True)))
        try:
            result = _dispatch(name, args)
            span.set_attribute("tool.ok", True)
            return result
        except Exception as e:
            span.set_attribute("tool.ok", False)
            span.set_attribute("tool.error", str(e)[:200])
            span.set_status(Status(StatusCode.ERROR))
            raise

多层嵌套时不需要手动传 parent——start_as_current_span 会读当前 context:

answer = invoke_agent("上周销售怎么样", "s_001", "u_42")
#   自动形成:  invoke_agent
#                ├── chat(改写查询)
#                ├── retrieve
#                └── chat(生成)

六、从 trace 里能看出什么

埋好之后,几类问题变得可查:

现象trace 里的特征指向
答非所问retrieve 的 hit_count 正常但 top_score 很低检索质量,不是生成质量
有时快有时慢chat span 的耗时方差大模型侧波动 / 队列排队
越用越贵同一 session.id 下 input_tokens 逐轮增长上下文没做裁剪
工具总失败execute_tool 的 tool.ok=false 集中在某个工具工具参数校验或下游故障
只有个别用户出问题按 user.id 聚合,某些值异常权限、配额或数据隔离

第三行值得展开。多轮对话里 input_tokens 的增长曲线,是最容易被忽略的成本信号。 单看每条请求都不高,但一条会话聊到第 8 轮时,输入可能已经翻了五六倍——因为历史全带着。trace 上按 session.id 把 input_tokens 画成折线,一眼就能看出来。

做了什么

给现有的问答服务补了 trace:

  1. 按 invoke_agent / chat / retrieve / execute_tool 四类切 span,一次请求里多次 LLM 调用各自独立
  2. 属性统一用 gen_ai.* 语义约定名,业务侧补 session.id、user.id、retrieval.hit_count
  3. 采样改成 tail sampling:错误和慢请求全留,正常流量采 5%
  4. prompt 默认只存 hash + 长度 + 前 200 字符,配一个 RECORD_CONTENT 开关,排查时临时打开
  5. 检索 span 额外记 top_score / min_score,用来区分"没召回到"和"召回到但分数接近噪音"

第 5 点是意外收获。以前只知道"这题答得不好",现在能一眼看出来是召回为空、还是召回了一堆 0.3 分的噪音。

一些体会

日志和 trace 的分工要划清。 日志记录"发生了什么事件"(用户登录、配置变更),trace 记录"这次请求内部怎么走的"。把 prompt、token 这类信息塞进日志,最后会得到一堆无法关联的行。

span 粒度宁细勿粗。 粗的 span 只告诉你"慢",细的 span 告诉你"慢在哪一步"。多加几个 span 的成本,远低于事后靠猜排查的成本。

固定比例采样是 LLM 可观测性里最常见的错误。 它的前提是"错误均匀分布",而 LLM 应用恰恰相反——大部分请求顺利,少数请求以各种奇怪的方式失败,而你只想看那些少数。

content 存不存,本质不是技术问题而是数据治理问题。 决定要不要存之前,先回答:谁能看?留多久?用户要求删除时怎么删?这三个问题答不上来,先只存摘要。

最后一点:trace 的价值在于事后。真正上线时,至少配两条告警——错误率、P95 首 token 延迟。trace 负责告诉你"为什么",告警负责告诉你"现在有问题"。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。