如何用LangGraph构建生产级复杂工作流:图、路由、Fallback与可观测性完整指南(engenharia-de-software-com-ia-aplicada)
如何用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 应用,从电商智能推荐到金融账单分析,背后都有这类工作流在支撑:
图编排的核心价值在于:把「流程」变成代码。每一步是节点(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」的例子,说明同一条「思考 → 行动 → 观察」的循环模式,在游戏智能体里同样成立:
三、路由节点(Router):用结构化输出做 LLM 决策
生产级图 production-graph.ts 的主流程是:
START → contexto(组装上下文) → roteador(路由) → react | planExecute | reflect → resposta(响应) → END
🧭 路由节点有四个关键设计(见 router.ts):
- 结构化输出:用 zod schema 约束 LLM 只能返回
{ route, reason }结构,通过withStructuredOutput调用,避免解析自由文本; - 决策表 Prompt:router-prompt.ts 把决策表直接写进提示词,规则明确、可人工复核:
| 何时 | 路由 |
|---|---|
| 点查 / 简单工具调用(列告警、查状态、单个服务) | react |
| 多步骤请求 / 显式计划 / 涉及多个服务或步骤 | planExecute |
| 需要校验 / 高关键度 /「复核」/ 需要审计的回答 | reflect |
- 失败兜底:分类结果非法或调用失败时,不抛错,自动降级到
react路由,并把原因(如fallback: router failed; using react)记入 trace; - 人工覆盖:请求体若显式传入
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 事件链。
- 类型化事件流:事件类型包括
thought / action / observation / plan / critique / answer / summarize / route / fallback,定义在 domain/types.ts;builder.ts 能把策略产生的消息历史自动转成「思考 → 工具调用 → 观察 → 回答」的 trace; - 节点盖戳:stamp-node.ts 给每个事件盖上
node字段,标明事件由图中哪个节点产生——契约要求 100% 事件覆盖(见 contracts/trace.md); - 持久化与审计:第 7 单元(UNIDADE.md)把请求与 trace_events 写入 SQLite,
GET /requests/:id可回溯任意一次历史请求的完整推理链;GET /stats按路由、按模型聚合请求量、错误率、延迟与 token; - 结构化日志不泄漏内容:logger 只记录标量元数据(latencyMs、llmCalls、modelUsed……),「永不记录内容」这一规则甚至被写成了测试;
- 人工审批(Human-in-the-loop):破坏性操作可携带
awaitHumanApproval: true发起,/chat先返回202 + approvalId,人工POST /approvals/:id批准后才真正执行。
金融账单、生产告警这类场景对 AI 的审计要求最高,而 LangGraph 的 trace + 审计正是这类 Fallback 与可观测性能力的用武之地:
六、快速上手:运行生产级 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 模型跑通),可以直接作为你项目的参考骨架。


