3.4 故障排查：调试与日志

3.4 故障排查：调试与日志

本节摘要：链式调用的故障被层层封装包住，排障要靠分级工具：调试开关看单次执行的完整轨迹，回调日志建生产台账，追踪平台做全链路可视化。本节给出三级排障路径与各自的实操代码。

链式调用的故障有多隐蔽

产线越长，故障定位越难。一次问答要穿过检索、拼装、模型、解析四道工序，最终答案不对时，问题可能在任何一站：检索没拣到料？拼装把资料截断了？模型拿到了料却没用？解析把好答案切碎了？直觉在这里基本失效，必须靠工具把黑盒拆开。

三级排障路径

一级：调试开关，五分钟见效

环境变量一开，链的每步输入输出全部打到控制台：

import os
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI

# 调试开关：一开，每道工序的进出全部打印
os.environ["LANGCHAIN_DEBUG"] = "true"

chain = (ChatPromptTemplate.from_template("给{p}的公司起名")
         | ChatOpenAI(temperature=0)
         | StrOutputParser())

print(chain.invoke({"p": "彩色袜子"}))
# 控制台会输出（节选）：
# [chain/start] Entering PromptChain with input {"p": "彩色袜子"}
# [chain/end] Exiting PromptChain with value 给彩色袜子的公司起名
# [llm/start] Entering ChatOpenAI
# [llm/end] Exiting ChatOpenModel with 彩织坊
# 彩织坊

os.environ["LANGCHAIN_DEBUG"] = "false"  # 排查完关掉
​

排查的读法：沿着输出从最后一站往回走，第一处"输入正常但输出不对"的工序就是病灶。调试开关只适合开发机单次执行，生产环境打印量会把日志系统打爆。

二级：回调日志，建生产台账

2.9 节的回调在这里派上真用场——把事件流写进标准日志，就是生产台账：

import logging
from langchain_core.callbacks import BaseCallbackHandler

# 结构化日志：生产排障的主力
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s")
logger = logging.getLogger("socks-line")

class LoggingHandler(BaseCallbackHandler):
    """把链与模型事件写进日志台账"""

    def on_chain_start(self, serialized, inputs, **kwargs):
        # 输入可能很长，只记前80字足够排障
        logger.info("链启动 输入 %s", str(inputs)[:80])

    def on_chain_end(self, outputs, **kwargs):
        logger.info("链结束 输出 %s", str(outputs)[:80])

    def on_llm_end(self, response, **kwargs):
        usage = (response.llm_output or {}).get("token_usage", {})
        logger.info("模型调用 token %s", usage.get("total_tokens"))

    def on_tool_error(self, error, **kwargs):
        logger.error("工具故障 %s", error)

handler = LoggingHandler()
# 挂到任意链上，从此每次执行都留痕
​

⚠️ 日志里别存完整对话原文：一是隐私合规风险，二是量太大。截断到能定位问题的长度，全文按需落对象存储并只在日志里留索引号。

三级：追踪平台，全链路可视化

当"单次执行正常、统计上异常"（比如某类问题答对率低）时，需要横向对比成百上千次执行——这是 LangSmith 这类追踪平台的主场：

import os

# 追踪平台接入：三个环境变量即可
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "你的追踪平台密钥"
os.environ["LANGCHAIN_PROJECT"] = "socks-qa-line"

# 之后所有链的执行自动上报：每站的输入输出 耗时 token
# 打开平台网页就能看到树状执行轨迹
​

接入零代码改动是这套体系的杀手锏：产线代码一行不动，每个 run 的完整轨迹自动汇聚。平台侧能做的事：按耗时排序找出最慢请求；按失败率筛出问题工位；两次版本之间对比延迟与成本分布。3.3 节的评估也可以挂到平台上做持续回归。

三级工具怎么配合，一张表收拢：

💡 排障顺序本身就是成本控制：一级五分钟、二级需要日志留存、三级要平台预算。从轻到重逐级上，别一上来就申请平台账号。

把故障变成资产

每次故障修复后做两件事：把触发场景补进 3.3 节的评估集（防止复发），把排障路径记进团队的故障手册。链式应用的成熟度不看它不出故障，而看故障重复率是不是在下降。下一节讲另一类必须在上线前想清楚的事：安全——恶意输入怎么打穿你的产线，护栏装在哪两道闸门。