必须手动设置请求头X-Request-ID并从响应头提取该值，用于全链路追踪：客户端传入合法UUID，服务端透传并写入日志；响应后立即持久化该ID，再通过APM Plus输入该ID搜索Trace定位问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在火山引擎上排查模型调用失败、延迟高或结果异常时，必须能准确定位某一次具体请求——这依赖于每次调用都携带且返回一个全局唯一、贯穿全链路的请求标识。没有它，日志分散、监控断点、问题复现无从谈起。
确认请求中已携带 X-Request-ID（客户端侧）
向火山引擎模型服务（如 Chat API、LLM 接口）发起 HTTP 请求时，【必须手动设置请求头 X-Request-ID】，值为符合 RFC 7231 的合法 UUID 字符串（如 550e8400-e29b-41d4-a716-446655440000）。该字段不参与签名计算，但会被服务端完整透传并写入所有下游组件日志。
若未显式设置，服务端将自动生成一个 ID，但你无法在客户端侧主动关联，导致调试时丢失起点。
使用 curl 示例：
curl -X POST https://ark.cn-beijing.volces.com/api/v1/chat/completions \
-H "X-Request-ID: 7a2b3c4d-8e9f-11ec-b909-0242ac120002" \
-H "Authorization: Bearer your_token" \
-d '{"messages":[{"role":"user","content":"你好"}]}'
从响应头提取并持久化 Request-ID（服务端侧）
火山引擎模型接口成功响应后，【务必从响应头中读取 X-Request-ID 字段】，而非解析响应体中的任何字段。该值与你在请求头中传入的完全一致（若传入），或为服务端生成的 UUID（若未传入）。
例如在 Python requests 中获取：
response = requests.post(url, headers=headers, json=payload)
request_id = response.headers.get("X-Request-ID")
拿到后立即写入本地业务日志、数据库记录或消息队列上下文，确保与本次请求的输入、输出、耗时、错误码强绑定。
在链路追踪系统中定位该请求
第一步：登录火山引擎控制台 → 进入「应用性能监控 APM Plus」→ 选择对应工作区。
第二步：点击「链路追踪」→ 在搜索框中粘贴你记录的 【X-Request-ID 值】 → 点击搜索。
第三步：命中后展开 Trace，查看 Span 列表：最顶层 Span 的 operationName 为 `chat.completions` 或 `llm.invoke`，其 tags 中包含 `http.status_code`、`llm.model_name`、`duration_ms` 等关键指标。
第四步：点击任意 Span 查看详情，可下钻到日志聚合、指标趋势、上下游依赖拓扑。
注意：若搜索不到，说明该请求未进入 APM 数据采集路径——检查是否已为对应服务部署 apmplus-server-agent 组件，且版本 ≥ v1.12.0。
