我见过太多团队在 demo 阶段一切丝滑一到生产环境就开始一天三崩。不是代码写错了而是有 10 个坑开发阶段根本没机会踩到偏偏上线后一个接一个地冒出来。这篇我把这 10 个坑全部列出来附真实代码附修复方案。你现在花 10 分钟读完能省掉上线后 3 天的排查时间。01 Thread ID 当用户 ID 用一个会话污染另一个踩坑场景直接把用户 ID 当thread_id用上线后发现用户 A 的第二次对话带着上次的记忆甚至 A 的问题偶尔混入 B 的回复里。根源LangGraph 的thread_id是会话级别的不是用户级别的。同一用户的不同对话共用一个状态快照状态在每次invoke里累积不会自动重置。// ❌ 错误用户 ID 直接做 thread_id旧对话状态永久累积constawaitinvokemessagesnewHumanMessageconfigurablethread_id// ✅ 正确每次新对话生成独立 thread_idimportasfromuuidasyncfunctionstartNewConversationuserId: string, input: stringconst${userId}-${uuidv4()}// 用户 ID 唯一 uuidawaitsaveThreadcreatedAtnewDatereturnawaitinvokemessagesnewHumanMessageconfigurablethread_id错误用法正确用法thread_id userIdthread_id userId - uuid()每个用户只有一个 thread每次对话创建新 thread旧对话状态永久累积旧对话可归档清理02 State 越来越大消息列表无限膨胀 大对象塞进 State踩坑场景一上线一周后某些重度用户 token 消耗暴增调一次模型传入 30,000 tokens费用直接翻几十倍——messages数组存着这个用户从第一次对话到现在的全部历史每轮都全量传给模型。踩坑场景二Postgres checkpointer 写入速度越来越慢某些请求要等 3-5 秒——有团队把文件 Buffer、完整 API 响应直接放进 State单条 checkpoint 记录超过 50MB。LangGraph 在每个 super-step 都会序列化整个 State 写入 checkpointState 越大写入越慢。importfromlangchain/core/messages// ✅ 方案一节点入口裁剪消息历史推荐asyncfunctionchatNodestate: typeof StateAnnotation.StateconsttrimMessagesmessagesmaxTokens4000strategylasttokenCounterincludeSystemtrueconstawaitinvokereturnmessages// ✅ 方案二State 只存引用大对象存外部存储constGoodStateAnnotationRootmessagesAnnotationBaseMessagereducerdefault() fileRefAnnotationstringdefault() // 只存 S3 keyapiResponseSummaryAnnotationstringdefault() // 只存摘要asyncfunctionprocessNodestate: typeof GoodState.State// 需要时才按需加载处理完不回写原始数据constfileRefawaitgetObjectKeyfileRefpromisenullreturnapiResponseSummarysummarizeState 该存什么State 不该存什么对话消息列表加窗口限制文件二进制内容关键元数据ID、状态标记完整 API 原始响应引用URL、S3 key大型嵌套 JSON03 工具报错直接崩图没有兜底的错误节点踩坑场景外部 API 一旦超时整个 graph 调用直接抛出未捕获异常用户侧 500日志里啥信息都没有。更糟糕的是如果这个请求已经写了 checkpoint下次用户重试时graph 从中断点续跑再次调用同一个失败工具进入死循环。// ✅ 工具层捕获异常返回结构化错误State 层加错误计数路由consttoolasynctryconstawaitPromiseracesearchnewPromise(_, reject) setTimeout() rejectnewErrortimeout5000returnJSONstringifysuccesstruedatadatacatch// 不 throw返回错误信息让 LLM 感知并决策returnJSONstringifysuccessfalseerrormessagesuggestiontry rephrasing or use fallbacknamesearchschemaobjectquerystring// State 加错误计数超 3 次自动走降级节点constStateAnnotationAnnotationRootmessagesAnnotationBaseMessagereducerdefault() errorCountAnnotationnumberreducer(a, b) default() 0functionrouteAfterToolsstate: typeof StateAnnotation.StatestringiferrorCount3returnerror_handlerreturnagent04 条件路由陷入死循环 并发 Thread 写入冲突踩坑场景一死循环某些复杂查询让 LLM 陷入反复调用同一个工具的循环一次请求持续跑了 20 分钟把 OpenAI quota 跑爆了。踩坑场景二并发冲突用户快速重复提交偶发性出现「state mismatch」或「checkpoint version conflict」错误。复现概率低但每天总会发生几次——两个请求同时用同一个thread_id调用graph.invoke后写的那个因 checkpoint 版本冲突失败。importMutexfromasync-mutex// ✅ 死循环防护State 加迭代计数 路由强制退出 框架层 recursionLimitconstStateAnnotationAnnotationRootmessagesAnnotationBaseMessagereducerdefault() iterationCountAnnotationnumberreducer(a, b) default() 0asyncfunctionagentNodestate: typeof StateAnnotation.StateconstawaitbindToolsinvokemessagesreturnmessagesiterationCount1// 每次 1functionrouteAgentstate: typeof StateAnnotation.StatestringifiterationCount10returnEND// 超 10 次强制结束returnmessagesat1tool_callslengthtoolsEND// 框架层硬限制constawaitinvokeconfigurablethread_idrecursionLimit25// ✅ 并发冲突防护应用层加 thread 级别互斥锁constnewMapstringMutexfunctiongetThreadLockthreadId: stringMutexifhassetnewMutexreturngetasyncfunctionhandleUserMessagethreadId: string, input: stringreturngetThreadLockrunExclusiveasyncinvokemessagesnewHumanMessageconfigurablethread_id05 SubGraph 状态不同步父子 Graph 状态传递出错踩坑场景SubGraph 执行完了父 Graph 里的finalAnswer永远是空字符串。查了半天发现是 SubGraph 的输出字段名和父 Graph 的字段名不匹配LangGraph 没有自动映射也没有报错状态就这么静悄悄地丢了。LangGraph 规则SubGraph 和父 Graph 通过共同拥有的字段名传递状态字段名必须严格对应。// ❌ 错误SubGraph 的 result 字段父 Graph 里根本不存在数据丢失constSubGraphStateBadAnnotationRootinputAnnotationstringdefault() resultAnnotationstringdefault() // ← 父 Graph 里没有 result// ✅ 正确SubGraph State 必须包含父 Graph 的传出字段名constParentStateAnnotationRootmessagesAnnotationBaseMessagereducerdefault() finalAnswerAnnotationstringdefault() // 父 Graph 字段constSubGraphStateGoodAnnotationRootmessagesAnnotationBaseMessagereducerdefault() finalAnswerAnnotationstringdefault() // ← 和父 Graph 严格同名internalStepsAnnotationstringreducer(a, b) default() 06 Human-in-the-Loop 超时后续跑Graph 状态卡死踩坑场景数据库里有几百个INTERRUPTED状态的 checkpoint 从来没有被恢复占着存储资源。更糟糕的是有些用户几天后才想起来点「确认」按钮结果触发了几天前的操作业务逻辑全乱了。// ✅ 中断时记录超时时间节点入口检查是否已过期超时自动取消constStateAnnotationAnnotationRootmessagesAnnotationBaseMessagereducerdefault() interruptedAtAnnotationnumbernulldefault() nullinterruptTimeoutMsAnnotationnumberdefault() 30601000// 30 分钟asyncfunctionreviewNodestate: typeof StateAnnotation.StateifinterruptedAtconstDatenowinterruptedAtifinterruptTimeoutMsreturnmessagesnewAIMessage操作超时已自动取消。interruptedAtnullifinterruptedAtreturninterruptedAtDatenow// 先记录中断时间constinterruptmessage请确认操作pendingActionreturnapprovedActioninterruptedAtnull07 LangSmith 全量追踪 InMemoryCheckpointer 上生产数据泄露 全部丢失踩坑场景一数据泄露LangSmith dashboard 上能看到所有用户完整对话记录包括手机号、支付信息。原因是开发时设置了LANGCHAIN_TRACING_V2true忘记在生产环境关闭。踩坑场景二对话全丢这个坑听起来明显但我见过好几个团队在「先跑起来」的心态下用了 MemorySaver结果一次发版部署客服被打爆——所有用户的对话全没了。// ❌ 生产环境两个最常见配置错误// LANGCHAIN_TRACING_V2true ← 全量上报所有用户数据到 LangSmith隐私问题// const checkpointer new MemorySaver() ← 进程重启即全丢// ✅ 生产环境正确配置// LANGCHAIN_TRACING_V2false ← 关闭 LangSmith 追踪或只传脱敏 metadataimportPostgresSaverfromlangchain/langgraph-checkpoint-postgresconstPostgresSaverfromConnStringenvDATABASE_URLawaitsetup// 首次初始化只需一次constcompile// 重启不丢数据// 如果需要追踪只传脱敏 metadataconstawaitinvokeconfigurablethread_idmetadatauserIdhashUserId// 脱敏不传原始 PIICheckpointer 选型对比Checkpointer重启持久多实例共享适用场景MemorySaver❌❌本地开发、单测PostgresSaver✅✅生产首选RedisSaver✅✅高并发、短会话SqliteSaver✅❌单机部署总结这 10 个坑每一个我都亲眼见过或亲手踩过Thread ID 要设计成会话级不是用户级用户 ID 是身份标识会话 ID 才是状态容器State 要管好边界消息列表加窗口限制大对象只存引用别让 checkpoint 无限膨胀工具层要自己兜底永远不要让外部 API 的异常裸抛返回结构化错误让 LLM 感知并决策循环要有出口并发要加锁条件路由加计数器同一 thread 的并发请求串行化双重保险SubGraph 字段名要严格对齐父子 Graph 通过共同字段名传递状态不匹配会静悄悄丢数据生产 checkpointer 必须持久化追踪必须脱敏MemorySaver 只能本地用LangSmith 配置别带进生产学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】