技术思考问题17：上了LangChain框架就等于AI-Agent工程化吗？
# 为什么需要 LangChain：从调 API 到搭应用的结构性鸿沟 > 裸调 API 能跑通，一进多步编排就散架。 ```text [读者] 正在把 LLM 从 Demo 推向生产的中高级工程师 [痛点] 裸调 API 重复代码多，多步链路难定位 [现在读] 因为单次调用的经验已经顶不住编排复杂度 [读完] 能判断何时抽象、何时保留直调 ``` ```text [旧方案] 裸调 SDK + 脚本拼装 | v [新需求] 多步、结构化、检索、工具调用 | v [冲突] 重复逻辑可复用，但硬套编排框架增加仪式感 | v [后果] 版本升级、调试和定位成本上升 ``` 我是老李，做过多套企业应用，也带过 LLM 应用从试点走向生产。最常遇到的不是模型能力不够，而是调用链一长，工程结构开始失控。 这次要说的系统是一套工单智能分类与处置建议服务。当前方案很朴素：一个 Python 脚本，直接调用模型 SDK，把工单文本塞进 prompt，再把返回文本切一切。 变化来得很快。业务要求增加知识库检索、结构化标签、工具调用、失败重试和人工兜底。脚本开始从一个文件长成一层一层复制粘贴的函数。 一次模型调用明明能跑通，为什么进入多步链路后，重复代码和不可定位的失败会一起出现？ 统一抽象一定让所有调用更简单吗，还是会给简单分类套上不必要的仪式？ 如果不引入编排框架，重试、超时、幂等和兜底到底应该由谁负责？ # 01、故事 现场是一套工单系统。任务是给每张工单分类，并生成一段可执行的处置建议。V1 只有一次模型调用，输入工单文本，输出一个标签和一句建议。 最初的代码很直接：读取工单、拼接提示词、调用模型、解析返回。业务量不大时，它稳定、好懂，改一行就能上线。 后来需求变成多步：先分类，再检索知识库，再生成建议，最后校验结构化输出；如果模型建议涉及退款或账号安全，还要调用工具查询订单状态。 团队试图继续用脚本拼装。分类、检索、生成三处各自维护 prompt、解析和异常捕获。每次加一个步骤，就多复制一段重试和日志。 冲突出现在这里：重复逻辑明明可以复用，但把简单分类硬套进整套编排，又会带来新的版本、调试和阅读成本。 > 单调用顺手 > 多步即散乱 > 抽象未落地 > 契约先失守 # 02、问题 旧方案失效不是模型突然变差，而是调用外围的工程组织开始失效。提示词、解析、检索、重试、兜底散落在多个函数里，没有统一定义。 业务影响很具体：处置建议偶发格式错误，人工需要重新判断；失败原因难以复现，值班同学只能从日志里猜是哪一步出错。 技术表现同样明确：同一类异常在多个文件中重复捕获；结构化输出没有统一 schema；重试没有幂等约束；超时设置分散，且互相覆盖。 可验证的完成标准可以写成四条：每个步骤有明确输入输出记录；结构化结果必须通过 schema 校验；失败能定位到具体步骤和原因；变更影响范围可以枚举，而不是靠搜索同名函数。 > 旧法非无错 > 错在无边界 > 边界未定义 > 重复必反噬 # 03、原理 芒格模型里有两个工具很适合这个问题。奥卡姆剃刀说，同样解决问题时，优先选择更少且可验证的假设与复杂度。机会成本说，评估一种选择时，要计入被它挤掉的其他投入。 把它们放进 LLM 应用：裸调 API 的假设是“模型输出即结果”。多步链路里，这个假设不再成立，因为还要校验、检索、重试和兜底。 反直觉判断：引入编排框架往往不是复杂度上升的主因，缺少契约才是。框架只是把散落的调用组织起来，契约才决定每一步是否可验证。 反直觉判断：抽象不一定减少代码行数。它可能增加少量结构，但减少的是重复决策、重复调试和重复回归。 官方文档的 LangChain overview 更适合用来核对当前 API 边界：https://docs.langchain.com/oss/python/langchain/overview 。腾讯云开发者社区那篇《为什么需要 LangChain：从调 API 到搭应用的结构性鸿沟》也讨论了同类结构问题：https://cloud.tencent.com/developer/article/2759677 。具体 API 和版本行为需按当前官方文档核验。 > 假设越少越清 > 验证越近越明 > 机会有价有本 > 取舍有据有界 # 04、架构 ```text [输入] 工单文本 + 用户画像 | v [模块] 契约层 / 编排层 / 策略层 | v [数据/状态] 结构化意图、检索片段、重试次数 | v [处理] 分类→检索→生成→校验→兜底 | v [输出] 标签、处置建议、人工复核标记 ``` 边界在于：契约层只定义输入输出结构和校验规则，不负责业务判断；编排层只负责步骤顺序和数据传递，不负责模型能力；策略层只负责重试、超时、幂等和兜底，不负责内容生成。 收益是重复逻辑集中、失败步骤可定位、结构化输出可校验。代价是引入抽象层后，简单调用也需要理解链式组织方式，并承担依赖版本变化带来的适配成本。 适用条件是多步组合、结构化输出、检索或工具调用同时存在。若只是单次轻量分类，这层架构的机会成本可能高于收益。 > 契约先定形 > 编排后定序 > 策略兜失败 > 边界即架构 # 05、实战一次 环境以 Python 3.11 为例，依赖 `langchain-core`、`langchain-openai`、`pydantic`。具体版本需按当前官方文档核验。未在当前环境实测，以下为预期结果。 先建虚拟环境并安装依赖： ```bash python -m venv .venv source .venv/bin/activate pip install langchain-core langchain-openai pydantic ``` 配置模型密钥和地址： ```bash export OPENAI_API_KEY='你的密钥' export OPENAI_BASE_URL='你的兼容地址' ``` 核心实现用最小 V1 跑通“分类 + 结构化输出”： ```python from typing import Literal from pydantic import BaseModel, Field from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI class TicketDecision(BaseModel): intent: Literal['refund', 'bug', 'consult', 'other'] = Field(description='工单意图') need_human: bool = Field(description='是否需要人工复核') reason: str = Field(description='判断依据，一句话') prompt = ChatPromptTemplate.from_messages([ ('system', '你是工单分类助手。只输出结构化结果，不要寒暄。'), ('human', '工单内容：{ticket}') ]) llm = ChatOpenAI(model='gpt-4o-mini', temperature=0) chain = prompt | llm.with_structured_output(TicketDecision) if __name__ == '__main__': result = chain.invoke({'ticket': '我上周买的会员想退款，找不到入口。'}) print(result.model_dump_json()) ``` 启动： ```bash python app.py ``` 请求后验证两件事：输出是否命中 `TicketDecision` 的字段；`intent` 是否等于 `refund`，`need_human` 是否为布尔值而不是字符串。 示例输出： ```json {"intent": "refund", "need_human": false, "reason": "用户明确表达退款诉求"} ``` V1 能跑通，但它只覆盖单步结构化调用。检索、工具、重试、幂等和兜底还没有进入同一条可观测链路。 > 先跑通一步 > 再谈多步链 > 未测不妄断 > 有证再优化 # 06、排查 现象一：升级依赖后，原有链式调用在参数上直接报错。怀疑是 API 行为变化。检查本地最小复现和官方文档当前示例，证据是同一段代码在锁定旧版本时可运行。根因是依赖未锁定，环境漂移把适配问题带进生产。 **错误尝试：** 直接把所有包降级到最早版本。这个做法错误，因为它把版本问题当成单个包的问题，忽略了 `langchain-core` 与模型适配包之间的传递依赖，可能引入新的不兼容。 现象二：结构化输出偶发解析失败。怀疑是模型输出格式漂移。检查原始返回，证据是部分返回包含 Markdown 代码围栏或额外解释。根因是提示词没有约束输出格式，解析层又把自然语言当 JSON 直接读取。 修复方式是把结构化输出校验前移，使用模型侧的结构化输出能力，或者保留原始文本并用 schema 校验失败后重试。重试策略必须带次数上限，并记录失败样本。 现象三：重试导致重复工单或重复工具调用。怀疑是网络抖动触发了多次执行。检查调用日志，证据是同一个工单 ID 在多个请求中出现。根因是重试没有幂等键，所有失败都被当成可重试。 修复方式是为每个业务步骤生成幂等键，并把超时、重试、兜底拆成独立策略，让它们可以被单元测试，而不是散落在业务代码里。 > 先看现象再找证 > 再找证据再定因 > 错试记录不白费 > 根因才现可修复 # 07、优化 根因一：依赖漂移。修改方式是锁定依赖版本，并增加一个最小契约测试，覆盖提示模板、结构化输出解析和链式调用。原因是版本变化属于常态化风险，测试比记忆更可靠。新行为是升级前先跑契约测试，失败就停止发布。 根因二：结构化输出缺少约束。修改方式是把输出契约写成 Pydantic 模型，在调用边界做 schema 校验；解析失败进入受控重试。原因是有明确 schema，失败才可分类。新行为是格式错误不再混入业务逻辑。 根因三：重试和幂等没有独立策略。修改方式是把策略抽成可测试对象，例如： ```python from dataclasses import dataclass from hashlib import sha256 @dataclass(frozen=True) class RetryPolicy: max_attempts: int = 3 timeout_s: float = 8.0 def idempotency_key(ticket_id: str, step: str) -> str: return sha256(f'{ticket_id}:{step}'.encode()).hexdigest()[:16] ``` 原因是重试、超时、幂等和兜底是横切关注点，放在业务函数里会让测试变难。新行为是同一策略可被多个链路复用，也能单独验证。 简单分类调用仍保留直调 SDK 的分支，不强行套入编排。验证方式是同一批任务上比较变更影响范围和定位耗时，不预设提升数字。 > 锁定依赖防漂移 > 显式契约可校验 > 抽出策略好测试 > 保留直调不硬套 # 08、演进 ```text [同一输入] | +--[V1] 裸调 + 脚本拼接 / 重复代码、难定位 | +--[V2] 统一契约 + 可测试策略 / 抽象与版本成本 | [Trade-off] 得到复用与可观测，失去简单调用的直接性，适用于多步组合 ``` 正确性上，V2 把结构化输出校验前移，比 V1 的文本解析更可控。稳定性上，V2 把依赖和策略显式化，但引入了抽象层自身的版本变化风险。 复杂度上，V2 增加了契约层和策略层，理解成本高于 V1。成本上，V2 需要维护测试和版本适配，机会成本是这些投入挤掉了其他优化项。 适用范围上，V2 适合多步、检索、工具调用和结构化输出并存的链路；单次轻量分类仍适合 V1 的直调方式。遗留问题是真实生产指标还需要在业务任务上持续采集，不能靠框架本身证明收益。 > 一版求能跑 > 二版求可证 > 得失同账算 > 适用即边界 # 09、洞见 ## 9.1 抽象要消灭重复劳动，不能制造新的仪式感 把分类、检索、生成都硬套进同一条链，代码看起来统一，实际把简单调用也拖入了编排、版本和调试成本。判断标准不是“用了框架没有”，而是是否有重复决策被消除。 反直觉判断：框架使用得越多，不代表工程能力越强；有时它只是把复杂度从业务代码搬到了依赖和配置里。 ## 9.2 框架不替代契约、测试和业务验收 LangChain 解决的是调用外围的工程组织问题，例如提示模板、结构化输出、链式组合和工具接入。它不替你定义业务字段，也不替你做验收。 反直觉判断：把模型输出接进框架，不等于输出就可靠；可靠来自 schema、测试和失败处理，而不是来自类名。 ## 9.3 最简单方案不是最少代码，而是最少可验证假设 奥卡姆剃刀不是“能不写就不写”，而是同样解决问题时，优先选更少且能验证的假设。单次分类的假设少，直接调用即可；多步链路的假设多，才需要统一接口和校验。 ## 9.4 机会成本要按任务级核算 评估是否引入编排，不能只看代码行数。被挤掉的是调试时间、变更影响范围、回归缺陷和每笔有效任务成本。单一指标很容易把复杂链路的收益算丢。 > 抽象去重复 > 契约定边界 > 假设要可验 > 成本按任务 # 10、系统落地 原来有的是一套裸调 SDK 的工单分类脚本，能完成单次分类，但多步链路靠复制和人工兜底。 本篇新增三层：调用链盘点、契约层和策略层。调用链盘点回答哪些步骤是多步组合；契约层定义结构化输出和校验；策略层承载重试、超时、幂等和兜底。 现在能做的事情更明确：复杂链路使用统一接口和结构化输出校验，单次调用保留 SDK 方案；重试、超时、幂等和兜底变成可测试策略；同一批任务可以比较代码变更成本、定位耗时和有效完成率。 还缺的是真实运行数据和长期维护策略。下一步是在同一批任务上记录故障定位时长、变更影响范围、回归缺陷和每笔有效任务成本，再决定哪些链路继续抽象。 若参考 LangChain 当前能力，需要以官方 overview 文档为准：https://docs.langchain.com/oss/python/langchain/overview 。相关结构性讨论可参考腾讯云开发者社区文章：https://cloud.tencent.com/developer/article/2759677 。 > 原有单调用 > 新增契约层 > 策略可测试 > 缺口是数据 # 11、小结 ```text Q1 → 多步链路需要契约和统一编排，重复逻辑才可复用 Q2 → 不是所有调用都该套框架，单次轻量分类保留直调 Q3 → 重试、超时、幂等和兜底应由明确策略层负责 状态 → 产出可判断 LangChain 使用边界的调用链基线 ``` Q1 的答案是：问题不在模型单次调用，而在调用外围的工程组织；契约和编排让多步链路可定位、可复用。Q2 的答案是：统一抽象有适用条件，简单分类硬套编排会增加版本和调试成本。Q3 的答案是：重试、超时、幂等和兜底不能散落在业务函数里，要抽成可测试策略。 本篇最终可交付的是一份调用链基线：能画清步骤，能判断复杂度，能在复杂链路上使用统一接口，也能在简单调用上保留直调。 > 问在单调用 > 答在多步链 > 界在任务级 > 证在可验收 # 12、作业 ## 12.1 理解题：奥卡姆剃刀在 LLM 应用里最容易被误用成什么？ 参考答案：容易被误用成“代码越少越好”。正确理解是同样解决问题时优先选择更少且可验证的假设与复杂度。单次调用可以用直调，多步链路才需要统一接口和校验。 ## 12.2 实战题：给一个“分类→检索→生成→校验”的链路画出调用链，并标出哪些部分应抽为策略层。 参考答案：调用链可分为输入、分类、检索、生成、校验、输出。检索和生成属于核心过程，分类和校验属于契约边界，重试、超时、幂等、兜底属于策略层。策略层应可独立测试，不应写进业务函数。 ## 12.3 排障题：结构化输出偶发解析失败，排查顺序是什么？ 参考答案：先看原始输出，确认是否有代码围栏或额外解释；再看提示词是否约束格式；再看是否使用结构化输出能力或 schema 校验；最后看失败是否进入受控重试。不要直接把所有解析失败当成模型问题。 ## 12.4 架构判断题：单次轻量分类是否应该引入 LangChain 这类编排框架？ 参考答案：不强制。单次轻量分类的假设少、调用链短，直调 SDK 的机会成本更低。只有出现多步组合、结构化输出、检索或工具调用时，才需要衡量编排收益。 > 题目问的是边界 > 答案给的是条件 > 实战先画调用链 > 判断先算机会账 # 13、思考 回到核心冲突：裸调 API 能快速跑通，多步编排却会暴露重复代码、隐式契约和不可定位的失败。LangChain 主要解决调用外围的工程组织问题，但它不能替代契约、测试和业务验收。 可复用的工程判断是：先画调用链，再判断复杂度；复杂链路使用统一接口和结构化输出校验，单次调用保留直调；重试、超时、幂等和兜底抽为可测试策略；基于同一批任务比较代码变更成本、定位耗时和有效完成率。 抽象要消灭重复劳动，不能制造新的仪式感。机会成本要按任务核算，而不是只看代码行数。奥卡姆剃刀要落在可验证假设上，而不是落在“看起来简单”上。 > 抽象去重复 > 契约定边界 > 取舍看任务 > 证据定去留
