知识全景图/ 软件工程与系统/ 人工智能全景图/ Request Trace / Observability / Debugging

LLM 请求 Trace、观测字段与排障模板全景图

把一次请求的输入、上下文、路由、生成、流式、工具、成本、风险和反馈记录成可复盘、可排障、可回流的证据链

阅读定位: 一次请求的一生回答请求如何穿过系统，生成运行时回答生成阶段如何排队、流式、停止和重试， LLMOps回答 Trace 如何进入评测、发布和运营闭环。本页专门补“请求证据模板”：一次请求到底应该记录哪些字段、怎样串成 Span、遇到慢 / 贵 / 错 / 断流 / 越权时怎样排障，以及哪些样本要回流；跨 Prompt、RAG、Tool、发布和事故的总索引见 AI 证据包索引。

一、Trace 不是日志堆积，而是请求证据链

Request
入口身份

→

Context
输入证据

→

Route
模型决策

→

Generation
运行时状态

→

Tool / RAG
外部事实

→

Output
结束原因

→

Feedback
回流闭环

证据层	记录对象	回答的问题	缺失后的后果
入口证据	request_id、tenant、user、session、feature、risk_tier	谁在什么场景发起了请求	无法分租户、分场景、分风险排查
输入证据	raw_input_hash、files、attachments、locale、task_type	用户真正给了什么输入	坏例不可复现，隐私数据难脱敏
上下文证据	prompt_version、rendered_prompt_hash、token_budget、dropped_segments	模型到底看到了什么	无法判断问题来自 Prompt、RAG 还是截断
路由证据	model_route、model_version、fallback_reason、sampling_config	请求为什么走这个模型和配置	模型升级、Fallback 和灰度问题不可追
运行证据	stage_timing、stream_events、finish_reason、retry_lineage	请求在哪里慢、断、超时或重试	只能说“模型慢”，不能定位阶段
外部证据	retrieval_results、tool_calls、permission_snapshot、side_effects	模型依据了哪些事实，做了哪些动作	幻觉、越权、重复执行和引用错误不可查
结果证据	output_hash、usage、cost、safety_labels、user_feedback	结果是否可用、成本多少、风险如何	无法进入 Eval、审计、回归和成本治理

二、最小字段模板：一次请求至少要留下什么

字段组	最小字段	建议粒度	用途
Identity	request_id、conversation_id、tenant_id、user_role、feature_id	请求级	定位入口、权限、租户和产品场景
Input	input_type、input_hash、attachment_ids、language、task_type	请求级	复现坏例和按任务切片评测
Context	prompt_version、chat_template_version、context_tokens、dropped_segments、rendered_prompt_hash	生成尝试级	排查上下文污染、截断、模板回归和 token 膨胀
Retrieval	query_rewrite_version、index_version、top_k、evidence_ids、rerank_scores	检索 Span	排查 RAG 漏召、错召、证据位置和知识版本
Routing	route_policy_version、model_id、provider、region、fallback_chain	生成尝试级	排查模型切换、供应商故障、灰度和成本差异
Runtime	queue_ms、prefill_ms、ttft_ms、decode_ms、tokens_per_second、finish_reason	生成尝试级	拆解慢、断流、超时和首 token 体验
Streaming	event_count、last_event_id、stream_error、client_cancelled、partial_output_hash	流式事件级	排查前端断流、重复片段、取消和恢复
Tools	tool_name、tool_schema_version、tool_status、idempotency_key、side_effect_committed	工具调用 Span	排查工具失败、越权、重复执行和补偿
Output	output_hash、structured_parse_status、citation_coverage、safety_labels	请求级	排查格式破损、引用缺失和安全策略命中
Usage	input_tokens、output_tokens、cache_hit、billable_units、cost_center	请求级	成本归因、预算治理和租户计费
Feedback	user_rating、review_label、error_taxonomy、eval_sample_id、incident_id	回流级	把线上坏例送进回归、审计和发布闸门

三、Trace 形态：请求、生成尝试、Span 和事件

Request

一个用户动作对应一个 request。它可能包含多次生成尝试、多个工具调用和多条流式事件。产品层排查通常先看 request。

Generation Attempt

一次实际模型生成。重试、Fallback、repair retry 和 continue 都应该产生新的 attempt，并用 retry_lineage 串起来。

Span / Event

检索、工具、排队、prefill、decode、stream delta、后处理都可以作为 Span 或 Event，方便定位阶段性问题。

层级	关系	示例	为什么要分开
request_id	一次产品请求	用户点击“生成周报”	用于用户体验、审计和最终结果归档
generation_id	一次模型生成尝试	第一次用大模型，失败后 Fallback 到小模型	用于区分重试、模型路由和运行时字段
span_id	链路中的阶段	RAG 检索、工具调用、模型 prefill、后处理	用于定位具体耗时和失败点
event_id	流式或状态事件	message_start、delta、heartbeat、message_end	用于重放前端体验、断流恢复和顺序校验

四、JSON 模板：字段要结构化，而不是散在日志里

{
  "request_id": "req_20260530_001",
  "conversation_id": "conv_42",
  "tenant_id": "tenant_a",
  "feature_id": "support_rag_answer",
  "risk_tier": "L2",
  "input": {
    "task_type": "rag_qa",
    "input_hash": "sha256:...",
    "language": "zh-CN",
    "attachments": []
  },
  "context": {
    "prompt_version": "support.answer.v17",
    "chat_template_version": "template.v5",
    "context_tokens": 6842,
    "token_budget": 12000,
    "dropped_segments": ["old_history:12", "low_score_doc:7"],
    "rendered_prompt_hash": "sha256:..."
  },
  "retrieval": {
    "index_version": "kb_2026_05_29",
    "query_rewrite_version": "qr.v3",
    "top_k": 8,
    "evidence_ids": ["doc_18#p4", "doc_21#p2"],
    "acl_filtered_count": 3
  },
  "generation_attempts": [
    {
      "generation_id": "gen_1",
      "model_id": "model_a",
      "route_policy_version": "route.v9",
      "sampling": {"temperature": 0.2, "max_output_tokens": 1200},
      "stage_timing": {
        "gateway_ms": 42,
        "context_ms": 128,
        "queue_ms": 310,
        "prefill_ms": 760,
        "ttft_ms": 1280,
        "decode_ms": 4200,
        "postprocess_ms": 95
      },
      "stream_events": {
        "event_count": 96,
        "last_event_id": "evt_96",
        "client_cancelled": false,
        "stream_error": null
      },
      "finish_reason": "stop",
      "retry_lineage": null,
      "usage": {
        "input_tokens": 6842,
        "output_tokens": 843,
        "cache_hit": true,
        "billable_units": 7685
      }
    }
  ],
  "output": {
    "output_hash": "sha256:...",
    "structured_parse_status": "ok",
    "citation_coverage": 0.86,
    "safety_labels": []
  },
  "feedback": {
    "user_rating": null,
    "review_label": null,
    "eval_sample_id": null,
    "incident_id": null
  }
}

模板不是越全越好，而是要能回答排障问题

字段如果不能用于复现、归因、审计、成本、评测或回滚，就很可能只是噪声。先保证关键字段稳定，再逐步扩展。

五、慢请求排障：先拆阶段，不要先换模型

现象	先看字段	可能根因	下一步动作
TTFT 高	gateway_ms、context_ms、queue_ms、prefill_ms、context_tokens	网关依赖慢、上下文装配慢、排队、长上下文 prefill	拆分时间段，压缩上下文，模型池分流，启用 Prompt Cache
总耗时高	decode_ms、output_tokens、tokens_per_second、tool_call_count	输出太长、decode 慢、工具串行、多轮 Agent 循环	限制输出预算，拆分任务，工具并行，减少循环步数
P99 飘高	pool_id、queue_ms、request_length_bucket、provider_region	长短请求混跑、区域抖动、供应商尾延迟	SLA 分池、区域切换、长请求隔离、熔断降级
流式首屏快但中途卡	stream_events、heartbeat_gap_ms、decode_tokens_per_second	后处理阻塞、网络缓冲、工具插入、batch 调度抖动	增加心跳，拆后处理，检查 SSE / WebSocket flush
用户取消后仍占资源	client_cancelled、cancel_stage、resource_released、billable_units	cancel signal 未传播，KV Cache 或工具未释放	补取消链路，记录释放状态，修正取消计费策略

六、错答案排障：先问模型看到了什么证据

现象	先看字段	可能根因	下一步动作
看似幻觉	evidence_ids、rerank_scores、citation_coverage、rendered_prompt_hash	没检到、检错、证据太靠后、引用与回答脱节	重放检索，调 Top-K / rerank，检查证据位置和引用校验
同问题前后答案不同	model_id、sampling、fallback_chain、prompt_version、context_hash	采样随机、Fallback、Prompt 变更、上下文不同	固定配置回放，比较 prompt diff，记录 retry_lineage
工具参数错	tool_schema_version、tool_call_delta、parse_error、repair_prompt_version	schema 描述不清、流式半截参数被执行、repair 改变语义	严格校验 message_end 后执行，加入工具参数 Eval
结构化输出破损	structured_parse_status、finish_reason、max_output_tokens、repair_retry_count	length 截断、schema 太复杂、采样不稳	缩短 schema，降低温度，增加 repair retry 和失败样本
安全误拒 / 漏拦	risk_tier、safety_labels、policy_version、review_label	策略版本变化、分类阈值不稳、场景标签错误	切片回放，人工校准，进入红队回归集

七、贵请求排障：成本要能归因到上下文、输出和重试

上下文成本

看 input_tokens、context_tokens、RAG top_k、history_tokens、dropped_segments。很多成本暴涨来自历史和证据越塞越多。

输出成本

看 output_tokens、finish_reason、max_output_tokens 和 continue 次数。长输出如果没有产品价值，就要压预算和结构。

重试成本

看 retry_count、retry_reason、fallback_chain、repair_retry_count。无退避重试会把一次失败变成三次账单。

成本问题	诊断字段	治理动作
单次请求过贵	input_tokens、output_tokens、model_id、billable_units	任务分级路由、小模型预处理、上下文预算、输出上限
某租户成本异常	tenant_id、feature_id、cost_center、request_count	租户配额、功能限流、异常告警和成本仪表盘
RAG 成本高	top_k、chunk_tokens、rerank_count、context_tokens	检索候选压缩、证据摘要、分层检索、缓存
Agent 成本高	step_count、tool_call_count、generation_attempts、max_steps	阶段预算、停止条件、计划审查、长任务检查点

八、断流、重试与恢复：前端体验也要能重放

问题	关键字段	排查方法	恢复策略
流式重复片段	event_id、chunk_index、last_event_id、retry_lineage	检查客户端重连是否重复消费旧事件	事件幂等、按 event_id 去重、支持 resume from last_event_id
前端显示半截 JSON	tool_call_delta、message_end、structured_parse_status	检查是否在 message_end 前执行解析	半结构只展示状态，最终事件后再提交
用户点停止但后端继续	client_cancelled、cancel_stage、resource_released	检查取消信号是否到模型服务和工具层	服务端取消传播，工具补偿和已用计费
重试后结果不可比	previous_request_id、changed_inputs、fallback_reason、prompt_hash	比较重试是否改了模型、上下文、采样或 Prompt	明确 retry_lineage，在 UI 中标记新尝试或恢复点

九、样本回流：哪些请求必须进入 Eval / 审计 / 事故

触发条件	回流去向	必须带上的证据	目的
用户差评或人工判错	坏例池 / Eval 回归集	request_id、input_hash、output_hash、error_taxonomy、review_label	让线上失败变成固定回归样本
高风险策略命中	安全评测 / 审计证据链	risk_tier、policy_version、safety_labels、decision_reason	校准误拒误放，证明策略动作
工具副作用失败	事故 / Runbook / 补偿系统	tool_call_id、idempotency_key、side_effect_committed、compensation_id	修正状态，避免重复执行和责任不清
成本或延迟异常	成本性能治理 / LLMOps	stage_timing、usage、model_route、retry_lineage、tenant_id	定位异常水位，决定限流、分池或降级
发布后质量回归	Release Gate / Canary 复盘	artifact_manifest、prompt_version、model_version、eval_delta	证明哪个版本导致变化，支持回滚

9.1 Trace 怎样生成反馈闭环输入

Trace 字段	生成闭环对象	需要补充的人工判断	进入哪条修复线
user_rating、review_label、error_taxonomy	feedback_item_id	是否真实错误、严重程度、用户影响面	问题分流、坏例池、业务 owner 跟进
retrieval_results、citation_coverage、index_version	rag_failure_case	是漏召、错召、过期、权限过滤还是引用不忠实	知识更新、索引重建、RAG Eval
tool_name、tool_schema_version、permission_snapshot、side_effects	tool_failure_case	是参数错误、权限错误、执行失败还是补偿失败	工具 schema、权限策略、Runbook
policy_version、safety_labels、decision_reason	safety_review_case	是误拒、漏拦、策略冲突还是灰区需人工	红队回归、Guardrail / Policy 变更
route_policy_version、model_id、fallback_chain、usage	routing_cost_case	质量损失是否来自路由，成本异常是否来自重试	模型路由、预算、Fallback 策略
release_id、canary_group、artifact_manifest	release_regression_case	是否属于新版本回归，是否触发停止条件	发布闸门、回滚、fixed_version 验证

Trace 要能自动变成闭环入口

排障字段如果不能生成 feedback_item、eval_case、artifact_change 或 incident_candidate，就只能停留在日志层。好的 Trace 模板会提前带上足够的版本、风险、工具、RAG 和发布信息，让坏例可以直接进入分流和修复流程。

十、Dashboard 最小视图

请求健康

请求量、成功率、错误率、取消率、超时率、finish_reason 分布、重试率。

延迟分解

TTFT、gateway、context、queue、prefill、decode、postprocess、P95 / P99。

质量与风险

差评率、人工判错率、引用覆盖率、结构解析失败率、安全误拒误放、风险等级分布。

成本归因

token、cache hit、模型路由、Fallback、重试成本、租户 / 功能 / 成本中心分布。

十一、和相邻页面怎么接

相邻页	它回答什么	本页补什么
AI 证据包索引	请求、上下文、RAG、工具、发布、事故和反馈字段的总目录	把其中的请求级字段展开成 Span、事件、Dashboard 和排障模板
一次请求的一生	一次请求从输入到闭环的时间顺序	把每个阶段变成可记录、可排查、可回流的字段
上下文组装 / 窗口预算	模型到底看到什么上下文	把 prompt_hash、dropped_segments、token_budget 变成复盘证据
生成运行时 / 流式重试	生成阶段怎样排队、流式、停止、取消和重试	把 stage_timing、stream_events、finish_reason、retry_lineage 落成排障模板
模型路由 / Fallback	请求该走哪个模型，失败时怎么降级	记录 route_policy、fallback_chain 和质量 / 成本差异
LLMOps / 可观测	Trace 如何进入 Eval、Release 和线上运营	提供请求级字段和故障分类，作为 LLMOps 的输入证据
审计证据链	如何追责、复现、审计和归因	提供 request_id 到 artifact、permission、tool、incident 的最小证据

十二、回到 AI 主干

AI 全景 → AI 阅读路线 → 一次请求的一生 → 生成运行时 → AI 证据包索引 → 请求 Trace / 排障模板 → LLMOps → 审计证据链