langchain 学习初探系列写到第二篇，这一篇专门围绕 model 展开。说实话，我一开始以为 model 就是拿 API 密钥换一个模型对象，真正开始写项目才发现，模型这一层的封装和细节比想象中多——模型形态怎么选、消息结构怎么传、参数怎么配、报错怎么排查，每一项都有不少坑。这篇文章会把我在 langchain 里折腾 model 的完整过程记录下来，包括初始化配置、消息结构、流式调用、链内多模型协作，以及 model not found 这类高频报错的排查方法。适合正在学 langchain、尤其是被模型调用问题卡住的朋友参考。
1. 为什么单独把 model 拎出来讲
1.1 model 是整个 langchain 工作流最先被调用的一环
先交代一下背景：上一篇我已经把 langchain 的基本概念过了一遍，知道它有模型、提示词、链、记忆、代理这些抽象模块。但真正动手写第一个能跑的项目时，发现所有模块都是围绕 model 展开的——prompt 要传给 model，记忆要喂给 model，链的核心执行者是 model，代理做决策的也是 model。说白了，model 就是整个工作流的发动机。
所以我决定先把 model 吃透。如果发动机没调明白，后面所有花活都建立在沙地上。举个例子：你在链里配了一个模型，但初始化参数没设对，或者消息结构传错了，报错的时候不会直接告诉你是 model 的问题，而是会在某个链的中间环节爆出来，排查起来非常绕。反过来，如果 model 这一层你心里有数，链、代理、记忆这些上层组件出问题的时候，你就知道边界在哪里，能快速判断是不是模型层的问题。
langchain 之所以值得学，很大一部分原因在于它对 model 层做了一层抽象。不同的模型服务，接口格式千差万别，但 langchain 把它们收敛成一套统一的调用方式。也就是说，你这套业务代码里写的是 ChatModel 的 invoke、stream、batch，换后端服务的时候，只改初始化那几行配置，链路层、记忆层、代理层基本不用动。这一点是 langchain 最值钱的地方，也是我愿意花一整篇把它讲清楚的原因。
1.2 三种模型形态怎么选：对话型、文本补全型、嵌入型
langchain 里说的 model，其实不是一个东西。它至少分成三个形态，选错形态会直接导致调用方式不匹配。
第一是对话型模型，也就是 Chat Model。它接收的是消息列表，每条消息带角色（系统、用户、助手），返回的也是一条消息。现在的主流模型基本都是这个形态，因为它能表达多轮对话的上下文结构，也是 langchain 里链、代理、记忆组件默认对接的形态。
第二是文本补全型模型，也就是 LLM 接口。它接收一段纯文本，返回续写的文本，更接近早期语言模型的调用方式。现在一些文本处理类和工具链场景还在用，但对话模型已经是绝对主流。
第三是嵌入模型，也就是 Embedding Model。它把文本转成一个高维向量，主要给向量检索、知识库问答用，和对话模型完全是两条技术路线。
一开始我没分清这三个形态，写代码的时候把一个对话型的调用方式硬套在文本接口上，参数对不上，折腾了小半天。后来才意识到：学习顺序应该是先搞懂 Chat Model，文本补全和嵌入在需要的时候再补。如果你是按对话模型的消息结构来学，链、代理、记忆这些上层组件全部能顺下来，不会做无用功。
1.3 我的模型选型思路与实战场景对照
选模型这件事没有标准答案，跟你跑的业务场景强相关。我的思路是分三层来看：
- 效果优先的场景，比如内容生成、复杂推理，选能力强的云端模型，上下文窗口大、推理质量高，代价是成本和延迟会高一些。
- 成本敏感的场景，比如批量分类、结构化信息抽取，选同服务商的轻量模型，速度和成本都友好，虽然单次质量略低，但这类任务本身对创造性要求不高。
- 数据敏感或者需要离线运行的场景，用本地模型服务，自己下载权重，通过兼容接口暴露给 langchain。灵活但环境依赖多，最容易出 model not found 这类问题。
这三类我都试过。云端模型配置起来最省事，只要把 API 密钥和模型名填对就行；本地模型最折腾，端口、模型名、加载状态、版本前缀，任何一个环节不对都会报错。后面第 5 章我会专门讲排查路径。
2. 模型初始化与参数配置，手把手过一遍
2.1 两种常见初始化写法，以及我推荐哪种
langchain 里初始化模型，常见的是两种写法。
第一种是把一个模型对象直接构造出来，代码直观可控，适合项目里明确知道要用哪家模型服务的场景。大致长这样：
from langchain_openai import ChatOpenAI model = ChatOpenAI( model="your-model-name", temperature=0.7, )如果走的是这一种，api_key 和接口地址默认从环境变量读。如果你用的是兼容 OpenAI 协议的服务，也可以在构造函数里显式传 base_url 和 api_key，指向你自己的服务地址。
第二种是 langchain 提供的一个统一初始化入口，通过字符串来指定模型标识符和供应商：
from langchain.chat_models import init_chat_model model = init_chat_model( "your-model-name", model_provider="your-provider", temperature=0.7, )这种写法更适合写通用代码或者做配置化管理——模型名、供应商都放到配置文件里，代码不用改。我后来把项目改成这种写法，因为要同时对接几个不同模型服务，统一入口维护成本低很多，换一个模型只改一行配置。
两种写法没有谁绝对更好，看你的场景。单服务、求简单就直接构造对象；多服务、要灵活就上 init_chat_model。下面代码里的占位符，记得替换成你实际用的模型标识符和供应商标识。
2.2 环境变量和密钥管理，别把密钥写进代码
配置模型绕不开 API 密钥。我最开始直接把密钥写在代码里，后来发现风险很大——代码一提交到仓库，密钥也跟着进了版本历史，非常被动。后来统一改成环境变量管理：
import os from dotenv import load_dotenv load_dotenv() # 从项目根目录的 .env 文件加载 api_key = os.getenv("YOUR_API_KEY") if not api_key: raise ValueError("缺少 API 密钥，请检查环境变量配置")注意 .env 文件要加进 .gitignore，别提交到仓库。另外不同服务商的密钥命名习惯不一样，我的做法是在 .env 里统一用项目前缀，比如 APP_LLM_API_KEY、APP_LLM_BASE_URL，然后在代码里做一次映射，后面换服务商只改 .env，代码完全不动。
如果是本地模型服务，配置方式的重点在于 base_url 和 api_key。很多本地服务走的是兼容接口，你只需要把 base_url 指向本地的监听地址，比如 http://127.0.0.1:11434/v1 这种形式，具体端口以你用的服务为准，api_key 用任意非空字符串占位就行。最容易出问题的点在于：本地服务是否真的加载了你指定的模型、端口是否被占用、模型加载了但名字带版本前缀。这三件事我都分别踩过一遍，后面排查章节会展开。
2.3 4 个关键参数：temperature、max_tokens、timeout、max_retries
模型初始化时有几个参数几乎天天要调，我按自己的使用频率整理一下。temperature 控制回答的随机性，取值越低输出越确定，越高越有创造性。写代码、做数据抽取这类任务，我习惯设 0 到 0.3，保证输出稳定；做创意文案、头脑风暴，会调到 0.8 以上。注意不同服务商对 temperature 的支持范围不完全一样，超范围会在请求阶段直接报错。
max_tokens 控制单次回复的最大长度。这个参数很容易被忽略，我踩过两次坑：一次是让模型生成一份详细报告，没设这个参数，模型在输出中途被截断；另一次是设得太小，输出被硬生生切断在半句话上。建议根据任务复杂度设置，并给输出预留足够余量。
timeout 和 max_retries 这两个参数新手容易忽略。timeout 是单次请求的超时时间，网络不稳定或者模型推理慢的时候，不设 timeout 可能导致请求长时间挂起，整个服务被拖住；max_retries 是失败后的重试次数，遇到瞬时错误时能自动恢复。这两个参数直接关系到你服务的稳定性，生产环境一定要配。
3. 消息结构、多轮对话与流式输出
3.1 三种消息角色，分清边界很重要
对话模型的消息是有角色的，langchain 里最常用的三种是 SystemMessage、HumanMessage、AIMessage。SystemMessage 是系统提示，用来设定模型的身份和行为边界；HumanMessage 是用户输入；AIMessage 是模型的历史回复。
调用的时候把消息列表传给模型：
from langchain_core.messages import SystemMessage, HumanMessage messages = [ SystemMessage(content="你是一名严谨的技术文档工程师，回答要简洁、准确。"), HumanMessage(content="请解释一下什么是 model context window。"), ] response = model.invoke(messages) print(response.content)这里有一个很容易犯的错：把 SystemMessage 的内容和 HumanMessage 混在一起。虽然目前很多模型对消息角色不太敏感，但它会影响你在做多轮对话时的历史结构，建议从一开始就把角色分清楚。后面接记忆组件的时候，系统消息和对话历史往往要走不同的处理通道，角色混在一起会非常难受。
另外，消息对象的 content 不一定只是字符串，有些模型支持多模态内容，把图片、音频、文档作为消息的一部分传进去。这属于进阶玩法，这里先知道有这回事，等基础流程跑通再去尝试也不迟。
3.2 多轮对话的历史维护，模型不会自动记住
多轮对话的本质，是把历史消息拼进消息列表再一起发给模型。我刚开始做聊天机器人时，天真地以为模型会自动记住之前说过什么，实际上对话模型大多是无状态的，每次调用都是全新的输入，上下文全靠你在消息列表里手动带历史。
所以正确的姿势是：维护一个消息队列，每轮把用户消息和模型回复追加进去，下一次请求时把完整的消息列表传过去。但这里有个很现实的问题——历史消息无限膨胀，很快会撞上上下文窗口上限。我的处理办法是只保留最近 N 轮消息，同时把更早的内容压缩成一段摘要，既保留关键信息又不撑爆上下文。这个方案在长对话场景下实测比较稳定，你可以直接抄作业。
还有一个小细节：构造历史消息时，建议按 user 和 assistant 交替的顺序排列，并且保证最后一条是用户消息。有些模型对消息顺序敏感，顺序乱了会降低回复质量，甚至出现角色错乱的问题。
3.3 流式输出、批处理和异步调用怎么选
聊天的体验，流式输出几乎是刚需。langchain 里调用 stream 方法就能拿到流式结果：
for chunk in model.stream(messages): print(chunk.content, end="", flush=True)这里要注意，流式返回的是一个个增量块，你需要自己拼接内容，而不是一次性拿到完整回复。如果是在 Web 服务里，可以把块通过网络协议实时推给前端，体感会好很多。
批量场景用 batch，一次传多组输入：
result = model.batch([ [HumanMessage(content="第一条问题")], [HumanMessage(content="第二条问题")], ])异步场景用 ainvoke 和 astream，在异步框架里很常用，不会阻塞事件循环。我自己的经验是：能用 async 的地方尽量用 async，尤其是一个服务要并发处理多个用户请求时，同步等待模型返回会让吞吐量低得可怜。如果你的项目是同步的，也要考虑用线程池把耗时的模型调用丢到后台，别在主线程里硬等。
4. 模型在链与代理里的实战配合
4.1 一条链串联多个模型，省成本又保质量
很多人以为一条链只能有一个模型，其实可以多个，而且这种设计很常用。我做过一个实际项目：第一步用一个轻量模型做文本分类，判断内容属于哪一类；第二步把分类结果拼进提示词，交给一个更强的大模型做生成。这样既省成本，又保证了关键步骤的生成质量。
你可能会问，分类这种活儿用一个轻量模型和一个强模型都能干，为什么非要分两步？因为分类任务本身的判断逻辑很简单，轻量模型跑得快、费用低；而生成任务需要语言组织能力和知识调用，强模型明显更好。把任务按难度拆开，让不同模型干各自擅长的事，是控制成本和延迟的核心思路。
串联的方式不复杂，核心是把前一个模型的结果作为后一个模型的输入。用 RunnableLambda 包装你的逻辑，再按顺序拼起来。设计多模型链时，关键是明确每一步的职责边界，不要让两个模型抢同一个活儿，那样只会白白增加延迟和成本。
4.2 模型回退机制，生产环境必备
稳定性是生产环境里最容易被忽略的事。某个模型服务偶尔会过载、限流，甚至短暂不可用。如果你只有单一依赖，用户体验就是断崖式的。langchain 提供了回退机制，可以给主模型配一个备用模型：
main_model = init_chat_model("your-main-model", model_provider="your-provider") backup_model = init_chat_model("your-backup-model", model_provider="your-provider") model_with_fallback = main_model.with_fallbacks([backup_model])这样主模型失败时，会自动尝试备用模型。我建议备用模型选一个不同服务商或者不同技术栈的，因为如果主和备都在同一个服务商，服务商整体故障时回退就失效了。这一点很容易被忽略，等你真正遇到整条链路集体不可用的时候，就会后悔没做差异化。
回退不只能配在单模型上，还能配在整个链上。你可以给一个完整的链配上备用链，这样任何一步失败都有兜底。代价是复杂度上升，所以我的建议是先从单模型回退开始，跑通了再考虑链级回退。
4.3 和 langgraph 结合做有状态的流程
langchain 生态里，langgraph 是处理复杂、有状态流程的主流方案。它把流程描述成一张图，节点是处理函数，边是流转关系。模型在图形里通常出现在"执行"类的节点上。
一个最简流程是：用户问题进入节点，模型生成回答，然后根据回答内容走不同分支。这种设计比单纯的链多了一个状态管理的维度，适合需要记忆、循环、条件跳转的任务。langgraph 里，每个节点函数接收当前状态，返回状态更新，图的边决定了下一步去哪。模型调用就是节点的核心动作。
我建议学到这里的时候，先把单个模型的调用在 langgraph 里跑通，再往里面加记忆和工具，一步步搭。别一开始就把图画得太复杂，否则排查问题非常痛苦。我见过不少人一上来就想做一个多智能体协作的复杂图，结果状态字段对不上、节点顺序乱掉，最后连问题出在哪都找不到。小步快跑，先把地基打稳。
5. model 相关高频报错排查速查表
5.1 model not found 到底哪里没对上
这个报错我遇到的次数最多。第一次是在本地模型服务上，明明服务启动成功了，但调用时一直提示找不到模型。排查了一圈，最后发现是模型标识符和本地服务里加载的模型名没对上——模型服务端加载的名字带了一个版本标记，而我代码里写的是别名。
所以遇到这类报错，按下面的顺序查：
- 核对代码里的模型标识符是否和服务文档一致，注意有没有版本后缀或路径前缀。
- 确认服务端是否真的加载了目标模型，有的服务需要先主动加载才能被调用，光启动进程还不够。
- 检查模型名是不是被某个配置文件里的默认值覆盖了，代码传参不一定优先级最高。
- 如果是走统一入口初始化，确认 model_provider 和 model 名称的组合是服务商支持的，有些模型只存在于特定供应商的目录下。
5.2 model is at capacity 是服务端过载
selected model is at capacity 这类提示，说明服务端的资源已经被占满或触发限流了。这不是你代码的 bug，我一开始以为是配置错了，反复排查浪费了很多时间。
处理思路就几个：一是做好重试，加上退避策略，不要密集重试把服务端的限流状态越搞越重；二是临时切换备用模型，生产环境一定要有，否则用户请求会大量失败；三是如果某个时段经常 capacity，可以考虑错峰调用，或者换一个负载更小的模型实例。在本地模型服务上，这类问题通常表现为显存不足、推理线程全被占满，处理思路类似——降低并发，或者换更小的模型。
5.3 上下文超限怎么处理
上下文超限是另一类高频问题，报错里通常会出现 maximum context length 的字样。原因很简单：你传给模型的输入太长，超过了模型的上下文窗口。最容易踩的雷是直接把整份文档拼进提示词，文档一大，一个请求就爆了。
我的处理思路分三层：先压缩输入，无用的背景信息去掉，只保留跟任务直接相关的内容；再分段处理，把长文档拆成小块分别调用，需要汇总再做一次聚合；最后按需选更大的窗口模型。注意，模型的最大上下文是输入加输出共用的，不是只算输入，所以给回复预留的空间也要考虑进去。比如上下文是 128k，你输入用了 120k，回复空间就只剩 8k，超出照样报错。
5.4 配置文件相关的几个检查点
有些报错乍一看跟模型没关系，比如启动工具时报 config.toml 相关错误。这类问题的根源往往是配置文件缺失、路径不对，或者配置里的模型名写错了。我整理了一个简单的检查顺序：
- 配置文件是否存在，路径是否和你运行时的工作目录匹配。很多人改了配置，但进程是在另一个目录下启动的，读的根本不是那份文件。
- 配置里的模型名是否真实存在，注意大小写和下划线，模型中这些细节非常敏感。
- 配置是否被环境变量覆盖，环境变量的优先级在很多工具里高于配置文件。
- 改完配置后，是否重启了相关进程，很多工具只在启动时读取一次配置。
这套顺序帮我解决了不少看起来神秘的问题。很多时候不是模型本身的问题，而是配置链路里的某一个环节没对上，把配置当成第一嫌疑人去查，往往能快速定位。
6. 一个完整示例：分类路由 + 模型回退
这里放一个完整的可跑示例，占位符按你的实际服务替换。这个例子实现的是：用户输入问题，系统先做分类，再让模型根据分类结果生成回答，并且带了回退机制。
from langchain.chat_models import init_chat_model from langchain_core.messages import SystemMessage, HumanMessage from langchain_core.runnables import RunnableLambda, RunnablePassthrough main_model = init_chat_model("your-main-model", model_provider="your-provider") backup_model = init_chat_model("your-backup-model", model_provider="your-provider") model = main_model.with_fallbacks([backup_model]) def classify(question: str) -> str: # 这里用简单的关键词规则代替分类模型，实际项目可以换成真正的分类模型 keywords = ["安装", "配置", "报错", "启动"] return "troubleshooting" if any(k in question for k in keywords) else "general" def build_messages(payload: dict) -> list: category = payload["category"] system_content = ( "你是一个技术支持助手。如果问题属于故障排查类，请给出分步骤的排查建议；" "如果是通用问题，请给出简要、准确的解释。" if category == "troubleshooting" else "你是一个通用知识助手，回答要准确、简洁。" ) return [ SystemMessage(content=system_content), HumanMessage(content=payload["question"]), ] chain = ( RunnablePassthrough.assign(category=lambda x: classify(x["question"])) | RunnableLambda(build_messages) | model ) result = chain.invoke({"question": "模型调用时报 model not found，怎么排查？"}) print(result.content)这里的关键点有三个。一是 RunnablePassthrough.assign 给状态里动态加了一个 category 字段，后面的节点可以直接用。二是 build_messages 根据 category 构造不同的系统提示，让模型知道自己是哪种角色。三是末尾接的是带 fallback 的 model 对象，主模型挂了会自动切到备用模型，整个链的稳定性比单模型高一个档次。
如果你想把这个示例工程化，可以把 classify 换成真正的分类模型，或者把回退扩展成多级回退，还可以把 question 换成更复杂的结构化输入。核心思路不变：先路由，再生成，最后兜底。这是我目前觉得最实用的一个组合。
7. 学习小结和个人体会
到这里，model 这一层算是初步拿下了。在我看来，langchain 里 model 的学习曲线主要不在于调接口，而在于理解封装背后的几个关键点：模型形态的区分、消息结构的设计、参数配置的边界，以及错误排查的路径。你把这几件事搞明白，后面学链、记忆、代理的时候，会顺很多。
最后分享两个个人经验。第一个是学习时不要贪多，先把一个模型在一个场景里跑通，再横向扩展。我因为想一口气同时搞定多个服务商，初期浪费了不少时间，每个都没吃透。第二个是报错信息一定要逐字读，很多问题其实就是模型名大小写或者配置文件路径这种小事，看仔细点能省下大把排查时间。遇到 model not found 先别怀疑人生，先去核对名字，比什么排查技巧都管用。
下一篇我打算接着写提示词和输出解析，把模型读完输入后怎么拿结构化结果这一块展开讲。如果你也在学 langchain，遇到和 model 相关的怪问题，欢迎一起交流。
