上个月我把一个跑了大半年的项目从 LangChain 0.2 迁到 LangChain v1.0没想到第一个报错就出在最基础的 Models 组件这一层。代码里原本用的旧模型类突然找不到了接入包拆了一堆构造函数参数也变了调用返回的结构看起来也不像以前那样“说人话”。折腾完那几天我才真正意识到v1.0 的 Models 组件看起来只是换了一个入口实际上把整个模型层的接口哲学都重做了一遍。这是学习笔记系列里的第四篇前面几篇分别记录了框架总览、提示词模板、链的编排与输出解析这一篇集中把核心组件 Models 过一遍。如果你是刚开始接触 LangChain v1.0或者正在从 0.2 往 v1.0 迁移这篇文章应该能帮你省下不少查文档的时间。1. Models 不是一个类v1.0 把模型层拆成了三层来管很多人写 LangChain 第一行代码是从 model ChatOpenAI(...) 开始的所以容易把 Models 当成一个类或者一个配置文件。实际上 v1.0 的 Models 组件是一组接口的集合它至少要覆盖三类东西对话模型、补全模型、向量模型。这三类模型之间的输入、输出和职责完全不同把它们拆开是一套很清醒的设计——因为只有在这层把边界划清楚后续的提示词、链、检索、Agent 才有一个统一的对接基础。1.1 ChatModel、LLM、Embeddings 各自负责什么先看一张对照表这是我整理笔记时放在最前面的分类核心接口输入输出主要用途对话模型 ChatModelBaseChatModel消息列表AIMessage 对象聊天、Agent、工具调用补全模型 LLMBaseLLM字符串字符串老接口迁移、纯补全场景向量模型 EmbeddingsEmbeddings文本列表/字符串向量列表语义检索、向量库写入v1.0 里真正的主角是 ChatModel。原因很简单现在主流的模型服务商都提供了 Chat 类型的接口连很多本地部署方案也都在做协议兼容。LLM 这种只吃字符串、返回字符串的旧式补全接口虽然在 BaseLLM 里还留着但 LangChain 官方已经把默认使用的方向偏向 ChatModel一般新项目不需要再主动选 LLM。Embeddings 和对话模型是完全不同的一种东西。对话模型产出的是自然语言文本Embeddings 产出的是固定长度的浮点数向量。向量本身人类看不懂但在语义检索、去重、分类这些场景里非常关键。后面的检索增强链路里文档入库和查询改写都要用到它。1.2 统一入口 init_chat_model 是怎么做到“一个函数加载所有模型”的v1.0 提供了一个很省心的入口 init_chat_model。它的核心思路是你只需要告诉它模型名和模型服务商它会自动去已安装的接入包里找到匹配的 ChatModel 类并完成初始化。from langchain.chat_models import init_chat_model model init_chat_model( modelsome-chat-model-id, model_providersome-provider, temperature0, max_tokens1024, )如果 model_provider 不传它会尝试从模型名判断服务商但我的建议是显式传。判断逻辑在模型名不常见的时候很容易猜错猜错之后要么直接报 ModuleNotFoundError要么加载成另一个不存在的模型类查起来反而麻烦。这里有一个很多人会忽略的点init_chat_model 找不到接入包时报错信息并不会直接告诉你“去装哪个包”它只会说 No module named xxx。实际上你需要先确认对应的接入包已经 pip install 过。也就是说这个统一入口并没有帮你省掉安装依赖的步骤它只是帮你省掉了 import 时选包的步骤。2. ChatModel 的三种调用节奏invoke、stream、batch 的底层逻辑ChatModel 在 v1.0 里被设计成 Runnable意味着它天然支持 invoke、stream、batch 这一套统一调用协议。很多教程只是把三种方法各贴一次代码但没有讲清楚它们各自适合什么场景。我的理解是invoke 是单发完整问答stream 是边生成边接收batch 是多条请求并发执行。选错调用方式轻则体验变差重则直接把服务商限流打出来。2.1 invoke 返回的是 AIMessage不是字符串from langchain_core.messages import HumanMessage, SystemMessage messages [ SystemMessage(content你是一个数据库运维助手回答尽量简短。), HumanMessage(content一条 SQL 执行很慢我应该先看什么), ] resp model.invoke(messages) print(type(resp)) # class langchain_core.messages.ai.AIMessage print(resp.content) # 真正的回答文本 print(resp.tool_calls) # 默认是空列表有工具调用时才有值 print(resp.usage_metadata) # 有的服务商返回 token 用量有的为 None三件事必须记在脑子里。第一resp 是一个 AIMessage 对象不是字符串需要 .content 才能拿到文本。第二v1.0 里 content 不一定是 str当模型返回的内容包含多个模态块或者工具调用时content 可能是一个块列表所以代码里最好不要直接用 isinstance(resp.content, str) 来断言除非你明确知道自己用的是文本模型。第三token 用量不是所有服务商都会返回打印 usage_metadata 之前先打个空值判断免得日志频繁报错。和这三种同步调用一一对应的还有异步版本ainvoke、astream、abatch。异步接口除了 await 之外签名和同步版本基本对齐。我一般是在 FastAPI 这类异步服务里才用异步版避免长耗时调用阻塞整个事件循环。2.2 stream 的增量拼接与工具调用块stream 和 invoke 最大的区别是invoke 等到全部生成完才返回stream 每生成一小段就吐出来。体验上类似从“等一封长信”变成“看直播打字”对用户体验和首字延迟的提升非常明显。full_text for chunk in model.stream(messages): piece chunk.content if isinstance(piece, str): full_text piece print(piece, end, flushTrue)如果你只处理纯文本输出这种拼接方式够用。但如果这个模型同时启用了工具调用就要非常小心流式的工具调用是以 tool_call_chunks 的形式一点点拼出来的直接用上面这种 content 拼接会丢掉工具调用信息。我建议在涉及工具调用的流式场景里优先用更底层的 astream_events 去监听具体事件或者干脆在流式请求里只做文本展示工具调用的判定用一次单独的 invoke 完成。另外stream 返回的每个 chunk 都是 AIMessageChunk它同样有 content 和 tool_call_chunks 字段。我一开始以为每个 chunk 都是一小段完整文本后来才发现有的接入包一次会吐多个碎片有的则会把标点和空格单独拆成一个 chunk。所以拼接收敛条件一定要写得宽容一些。2.3 batch 的并发控制与单条失败隔离inputs [ [HumanMessage(content把这句话压缩成十个字今天的会议纪要大家都看了吗)], [HumanMessage(content给这段文案写三个标题。)], [HumanMessage(content把下面的商品信息提炼成结构化标签。)], ] results model.batch(inputs, return_exceptionsTrue) for idx, item in enumerate(results): if isinstance(item, Exception): print(f第 {idx} 条失败{item}) else: print(f第 {idx} 条成功{item.content})batch 并不会保证顺序返回但它会把每条输入独立交给底层的并发执行器。这里最重要的参数是 return_exceptionsTrue。不传的话只要其中一条请求报错整批结果可能直接被中断排查时你会看到一堆无关异常传了之后每条结果要么是正常消息要么是异常对象配合 for 循环就能快速定位到底是哪一条出了问题。并发虽然快但要保持清醒模型服务商的 API 是按并发配额计费和限流的。我一口气 batch 50 条请求的时候触发过 429 限流。建议的做法是控制每批次数量比如 5 到 10 条再配合接入包里的 max_retries 参数做自动重试。3. Embeddings 向量化的工程细节文本到向量的全链路如果说 ChatModel 是对话用的“嘴”Embeddings 就是检索用的“尺子”。它负责把一段文本变成一组固定维度的浮点数让计算机能用数学距离衡量语义相似度。LangChain v1.0 里 Embeddings 也是一个 Runnable 化的接口集合但它和 ChatModel 的差异很大很多工程问题恰恰藏在这种差异里。3.1 embed_documents 和 embed_query 有着完全不同的语义from some_embedding_package import SomeEmbeddings embeddings SomeEmbeddings(modelsome-embedding-model) doc_vectors embeddings.embed_documents([文档标题A, 文档内容B, 用户反馈C]) query_vector embeddings.embed_query(和文档A相关的查询)很多人第一次用都会问为什么要分成两个方法直接统一成一个不行吗原因在于部分模型的训练方式是“非对称”的。文档侧应该用普通文本直接编码查询侧则需要带上“这是一个查询”的语义前缀或特殊指令两侧经过不同的预处理之后向量空间里的相似度才可靠。虽然也有对称模型但接口上仍然保留了这两个习惯就是为了照顾非对称模型的约束。另外一个容易踩的点是参数类型完全不同。embed_documents 接收一个字符串列表返回一个二维列表embed_query 接收一个字符串返回一维列表。如果把一条查询误传成 embed_documents([query])也不是不行但语义上不严谨等后续换模型时容易出现向量形态对不上的问题。3.2 向量维度、归一化与换模型的连锁反应向量维度是 Embeddings 最不容商量的约束。主流模型有 768、1024、1536、3072 等常见取值具体看模型的输出配置。维度影响的不只是存储空间更重要的是向量数据库的索引结构。我在项目里把向量集合建立在 1536 维中途想换一个 768 维的模型结果发现整个集合要么重建索引要么要多维护一套字段改动量极大。归一化同样值得注意。很多模型默认输出的向量不是单位向量做余弦相似度计算前通常需要先归一化否则结果会受向量长度干扰。LangChain 的接口不会替你完成归一化所以建议在入库和查询两条路径上做同样的处理先归一化再存入查询时也用归一化后的向量去检索。这里还要提醒一个容易忽略的细节换了 Embedding 模型之后不只是维度可能变化同一段文本的向量数值也会完全不同。即使维度一致也不能把旧向量和新向量混在一个集合里做最近邻检索否则语义匹配基本都是错的。所以决定换模型之前先确认自己愿意承担重新向量化全量数据的成本。3.3 缓存和批量控制这笔钱应该花得明明白白Embeddings 是按 token 计费的而且使用频率往往比对话模型高得多因为文档入库要批量编码线上查询也要逐个编码。我后来养成了一个习惯给 Embeddings 加一层内存缓存避免完全相同的文本反复请求服务商。_cache {} def get_query_vector(text: str): if text not in _cache: _cache[text] embeddings.embed_query(text) return _cache[text]如果文本规模更大可以换成带过期时间的缓存或者直接把向量落盘。除此之外embed_documents 一次传几十篇长文档很容易触发服务商的请求长度限制或限流更稳妥的做法是先做文本切分每批控制在固定 token 数内分批编码后再拼接向量列表。文本切分本身是个独立话题但你要记住Embeddings 的质量上限由切分质量决定模型只是在这里执行编码工作。4. 结构化输出与工具绑定模型输出直接变成可执行对象Models 组件在 v1.0 里最让我觉得省事的是它把“结构化输出”和“工具调用”都做成了模型对象的通用方法。在 0.x 时代我们经常要在提示词里写“请只返回 JSON”然后自己面对模型输出里的 Markdown 代码块、遗漏字段做各种清洗。v1.0 直接用 with_structured_output 和 bind_tools 把这件事标准化了。4.1 with_structured_output让模型按 Pydantic 骨架输出from pydantic import BaseModel, Field class MovieInfo(BaseModel): title: str Field(description电影标题) year: int Field(description上映年份) genres: list[str] Field(description类型标签例如喜剧、科幻) structured_model model.with_structured_output(MovieInfo) result structured_model.invoke(《星河旅人》是什么时候上映的属于什么类型) print(result.title) # 星河旅人 print(result.year) # 2026 print(type(result)) # MovieInfo 实例with_structured_output 做的事情是把 Pydantic 对象的字段定义和描述翻译成模型能够理解的输出约束再让模型通过工具调用或者 JSON 模式生成内容最终帮你反序列化成对象。你手里拿到的是 Pydantic 实例不是 JSON 字符串后面接业务逻辑会舒服很多。这里有个非常实用的调试参数include_rawTrue。开启后返回结果会变成一个包含 raw 和 parsed 等字段的字典你既能拿到模型原始输出又能拿到解析后的对象。我在调字段描述的时候几乎每次都开着它因为可以直观看到模型到底是因为字段命名含糊而漏填还是因为描述不合理而填错。4.2 bind_tools给模型一把可以调用的扳手工具调用是 Agent 链路的地基。它的核心交互是模型并不真正执行函数它只是在回答里声明“我决定调用某个函数”并给出参数。真正执行的是你的代码执行完把结果作为 ToolMessage 再喂回模型。class WeatherQuery(BaseModel): city: str Field(description城市名例如海州市) date: str Field(description查询日期格式 YYYY-MM-DD) binding model.bind_tools([WeatherQuery]) resp binding.invoke(帮我查一下后天海州市的天气怎么样) if resp.tool_calls: call resp.tool_calls[0] print(call[name]) # WeatherQuery 的类名 print(call[args]) # {city: 海州市, date: 2025-07-19}这段示例看起来很短但背后有两个容易忽略的点。第一bind_tools 接收一个“工具定义”集合Pydantic 类只是其中一种写法BaseTool 实例和 dict 形式的工具描述也可以。定义里字段的 description 写得越清楚模型传参就越准。第二resp.tool_calls 是一个字典列表每个元素包含 name、args、id 三个字段其中工具调用的 id 相当重要因为后面把执行结果返回给模型时ToolMessage 要靠 tool_call_id 和之前的调用对上号。我刚开始做 Agent 时经常只盯着 resp.content 看导致模型已经发起工具调用我却完全没反应。记住一个判断顺序优先检查 resp.tool_calls 是否有内容没有再去读 content。这个顺序能避免很多无效问答。如果你的模型服务商本身不支持原生工具调用with_structured_output 的底层实现可能会退回 JSON 模式。遇到输出格式混乱的情况优先升级接入包版本再考虑是不是模型能力本身的问题。5. 模型接入配置的实战排查环境变量、base_url 与超时重试Models 组件一半的坑不在代码逻辑而在接入配置。同一个模型名在不同服务商的接入包里的环境变量可能不同同一个兼容协议接口base_url 多一个 /v1 少一个 /v1 就是 404 和 200 的区别。这一章把我在真实项目里排查过的配置问题集中列出来。5.1 接入一个模型至少要备齐的三样东西接一个云端对话模型代码之外要备齐三样东西接入包、API Key、base_url。接入包负责提供 ChatModel 类API Key 负责鉴权base_url 负责把请求指向正确的服务地址。三者缺一个模型就在加载或首次调用时报错。import os os.environ[OPENAI_API_KEY] sk-your-key os.environ[OPENAI_BASE_URL] https://api.example.com/v1 from langchain.chat_models import init_chat_model model init_chat_model(modelyour-model-id, model_provideryour-provider)上面代码里的环境变量名以 openai 兼容协议为例。如果你用的是其他模型服务商自己的 SDK 接入包环境变量名会换成对应文档里写的那个。我的建议是API Key 和 base_url 不要散布在每个脚本里统一放在环境配置里模型名、温度、最大 token、超时设置集中在一个配置文件里。这样后续换模型或换服务商改动范围能控制在很小的文件内。5.2 常见的五类报错与排查链路报错场景报错类型大概率原因排查动作加载时报 ModuleNotFoundErrorImportError接入包未安装pip install 对应的 langchain-xxx首次调用返回 401 鉴权失败AuthenticationErrorAPI Key 缺失或错误打印环境变量确认变量名和值返回 404 模型不存在/路径错误NotFoundErrorbase_url 或模型名不对直接测一遍模型列表接口确认模型 ID返回 429 限流RateLimitError并发过高或配额不足减小 batch、调大 max_retries长时间无响应TimeoutError请求体过大或网络不稳定调 request_timeout检查日志看卡在哪个阶段排查的时候我最常用的方法是先绕开 LangChain直接用 HTTP 客户端打一次模型服务的接口。这样可以快速确认问题到底在服务端、网络层还是 LangChain 封装层。curl -X POST https://api.example.com/v1/chat/completions \ -H Authorization: Bearer $MODEL_API_KEY \ -d {model: your-model-id, messages: [{role: user, content: hi}]}如果直接打接口报 404那基本就是 base_url 或模型名写错再回头检查 LangChain 里传的参数比看一长串堆栈高效得多。5.3 从 v0.x 迁到 v1.0 的代码级差异如果你的项目和我一样是从 LangChain 0.2 迁移过来的最明显的变化集中在三处。第一import 路径变了。旧的 langchain.llms 里的通用 LLM 类不再随便可用对话模型要从 langchain.chat_models 或者对应接入包里导入。很多老代码直接 from langchain.llms import ... 就会在第一步被卡住。第二predict 系列方法退出主流程。0.x 时期常用的 model.predict(...) 在 v1.0 里只建议使用 invoke而且 invoke 接收的是消息列表而不是裸字符串。刚开始迁移时我总是忘记把字符串包装成 HumanMessage模型照样能跑但提示词里的指令会逐渐失效这种隐性 bug 比报错更难发现。第三返回值结构变复杂了。v1.0 的消息对象更规范化content、tool_calls、usage_metadata 这些字段都齐备了但代价是不能再用一个简单的字符串变量去接结果。老代码里直接 print(model(prompt)) 这种写法在新版本下看到的会是消息对象的一堆打印信息。我建议迁移时统一写一个小的 resp_to_text 工具函数把 AIMessage 转成字符串后面所有调用点共用同一个转换逻辑比逐个改稳妥。6. 笔记收尾我保留的关于 Models 的三个实操习惯每次学一个组件我都会在笔记最后记几条自己验证过的习惯方便下次开新项目直接照做。今天这篇也照例记三条。第一拿到一个新接入包第一件事不是写业务代码而是跑一个最小最小 invoke 用例打印 type(resp) 和 resp.content。这一步耽误不了两分钟却能确认环境变量、模型名、接入包三者都没问题之后写链和 Agent 时才不会满屏找错误。第二涉及流的场景先在本地把 full_text 完整打印出来确认流式输出没有中途断裂再上生产。流式代码最容易出现的问题不是不输出而是拼接到一半遇到非字符串类型的 content 块表现就是 UI 上卡在空位置或者文本缺一段。第三给模型的每次调用埋一点 token 用量日志。usage_metadata 能拿到的场景一行日志就能记录输入输出 token拿不到的就记录调用条数和耗时。我见过太多项目上线后才发现模型账单超支都是因为从一开始就没有统计习惯。LangChain v1.0 的 Models 组件说到底就是一层“模型适配层”它把不同服务商的差异收敛到统一的接口后面让你写业务代码时不用关心今天接的是谁。理解这一点后面消化 Prompt、Chain、Agent 这些组件时会顺畅很多。最后再提醒一句如果迁移时在 Models 层反复报错不要急着改调用代码先回头确认环境和接入包版本。v1.0 的模型接口已经足够稳定绝大多数坑都是版本错位和参数残留造成的。把这层底座理干净后面写提示词、搭链、做 Agent 都会顺手很多。
上个月我把一个跑了大半年的项目从 LangChain 0.2 迁到 LangChain v1.0没想到第一个报错就出在最基础的 Models 组件这一层。代码里原本用的旧模型类突然找不到了接入包拆了一堆构造函数参数也变了调用返回的结构看起来也不像以前那样“说人话”。折腾完那几天我才真正意识到v1.0 的 Models 组件看起来只是换了一个入口实际上把整个模型层的接口哲学都重做了一遍。这是学习笔记系列里的第四篇前面几篇分别记录了框架总览、提示词模板、链的编排与输出解析这一篇集中把核心组件 Models 过一遍。如果你是刚开始接触 LangChain v1.0或者正在从 0.2 往 v1.0 迁移这篇文章应该能帮你省下不少查文档的时间。1. Models 不是一个类v1.0 把模型层拆成了三层来管很多人写 LangChain 第一行代码是从 model ChatOpenAI(...) 开始的所以容易把 Models 当成一个类或者一个配置文件。实际上 v1.0 的 Models 组件是一组接口的集合它至少要覆盖三类东西对话模型、补全模型、向量模型。这三类模型之间的输入、输出和职责完全不同把它们拆开是一套很清醒的设计——因为只有在这层把边界划清楚后续的提示词、链、检索、Agent 才有一个统一的对接基础。1.1 ChatModel、LLM、Embeddings 各自负责什么先看一张对照表这是我整理笔记时放在最前面的分类核心接口输入输出主要用途对话模型 ChatModelBaseChatModel消息列表AIMessage 对象聊天、Agent、工具调用补全模型 LLMBaseLLM字符串字符串老接口迁移、纯补全场景向量模型 EmbeddingsEmbeddings文本列表/字符串向量列表语义检索、向量库写入v1.0 里真正的主角是 ChatModel。原因很简单现在主流的模型服务商都提供了 Chat 类型的接口连很多本地部署方案也都在做协议兼容。LLM 这种只吃字符串、返回字符串的旧式补全接口虽然在 BaseLLM 里还留着但 LangChain 官方已经把默认使用的方向偏向 ChatModel一般新项目不需要再主动选 LLM。Embeddings 和对话模型是完全不同的一种东西。对话模型产出的是自然语言文本Embeddings 产出的是固定长度的浮点数向量。向量本身人类看不懂但在语义检索、去重、分类这些场景里非常关键。后面的检索增强链路里文档入库和查询改写都要用到它。1.2 统一入口 init_chat_model 是怎么做到“一个函数加载所有模型”的v1.0 提供了一个很省心的入口 init_chat_model。它的核心思路是你只需要告诉它模型名和模型服务商它会自动去已安装的接入包里找到匹配的 ChatModel 类并完成初始化。from langchain.chat_models import init_chat_model model init_chat_model( modelsome-chat-model-id, model_providersome-provider, temperature0, max_tokens1024, )如果 model_provider 不传它会尝试从模型名判断服务商但我的建议是显式传。判断逻辑在模型名不常见的时候很容易猜错猜错之后要么直接报 ModuleNotFoundError要么加载成另一个不存在的模型类查起来反而麻烦。这里有一个很多人会忽略的点init_chat_model 找不到接入包时报错信息并不会直接告诉你“去装哪个包”它只会说 No module named xxx。实际上你需要先确认对应的接入包已经 pip install 过。也就是说这个统一入口并没有帮你省掉安装依赖的步骤它只是帮你省掉了 import 时选包的步骤。2. ChatModel 的三种调用节奏invoke、stream、batch 的底层逻辑ChatModel 在 v1.0 里被设计成 Runnable意味着它天然支持 invoke、stream、batch 这一套统一调用协议。很多教程只是把三种方法各贴一次代码但没有讲清楚它们各自适合什么场景。我的理解是invoke 是单发完整问答stream 是边生成边接收batch 是多条请求并发执行。选错调用方式轻则体验变差重则直接把服务商限流打出来。2.1 invoke 返回的是 AIMessage不是字符串from langchain_core.messages import HumanMessage, SystemMessage messages [ SystemMessage(content你是一个数据库运维助手回答尽量简短。), HumanMessage(content一条 SQL 执行很慢我应该先看什么), ] resp model.invoke(messages) print(type(resp)) # class langchain_core.messages.ai.AIMessage print(resp.content) # 真正的回答文本 print(resp.tool_calls) # 默认是空列表有工具调用时才有值 print(resp.usage_metadata) # 有的服务商返回 token 用量有的为 None三件事必须记在脑子里。第一resp 是一个 AIMessage 对象不是字符串需要 .content 才能拿到文本。第二v1.0 里 content 不一定是 str当模型返回的内容包含多个模态块或者工具调用时content 可能是一个块列表所以代码里最好不要直接用 isinstance(resp.content, str) 来断言除非你明确知道自己用的是文本模型。第三token 用量不是所有服务商都会返回打印 usage_metadata 之前先打个空值判断免得日志频繁报错。和这三种同步调用一一对应的还有异步版本ainvoke、astream、abatch。异步接口除了 await 之外签名和同步版本基本对齐。我一般是在 FastAPI 这类异步服务里才用异步版避免长耗时调用阻塞整个事件循环。2.2 stream 的增量拼接与工具调用块stream 和 invoke 最大的区别是invoke 等到全部生成完才返回stream 每生成一小段就吐出来。体验上类似从“等一封长信”变成“看直播打字”对用户体验和首字延迟的提升非常明显。full_text for chunk in model.stream(messages): piece chunk.content if isinstance(piece, str): full_text piece print(piece, end, flushTrue)如果你只处理纯文本输出这种拼接方式够用。但如果这个模型同时启用了工具调用就要非常小心流式的工具调用是以 tool_call_chunks 的形式一点点拼出来的直接用上面这种 content 拼接会丢掉工具调用信息。我建议在涉及工具调用的流式场景里优先用更底层的 astream_events 去监听具体事件或者干脆在流式请求里只做文本展示工具调用的判定用一次单独的 invoke 完成。另外stream 返回的每个 chunk 都是 AIMessageChunk它同样有 content 和 tool_call_chunks 字段。我一开始以为每个 chunk 都是一小段完整文本后来才发现有的接入包一次会吐多个碎片有的则会把标点和空格单独拆成一个 chunk。所以拼接收敛条件一定要写得宽容一些。2.3 batch 的并发控制与单条失败隔离inputs [ [HumanMessage(content把这句话压缩成十个字今天的会议纪要大家都看了吗)], [HumanMessage(content给这段文案写三个标题。)], [HumanMessage(content把下面的商品信息提炼成结构化标签。)], ] results model.batch(inputs, return_exceptionsTrue) for idx, item in enumerate(results): if isinstance(item, Exception): print(f第 {idx} 条失败{item}) else: print(f第 {idx} 条成功{item.content})batch 并不会保证顺序返回但它会把每条输入独立交给底层的并发执行器。这里最重要的参数是 return_exceptionsTrue。不传的话只要其中一条请求报错整批结果可能直接被中断排查时你会看到一堆无关异常传了之后每条结果要么是正常消息要么是异常对象配合 for 循环就能快速定位到底是哪一条出了问题。并发虽然快但要保持清醒模型服务商的 API 是按并发配额计费和限流的。我一口气 batch 50 条请求的时候触发过 429 限流。建议的做法是控制每批次数量比如 5 到 10 条再配合接入包里的 max_retries 参数做自动重试。3. Embeddings 向量化的工程细节文本到向量的全链路如果说 ChatModel 是对话用的“嘴”Embeddings 就是检索用的“尺子”。它负责把一段文本变成一组固定维度的浮点数让计算机能用数学距离衡量语义相似度。LangChain v1.0 里 Embeddings 也是一个 Runnable 化的接口集合但它和 ChatModel 的差异很大很多工程问题恰恰藏在这种差异里。3.1 embed_documents 和 embed_query 有着完全不同的语义from some_embedding_package import SomeEmbeddings embeddings SomeEmbeddings(modelsome-embedding-model) doc_vectors embeddings.embed_documents([文档标题A, 文档内容B, 用户反馈C]) query_vector embeddings.embed_query(和文档A相关的查询)很多人第一次用都会问为什么要分成两个方法直接统一成一个不行吗原因在于部分模型的训练方式是“非对称”的。文档侧应该用普通文本直接编码查询侧则需要带上“这是一个查询”的语义前缀或特殊指令两侧经过不同的预处理之后向量空间里的相似度才可靠。虽然也有对称模型但接口上仍然保留了这两个习惯就是为了照顾非对称模型的约束。另外一个容易踩的点是参数类型完全不同。embed_documents 接收一个字符串列表返回一个二维列表embed_query 接收一个字符串返回一维列表。如果把一条查询误传成 embed_documents([query])也不是不行但语义上不严谨等后续换模型时容易出现向量形态对不上的问题。3.2 向量维度、归一化与换模型的连锁反应向量维度是 Embeddings 最不容商量的约束。主流模型有 768、1024、1536、3072 等常见取值具体看模型的输出配置。维度影响的不只是存储空间更重要的是向量数据库的索引结构。我在项目里把向量集合建立在 1536 维中途想换一个 768 维的模型结果发现整个集合要么重建索引要么要多维护一套字段改动量极大。归一化同样值得注意。很多模型默认输出的向量不是单位向量做余弦相似度计算前通常需要先归一化否则结果会受向量长度干扰。LangChain 的接口不会替你完成归一化所以建议在入库和查询两条路径上做同样的处理先归一化再存入查询时也用归一化后的向量去检索。这里还要提醒一个容易忽略的细节换了 Embedding 模型之后不只是维度可能变化同一段文本的向量数值也会完全不同。即使维度一致也不能把旧向量和新向量混在一个集合里做最近邻检索否则语义匹配基本都是错的。所以决定换模型之前先确认自己愿意承担重新向量化全量数据的成本。3.3 缓存和批量控制这笔钱应该花得明明白白Embeddings 是按 token 计费的而且使用频率往往比对话模型高得多因为文档入库要批量编码线上查询也要逐个编码。我后来养成了一个习惯给 Embeddings 加一层内存缓存避免完全相同的文本反复请求服务商。_cache {} def get_query_vector(text: str): if text not in _cache: _cache[text] embeddings.embed_query(text) return _cache[text]如果文本规模更大可以换成带过期时间的缓存或者直接把向量落盘。除此之外embed_documents 一次传几十篇长文档很容易触发服务商的请求长度限制或限流更稳妥的做法是先做文本切分每批控制在固定 token 数内分批编码后再拼接向量列表。文本切分本身是个独立话题但你要记住Embeddings 的质量上限由切分质量决定模型只是在这里执行编码工作。4. 结构化输出与工具绑定模型输出直接变成可执行对象Models 组件在 v1.0 里最让我觉得省事的是它把“结构化输出”和“工具调用”都做成了模型对象的通用方法。在 0.x 时代我们经常要在提示词里写“请只返回 JSON”然后自己面对模型输出里的 Markdown 代码块、遗漏字段做各种清洗。v1.0 直接用 with_structured_output 和 bind_tools 把这件事标准化了。4.1 with_structured_output让模型按 Pydantic 骨架输出from pydantic import BaseModel, Field class MovieInfo(BaseModel): title: str Field(description电影标题) year: int Field(description上映年份) genres: list[str] Field(description类型标签例如喜剧、科幻) structured_model model.with_structured_output(MovieInfo) result structured_model.invoke(《星河旅人》是什么时候上映的属于什么类型) print(result.title) # 星河旅人 print(result.year) # 2026 print(type(result)) # MovieInfo 实例with_structured_output 做的事情是把 Pydantic 对象的字段定义和描述翻译成模型能够理解的输出约束再让模型通过工具调用或者 JSON 模式生成内容最终帮你反序列化成对象。你手里拿到的是 Pydantic 实例不是 JSON 字符串后面接业务逻辑会舒服很多。这里有个非常实用的调试参数include_rawTrue。开启后返回结果会变成一个包含 raw 和 parsed 等字段的字典你既能拿到模型原始输出又能拿到解析后的对象。我在调字段描述的时候几乎每次都开着它因为可以直观看到模型到底是因为字段命名含糊而漏填还是因为描述不合理而填错。4.2 bind_tools给模型一把可以调用的扳手工具调用是 Agent 链路的地基。它的核心交互是模型并不真正执行函数它只是在回答里声明“我决定调用某个函数”并给出参数。真正执行的是你的代码执行完把结果作为 ToolMessage 再喂回模型。class WeatherQuery(BaseModel): city: str Field(description城市名例如海州市) date: str Field(description查询日期格式 YYYY-MM-DD) binding model.bind_tools([WeatherQuery]) resp binding.invoke(帮我查一下后天海州市的天气怎么样) if resp.tool_calls: call resp.tool_calls[0] print(call[name]) # WeatherQuery 的类名 print(call[args]) # {city: 海州市, date: 2025-07-19}这段示例看起来很短但背后有两个容易忽略的点。第一bind_tools 接收一个“工具定义”集合Pydantic 类只是其中一种写法BaseTool 实例和 dict 形式的工具描述也可以。定义里字段的 description 写得越清楚模型传参就越准。第二resp.tool_calls 是一个字典列表每个元素包含 name、args、id 三个字段其中工具调用的 id 相当重要因为后面把执行结果返回给模型时ToolMessage 要靠 tool_call_id 和之前的调用对上号。我刚开始做 Agent 时经常只盯着 resp.content 看导致模型已经发起工具调用我却完全没反应。记住一个判断顺序优先检查 resp.tool_calls 是否有内容没有再去读 content。这个顺序能避免很多无效问答。如果你的模型服务商本身不支持原生工具调用with_structured_output 的底层实现可能会退回 JSON 模式。遇到输出格式混乱的情况优先升级接入包版本再考虑是不是模型能力本身的问题。5. 模型接入配置的实战排查环境变量、base_url 与超时重试Models 组件一半的坑不在代码逻辑而在接入配置。同一个模型名在不同服务商的接入包里的环境变量可能不同同一个兼容协议接口base_url 多一个 /v1 少一个 /v1 就是 404 和 200 的区别。这一章把我在真实项目里排查过的配置问题集中列出来。5.1 接入一个模型至少要备齐的三样东西接一个云端对话模型代码之外要备齐三样东西接入包、API Key、base_url。接入包负责提供 ChatModel 类API Key 负责鉴权base_url 负责把请求指向正确的服务地址。三者缺一个模型就在加载或首次调用时报错。import os os.environ[OPENAI_API_KEY] sk-your-key os.environ[OPENAI_BASE_URL] https://api.example.com/v1 from langchain.chat_models import init_chat_model model init_chat_model(modelyour-model-id, model_provideryour-provider)上面代码里的环境变量名以 openai 兼容协议为例。如果你用的是其他模型服务商自己的 SDK 接入包环境变量名会换成对应文档里写的那个。我的建议是API Key 和 base_url 不要散布在每个脚本里统一放在环境配置里模型名、温度、最大 token、超时设置集中在一个配置文件里。这样后续换模型或换服务商改动范围能控制在很小的文件内。5.2 常见的五类报错与排查链路报错场景报错类型大概率原因排查动作加载时报 ModuleNotFoundErrorImportError接入包未安装pip install 对应的 langchain-xxx首次调用返回 401 鉴权失败AuthenticationErrorAPI Key 缺失或错误打印环境变量确认变量名和值返回 404 模型不存在/路径错误NotFoundErrorbase_url 或模型名不对直接测一遍模型列表接口确认模型 ID返回 429 限流RateLimitError并发过高或配额不足减小 batch、调大 max_retries长时间无响应TimeoutError请求体过大或网络不稳定调 request_timeout检查日志看卡在哪个阶段排查的时候我最常用的方法是先绕开 LangChain直接用 HTTP 客户端打一次模型服务的接口。这样可以快速确认问题到底在服务端、网络层还是 LangChain 封装层。curl -X POST https://api.example.com/v1/chat/completions \ -H Authorization: Bearer $MODEL_API_KEY \ -d {model: your-model-id, messages: [{role: user, content: hi}]}如果直接打接口报 404那基本就是 base_url 或模型名写错再回头检查 LangChain 里传的参数比看一长串堆栈高效得多。5.3 从 v0.x 迁到 v1.0 的代码级差异如果你的项目和我一样是从 LangChain 0.2 迁移过来的最明显的变化集中在三处。第一import 路径变了。旧的 langchain.llms 里的通用 LLM 类不再随便可用对话模型要从 langchain.chat_models 或者对应接入包里导入。很多老代码直接 from langchain.llms import ... 就会在第一步被卡住。第二predict 系列方法退出主流程。0.x 时期常用的 model.predict(...) 在 v1.0 里只建议使用 invoke而且 invoke 接收的是消息列表而不是裸字符串。刚开始迁移时我总是忘记把字符串包装成 HumanMessage模型照样能跑但提示词里的指令会逐渐失效这种隐性 bug 比报错更难发现。第三返回值结构变复杂了。v1.0 的消息对象更规范化content、tool_calls、usage_metadata 这些字段都齐备了但代价是不能再用一个简单的字符串变量去接结果。老代码里直接 print(model(prompt)) 这种写法在新版本下看到的会是消息对象的一堆打印信息。我建议迁移时统一写一个小的 resp_to_text 工具函数把 AIMessage 转成字符串后面所有调用点共用同一个转换逻辑比逐个改稳妥。6. 笔记收尾我保留的关于 Models 的三个实操习惯每次学一个组件我都会在笔记最后记几条自己验证过的习惯方便下次开新项目直接照做。今天这篇也照例记三条。第一拿到一个新接入包第一件事不是写业务代码而是跑一个最小最小 invoke 用例打印 type(resp) 和 resp.content。这一步耽误不了两分钟却能确认环境变量、模型名、接入包三者都没问题之后写链和 Agent 时才不会满屏找错误。第二涉及流的场景先在本地把 full_text 完整打印出来确认流式输出没有中途断裂再上生产。流式代码最容易出现的问题不是不输出而是拼接到一半遇到非字符串类型的 content 块表现就是 UI 上卡在空位置或者文本缺一段。第三给模型的每次调用埋一点 token 用量日志。usage_metadata 能拿到的场景一行日志就能记录输入输出 token拿不到的就记录调用条数和耗时。我见过太多项目上线后才发现模型账单超支都是因为从一开始就没有统计习惯。LangChain v1.0 的 Models 组件说到底就是一层“模型适配层”它把不同服务商的差异收敛到统一的接口后面让你写业务代码时不用关心今天接的是谁。理解这一点后面消化 Prompt、Chain、Agent 这些组件时会顺畅很多。最后再提醒一句如果迁移时在 Models 层反复报错不要急着改调用代码先回头确认环境和接入包版本。v1.0 的模型接口已经足够稳定绝大多数坑都是版本错位和参数残留造成的。把这层底座理干净后面写提示词、搭链、做 Agent 都会顺手很多。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
