1. 从“感觉流”到“工程流”两种编程范式的本质差异1.1 什么是 Vibe Coding它为什么突然火了Vibe Coding 这个词最早在开发者圈子里流传开来描述的是一种“跟着感觉走”的编程方式。你打开编辑器脑子里有一个模糊的目标然后开始跟 AI 对话——“帮我写一个函数接收用户 ID返回订单列表”“不对再加个时间范围过滤”“把返回格式改成 JSON”。整个过程没有详细的设计文档没有严格的类型定义甚至没有完整的测试用例全靠你和 AI 之间的来回对话把代码“聊”出来。这种方式之所以能火核心原因是它把编程的门槛降到了历史最低点。以前你想做一个 side project得先想清楚数据模型、接口设计、状态管理然后一行行敲代码。现在你只需要把想法用自然语言描述出来AI 就能给你一个能跑的版本。对于原型验证、快速试错、个人小工具开发来说Vibe Coding 的效率是传统方式的数倍。我自己的体验是用 Vibe Coding 做一个简单的 CLI 工具或者数据处理脚本从想法到能跑起来可能只需要十几分钟。这在以前是不可想象的。但问题也随之而来——当你试图把这个“能跑”的东西变成“能维护”的东西时麻烦就开始了。1.2 Vibe Coding 的天花板在哪里Vibe Coding 最大的问题在于状态管理和上下文一致性。当你跟 AI 对话到第 20 轮的时候它可能已经忘记了第 3 轮你定义的某个关键约束。你让它改一个函数它可能会把之前约定好的错误处理逻辑给删掉。你让它加一个功能它可能会引入一个跟你现有架构完全不兼容的依赖。更麻烦的是Vibe Coding 产出的代码往往缺乏可观测性。你很难知道 AI 在每一步到底做了什么决策为什么选择这个方案而不是那个方案。当代码出问题的时候你面对的是一个黑盒——你知道输入和输出但中间的推理过程完全不可见。还有一个容易被忽视的问题是测试的缺失。Vibe Coding 的节奏太快了快到你可能根本来不及写测试。而没有测试的代码就像没有安全网的走钢丝——能走多远全靠运气。1.3 LangGraph 带来的范式转换LangGraph 的出现本质上是在解决 Vibe Coding 留下的烂摊子。它把 AI 应用的开发从“对话式”变成了“图式”。你不再是通过对话让 AI 帮你写代码而是用图结构来定义 AI 的行为——每个节点是一个具体的操作每条边是一个条件判断整个图就是一个完整的状态机。这个转变的意义在于它把 AI 应用的开发从艺术变成了工程。你可以清晰地看到数据在每一步是如何流动的可以在任意节点插入日志和监控可以对每个节点单独进行测试。更重要的是图结构天然支持循环和条件分支这意味着你可以实现复杂的重试逻辑、人工审核环节、多轮对话管理——这些在纯对话式开发中极其困难的事情。LangGraph 和 LangChain 的关系也值得说清楚。LangChain 提供的是组件——LLM 封装、提示词模板、输出解析器、向量存储等等。而 LangGraph 提供的是编排——如何把这些组件组织成一个有状态的、可循环的、可中断的工作流。你可以把 LangChain 想象成乐高积木LangGraph 则是说明书和底板告诉你这些积木该怎么拼、拼成什么形状。2. LangGraph 核心概念拆解节点、边与状态2.1 状态图一切从 State 开始LangGraph 的核心抽象是状态图StateGraph。你首先需要定义一个状态对象这个对象会在图的各个节点之间传递。状态可以是一个简单的字典也可以是一个带有类型注解的 TypedDict 或者 Pydantic 模型。from typing import TypedDict, Annotated from langgraph.graph import StateGraph, END class AgentState(TypedDict): messages: list next_step: str retry_count: int这个状态定义决定了整个图的“记忆”范围。每个节点接收当前状态返回一个更新后的状态。LangGraph 会自动合并这些更新——默认是覆盖但你可以通过Annotated来指定合并策略比如operator.add用于列表追加。我踩过的一个坑是状态字段太多会导致图变得难以维护状态字段太少又会导致节点之间需要传递额外的参数。我的经验是把状态分成三类——输入状态初始化时设定、中间状态节点间传递、输出状态最终结果。这样结构会清晰很多。2.2 节点每个节点只做一件事节点是 LangGraph 中的基本执行单元。每个节点就是一个 Python 函数接收状态返回状态更新。节点的设计原则是单一职责——一个节点只做一件事做好一件事。比如在一个客服机器人中你可能有这些节点classify_intent判断用户意图retrieve_knowledge检索相关知识generate_response生成回复human_review人工审核每个节点都可以独立测试独立替换。你想把意图分类从关键词匹配换成 LLM 分类只需要改classify_intent这一个节点其他部分完全不受影响。节点的另一个重要特性是可中断性。你可以在任意节点设置interrupt_before或interrupt_after让图在执行到该节点时暂停等待外部输入。这是实现 Human-in-the-Loop 的关键机制。2.3 边控制流的三种形态LangGraph 支持三种类型的边普通边是最简单的从节点 A 直接到节点 B无条件跳转。条件边允许你根据当前状态决定下一步去哪个节点。你需要提供一个路由函数它接收状态返回下一个节点的名称。def should_continue(state: AgentState): if state[retry_count] 3: return give_up if state[next_step] tool: return call_tool return respond graph.add_conditional_edges( agent, should_continue, { call_tool: tools, respond: respond, give_up: END } )入口边和条件入口边用于定义图的起点。入口边从一个虚拟的START节点出发条件入口边则允许你根据输入动态选择起始节点。这三种边的组合让 LangGraph 能够表达任意复杂的工作流。你可以实现循环通过条件边回到之前的节点、并行多个节点同时执行、分支根据条件走不同的路径。2.4 检查点让状态可以持久化LangGraph 的检查点机制是我最喜欢的功能之一。它允许你在每一步之后自动保存状态这样即使程序崩溃或者需要人工介入你也可以从上次中断的地方继续执行。from langgraph.checkpoint.sqlite import SqliteSaver memory SqliteSaver.from_conn_string(:memory:) graph workflow.compile(checkpointermemory) config {configurable: {thread_id: user-123}} graph.invoke({messages: [...]}, config)检查点的价值在于它把有状态的 AI 应用变成了可能。你可以实现多轮对话、长时间运行的任务、需要人工审批的流程——这些在无状态的 API 调用中极其困难。3. 从零搭建一个 LangGraph 工作流完整实操3.1 环境准备与依赖安装先说一下环境。我推荐用 conda 来管理 Python 环境因为 LangGraph 和 LangChain 的依赖比较多用 conda 可以避免很多版本冲突问题。conda create -n langgraph-demo python3.11 conda activate langgraph-demo pip install langgraph langchain langchain-openai如果你需要用本地模型可以额外安装langchain-community和对应的模型库。我实测下来Python 3.11 的兼容性最好3.12 在某些依赖上还有问题。注意LangGraph 的版本更新很快建议锁定版本号避免因为自动升级导致 API 不兼容。我一般会在 requirements.txt 里写死版本。3.2 定义状态与节点函数我们来实现一个简单的“研究助手”工作流。这个助手接收一个问题先判断是否需要搜索如果需要就调用搜索工具然后根据搜索结果生成回答最后让用户确认是否满意。from typing import TypedDict, Annotated import operator from langgraph.graph import StateGraph, END class ResearchState(TypedDict): question: str search_results: Annotated[list, operator.add] answer: str user_feedback: str retry_count: int状态定义好了接下来写节点函数。第一个节点是analyze_question判断问题是否需要搜索。def analyze_question(state: ResearchState): question state[question] # 这里可以用 LLM 来判断为了演示先用简单规则 need_search any(kw in question for kw in [最新, 2024, 2025, 新闻]) return {search_results: [], retry_count: 0}第二个节点是search执行搜索并返回结果。def search(state: ResearchState): # 实际项目中这里会调用搜索 API results [f关于{state[question]}的搜索结果1, f关于{state[question]}的搜索结果2] return {search_results: results}第三个节点是generate_answer基于搜索结果生成回答。def generate_answer(state: ResearchState): context \n.join(state[search_results]) if state[search_results] else 无搜索结果 answer f基于以下信息回答问题\n{context}\n\n问题{state[question]} return {answer: answer}第四个节点是human_review等待用户反馈。def human_review(state: ResearchState): # 在实际应用中这里会暂停等待用户输入 # 演示中我们直接返回满意 return {user_feedback: 满意}3.3 构建图与条件路由节点写好了现在把它们组装成图。workflow StateGraph(ResearchState) workflow.add_node(analyze, analyze_question) workflow.add_node(search, search) workflow.add_node(generate, generate_answer) workflow.add_node(review, human_review) workflow.set_entry_point(analyze) workflow.add_conditional_edges( analyze, lambda state: search if state[search_results] [] else generate, {search: search, generate: generate} ) workflow.add_edge(search, generate) workflow.add_edge(generate, review) workflow.add_conditional_edges( review, lambda state: end if state[user_feedback] 满意 else generate, {end: END, generate: generate} ) app workflow.compile()这个图的结构是分析问题 → 如果需要搜索则搜索 → 生成回答 → 人工审核 → 如果不满意则重新生成。3.4 运行与调试运行图很简单result app.invoke({ question: 2025年AI编程有哪些新趋势, search_results: [], answer: , user_feedback: , retry_count: 0 }) print(result[answer])调试的时候我强烈建议开启 LangGraph 的追踪功能。你可以用 LangSmith 来可视化整个执行过程看到每个节点的输入输出、耗时、状态变化。这对于排查问题非常有帮助。实操心得在开发阶段我会在每个节点里加print语句输出当前状态。虽然原始但比任何调试工具都直接。等逻辑稳定了再移除。4. Human-in-the-Loop 与多 Agent 协作实战4.1 人工介入的三种模式LangGraph 实现 Human-in-the-Loop 有三种模式我分别说一下适用场景。审批模式在关键节点前暂停等待人工批准。比如 AI 要执行一个删除操作先暂停让人类确认。实现方式是interrupt_before[delete_node]。编辑模式在节点执行后暂停允许人工修改状态。比如 AI 生成了一个回复人工可以编辑后再发送。实现方式是interrupt_after[generate_node]。输入模式在节点执行前暂停等待人工提供额外信息。比如 AI 需要用户提供更多细节才能继续。实现方式是在节点内部调用interrupt()。from langgraph.types import interrupt def ask_for_clarification(state): user_input interrupt(请提供更多信息) return {question: state[question] user_input}4.2 多 Agent 协作的图结构设计LangGraph 天然适合多 Agent 协作。你可以把每个 Agent 定义为一个子图然后用一个主图来编排它们之间的交互。常见的多 Agent 模式有主管模式一个主管 Agent 负责分配任务多个工作 Agent 负责执行。主管根据任务类型决定调用哪个工作 Agent。流水线模式多个 Agent 按顺序执行每个 Agent 的输出是下一个 Agent 的输入。适合有明确阶段划分的任务。辩论模式多个 Agent 对同一问题给出不同答案然后由一个仲裁 Agent 来综合判断。适合需要多角度分析的任务。def create_agent_graph(agent_name, tools): agent_workflow StateGraph(AgentState) agent_workflow.add_node(agent, lambda s: call_agent(s, agent_name)) agent_workflow.add_node(tools, lambda s: call_tools(s, tools)) agent_workflow.set_entry_point(agent) agent_workflow.add_conditional_edges(agent, should_use_tool, {tools: tools, end: END}) agent_workflow.add_edge(tools, agent) return agent_workflow.compile()4.3 状态共享与隔离的权衡多 Agent 协作时状态管理是一个关键决策点。所有 Agent 共享一个全局状态还是每个 Agent 维护自己的状态共享状态的好处是信息透明Agent 之间可以直接看到彼此的输出。坏处是状态会变得很大而且容易出现命名冲突。隔离状态的好处是每个 Agent 可以独立演化互不干扰。坏处是需要额外的机制来传递信息。我的经验是核心状态共享中间状态隔离。把最终结果、关键决策、用户输入这些放在共享状态里把每个 Agent 的中间推理过程放在各自的局部状态里。5. 常见问题排查与性能优化5.1 图执行卡住或死循环这是最常见的问题。原因通常是条件边没有正确终止或者循环没有退出条件。排查方法先用app.get_graph().draw_mermaid()把图结构画出来检查是否有环。然后在每个节点加日志看执行到哪一步开始重复。解决方案给循环加一个计数器超过阈值就强制退出。def should_continue(state): if state.get(retry_count, 0) 5: return end return continue5.2 状态更新丢失或覆盖LangGraph 默认是覆盖式更新。如果你在节点 A 返回了{messages: [msg1]}在节点 B 返回了{messages: [msg2]}最终状态里只有[msg2]。解决方案是用Annotated指定合并策略from typing import Annotated import operator class State(TypedDict): messages: Annotated[list, operator.add]这样msg1和msg2都会被保留。5.3 性能优化减少不必要的 LLM 调用LLM 调用是最大的性能瓶颈。优化思路有三个缓存对相同的输入缓存 LLM 的输出。LangChain 提供了set_llm_cache接口。批处理把多个小请求合并成一个大请求。比如把 10 个独立的分类任务合并成一个批量分类请求。路由优化用轻量级模型做路由决策只在必要时调用重量级模型。比如用关键词匹配做初步筛选只有匹配不明确时才调用 LLM。5.4 常见问题速查表问题现象可能原因排查方法解决方案图执行卡住条件边未终止检查路由函数返回值加循环计数器状态字段丢失覆盖式更新打印节点返回值用 Annotated 合并LLM 调用超时网络或模型问题查看日志加重试和超时内存占用过高状态累积过多监控状态大小定期清理中间状态检查点写入失败数据库连接问题检查连接配置用内存检查点调试6. 从 LangChain 到 LangGraph 的迁移策略6.1 什么时候该用 LangGraph不是所有项目都需要 LangGraph。如果你的应用是简单的“输入 → LLM → 输出”模式用 LangChain 的 Chain 就够了。LangGraph 的价值在于复杂控制流——需要循环、分支、人工介入、多 Agent 协作的场景。我的一般判断标准是如果你的流程用流程图能画出来而且流程图里有环或者有多个决策点那就该用 LangGraph。如果是一条直线走到底LangChain 的 LCEL 更简洁。6.2 渐进式迁移的步骤从 LangChain 迁移到 LangGraph我建议分三步走第一步把现有的 Chain 拆解成独立的节点函数。每个 Chain 的每一步就是一个节点。第二步用 StateGraph 把这些节点串起来。先用普通边确保流程能跑通。第三步把需要条件判断的地方改成条件边把需要循环的地方加上回边。这个过程不需要一次性完成可以边迁移边测试。LangGraph 的节点函数和 LangChain 的 Chain 可以共存你可以在节点里调用现有的 Chain。6.3 工业智能体开发中的实际案例我之前参与过一个工业质检的智能体项目。需求是接收质检图片判断是否有缺陷如果有缺陷则生成报告报告需要人工审核审核不通过则重新生成。用 LangGraph 实现的话图结构是这样的workflow StateGraph(InspectionState) workflow.add_node(classify, classify_image) workflow.add_node(generate_report, generate_report) workflow.add_node(human_review, human_review) workflow.add_node(finalize, finalize_report) workflow.set_entry_point(classify) workflow.add_conditional_edges(classify, lambda s: generate_report if s[has_defect] else finalize, {generate_report: generate_report, finalize: finalize}) workflow.add_edge(generate_report, human_review) workflow.add_conditional_edges(human_review, lambda s: finalize if s[approved] else generate_report, {finalize: finalize, generate_report: generate_report})这个图清晰表达了业务逻辑而且每个节点都可以独立测试和替换。人工审核环节通过interrupt实现审核员在界面上看到报告点击通过或驳回图会自动继续执行。7. 一些踩坑之后的经验之谈7.1 状态设计宁简勿繁我一开始做 LangGraph 项目的时候恨不得把所有东西都塞进状态里。结果状态对象越来越大节点之间的依赖越来越复杂最后改一个字段要动好几个地方。后来我学乖了状态只放必须跨节点传递的数据。节点内部的临时变量、中间计算结果能不放状态就不放。状态越简单图越好维护。7.2 节点函数保持纯粹节点函数最好是纯函数——给定相同的输入总是返回相同的输出不依赖外部变量不产生副作用。这样测试起来非常方便你不需要启动整个图只需要单独调用节点函数就行。如果节点需要调用外部服务比如数据库、API把这些调用封装成独立的函数在节点里调用。这样你可以用 mock 来测试节点逻辑而不需要真的连数据库。7.3 日志和追踪要趁早加不要等到出问题了才想起来加日志。在项目初期就把日志框架搭好每个节点入口和出口都打日志。LangGraph 配合 LangSmith 可以自动记录每一步的状态变化但自定义的业务日志还是需要自己加。我一般会在节点里加这样的日志import logging logger logging.getLogger(__name__) def my_node(state): logger.info(fEntering my_node, state keys: {list(state.keys())}) result do_something(state) logger.info(fExiting my_node, result keys: {list(result.keys())}) return result7.4 版本锁定与升级策略LangGraph 还在快速迭代中API 变化比较频繁。我的做法是生产环境锁定版本开发环境定期升级测试。升级之前先看 changelog确认没有破坏性变更。如果有先在开发环境跑一遍完整的测试用例确认没问题再升级生产。最后分享一个小技巧LangGraph 的draw_mermaid方法可以生成图的可视化我习惯在每次修改图结构后都跑一下把生成的图保存下来。这样代码审查的时候 reviewer 可以直观地看到图结构的变化比看代码快多了。这个领域变化很快今天的最佳实践可能明天就被推翻了。保持学习保持动手比什么都重要。
