企业官网建设流程全解析

LangChain 全景：从模型 SDK 到数字人 Agent 的选型与落地

直接调 SDK 到第三周就撑不住了，卡住我们的不是模型，是协议。

[读者] 正在把大模型接进业务系统的后端工程师与架构师 [痛点] 手写 SDK 调用越写越乱，多轮、工具、追踪全靠自己拼 [现在读] 数字人项目已进入联调，框架选型需要一次定型 [读完] 能判断何时用 SDK、LangChain 或 LangGraph，并跑通最小闭环

[旧方案] 直接调模型 SDK + 手写 while 循环拼消息 | v [新需求] 多轮记忆 / 工具调用 / 语音链路 / 全链路可观测 | v [冲突] 业务逻辑与模型协议细节缠死在一起，换模型=改主流程 | v [后果] 每加一个能力就重写一遍主流程，排障只能靠 print

我是老李，做过几年客服系统，去年下半年开始接手一个银行网点的数字人项目。屏幕里是一位会说话的数字员工，用户在网点大屏或手机 H5 上开口提问，它要能查余额、查物流、改地址、引导办业务。第一期我们没上任何框架，三个人直接拿模型 SDK 硬撸，两周就上线了单轮问答。

真正的麻烦是从第三周开始的。业务方要求“能记住上一句”“能自己查系统”“语气要像真人、回答要边想边说”，同时合规团队要求“每一句回答都能回溯到是哪个工具、哪版提示词产出的”。这三件事同时压下来，我们才发现原来的代码结构根本接不住。

当时团队里有个很典型的分歧：框架到底是帮你少写代码，还是给你套上一层看不见的黑盒？

如果继续手写循环，我们能在两周内补齐多轮和工具调用吗，还是会在第四周被排障拖死？

如果直接引框架，我们是省下了协议层的工作，还是把调试难度从“看自己的代码”变成了“猜框架的行为”？

选错了会怎样——是回滚到 SDK 重写一遍，还是硬着头皮在抽象层上再叠一层补丁，最后谁也说不清一句话是怎么生成的？

01、故事

项目背景很具体：网点数字人，前端是 Web 页面加 RTC 通道，后端要串起 ASR、大模型、TTS 和形象渲染四段。第一期我们只做文本问答：前端把用户问题发过来，后端调一次模型 SDK，把字符串返回去。代码不到两百行，跑得挺好。

第二期需求变了。任务是让数字人从“问答机”变成“能办事的员工”：要支持多轮追问、要能调用订单查询和地址修改两个内部接口、要在说话时把首句尽快吐给 TTS、还要把每轮的工具调用记录进审计日志。

我们按老办法改：在 while 循环里手工维护 messages 数组，手工解析模型返回的 function call，手工把工具结果拼回对话，手工记录日志。一周之后，主函数变成了六百行，里面混着协议解析、业务分支、异常兜底和日志埋点。

最难受的不是代码长，是没法定位问题。用户说“它答错了”，我们只能把整段对话打印出来，一行行肉眼比对，判断是模型没理解、工具没调、还是工具调了但结果没拼回去。

这时候再回头看那个问题：框架省下的是代码量，还是省下的是“可被验证的结构”？

需求先变一步
代码后乱一片
一处小小改动
牵动整个主流程

02、问题

旧方案失效的信号非常清晰，而且是从业务侧先冒出来的。

业务影响上：多轮对话里用户报过的订单号，第三轮就丢了，用户要重复说一遍；工具调用的成功率无法统计，因为根本没有结构化的调用记录；合规抽查要求“这句话为什么这么答”，我们只能给出一段日志文本，给不出工具入参与返回。

技术表现上：主流程是一个巨大的函数，模型调用、协议解析、业务分支三者耦合；更换模型供应商要改十几处；流式输出接不进去，因为整条链路是同步阻塞的；没有任何一处可以插入追踪探针。

于是我们把“这活儿算干完了”翻译成可验证的完成标准，一共四条：

第一，同一份业务代码，换模型只改一行配置，不改主流程。

第二，一次请求的完整链路——用户输入、模型决策、工具入参、工具返回、最终回复——能以结构化形式落库并可回放。

第三，多轮会话状态与业务代码分离，服务重启后会话可恢复。

第四，首句延迟可控，模型边生成边向下游推送，而不是等全文生成完再送 TTS。

这四条标准，本质上不是“要用框架”，而是“要把协议、状态、观测三件事从业务代码里剥出来”。框架只是实现手段之一。

旧法已到边界
新需逼出重构
标准先立再写
否则越改越乱

03、原理

要理解 LangChain 这类框架到底在做什么，得先看清模型 SDK 暴露的是什么。SDK 暴露的是“一次 HTTP 调用的封装”：你给它一串消息，它给你一个响应对象。它不关心你的会话、你的工具、你的追踪。

LangChain 做的事情，用一句话说：它把“消息”提升为一等数据结构，把“工具调用”标准化成一套模型无关的协议，再在这两者之上提供可组合的运行时。

拆开看是三层。langchain-core定义抽象：消息类型（SystemMessage、HumanMessage、AIMessage、ToolMessage）、提示模板、工具接口、Runnable 组合协议。langchain提供高层封装，比如模型初始化与 Agent 构造。langgraph提供低层编排，把一次会话建模成有状态的图，支持持久化与中断。langsmith则独立于运行时，负责追踪、评测与监控。

这里有个反直觉判断：框架最大的价值不是让你少写代码，而是让“模型行为”变成可以被观测和被替换的东西。少写代码是副产品，甚至是错觉——引入框架后你的总代码量未必下降，因为你多了一层配置和一层调试。真正的收益是：换模型不动业务、加工具不改主流程、出问题能回放。

第二个反直觉判断：抽象层的成本不在写的时候，在读的时候。手写循环时你一眼能看懂全部逻辑；上了框架，一次请求要穿过模型封装、工具绑定、Agent 循环、回调系统。所以框架能不能用，取决于你有没有同步把可观测性接上——没有追踪的框架，是纯粹的成本。

第三个判断关于 Agent：Agent 的本质不是“更聪明的模型”，而是“模型可以在循环里决定下一步调哪个工具”。一旦引入循环，你就必须回答三个问题：循环何时终止、状态存在哪里、失败如何回退。这三个问题不解决，Agent 就是不可控的。

抽象不是省码
是把协议定型
消息一旦成数
模型皆可替换

04、架构

放在数字人这条链路上，LangChain 并不占据全部，它只占据中间决策那一段。完整的请求流是这样的：

[输入] 用户语音 / 文本（Web / RTC 通道） | v [模块] ASR → LangChain Agent（模型 + 工具 + 提示模板） | v [数据/状态] 消息历史 + 会话状态（thread_id / checkpoint） | v [处理] 模型推理 → 工具调用 → 结果回填 → 生成回复 | v [输出] 分句文本 → TTS → 形象渲染（口型 / 表情）

这个结构里，LangChain 的边界非常明确：它负责“听懂之后怎么想、想完调什么、调完怎么说”，不负责音频流、不负责渲染、不负责会话路由。很多团队踩的坑就是把框架当成全栈方案，结果把 ASR 和 TTS 也塞进去，最后整条链路的延迟无法归因。

收益方面：消息模型统一后，ASR 传来的文本、系统提示、工具返回可以放进同一个消息列表，模型侧不需要为每种来源写适配；工具用统一接口声明，模型决策与业务实现解耦；Agent 循环由框架托管，业务只关心工具函数本身。

代价方面：多了一层抽象，调试链路变长；框架版本迭代快，API 变动需要跟进，生产环境必须锁版本；工具数量上去之后，工具描述本身会占用大量上下文，需要做筛选和分组。

适用条件也很清楚：当你的系统只有单轮问答、工具不超过两个、不需要审计回放时，直接用模型 SDK 更省事；当你需要多轮状态、多个工具、可观测与可替换模型时，框架的收益才开始为正。

一条链路五段
各段职责分明
边界先划清楚
再谈性能成本

05、实战一次

先把最小闭环跑通，再谈架构。环境以 Python 3.11 为基线，包版本以官方文档为准，下面这套 API 属于 LangChain 1.x 的写法，具体签名需按当前官方文档核验。

安装与配置：

python-mvenv .venvsource.venv/bin/activate pipinstall-Ulangchain langchain-openaiexportOPENAI_API_KEY="sk-***"# 使用兼容 OpenAI 协议的国内模型网关时，再加一行 base_url 配置exportOPENAI_BASE_URL="https://your-gateway.example.com/v1"

核心实现分三步。第一步，用init_chat_model初始化模型，这是“换模型只改一行”的落点：

fromlangchain.chat_modelsimportinit_chat_modelfromlangchain_core.messagesimportSystemMessage,HumanMessage model=init_chat_model("openai:gpt-4o-mini",temperature=0)msgs=[SystemMessage("你是银行网点的数字员工小粤，回答简短、口语化。"),HumanMessage("我的订单 A1001 到哪了？"),]resp=model.invoke(msgs)print(resp.content)# 1.x 提供 .text 便捷属性，需按当前版本核验

示例输出（未在当前环境实测，以下为预期结果）：

您好，我这边需要先查一下订单 A1001 的物流状态，稍等。

第二步，声明工具。工具的描述就是模型的决策依据，写得含糊，模型就不会调：

fromlangchain.toolsimporttool@tooldefquery_order(order_id:str)->str:"""根据订单号查询物流状态。当用户询问订单到哪了、什么时候到、是否发货时调用。 Args: order_id: 订单号，形如 A1001，仅字母 A 加四位数字。 """fake_db={"A1001":"已发货，预计明天送达"}returnfake_db.get(order_id,"未查询到该订单")

第三步，用 Agent 把模型和工具绑起来，形成一个可循环的决策单元：

fromlangchain.agentsimportcreate_agent agent=create_agent(model=model,tools=[query_order],system_prompt="你是数字员工小粤，涉及订单必须调用工具查询，不要编造。",)result=agent.invoke({"messages":[{"role":"user","content":"帮我查下 A1001"}]})forminresult["messages"]:print(type(m).__name__,getattr(m,"content",""))

启动后验证三件事：返回里是否出现了 ToolMessage（说明工具真的被调了）、AIMessage 的 content 是否基于工具结果、以及把init_chat_model换成另一个 provider 后主流程是否一行不用改。

这三步跑通，V1 就成立了。但它还留着三个明显的洞：状态在内存里、没有追踪、不支持流式。

先跑通再谈优
最小闭环为王
一行一行验证
方知哪里会漏

06、排查

现象一：用户问“帮我查订单 A1001”，数字人回“我没有查询权限”，工具一次都没被调用。

怀疑：模型能力不足，理解不了意图。检查：打印result["messages"]，看 AIMessage 里tool_calls是否为空；再看工具是否真的被绑定（create_agent的tools参数是否传了、bind_tools是否生效）；最后看工具函数的 docstring。证据：AIMessage 只有纯文本 content，tool_calls为[]，说明模型压根没打算调工具，而不是调用失败。根因：工具描述缺失——@tool只拿到了函数名，没有拿到“什么时候该用它”的语义，模型无法建立从用户意图到工具的映射。修复：补全 docstring 与参数说明，把触发条件写进描述里。

错误尝试：一开始我们把temperature从 0 调到 0.9，想让模型“更灵活地”去选工具。这是错的。工具选择取决于工具描述与参数 schema，属于结构化决策，跟采样随机性关系不大；调高温度只会让参数值出现幻觉，比如把 A1001 编成 A1002。后来我们把温度调回 0，把力气全部花在工具描述上，问题才解决。

现象二：第三轮对话开始，数字人忘了用户第一轮报过的订单号，用户被迫重复输入。

怀疑：模型上下文窗口不够。检查：打印每轮传入的消息列表长度和内容。证据：每次invoke传入的都是一个全新的单元素列表，历史消息从未被带进去。根因：Agent 默认是无状态的，create_agent只负责一次决策循环，不负责跨请求保存对话；我们以为“框架会记住”，实际上状态要靠 checkpointer 或自己维护。修复：把会话 ID 作为thread_id，接入持久化 checkpointer，让同一会话的消息自动累积。

现象三：数字人开口前的等待时间明显偏长，TTS 要等整段文本生成完才开始合成。

怀疑：TTS 性能问题。检查：在 Agent 调用前后打时间戳，发现耗时集中在模型生成阶段而非合成阶段。证据：日志显示模型调用是一次性返回完整文本，下游才开始工作。根因：整条链路用的是同步invoke，把“生成”和“播报”串行化了。修复：改用流式接口，按增量把文本分句推给 TTS，让首句尽早发声。

排查这件事有个共性：先确认是哪一段坏了，再猜为什么坏。我们最初三次判断，全部错在跳过证据直接归因。

现象先于猜测
证据重于经验
一次错误尝试
胜过十次盲改

07、优化

V2 的每一处改动，都对应第 06 章的一条证据，没有一处是“顺手重构”。

针对证据二（状态丢失），根因是会话状态没有归属，改法是把一次会话建模成一张状态图：节点负责“调模型”“执行工具”，边负责条件跳转，checkpointer 负责把每一步的消息列表按thread_id存下来。原因在于：状态一旦显式化，恢复、回放、人工介入才有挂载点。新行为是服务重启后同一thread_id的会话可以继续，且每一步都能被单独检视。验证方式：同一thread_id连发三轮，观察第二轮传入的消息列表是否包含第一轮内容。

针对证据三（首句延迟），根因是同步调用把生成与播报串行化，改法是改用流式模式，按消息增量向下游推送，并在标点处切句送给 TTS。原因在于：语音链路对首字延迟的敏感度远高于对总时长。新行为是模型开始吐字后，TTS 即可开始合成第一句。验证方式是记录“用户停止说话”到“首帧音频输出”的时间戳差值，这是可以在自己环境里量出来的，不需要引用任何外部数据。

针对证据一（工具不触发），根因是工具语义缺失，改法是把工具描述当成提示词工程的一部分来维护：写清触发条件、参数格式、反例；工具数量超过十个之后，按业务域分组，先做工具召回再绑定。原因在于：工具描述会持续占用上下文，无节制堆叠会挤压真正的对话内容。

最后补上可观测：把每一次模型调用、工具调用、状态流转打点到 LangSmith（或其兼容的追踪后端）。这一步不是“额外功能”，而是让前面所有改动的效果可被验证的前提。

注意，这一章里没有出现任何性能数字。原因很简单：延迟和成功率必须在你自己的机器和链路上量，任何从别处抄来的数字都不能作为你的验收依据。

根因若未坐实
优化只是搬运
改在关键一处
胜过遍地补丁

08、演进

同一个输入，两版实现的差别可以画成一张图：

[同一输入：用户说"帮我查 A1001，顺便把地址改成科技园"] | +--[V1] 单文件手写循环 | 行为：能答，消息在内存，换模型改主流程，出问题靠 print | 代价：每加一个能力就动一次主干，无法回放，无法审计 | +--[V2] LangGraph 状态图 + checkpointer + 流式 + 追踪 | 行为：状态显式、可恢复、可流式、每步可查 | 代价：多一层抽象，调试要跨过框架看内部，版本需锁定 | [Trade-off] 得到：可替换模型、可观测链路、可恢复会话、可增量输出 失去：一眼看懂全部逻辑的直观，以及一部分启动速度与学习成本 适用边界：单轮问答、工具极少、无审计要求时，V1 仍然是更优解

逐项比较。正确性上，V2 把工具调用变成结构化的 ToolMessage，参数错误可以在工具层拦截，比 V1 的字符串解析可靠。稳定性上，V2 的失败可以回退到上一个 checkpoint，V1 只能整段重来。复杂度上，V1 代码短但逻辑纠缠，V2 组件多但边界清晰，长期维护成本反而更低。成本上，V2 增加了框架依赖与追踪存储，需要版本管理与运维投入。适用范围上，V1 适合验证期和极简场景，V2 适合进入生产、需要多人协作与审计的场景。

遗留问题也要说清楚：工具数量增长后的上下文占用、多轮长会话的记忆压缩、语音链路里 ASR 误识别导致的错误工具调用，这三个问题在这一版里都没有彻底解决。

旧路快而难改
新路慢而可扩
取舍不在优劣
在你能担多少

09、洞见

9.1 框架卖的是协议，不是效率

回头看那次选型，最有价值的不是create_agent这一行代码，而是消息与工具被标准化之后带来的可替换性。我们后来把主力模型从一家换到另一家，业务代码一行没动，只改了一行初始化。这件事在 V1 里是不可想象的。反直觉判断：评估一个框架，不要看它让你少写多少行，要看它让你多改几处才能换掉一个依赖。换依赖的成本，才是架构的真实成本。

9.2 没有可观测的框架调用是负资产

我们在 V1 阶段其实也用过一次框架，结果一周后就退回去了，原因是“出了问题什么都看不见”。V2 之所以能立住，是因为追踪和状态回放同时到位。反直觉判断：可观测性不是上线后的运维功能，而是选型阶段就该纳入评估的第一等公民。一个不能被观测的抽象层，本质上是在业务代码和模型之间加了一堵不透明的墙。

9.3 Agent 越自由，状态越要收口

Agent 让模型自己决定调哪个工具，看起来很灵活，但灵活性直接换来的是不可预测的路径。我们最终把“能做什么”交给模型，把“做过什么”交给状态图，把“允许做什么”交给工具白名单。三者分开，系统才可控。如果让模型同时决定路径和记住路径，出问题时你连复现都做不到。

9.4 语音链路里，框架只占一段

数字人项目最容易犯的错，是把 LangChain 当成整条链路的中枢。实际上它只负责 ASR 之后、TTS 之前的决策环节。ASR 的断句、TTS 的分句策略、渲染的口型对齐，都有各自的工程问题，塞进框架只会让延迟归因变得不可能。边界清晰，比组件强大更重要。

9.5 术语是沟通工具，不是知识点

模型、消息、提示模板、工具、Agent、状态、可观测——这七个词的价值不在背诵，而在于团队开会时能一句话对齐“现在讨论的是哪一层”。我们后来定了一条规矩：任何一次故障复盘，必须明确落到七个术语中的一个，否则不许开会。这条规矩比任何文档都管用。

洞见来自现场
判断生于证据
反直觉处深思
方得不虚之言

10、系统落地

原来我们有什么：一个可以直接调模型 SDK 的文本问答服务，一套手写的消息拼接逻辑，一份只能靠人读的日志。

本篇新增了什么：一层标准化的消息与工具协议，一张带状态与检查点的会话图，一条从模型调用到工具执行的追踪链路，以及一套流式输出到 TTS 的推送机制。

现在能做什么：换模型只改配置；新增业务工具只写一个函数加一段描述；会话可以跨重启恢复；每次回答都能回溯到具体的工具入参与模型输出；首句可以边生成边播报。

还缺什么：长会话的记忆压缩策略、工具规模增长后的动态召回、ASR 误识别引发的错误调用的兜底、以及多轮对话的自动化评测集。这四件事目前都靠人工兜底。

下一步怎么演进：先把评测集建起来，让每次提示词或工具描述的改动都有回归基线；再考虑把工具按业务域拆成子图，用图的组合替代单图膨胀；最后把可观测数据接进告警，让“工具调用失败率突增”这类问题从人工发现变成自动发现。

原有先理清楚
新增才知轻重
能做什么写明
缺什么别遮掩

11、小结

Q1 手写循环还能不能撑住？ → 撑不住，但不是因为代码长，而是因为协议、状态、观测三件事和业务缠在了一起 Q2 引框架省下的是代码还是结构？ → 省下的是结构；代码量未必下降，多出来的是配置和一层调试成本 Q3 选错了会怎样？ → 要么回滚重写，要么在抽象层上叠补丁；判断依据是有没有同步把可观测接上 状态 → 已具备一套可替换模型、可恢复会话、可回溯链路的数字人问答骨架

这一篇交付的不是“会用 LangChain”，而是一次完整的判断：什么时候该用模型 SDK，什么时候该上 LangChain，什么时候必须上 LangGraph，以及在任何一种选择下，都必须自己承担的那部分工程责任。

三问皆有着落
一环已然闭合
状态可以交付
能力可以复现

12、作业

12.1 理解题：LangChain、LangGraph、LangSmith 各自解决什么问题？

参考答案：LangChain 提供模型、消息、提示模板、工具与 Agent 的高层抽象，解决“怎么写”的问题；LangGraph 提供有状态的图编排、持久化与中断恢复，解决“状态和流程怎么管”的问题；LangSmith 提供追踪、评测与监控，解决“怎么知道它做得对不对”的问题。三者是分层关系，不是替代关系，小项目可以只用第一层。

12.2 实战题：把一个手写 while 循环的问答服务改成用create_agent实现，要求换模型只改一行。

参考答案：先用init_chat_model把模型初始化抽成一处配置；把原来手工解析的函数调用改成@tool装饰的函数，写清 docstring 与参数说明；用create_agent(model=..., tools=[...], system_prompt=...)替代 while 循环；最后用第二个 provider 实例化一次模型，验证主流程代码零改动即可运行。注意版本 API 需按当前官方文档核验。

12.3 排障题：数字人始终不调用你写好的工具，而是自己编答案，怎么查？

参考答案：按顺序排除。先看返回消息里 AIMessage 的tool_calls是否为空，为空说明模型没有决策调用，问题在工具描述而非执行；再检查 docstring 是否写清了触发条件与参数格式；再确认工具是否真的绑定到了 Agent；最后确认所选模型支持工具调用能力。不要一上来就调温度或改提示词，那是没有证据的猜测。

12.4 架构判断题：业务方要求“数字人记住用户上周说过的偏好”，应该加在哪里？

参考答案：这不是提示词问题，而是状态归属问题。短期会话内用 checkpointer 按thread_id保存；跨会话的长期偏好应当落到业务侧的画像存储，作为每次请求的输入注入，而不是让对话状态无限增长。判断标准是：这份数据属于“这次对话”还是“这个用户”，前者归图状态，后者归业务系统。

题在纸上易答
事在现场难断
动手一遍便知
哪里才是真难

13、思考

这次选型留给我的最硬的一条经验是：不要在“用不用框架”这个层面做决策，要在“协议、状态、观测这三件事由谁负责”这个层面做决策。

模型 SDK 把这三件事全部留给你，所以它简单、直接、可控，适合验证期和极简场景；框架把这三件事接管过去，所以它换来可替换性与可回放性，代价是你必须多承担一层理解成本。而如果只接管了协议却没有接管观测，那这层抽象就是纯亏损。

同样重要的是认清边界。数字人这条链路上，LangChain 只占中间一段，ASR、TTS、渲染各有各的工程问题。把边界划清楚，比把组件堆强大更有价值。

最后是一个更朴素的判断：任何一次架构升级，如果说不清“改完之后，什么问题从不可解变成可解”，那它就不是升级，只是搬家。

一念辨边界
一证定根因
一改知取舍
一役见真章