如何用LangGraph构建生产级复杂工作流:图、路由、Fallback与可观测性完整指南(engenharia-de-software-com-ia-aplicada)

原创2026-10-13 23:11:001,459 阅读

如何用LangGraph构建生产级复杂工作流:图、路由、Fallback与可观测性完整指南(engenharia-de-software-com-ia-aplicada)

LangGraph 是构建 LLM 复杂工作流的主流编排框架:它把提示词、工具调用、模型降级串成一张可测试、可审计的图。开源课程仓库 engenharia-de-software-com-ia-aplicada(面向「Software Engineering with Applied AI」的课后代码库)里,从入门级 StateGraph 状态图,到带路由(Router)、Fallback 模型降级与 Trace 可观测性的生产级工作流(OpsPilot 运维助手),都有完整实现。本文带你快速看懂生产级 LangGraph 工作流的四大关键能力:图、路由、Fallback、可观测性。

一、为什么复杂 LLM 应用需要图编排

单轮提示词的聊天机器人离生产级还很远:真实业务里,一次「查询」、一次「多步规划」、一次「需要审计的回答」需要不同的推理策略;模型供应商会超时、限流;运维还需要回答「系统为什么这样决策」。这个仓库中的 AI 应用,从电商智能推荐到金融账单分析,背后都有这类工作流在支撑:

AI 智能推荐应用演示界面:LangGraph 复杂工作流驱动的智能体应用场景

图编排的核心价值在于:把「流程」变成代码。每一步是节点(Node),每个判断是边(Edge),整个流程可以像普通程序一样被单元测试覆盖。

二、最小 LangGraph 状态图:节点、边与条件路由

先看仓库里的入门示例 02-langchain-intro。graph.ts 定义了 5 个节点的状态图,结构一目了然:

const workflow = new StateGraph({ stateSchema: GraphState })
  .addNode("identifyIntent", identifyIntent)
  .addNode("uppercase", upperCaseNode)
  .addNode("lowercase", lowerCaseNode)
  .addNode("fallback", fallbackNode)
  .addEdge(START, "identifyIntent")
  .addConditionalEdges("identifyIntent", (state) => {
    switch (state.command) {
      case "uppercase": return "uppercase";
      case "lowercase": return "lowercase";
      default: return "fallback";
    }
  }, { uppercase: "uppercase", lowercase: "lowercase", fallback: "fallback" })
  .addEdge("chatResponse", END);

return workflow.compile();

四个关键概念:

  • StateGraph:节点与边的容器,状态 GraphState(消息、输出、命令)在节点之间传递共享;
  • addNode:把一个函数注册为节点,例如意图识别 identifyIntent;
  • addEdge / addConditionalEdges:固定流转 vs 条件路由——后者就是工作流里的「分岔路口」;
  • compile():把图编译为可执行的工作流。

仓库里还有一个「AI 打败游戏 Duck Hunt」的例子,说明同一条「思考 → 行动 → 观察」的循环模式,在游戏智能体里同样成立:

Duck Hunt 游戏场景截图:智能体行动循环示例,理解 LangGraph 工作流的节点执行模型

三、路由节点(Router):用结构化输出做 LLM 决策

生产级图 production-graph.ts 的主流程是:

START → contexto(组装上下文) → roteador(路由) → react | planExecute | reflect → resposta(响应) → END

🧭 路由节点有四个关键设计(见 router.ts):

  1. 结构化输出:用 zod schema 约束 LLM 只能返回 { route, reason } 结构,通过 withStructuredOutput 调用,避免解析自由文本;
  2. 决策表 Prompt:router-prompt.ts 把决策表直接写进提示词,规则明确、可人工复核:
何时 路由
点查 / 简单工具调用(列告警、查状态、单个服务) react
多步骤请求 / 显式计划 / 涉及多个服务或步骤 planExecute
需要校验 / 高关键度 /「复核」/ 需要审计的回答 reflect
  1. 失败兜底:分类结果非法或调用失败时,不抛错,自动降级到 react 路由,并把原因(如 fallback: router failed; using react)记入 trace;
  2. 人工覆盖:请求体若显式传入 strategy,则跳过 LLM 直接走指定路由,trace 中标记 override: true。

条件边本身只有一行核心逻辑:

.addConditionalEdges("roteador", (s) => s.route ?? "react", {
  react: "react", planExecute: "planExecute", reflect: "reflect",
})

即使路由为空也默认落到 react,图永远不会「断线」。

四、Fallback 与 Retry:模型故障的三层降级策略

🔁 生产环境里,模型调用必然会遇到超时、5xx、限流。model.ts 用「唯一模型工厂 + 三层阶梯」解决:

层级 机制 行为
第 1 层 withRetry({ stopAfterAttempt: 2 }) 主模型(OPENROUTER_MODEL)瞬时故障自动重试
第 2 层 withFallbacks([backup]) 重试耗尽后切换到备用模型(OPENROUTER_MODEL_FALLBACK)
第 3 层 ModelUnavailableError → HTTP 503 全部失败时诚实返回 503,而不是编造回答

两个值得学习的细节:

  • Fallback 是可看见的:备用模型接管时,trace 会追加一条 type: "fallback" 事件(内容形如 主模型 → 备用模型),metrics.modelUsed 记录真正应答的模型 id,运维一眼看清降级;
  • 只有一个工厂:路由、策略、摘要器全部通过 createModel() 拿到同一套「带防护」的模型,不存在旁路的「裸」调用——这是整条防线成立的前提。

完整的验收标准与边界情况(例如备用模型等于主模型时只保留 retry、401 等非瞬时错误快速失败)见设计文档 014-model-resilience/spec.md。

五、可观测性:Trace 事件、结构化日志与请求审计

📊 「这个回答是怎么来的?」——答案是 TraceEvent 事件链。

  1. 类型化事件流:事件类型包括 thought / action / observation / plan / critique / answer / summarize / route / fallback,定义在 domain/types.ts;builder.ts 能把策略产生的消息历史自动转成「思考 → 工具调用 → 观察 → 回答」的 trace;
  2. 节点盖戳:stamp-node.ts 给每个事件盖上 node 字段,标明事件由图中哪个节点产生——契约要求 100% 事件覆盖(见 contracts/trace.md);
  3. 持久化与审计:第 7 单元(UNIDADE.md)把请求与 trace_events 写入 SQLite,GET /requests/:id 可回溯任意一次历史请求的完整推理链;GET /stats 按路由、按模型聚合请求量、错误率、延迟与 token;
  4. 结构化日志不泄漏内容:logger 只记录标量元数据(latencyMs、llmCalls、modelUsed……),「永不记录内容」这一规则甚至被写成了测试;
  5. 人工审批(Human-in-the-loop):破坏性操作可携带 awaitHumanApproval: true 发起,/chat 先返回 202 + approvalId,人工 POST /approvals/:id 批准后才真正执行。

金融账单、生产告警这类场景对 AI 的审计要求最高,而 LangGraph 的 trace + 审计正是这类 Fallback 与可观测性能力的用武之地:

Pix 金融应用账单页面截图:需要 Fallback 降级与可观测性保障的生产级 AI 工作流业务场景

六、快速上手:运行生产级 LangGraph 工作流

git clone https://gitcode.com/gh_mirrors/en/engenharia-de-software-com-ia-aplicada
cd engenharia-de-software-com-ia-aplicada/modulo04-criacao-de-agentes-autonomos-novo/06-langgraph-e-workflows-complexos
npm ci && cp .env.example .env   # 配置 OPENROUTER_API_KEY 与 OPENROUTER_MODEL_FALLBACK
npm run dev                      # POST /chat,由路由器自动决定策略
npm test && npm run typecheck

两个冒烟验证场景(详见 quickstart.md):

  • 不传 strategy:路由器自动分类,trace 中出现一条 route 事件,override 为 false;
  • 传 "strategy": "planExecute":直接执行对应节点,trace 标记 override: true。

七、关键文件与资料清单

资料 路径
单元 6 总览(生产图 + 模型弹性) UNIDADE.md
生产图实现(节点与条件边) src/graph/production-graph.ts
路由器与结构化输出 src/graph/router.ts
模型 retry/fallback 工厂 src/agents/model.ts
Trace 事件类型定义 src/domain/types.ts
生产图契约规格 contracts/production-graph.md
Trace 契约规格 contracts/trace.md
模型弹性规格(Fallback 与 503) specs/014-model-resilience/spec.md
新手状态图示例 02-langchain-intro

小结:生产级 LangGraph 工作流的精髓可以浓缩成四件事——用 StateGraph 管住流程、用结构化输出做安全路由、用 retry → fallback → 503 三层降级兜底模型故障、用 trace + 结构化日志 + 持久化审计让每一步决策可解释。仓库中的完整实现与无网络测试用例(npm test 全部用 fake 模型跑通),可以直接作为你项目的参考骨架。

登录后查看全文
engenharia-de-software-com-ia-aplicada