你有没有遇到过这种情况：本地跑得好好的 LangChain 应用，上线之后突然崩了——API 超时、速率限制、模型输出格式不对……

没有错误处理，你的 Agent 就像一辆没有安全气囊的车，平时没问题，出事就是大事。

今天这篇，把 LangChain 错误处理的核心手段一次讲完。
01 为什么错误处理这么重要

LangChain 应用的调用链路很长：

用户输入 → 输入验证 → LLM 调用 → 工具调用 → 输出解析 → 返回结果

每一步都可能出错：

• LLM API 超时或限流（429 Rate Limit）
• 工具调用返回格式不对
• 模型输出不是你期望的 JSON
• 网络抖动导致请求失败

没有兜底，任何一步失败都会把整个链路炸掉。

---

02 最基础：with_retry 自动重试

LangChain 的 Runnable 接口内置了 with_retry 方法，这是最省力的重试方案。

import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({ modelName: "gpt-4" });

// 遇到这些错误自动重试，最多 3 次，指数退避
const modelWithRetry = model.withRetry({
  stopAfterAttempt: 3,
  onFailedAttempt: (error) => {
    console.log(`第 ${error.attemptNumber} 次重试...`);
  },
});

const response = await modelWithRetry.invoke("你好");

with_retry 做了什么：

• 网络错误、API 限流 → 自动重试
• 重试间隔指数递增（1s → 2s → 4s），避免雪崩
• 超过最大次数后抛出最后一次的错误

适合所有 Runnable 组件：模型、工具、链，都能直接加上去。

---

03 备用模型：withFallbacks 回退链

GPT-4 太贵或者挂了？自动切到 GPT-3.5。

import { ChatOpenAI } from "@langchain/openai";

const claudeSonnet = new ChatOpenAI({ modelName: "claude-sonnet-4-6" });
const gpt54 = new ChatOpenAI({ modelName: "gpt-5.4" });

// claudeSonnet 失败了自动用 gpt54 兜底
const modelWithFallback = claudeSonnet.withFallbacks({
  fallbacks: [gpt54],
});

const response = await modelWithFallback.invoke("分析这段代码");

也可以设整条链路的回退：

import { RunnableSequence } from "@langchain/core/runnables";

const primaryChain = RunnableSequence.from([prompt, claudeSonnet, outputParser]);
const fallbackChain = RunnableSequence.from([prompt, gpt54, outputParser]);

const chainWithFallback = primaryChain.withFallbacks({
  fallbacks: [fallbackChain],
});

实际用途：

• 主模型成本高 → 失败切便宜模型
• 主模型限流 → 失败切备用厂商
• 严格 JSON 解析失败 → 切宽松解析

---

04 工具错误处理：ToolException

工具调用出错，不能直接让 Agent 崩，要把错误信息反馈给模型让它自己修正。

import { tool } from "@langchain/core/tools";
import { ToolException } from "@langchain/core/tools";
import { z } from "zod";

const divisionTool = tool(
  async ({ a, b }) => {
    if (b === 0) {
      // 抛 ToolException，Agent 会把错误信息发回给模型
      throw new ToolException("除数不能为零，请换一个数字");
    }
    return `${a} ÷ ${b} = ${a / b}`;
  },
  {
    name: "division",
    description: "两数相除",
    schema: z.object({
      a: z.number().describe("被除数"),
      b: z.number().describe("除数"),
    }),
  }
);

关键区别：

• 普通 Error → Agent 直接崩溃
• ToolException → 错误信息被发回给 LLM，让模型自己纠正重试

---

05 输入验证：在出发前就拦截错误

别等到 LLM 调用时才报错，入参不对就直接拦截。

import { RunnableLambda } from "@langchain/core/runnables";

function validateInput(input: { query: string; maxLength?: number }) {
  if (!input.query || input.query.trim() === "") {
    throw new Error("查询内容不能为空");
  }
  if (input.query.length > 10000) {
    throw new Error("查询内容过长，请控制在 10000 字符以内");
  }
  return input;
}

const chain = RunnableLambda.from(validateInput)
  .pipe(prompt)
  .pipe(model)
  .pipe(outputParser);

前置校验的好处：

• 省掉无效的 API 调用，节省费用
• 错误信息更友好，用户体验更好
• 定位问题更快，不用翻 LLM 的调用日志

---

06 输出解析失败：OutputFixingParser 自动修复

模型输出了不合规的 JSON？不用 crash，让它自己修。

import { StructuredOutputParser } from "langchain/output_parsers";
import { OutputFixingParser } from "langchain/output_parsers";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";

const baseParser = StructuredOutputParser.fromZodSchema(
  z.object({
    name: z.string(),
    age: z.number(),
    hobbies: z.array(z.string()),
  })
);

// 解析失败时自动让模型修复输出格式
const fixingParser = OutputFixingParser.fromLLM(
  new ChatOpenAI({ temperature: 0 }),
  baseParser
);

// 即使模型输出格式有问题，也会自动修复
const result = await fixingParser.parse(badFormattedOutput);

工作原理： 解析失败 → 把原始输出 + 错误信息发给模型 → 让模型重新格式化 → 再次解析。

适合场景：对结构化输出有严格要求，但模型偶尔会格式不稳定。

---

07 回调监控：生产环境必备

知道出错是一回事，知道哪里出错、多频繁出错是另一回事。

import { BaseCallbackHandler } from "@langchain/core/callbacks/base";

class ErrorMonitorHandler extends BaseCallbackHandler {
  name = "ErrorMonitorHandler";

  async handleLLMError(error: Error) {
    console.error(`[LLM Error] ${error.message}`);
    // 上报到监控系统
    await reportToMonitor({
      type: "llm_error",
      message: error.message,
      timestamp: Date.now(),
    });
  }

  async handleChainError(error: Error) {
    console.error(`[Chain Error] ${error.message}`);
    await reportToMonitor({
      type: "chain_error",
      message: error.message,
      timestamp: Date.now(),
    });
  }

  async handleToolError(error: Error) {
    console.error(`[Tool Error] ${error.message}`);
    await reportToMonitor({
      type: "tool_error",
      message: error.message,
      timestamp: Date.now(),
    });
  }
}

// 全局注册
const chain = prompt.pipe(model).pipe(outputParser);
const response = await chain.invoke(
  { query: "分析这份报告" },
  { callbacks: [new ErrorMonitorHandler()] }
);

生产环境建议：

• 按错误类型分别上报，方便统计各环节失败率
• 记录完整的输入输出，方便复现问题
• 设置告警阈值，错误率超标立刻通知

---

08 组合用法：生产级错误处理方案

把上面这些组合起来，就是一个完整的健壮方案：

import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";
import { RunnableLambda } from "@langchain/core/runnables";

const primaryModel = new ChatOpenAI({ modelName: "claude-sonnet-4-6" })
  .withRetry({ stopAfterAttempt: 3 });              // ① 自动重试

const fallbackModel = new ChatOpenAI({ modelName: "gpt-5.4" })
  .withRetry({ stopAfterAttempt: 2 });

const robustModel = primaryModel.withFallbacks({    // ② 备用模型
  fallbacks: [fallbackModel],
});

const prompt = ChatPromptTemplate.fromTemplate("{input}");
const outputParser = new StringOutputParser();

function validateInput(input: { input: string }) {  // ③ 输入验证
  if (!input.input?.trim()) throw new Error("输入不能为空");
  return input;
}

const robustChain = RunnableLambda.from(validateInput)
  .pipe(prompt)
  .pipe(robustModel)
  .pipe(outputParser);

// 最外层 try-catch 兜底
try {
  const result = await robustChain.invoke(
    { input: "你好" },
    { callbacks: [new ErrorMonitorHandler()] }      // ④ 错误监控
  );
  console.log(result);
} catch (error) {
  console.error("所有重试和回退都失败了:", error);
  // 返回降级结果，而不是让用户看到崩溃页面
  return "服务暂时不可用，请稍后重试";
}

四层防护：输入验证 → 自动重试 → 备用模型 → 错误监控，任何一层都可以单独用，组合起来就是生产级的健壮性。

---

小结

场景	方案
API 限流/网络抖动	withRetry 自动重试
主模型挂了	withFallbacks 切备用
工具调用出错	ToolException 反馈给模型
入参格式不对	前置校验拦截
输出格式不对	OutputFixingParser 自动修复
生产环境监控	回调系统上报

健壮的错误处理不是写一堆 try-catch，而是在对的地方用对的工具。

下一篇，我们讲 LangChain 性能优化：10 个提速降本实用技巧，token 省一半，速度翻一倍。

这里给大家精心整理了一份全面的AI大模型学习资源，包括：AI大模型全套学习路线图（从入门到实战）、精品AI大模型学习书籍手册、视频教程、实战学习、面试题等，资料免费分享！

👇👇扫码免费领取全部内容👇👇

1. 成长路线图&学习规划

要学习一门新的技术，作为新手一定要先学习成长路线图，方向不对，努力白费。

这里，我们为新手和想要进一步提升的专业人士准备了一份详细的学习成长路线图和规划。可以说是最科学最系统的学习成长路线。

2. 大模型经典PDF书籍

书籍和学习文档资料是学习大模型过程中必不可少的，我们精选了一系列深入探讨大模型技术的书籍和学习文档，它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。（书籍含电子版PDF）

3. 大模型视频教程

对于很多自学或者没有基础的同学来说，书籍这些纯文字类的学习教材会觉得比较晦涩难以理解，因此，我们提供了丰富的大模型视频教程，以动态、形象的方式展示技术概念，帮助你更快、更轻松地掌握核心知识。

4. 2026行业报告

行业分析主要包括对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。

5. 大模型项目实战

学以致用 ，当你的理论知识积累到一定程度，就需要通过项目实战，在实际操作中检验和巩固你所学到的知识，同时为你找工作和职业发展打下坚实的基础。

6. 大模型面试题

面试不仅是技术的较量，更需要充分的准备。

在你已经掌握了大模型技术之后，就需要开始准备面试，我们将提供精心整理的大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。

7. 资料领取：全套内容免费抱走，学 AI 不用再找第二份

不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：

👇👇扫码免费领取全部内容👇👇