照文档跑通一个 Demo 不难，难的是换成自己的模型、自己的数据还能跑起来。这篇按「装环境→跑通最小链路→接检索→排查报错」的顺序，把 LangChain 应用开发里最容易卡住的几步拆开讲，每一步都给可复现的动作和对照判断，不追新特性，只求能落地。
照官方文档跑通一个 Demo 其实不难，难的是把示例里的模型换成自己的、把玩具数据换成公司文档之后，它还能跑起来。大多数卡点不在框架本身，而在「模型侧没通」「切分没切对」「报错没分层看」这几件事上。这篇按装环境、跑最小链路、接检索、排查报错四个阶段拆开讲。
每个阶段都只给可复现的动作和判断标准：什么情况下说明这一步过了，什么情况下说明问题在别处。不追新特性，也不假设你用的是某一家模型，只求换成你自己的东西还能落地。
第一步：把环境和模型接上
新手最容易犯的错，是把模型是否可用和框架是否串通混在一起调。一旦报错，你分不清是接口地址错了、密钥没读到，还是封装类选错了。顺序应该是反过来的：先让模型侧单独能用，再把它塞进 LangChain。
- 先脱开框架直连模型用最朴素的方式调一次接口，确认接口地址、密钥、模型名三项对齐。能返回内容说明模型侧通了，不通就别往下走。
- 只装必需依赖LangChain 相关包按官方文档装最少的那几个，别顺手升级所有依赖。装完立刻跑一次最小调用验证，而不是继续装别的。
- 分清封装类对话模型和文本补全模型用的是不同的封装类，选错会一直提示参数不匹配。拿不准就看返回体结构，对话类是消息数组，补全类是纯文本。
- 一次只改一个变量从「能调通」到「跑通链路」之间，每改一处就跑一次。同时改模型、改参数、改提示词，出了错你没法归因。
判断这一步是否真的过了，标准很简单：脱离 LangChain 直接调模型能稳定返回，且参数是你预期的。做不到就补模型侧，别在框架里绕。什么情况下不适用？如果你用的是托管平台的一体化 SDK，模型和框架本来就绑定，那就跳过这步分层的判断。
第二步：跑通一条最小链，再往上加
最小链的骨架就三件：提示词模板、模型、输出解析。把它当成后面所有例子的地基，输入是什么、输出是什么，先在纸上写清楚，再写代码。这样后面加任何东西，你都知道哪一层被动过。
跑通之后别急着加功能，先用固定输入连着跑几遍，看输出稳不稳定。不稳定先查温度这类采样参数，再谈框架问题——很多「模型答得飘」其实是参数问题，不是链路问题。
| 要加的能力 | 先确认的事 | 别急着做的事 |
|---|---|---|
| 记忆 | 基准输入跑一遍，原来链路没坏 | 一上来就接数据库存历史 |
| 多步串联 | 每一步的中间输出能打印出来 | 把整条链藏进一个函数里 |
| 条件分支 | 分支判断依据是结构化字段 | 用自然语言描述当判断条件 |
| 工具调用 | 单工具能独立调通 | 直接上多工具编排框架 |
需要多步工具调用的场景，先到 /stacks/frameworks 里的框架与 SDK 目录对比一下能力边界，确认轻量方案真的不够用，再上重框架。否则你会被框架自己的抽象层拖住，调错都不知道错在哪。
第三步：接检索，做一个能答自己资料的例子
检索问答是 LangChain 里最像「成品」的例子，也最容易翻车。常见现象是模型答得一本正经但完全不对，多数时候不是模型的问题，是检索根本没把对的片段找回来。所以切分、嵌入、检索、拼提示词这四步要分开调。
- 切分：先只看切出来的片段，人工判断是不是连贯、有没有被拦腰截断
- 嵌入：确认嵌入模型跟你的语种和领域匹配，中文尤其吃这一口
- 检索：给定一个问题，看召回的前几条是否真的相关，不相关就别看回答
- 拼提示词：把召回片段和问题拼好，先检查拼出来的内容，再看模型输出
挑嵌入模型时，维度和多语言支持是首要看的项，可以到 /embeddings 页对照当时的模型信息再选，术语拿不准就去 /ai-dict 查。判断标准是：你拿几个真实问题去检索，召回的片段能不能肉眼看出相关。看不出相关，后面调提示词都是白费。
检索不准时的调整顺序是：先调切分粒度，再调召回条数，最后才动提示词。跑得慢或显存不够，先看嵌入模型和对话模型是不是挤在同一张卡上，可以到 /models/deploy 做一遍部署测算再决定拆不拆。
报错排查顺序：从外到内，别跳步
LangChain 的报错信息经常指不到真正的病灶，因为它把好几层包在一起。有效的做法是固定一个从外到内的排查顺序，每一步都能排除掉一整类原因，而不是到处乱改。
- 脱离框架调模型接口能通说明问题在框架层，不通说明是模型侧。连通性和延迟基线可以到 /tools/speed-test 测一遍，留个参照。
- 看数据结构组件之间传的是对象不是纯字符串，字段名对不上会静默失败或返回空。先打印中间对象，别假设它是对的。
- 查版本同一个类在不同大版本里参数名可能不一样，看到参数不匹配的报错，先查你装的版本和文档是否一致。
- 最后看网络与限流接口偶发失败、长文本被截断，多半是超时或并发限流，不是代码逻辑。要不要加缓存和重试按实际失败率决定，别默认全加上。
什么情况下这个顺序不适用？如果你的应用是本地全离线部署，网络那一层可以跳过，但前两步依然要按顺序走。判断标准始终是：每一步都得出一个明确的「是这边的问题」或「不是这边的问题」，而不是猜。
先让模型自己能用，再让框架把它串起来；先看检索对不对，再怪模型胡说。下一步如果你要换成自己的模型或自己的资料，先把站内对应页面的当前信息核对一遍再动手，能省掉大半返工。→
常见问题
有没有必要一开始就用 LangChain，直接调接口不行吗？
就单个提示词、单轮问答来说，直接调接口更简单，少一层依赖少一堆版本问题。LangChain 的价值在于把提示词模板、模型切换、检索、多步串联这些重复劳动标准化，一旦你开始接多个模型或要串检索和多步流程，它的收益才显现。判断标准是：如果三个月后你要换模型或换数据源，改动量是不是很大。
跑示例报错但看不太懂，通常卡在哪？
按概率排：依赖版本冲突、模型返回结构与解析器预期不一致、密钥或接口地址配错、本地服务没起来。排查顺序就是先脱离框架直调接口，再逐层加回组件。把每一步的输入输出打印出来看，比读报错栈快得多。
本地模型和应用框架怎么配合比较稳？
本地推理服务尽量用 OpenAI 兼容接口暴露出来，LangChain 侧当普通云端接口用，这样换成本地还是云上只改地址和模型名。注意本地服务的上下文长度和并发上限一般比云上低，长对话要及时截断。具体的调用入口和兼容情况可以到 /official-api/providers 找对应平台页面核对。
