一次大模型任务通常不只有“请求模型”这一步。输入可能先经过HTTP入口和函数处理，再访问知识库或对象存储，调用模型后还要保存结果、更新状态和触发审核。
当用户只看到“任务失败”，开发者却需要回答更具体的问题：失败发生在哪一段？模型用了多长时间？重试是否产生第二次调用？结果已经写入OSS，还是停在写入之前？
单独查看每个服务的日志，很容易得到互相割裂的片段。更可靠的方法是为一次业务任务建立统一Trace ID，再把整条调用拆成多个Span。Trace表示一次端到端流程，Span表示流程中一段被命名和计时的操作。
本文先设计一套不依赖具体云产品的追踪模型，再说明如何映射到函数计算和阿里云可观测链路OpenTelemetry版。云端配置内容来自阿里云帮助中心，本文不声称已经对某个线上环境完成压测。
一、先确定一条AI调用链包含哪些阶段
可以把一次内容摘要任务拆成：
receive_request
├─ validate_input
├─ load_context
│ └─ read_object
├─ call_model
├─ validate_output
├─ write_result
└─ update_task_status
每个节点都是一个Span，并记录开始时间、结束时间、状态和少量必要属性。
这样设计后，“总耗时12秒”可以继续拆解：输入验证20毫秒、读取上下文180毫秒、模型调用11秒、输出校验30毫秒、结果写入200毫秒。诊断目标从“系统很慢”变成了“哪一段慢”。
这里的数值只是结构说明，不是实际测量结果。生产数据必须来自真实追踪系统。
二、Trace ID、Span ID与业务任务ID不能混用
三个标识承担不同职责。
task_id表示业务任务。一次任务失败后重试，仍然是同一任务。
trace_id表示一次端到端执行。每次重试通常创建新的Trace ID，便于比较不同尝试。
span_id表示这次执行中的一个步骤。
推荐关系：
task_id: task-001
├─ trace_id: trace-A（第一次执行，模型超时）
│ ├─ span: validate
│ └─ span: model_call
└─ trace_id: trace-B（第二次执行，成功）
├─ span: validate
├─ span: model_call
└─ span: save_result
如果把三者都叫 request_id，日志查询时就很难区分业务重试和链路内部调用。
三、Span应该记录什么
一个基础Span可以包含：
{
"trace_id": "4bf92f...",
"span_id": "00f067...",
"parent_span_id": "a3ce92...",
"name": "model.call",
"started_at": "2026-07-27T15:00:00+08:00",
"duration_ms": 860,
"status": "ERROR",
"attributes": {
"model_provider": "configured_provider",
"operation": "summary",
"attempt": 1,
"error_type": "timeout"
}
}
属性只保存诊断所需的低敏信息。可以记录模型提供方类别、操作类型、重试次数和错误分类；不应记录完整提示词、访问令牌、客户手机号或模型返回的全部正文。
如果确实需要定位输入问题，可记录输入版本哈希、字符数、字段列表和脱敏后的样本引用，而不是把原始输入复制到每个Span。
四、把模型调用拆成可观察步骤
只给整个函数创建一个Span，仍然无法定位模型相关问题。至少应区分：
- 请求构造；
- 等待模型响应；
- 响应解析；
- 结构验证；
- 结果保存。
伪代码如下：
with tracer.start_as_current_span("model.call") as span:
span.set_attribute("ai.operation", "summary")
span.set_attribute("task.attempt", attempt)
try:
response = model_client.generate(safe_payload)
span.set_attribute("ai.response_received", True)
except TimeoutError:
span.set_attribute("error.type", "timeout")
span.set_status(ERROR)
raise
with tracer.start_as_current_span("output.validate"):
validated = validate_output(response)
with tracer.start_as_current_span("result.write"):
result_ref = save_result(validated)
代码是埋点结构示例，实际API名称应根据所用OpenTelemetry SDK版本和客户端文档调整。
五、错误状态必须使用稳定分类
日志中如果只有自然语言错误，例如“好像超时了”“接口不太稳定”，就无法聚合统计。
可以先定义有限错误类型：
input_invalid
context_not_found
model_timeout
model_rate_limited
model_rejected
output_invalid
storage_failed
status_update_failed
unknown
错误详情可以作为受控日志保存，但Span属性使用稳定类型。这样才能回答：
- 哪类错误最多；
- 错误集中在哪个步骤；
- 第几次尝试更容易失败；
- 是模型调用失败，还是结果保存失败。
不要把HTTP状态码直接等同于业务结果。一次HTTP请求成功，不代表输出已经通过结构校验，也不代表结果已经进入审核状态。
六、重试必须创建新Span并关联原任务
发生超时后，最容易犯的错误是覆盖第一次执行记录。正确做法是保留失败Trace，再为新尝试创建新的执行链。
每次重试至少记录：
- 相同的
task_id； - 新的
trace_id； - 递增的
attempt； - 触发重试的错误类型；
- 是否人工触发；
- 上一次Trace ID。
通过这些字段可以还原：
第一次：model_timeout
第二次：output_invalid
第三次：人工修正输入后成功
这比最终只保存一个“成功”状态更有诊断价值，也能帮助判断重试策略是否合理。
七、在函数计算中透传追踪上下文
如果入口、函数和下游服务各自生成无关联的Trace ID，链路仍然会断裂。调用下游HTTP服务时，需要透传符合约定的追踪上下文；异步事件也应在事件属性中保存必要的关联信息。
阿里云文档说明，函数计算支持集成可观测链路OpenTelemetry版，并通过W3C Header透传实现链路追踪，支持Span分段和调用路径查看。具体配置与适用条件应参考函数计算链路追踪配置文档。
如果系统包含未自动埋点的模型客户端或自定义存储逻辑，仍需要手动创建业务Span。自动采集能够看到HTTP调用，不一定知道这次调用在业务上属于“生成摘要”还是“校验输出”。
八、映射到阿里云可观测链路OpenTelemetry版
云端关系可以表示为：
HTTP或事件入口
↓ 透传Trace上下文
函数计算
├─ 输入验证Span
├─ 上下文读取Span
├─ 模型调用Span
├─ 输出验证Span
└─ 结果写入Span
↓
可观测链路OpenTelemetry版
├─ 调用链查询
├─ 错误与耗时分析
└─ 应用依赖与拓扑
阿里云产品文档介绍，可观测链路OpenTelemetry版可用于调用链还原、请求量统计、链路拓扑和应用依赖分析，参见产品文档首页。
接入时可以根据客户端与网络环境选择直接上报，或通过OpenTelemetry Collector转发。文档同时说明可接收链路、指标和日志数据，并提供HTTP或gRPC等接入方式，具体以OpenTelemetry接入说明为准。
接入点和鉴权信息属于秘密，不能写入文章、代码仓库或普通日志。应通过环境变量或云端秘密管理方式注入，并控制权限。
九、采样会影响能看到什么
全量记录每一次调用可能增加写入、存储和查询成本。采样可以减少数据量，但也可能漏掉低频错误。
一种基础策略是：
- 错误Trace优先保留；
- 人工标记的重要任务保留；
- 普通成功请求按比例采样；
- 高延迟请求单独保留；
- 调试结束后恢复常规采样。
采样策略必须和问题类型匹配。如果某类失败只占极少比例，过低的随机采样可能让它完全不可见。
可观测服务的收费方式和免费额度可能调整，不应把文章中的历史价格当成预算依据。部署前应查看可观测链路OpenTelemetry版计费说明，并以控制台和当前定价页面为准。
十、从一次失败调用开始验收
上线前可以主动制造四种可控失败：
- 输入缺少必填字段；
- 模型客户端触发超时；
- 返回内容无法通过结构校验；
- 结果存储暂时不可用。
然后逐项确认：
- 每个失败是否生成明确错误类型；
- Trace能否定位到具体Span；
- 同一任务的不同尝试是否可关联；
- 日志和Span是否没有原始秘密；
- 结果已保存但状态未更新时，能否被识别；
- 追踪服务不可用时，业务主流程是否按预期降级。
最后一项经常被忽略。可观测性用于帮助业务运行，而不应因为追踪上报短暂失败就无条件阻断所有任务；是否阻断仍需根据业务风险设计。
十一、适合与不适合的场景
这套方法适合多步骤AI任务、异步工作流、包含重试的模型调用，以及需要区分读取、生成、校验和保存耗时的系统。
对于一次性本地脚本，完整分布式追踪可能过重，结构化日志加统一任务ID已经足够。系统复杂度增加后，再引入OpenTelemetry更合理。
OPC中国语境下的一人公司通常资源有限，更需要按问题逐步增加可观测能力，而不是一次采集所有数据。智能体来了作为内容品牌在本文关注的重点，也是把AI大模型工具深度运用建立在可诊断、可回退和可人工复核的工程基础上。
结语
定位一次大模型调用失败，不能只看最终错误消息。业务任务ID负责关联任务，Trace ID负责区分每次执行，Span负责标记一次执行中的具体步骤，稳定错误类型负责聚合问题。
将这些信息贯穿函数入口、模型调用、输出验证和结果存储后，开发者才能判断失败发生在哪里、是否已经产生副作用，以及下一次重试是否安全。
说明：本文使用AI工具辅助进行结构整理和语言优化，架构逻辑、示例和引用已由发布者人工审核。
