AI 大模型故障：LLM 问题排查的正确顺序：先查日志、再查检索、再查提示词、最后才动参数

一、为什么"先调参数"是错的：故障排查的经济学

在大模型应用团队里，有一个几乎普遍存在的条件反射：模型输出不对，第一反应是调 temperature、调 top_p、换模型、重训 embedding。这个动作看起来"专业"，实际上是把最贵、最不可复现、最远离根因的手段放在了第一位。

我们可以把排查动作按"成本—可复现性—根因接近度"三个维度排序。日志排查成本最低，几乎零边际成本，且完全可复现；检索链路排查成本中等，需要看召回内容与向量库状态；提示词排查成本较低但需要版本管理；参数调整成本最高，因为一次参数变更会同时影响所有请求，且效果具有随机性，很难归因。

从信息论角度看，日志与检索层提供的是"确定性证据"，而参数层提供的是"概率性调整"。确定性证据能直接定位根因，概率性调整只能改变输出的分布。用概率性手段去解决确定性问题，是典型的工具错配。

业界已有大量团队在实践中总结出类似经验。例如 OpenAI 在其 API 文档中明确建议，当输出不符合预期时，应先检查输入消息与系统提示，再考虑模型与参数选择（OpenAI API Documentation, 2024）。LangChain 官方文档也把"调试"章节的第一节放在"检查链路的中间输出"，而非参数调优（LangChain Docs, 2024）。本文评述：这些官方建议背后是同一个逻辑——先看数据流，再看配置。

二、四层递进定位法：总览与决策树

四层递进定位法的核心是：按"数据流方向"而非"直觉方向"排查。一个 LLM 请求的数据流是：用户输入 → 提示词组装 → 检索（可选）→ 模型推理 → 输出后处理。排查顺序应沿着数据流逆向或顺向逐层验证，而不是跳到末端改参数。

层级	排查对象	典型工具	成本	可复现性
第一层	日志、trace、指标	LangSmith、Langfuse、OpenTelemetry	极低	高
第二层	检索、向量库、chunk	向量库控制台、召回评估脚本	中	高
第三层	提示词、上下文、模板	Prompt 版本管理、diff 工具	中	高
第四层	模型、解码参数、微调	参数实验平台、A/B 测试	高	低

决策树的核心判断逻辑是：如果问题能稳定复现，优先查前三层；如果问题随机出现，优先查第一层与第四层。稳定复现意味着存在确定性缺陷，通常在数据流的前段；随机出现可能来自采样随机性、并发竞争或外部依赖抖动。

【四层递进定位法 · 决策树】

问题出现
  │
  ├─ 能稳定复现？
  │    ├─ 是 → 查日志(trace) → 查检索召回 → 查提示词版本
  │    │         └─ 三层都正常 → 才考虑参数/模型
  │    └─ 否 → 查日志中的随机性来源
  │              ├─ 采样参数(temperature/top_p) → 第四层
  │              ├─ 并发/超时/限流 → 第一层
  │              └─ 外部检索抖动 → 第二层
  │
  └─ 影响范围？
       ├─ 全量请求 → 优先查提示词版本与模型版本
       ├─ 特定 query 类型 → 优先查检索
       └─ 特定时段 → 优先查日志与依赖

这个决策树的价值在于：它把"我该先看什么"这个模糊问题，转化为几个可回答的二元判断。工程实践中，团队可以把这棵树做成 runbook，贴在故障响应群里。

三、第一层：日志与可观测性——证据链的起点

3.1 为什么日志是第一层

日志是唯一能完整还原"当时到底发生了什么"的证据。参数调整是"改未来"，日志排查是"看过去"。没有日志，所有排查都是猜测。LLM 应用的日志与传统的 Web 日志有本质区别：它需要记录完整的 prompt、检索到的上下文、模型原始输出、token 用量、延迟分解，而不仅仅是状态码。

OpenTelemetry 在 2023 年之后逐步扩展了对 LLM 语义约定的支持，提出了 GenAI semantic conventions，定义了 gen_ai.system、gen_ai.request.model、gen_ai.usage.input_tokens 等属性（OpenTelemetry Semantic Conventions, 2024）。本文评述：这意味着 LLM 可观测性正在从"各家自建"走向"标准化"，团队应尽早对齐这些约定，避免被单一厂商锁定。

3.2 必须记录的字段清单

其中"版本号"最容易被忽略，却往往是根因。很多"模型变笨了"的故障，实际是某次 prompt 模板更新或索引重建导致的。没有版本号，就无法做时间对齐。

3.3 工具链选型

当前主流的 LLM 可观测性工具可分为三类：开源自托管（Langfuse、Phoenix/Arize）、商业 SaaS（LangSmith、Helicone、Braintrust）、以及通用 APM 扩展（Datadog LLM Observability、New Relic AI Monitoring）。

工具	类型	核心能力	适用场景
Langfuse	开源	trace、prompt 管理、评估	数据合规要求高的团队
LangSmith	SaaS	调试、数据集、评估	LangChain 生态团队
Phoenix	开源	trace、embedding 可视化	RAG 调试
Helicone	SaaS/代理	一行接入、成本监控	快速上线的小团队

拓展阅读：Langfuse 官方文档的 tracing 章节（https://langfuse.com/docs/tracing）与 LangSmith 的 debugging 教程（https://docs.smith.langchain.com/）是入门第一层排查的实用材料。OpenTelemetry 的 GenAI 语义约定见 https://opentelemetry.io/docs/specs/semconv/gen-ai/。

3.4 日志排查的标准动作

拿到一条失败请求的 trace 后，标准动作是"三看一对比"：看 prompt 是否被截断、看检索内容是否为空或无关、看模型原始输出与后处理输出的差异、对比成功请求与失败请求的 trace 差异。

特别要强调的是"截断"问题。当 input tokens 超过模型上下文窗口时，很多框架会静默截断，导致关键信息丢失。这类问题在日志里表现为 prompt 末尾缺失，但如果不记录完整 prompt，就完全看不到。本文评述：静默截断是 LLM 应用中最隐蔽的故障源之一，建议在框架层强制记录截断事件并打标。

四、第二层：检索链路——RAG 的隐形故障源

4.1 RAG 故障的分类

RAG 系统的故障可以按链路阶段分为四类：索引阶段（chunk 切分、embedding 质量）、检索阶段（召回率、排序）、融合阶段（多路召回合并、重排）、生成阶段（上下文注入、引用）。其中前三个阶段的问题，在最终输出上往往表现为"模型胡说"，容易被误判为模型能力问题。

学术界对 RAG 故障已有系统研究。Chen 等人在 2024 年提出的 RAG 评估框架 RAGAS，把检索质量拆解为 context precision、context recall、faithfulness、answer relevancy 四个维度（Es et al., 2023；后续扩展见 RAGAS 文档 2024）。本文评述：这套拆解的价值在于，它把"RAG 好不好"这个模糊问题，转化为四个可测量的指标，从而让排查有据可依。

4.2 检索排查的操作步骤

第 5 步"embedding 一致性"是高频坑。团队在升级 embedding 模型后，如果只更新了查询侧而没重建索引，检索结果会整体劣化。这类问题的特征是：所有 query 的召回质量都下降，而不是特定 query。本文评述：embedding 模型与索引必须作为"原子版本"一起发布，任何单侧更新都是故障隐患。

4.3 检索评估的最小可行方案

不需要一上来就搭建完整的评估平台。最小可行方案是：准备 50 到 100 条"query—标准答案—标准来源文档"的三元组，写一个脚本计算 recall@k 与 MRR。这个脚本可以在每次索引变更后运行，作为回归测试。

# 检索回归测试的最小骨架（伪代码）
dataset = load_jsonl("eval_retrieval.jsonl")  # 每条含 query, gold_doc_id

def recall_at_k(k):
    hit = 0
    for item in dataset:
        docs = retriever.search(item["query"], top_k=k)
        ids = [d.id for d in docs]
        if item["gold_doc_id"] in ids:
            hit += 1
    return hit / len(dataset)

for k in [1, 3, 5, 10]:
    print(f"recall@{k} = {recall_at_k(k):.3f}")

关于数据集预处理细节：上述 eval_retrieval.jsonl 的构造方式是，从真实用户 query 日志中分层抽样（按 query 长度、意图类别分层），由标注人员标注 gold_doc_id，剔除标注不一致的样本。这是模拟数据构造流程，团队应按自身业务替换。

4.4 检索层的前沿进展

2023 年以来，检索增强领域出现了几个值得关注的方向：一是混合检索（BM25 + 向量）成为默认配置，Anthropic 在其 Contextual Retrieval 文章中报告混合检索可显著降低检索失败率（Anthropic, 2024）；二是上下文重排（rerank）模型如 Cohere Rerank、BGE-reranker 的普及；三是 GraphRAG 等结构化检索方法，用知识图谱补充向量检索的不足（Microsoft Research, 2024）。

本文评述：这些进展对排查的意义在于，检索链路的组件越来越多，故障面也随之扩大。排查时必须逐组件隔离验证，而不是把整个 RAG 当作黑盒。建议在 trace 中为每个检索组件单独打 span。

五、第三层：提示词与上下文契约

5.1 提示词是"代码"，不是"文案"

提示词在工程上应该被当作代码管理：有版本、有 diff、有测试、有回滚。很多团队把 prompt 写在配置文件甚至数据库里，改完即生效，没有版本记录，导致故障发生时无法判断"是不是 prompt 改了"。

本文评述：prompt 版本管理是 LLM 工程化最被低估的基础设施。一个简单的做法是，把 prompt 模板纳入 Git，每次变更走 PR 流程，并在 trace 中记录 prompt 的 commit hash。这样任何一次输出异常都能追溯到具体的 prompt 版本。

5.2 提示词故障的典型模式

故障模式	表现	排查动作
指令冲突	system 与 user 指令矛盾，模型随机选一个	检查 system/user 是否语义冲突
变量未注入	模板占位符原样出现在 prompt 中	检查模板渲染日志
上下文污染	检索内容含指令性文本，被模型当指令执行	检查检索内容是否含 prompt injection
格式约束失效	要求 JSON 输出但返回自然语言	检查是否用了结构化输出能力
示例误导	few-shot 示例与当前任务分布不符	检查示例是否覆盖当前 query 类型

5.3 上下文契约：一个被忽视的概念

笔者提出"上下文契约"这个概念，指的是 prompt 中各个部分（system 指令、检索上下文、对话历史、用户输入）之间的约定关系。一个健康的上下文契约应满足：各部分职责清晰、边界明确、优先级一致、总长度可控。

当上下文契约被破坏时，故障表现往往是"模型不听话"。例如，system 说"只根据提供的资料回答"，但检索资料为空，模型要么拒答要么编造。这不是模型问题，而是契约设计问题——没有定义"资料为空时怎么办"。

5.4 提示词注入与安全排查

提示词注入（prompt injection）是提示词层的重要故障类别。OWASP 在 2023 年将 prompt injection 列为 LLM 应用十大风险之首（OWASP LLM Top 10, 2023）。在 RAG 场景中，注入可能来自检索到的文档内容，而非用户输入，这使防御更困难。

排查注入类故障的动作包括：检查检索内容是否含"忽略以上指令"类文本、检查是否有间接注入（文档中嵌入指令）、检查输出是否泄露了 system prompt。本文评述：提示词注入目前没有银弹，工程上应采取"纵深防御"——输入过滤、上下文隔离、输出校验、权限最小化多管齐下。

六、第四层：模型参数与解码策略——最后才动

6.1 为什么参数是最后手段

解码参数（temperature、top_p、top_k、repetition_penalty、max_tokens）控制的是输出的概率分布，而不是输出的正确性。调低 temperature 能让输出更确定，但不能让错误的事实变正确；调高 top_p 能增加多样性，但不能修复缺失的检索内容。

本文评述：参数调整的适用场景其实很窄——当且仅当前三层都正常，且问题表现为"输出风格不符合预期"或"需要更多/更少多样性"时，才应该动参数。把参数当作万能药，是排查能力不足的表现。

6.2 解码参数的工程含义

参数	作用	调参风险	建议
temperature	控制采样随机性	过低导致重复，过高导致发散	事实类任务用 0–0.3
top_p	核采样，限制候选集	与 temperature 叠加会放大随机性	通常只调一个
max_tokens	限制输出长度	过小导致截断，过大增加成本	按任务设定并监控截断率
seed	固定随机种子	并非所有模型都支持	排查时用于复现

关于 temperature 与 top_p 的叠加效应，Hugging Face 的生成策略文档有清晰说明：同时调整两者会使得随机性难以预测（Hugging Face Docs, 2024）。本文评述：工程上应遵循"单变量原则"——一次只调一个参数，并记录调整前后的评估指标。

6.3 模型切换与微调的排查位置

模型切换和微调属于第四层中最重的动作。当团队考虑"换个模型试试"时，应该先问三个问题：前三层是否已穷尽？换模型的评估方案是什么？回滚方案是什么？

微调（fine-tuning）更应谨慎。微调能改变模型的行为分布，但也会引入灾难性遗忘、过拟合、以及新的安全风险。本文评述：微调应该是"提示词与检索都优化到极限后仍不满足"时的选择，而不是排查故障的手段。

七、实战案例：三类典型故障的完整排查路径

7.1 案例一：客服机器人突然"答非所问"

现象：某客服 RAG 系统在某天上午开始，约 30% 的请求回答与问题无关。

第一层排查：查 trace 发现，这些请求的检索结果为空。进一步看，检索 span 显示向量库返回 0 条结果。

第二层排查：用相同 query 直接调用向量库，仍然返回空。检查元数据过滤条件，发现 filter 中有一个"status=active"的条件，而当天凌晨的索引重建任务把所有文档的 status 字段写成了 null。

根因：索引重建脚本的字段映射 bug。修复脚本并重建索引后恢复。

这个案例中，如果一开始就去调 temperature 或换模型，问题永远不会解决。本文评述：检索为空的故障，在输出层表现为"模型胡说"，这是最典型的"表象误导"。

7.2 案例二：输出格式突然不符合 JSON 规范

现象：某信息抽取系统，下游解析器开始报 JSON 解析错误。

第一层排查：trace 显示模型原始输出中，JSON 前后多了"好的，以下是结果："这样的自然语言前缀。

第三层排查：对比 prompt 版本，发现前一天有人为了"让输出更友好"修改了 system prompt，加入了"请用友好的语气回复"。这条指令与"只输出 JSON"冲突。

根因：prompt 指令冲突。回滚 prompt 并改用结构化输出（structured output / JSON mode）后解决。

本文评述：这个案例说明 prompt 版本管理的重要性。如果 trace 中没有记录 prompt 版本，排查会困难得多。同时，能用结构化输出能力解决的格式问题，不应依赖自然语言指令。

7.3 案例三：同一问题有时答对有时答错

现象：某知识问答系统，同一问题多次提问，答案在正确与错误之间摇摆。

排查路径：这是典型的"随机性"故障，按决策树应查第一层与第四层。查 trace 发现，检索结果稳定，prompt 稳定，但 temperature=0.9。将 temperature 降至 0.2 后，答案稳定为正确。

根因：高 temperature 导致模型在多个候选答案间采样。但进一步追问：为什么模型会"知道"错误答案？检查检索内容发现，召回文档中同时包含正确与错误信息，模型在高 temperature 下随机选择。

本文评述：这个案例的深层根因其实在第二层——检索召回了矛盾信息。调 temperature 只是掩盖了症状。正确的修复是改进检索排序，让正确文档排在前面，或在 prompt 中要求"如资料冲突，以最新版本为准"。

八、工程化落地：检查清单、工具链与团队协作

8.1 故障响应检查清单

8.2 团队协作机制

四层递进定位法要落地，需要团队协作机制支撑。建议设立三个角色：on-call 工程师负责第一层快速定位、RAG 负责人负责第二层、prompt 负责人负责第三层、模型负责人负责第四层。故障响应时按层升级，避免所有人同时扑向参数。

同时建议建立"故障复盘库"，每次故障记录：现象、排查路径、根因、修复、预防措施。这个库是团队排查能力提升的最快途径。本文评述：排查能力不是个人天赋，而是组织资产，需要通过复盘不断沉淀。

8.3 工具链整合

一个完整的 LLM 可观测性工具链应覆盖：trace 采集（OpenTelemetry + Langfuse）、评估（RAGAS、DeepEval）、prompt 管理（Git + Langfuse Prompt Management）、实验（A/B 测试平台）、告警（基于指标的异常检测）。

拓展阅读：DeepEval 的评估指标文档（https://docs.confident-ai.com/）与 RAGAS 的 GitHub（https://github.com/explodinggradients/ragas）是构建评估体系的好起点。OpenAI 的 structured outputs 指南（https://platform.openai.com/docs/guides/structured-outputs）对第三层排查有帮助。

九、前沿预判：从人工排查到自动根因定位

9.1 LLM 可观测性的标准化

OpenTelemetry 的 GenAI 语义约定正在快速演进，2024 年以来已覆盖 chat、embeddings、tool calls 等场景。本文评述：标准化是自动根因定位的前提。当所有框架都输出统一的 trace 格式时，才能构建跨框架的自动分析工具。

9.2 自动根因定位的探索

学术界已开始探索用 LLM 自身来排查 LLM 故障。例如，有研究提出用 agent 自动分析 trace、定位异常 span（如 AIOps 领域的相关探索，2024）。工业界也有团队尝试用规则引擎 + 异常检测自动标记可疑 trace。

本文评述：自动根因定位短期内难以完全替代人工，因为 LLM 故障的根因往往涉及语义判断（如"检索内容是否相关"），这需要领域知识。但自动工具可以承担"缩小排查范围"的工作，把人工精力集中在关键判断上。

9.3 评估驱动的开发范式

长期看，LLM 应用开发正在从"改完看效果"转向"评估驱动开发"（eval-driven development）。在这种范式下，每次变更（prompt、检索、参数）都先跑评估集，指标不退化才上线。本文评述：评估驱动开发是四层递进定位法的"预防版本"——它让故障在发生前就被拦截。

关于评估集的构建，建议覆盖：正常 query、边界 query、对抗 query、历史故障 query。评估指标应分层：检索层看 recall/MRR，生成层看 faithfulness/relevancy，端到端看任务成功率。

十、结语

LLM 故障排查的正确顺序，本质上是对"证据"与"猜测"的排序。日志是证据，检索是证据，提示词是证据，参数是猜测。把证据放在猜测前面，是工程理性的体现。

四层递进定位法不是万能公式，但它提供了一条清晰的路径：从最便宜、最可复现、最接近根因的层开始，逐层排除。它把"模型又抽风了"这种无力感，转化为"我现在该看哪一层"的可执行动作。

本文评述：随着 LLM 应用复杂度提升，排查能力将成为团队的核心竞争力之一。工具会越来越好，但"先查什么"的判断力，仍然需要工程经验与系统思维的支撑。希望这条主线能帮助更多团队少走弯路。