1. 为什么 Model 接入是 Agent 开发的分水岭很多人学 Agent 开发卡在第一个真正意义上的门槛上不是 Prompt 写不好也不是工具调用逻辑理不清而是模型接不进来。你可能已经看了一堆 LangChain 的教程知道ChatModel、LLM、Embedding这些名词但真到自己动手写第一行代码的时候发现连一个能跑通的模型调用都搞不定。这不是你笨而是这一层本身就藏着大量“文档里不写、教程里不讲”的细节。我自己在带团队做 Agent 项目的时候发现一个规律凡是能独立把 Model 接入这一层吃透的人后面学 Agent 架构、工具编排、记忆管理都会顺很多。反过来如果这一层是糊里糊涂抄过来的后面每加一个功能都会踩坑。原因很简单——Agent 的所有能力最终都要通过模型调用来落地。模型调用这一层不稳上面盖什么都是空中楼阁。这篇笔记聚焦的就是这一层Model 的调用与接入。我会把 LangChain 里ChatModel的定位、不同模型提供方的接入方式、参数配置的取舍逻辑、流式输出的处理、以及实际项目里最容易翻车的几个点全部拆开讲清楚。不管你是刚入门的新手还是已经写过几个 Demo 但总觉得“没吃透”的开发者这篇内容都能帮你把这一层的地基打扎实。先明确一个概念边界。在 LangChain 的体系里LLM和ChatModel是两个不同的抽象。LLM是早期的纯文本补全接口输入一个字符串输出一个字符串ChatModel是现在的主流输入是一个消息列表输出是一条消息。现在几乎所有主流模型走的都是ChatModel这条路所以除非你在维护老代码否则一律用ChatModel。这个选择不是偏好问题而是因为 Chat 格式天然支持 system、user、assistant 三种角色这对 Agent 的场景至关重要——system 放人设和规则user 放用户输入assistant 放模型回复和历史上下文结构清晰扩展性强。那 Embedding 又是什么简单说ChatModel负责“说话”Embedding负责“把文字变成向量”。前者用于对话、推理、生成后者用于检索、相似度匹配、知识库。做 Agent 的时候如果你的场景涉及本地知识库问答那这两个你都得接。但它们的接入方式是两套独立的逻辑不要混在一起理解。这篇主要讲ChatModelEmbedding 我会在涉及知识库的部分简单带过。2. ChatModel 接入的整体设计思路2.1 为什么 LangChain 要抽象出 ChatModel 这一层你可能会问我直接调 OpenAI 的 HTTP 接口不就行了吗为什么要套一层 LangChain这个问题问得好答案在于可替换性。假设你今天用 A 家的模型写了一个 Agent明天老板说 A 家太贵了换成 B 家。如果你代码里到处是 A 家的 SDK 调用那你就得把整个项目翻一遍。但如果你用的是 LangChain 的ChatModel抽象理论上只需要改一行初始化代码其他逻辑完全不动。这就是抽象层的价值——把“模型是谁”和“怎么用模型”解耦。当然现实没有这么理想。不同模型的参数、返回格式、工具调用协议都有差异LangChain 的适配层能抹平大部分但不是全部。所以我的经验是抽象层要用但不要迷信它能抹平一切。你得知道底层发生了什么出问题的时候才能定位。LangChain 里ChatModel的核心接口其实很简单主要就是两个方法invoke()传一个消息列表返回一条消息同步阻塞。stream()传一个消息列表返回一个迭代器逐块吐出内容。还有一个batch()是批量调用本质上是把多个invoke打包性能上不一定有优势但写起来方便。对于 Agent 场景最常用的是invoke和stream。invoke用于需要完整结果的场景比如工具调用的参数解析stream用于需要实时反馈的场景比如聊天界面的打字机效果。2.2 消息类型的设计逻辑ChatModel的输入是消息列表LangChain 定义了三种基础消息类型消息类型角色用途SystemMessagesystem设定模型的人设、规则、约束HumanMessageuser用户输入AIMessageassistant模型回复也用于传入历史上下文还有一个ToolMessage用于工具调用场景把工具的执行结果回传给模型。这个在 Agent 开发里非常关键后面讲工具调用的时候会展开。为什么要分这么细因为不同模型对消息角色的处理方式不同。比如有些模型对 system 消息特别敏感你放什么进去它就会严格遵守有些模型则会把 system 和 user 混在一起处理。理解这一点你才能写出跨模型都能稳定工作的 Prompt。我踩过的一个坑是早期我把所有规则都塞在 user 消息里结果换了一个模型之后模型开始“忽略”这些规则。后来改成 system 消息稳定性立刻上来了。所以规则类的内容一律放 system这是经验。2.3 模型提供方的选择与接入方式现在市面上的模型提供方大致分几类官方 API比如 OpenAI、Anthropic、Google 等接入最直接但价格和可用性受地区影响。云厂商托管比如国内几家云厂商提供的模型服务接入方式类似官方 API但需要配置对应的 endpoint 和密钥。本地部署比如用 Ollama、vLLM 等工具在本地跑开源模型适合对数据隐私要求高的场景。聚合平台把多个模型提供方聚合到一个接口下方便切换但稳定性和延迟参差不齐。LangChain 对这几类都有对应的集成包。以 OpenAI 兼容接口为例很多提供方都支持 OpenAI 的 API 格式所以你可以直接用ChatOpenAI这个类只需要改base_url和api_key。这是最省事的接入方式。from langchain_openai import ChatOpenAI model ChatOpenAI( modelyour-model-name, base_urlhttps://your-provider-endpoint/v1, api_keyyour-api-key, temperature0.7, )这段代码看起来简单但里面有几个点值得说。base_url一定要带/v1后缀这是 OpenAI 兼容接口的约定漏了会报 404。api_key不要硬编码在代码里用环境变量或者配置文件。temperature是控制随机性的参数0 最确定1 最随机Agent 场景一般用 0 到 0.3 之间因为你需要模型稳定地执行任务而不是发挥创意。3. 核心参数配置与实操要点3.1 temperature 到底在做什么temperature是模型调用里最常被提到、也最容易被误解的参数。它的作用机制是这样的模型在生成每一个 token 的时候会先算出一个概率分布然后从这个分布里采样。temperature就是用来调整这个分布的“陡峭程度”的。temperature 0分布变得极其陡峭几乎总是选概率最高的那个 token输出最确定。temperature 1分布保持原样按原始概率采样输出有多样性。temperature 1分布变得平坦低概率的 token 也有机会被选中输出更随机甚至可能胡言乱语。用一个生活化的类比想象你在选餐厅。temperature 0就是你每次都去评分最高的那家绝不冒险temperature 1就是你会按评分概率随机选偶尔去个评分中等但没试过的temperature 2就是你完全随机可能选到一家很难吃的。对于 Agent 开发我的建议是工具调用、参数解析、结构化输出temperature 0你需要的是稳定和准确。对话、创意生成、文案撰写temperature 0.7左右保留一定灵活性。头脑风暴、多样性探索temperature 1.0以上但要注意输出质量会下降。还有一个相关参数叫top_p也叫 nucleus sampling。它的逻辑是只从累积概率达到top_p的那部分 token 里采样。比如top_p 0.9就是只考虑概率最高的那些 token直到累积概率到 0.9 为止。一般建议temperature和top_p只调一个两个都调会让行为难以预测。3.2 max_tokens 与上下文窗口的关系max_tokens控制的是模型单次输出的最大 token 数。注意它管的是输出不是输入。输入的长度限制是另一个概念叫上下文窗口context window。这两个概念经常被混淆。上下文窗口是模型能“看到”的总 token 数包括输入和输出。比如一个模型的上下文窗口是 128k意思是输入加输出总共不能超过 128k token。而max_tokens是你给输出设的上限。为什么要设max_tokens两个原因一是控制成本输出越多越贵二是防止模型“刹不住车”生成一堆废话。Agent 场景里如果模型是用来做工具调用的输出通常很短max_tokens设个 512 或 1024 就够了。如果是生成报告、长文那就得设大一点。注意有些提供方对max_tokens有硬性上限超过会直接报错。接入之前先查一下文档别等到线上才发现。3.3 超时与重试生产环境必须配的两个参数Demo 阶段你可以不配超时和重试但一旦上生产这两个是必须的。模型服务不是 100% 可用的网络抖动、服务限流、临时故障都会导致调用失败。如果你不配重试用户就会看到报错。LangChain 的ChatOpenAI支持通过timeout和max_retries参数来配置model ChatOpenAI( modelyour-model-name, base_urlhttps://your-provider-endpoint/v1, api_keyyour-api-key, timeout30, max_retries3, )timeout30表示 30 秒没响应就超时。max_retries3表示失败后最多重试 3 次。这两个值的取舍要看你的场景如果是实时对话超时设短一点比如 15 到 20 秒因为用户等不了太久如果是后台批处理任务可以设长一点60 秒甚至更长。重试次数也不是越多越好。如果模型服务本身挂了重试 10 次也是白搭反而拖慢整体响应。一般 2 到 3 次就够了。另外要注意重试只对可恢复的错误有意义比如超时、限流。如果是参数错误、认证失败这种重试多少次都没用应该直接失败并记录日志。3.4 流式输出不只是为了好看流式输出streaming在聊天类产品里几乎是标配用户看到文字一个个蹦出来体验比等半天然后一次性出现好得多。但流式输出的价值不只是体验它在 Agent 场景里还有实际作用。比如当模型在生成工具调用的参数时你可以通过流式输出提前拿到部分内容做一些预处理。再比如当模型输出很长的时候流式输出可以让你在生成过程中就判断是否需要中断节省 token 成本。LangChain 里用stream()方法实现流式输出for chunk in model.stream([HumanMessage(content你好)]): print(chunk.content, end, flushTrue)每个chunk是一个AIMessageChunk它的content是这一块的内容。注意流式输出的 chunk 不保证按语义切分可能一个词被切成两半所以如果你要做内容分析得先把 chunk 拼起来。实操心得流式输出和工具调用一起用的时候要小心。有些模型在流式模式下对工具调用的支持不完整可能拿不到完整的参数。如果你的 Agent 依赖工具调用建议先用invoke拿到完整结果确认没问题再考虑流式。4. 完整实操流程与关键环节实现4.1 从零搭建一个可切换模型的调用层我平时做项目习惯把模型调用封装成一个独立的模块而不是散落在各处。这样做的好处是换模型、调参数、加日志都只改一个地方。下面是我常用的一个封装结构基于 LangChain 的ChatModelimport os from langchain_openai import ChatOpenAI from langchain_core.messages import SystemMessage, HumanMessage, AIMessage class ModelClient: def __init__(self, config): self.model ChatOpenAI( modelconfig[model_name], base_urlconfig[base_url], api_keyos.getenv(config[api_key_env]), temperatureconfig.get(temperature, 0.0), max_tokensconfig.get(max_tokens, 1024), timeoutconfig.get(timeout, 30), max_retriesconfig.get(max_retries, 3), ) self.system_prompt config.get(system_prompt, ) def chat(self, user_input, historyNone): messages [] if self.system_prompt: messages.append(SystemMessage(contentself.system_prompt)) if history: messages.extend(history) messages.append(HumanMessage(contentuser_input)) response self.model.invoke(messages) return response.content def stream_chat(self, user_input, historyNone): messages [] if self.system_prompt: messages.append(SystemMessage(contentself.system_prompt)) if history: messages.extend(history) messages.append(HumanMessage(contentuser_input)) for chunk in self.model.stream(messages): yield chunk.content这个封装做了几件事把配置和代码分离system prompt 统一管理history 支持多轮对话同时提供同步和流式两种调用方式。你可以根据项目需要继续扩展比如加日志、加 token 计数、加缓存。配置部分我一般用 YAML 或 JSON 文件model_name: your-model-name base_url: https://your-provider-endpoint/v1 api_key_env: MODEL_API_KEY temperature: 0.0 max_tokens: 1024 timeout: 30 max_retries: 3 system_prompt: 你是一个专业的助手回答要简洁准确。这样换模型的时候只改配置文件代码一行不动。这是我踩过多次坑之后总结出来的做法——早期我把配置写死在代码里换一次模型要改十几个文件痛苦不堪。4.2 多轮对话的上下文管理Agent 场景里多轮对话是常态。但上下文不能无限增长因为模型的上下文窗口有上限而且 token 越多越贵。所以你需要一套上下文管理策略。最简单的策略是滑动窗口只保留最近 N 轮对话。N 的取值取决于你的场景和模型的上下文窗口。比如上下文窗口是 8k每轮对话平均 500 token那最多保留 16 轮留点余量实际保留 10 到 12 轮比较稳妥。稍微复杂一点的策略是摘要压缩当对话历史超过一定长度时用模型把前面的对话总结成一段摘要然后把摘要作为上下文传进去。这样既能保留关键信息又能控制长度。def compress_history(history, model_client, max_rounds10): if len(history) max_rounds * 2: return history old_history history[:-max_rounds * 2] summary_prompt 请把以下对话总结成一段简洁的摘要保留关键信息\n for msg in old_history: summary_prompt f{msg.type}: {msg.content}\n summary model_client.chat(summary_prompt) compressed [SystemMessage(contentf之前的对话摘要{summary})] compressed.extend(history[-max_rounds * 2:]) return compressed这个策略的代价是多一次模型调用增加延迟和成本。所以只在对话确实很长的时候才触发不要每轮都压缩。注意摘要压缩会丢失细节如果某些信息对后续对话很关键可能会被压掉。我的做法是把关键信息比如用户明确说过的偏好、约束单独存一份不参与压缩每次都带上。4.3 工具调用中的模型接入细节Agent 和普通聊天机器人的核心区别就是工具调用。模型不只是生成文本还要能决定“调用哪个工具、传什么参数”。这部分的接入细节比较多我挑几个关键的讲。首先不是所有模型都支持工具调用。接入之前要确认模型的 function calling 或 tool use 能力。LangChain 里通过bind_tools()方法把工具绑定到模型上from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市的天气 return f{city}今天晴25度 model_with_tools model.bind_tools([get_weather]) response model_with_tools.invoke([HumanMessage(content北京天气怎么样)])模型返回的response里会包含tool_calls字段告诉你它想调用哪个工具、传什么参数。然后你执行工具把结果用ToolMessage回传再让模型生成最终回复。这里有个坑不同模型对工具描述的格式要求不同。有些模型对工具描述的措辞很敏感描述写得不好模型就不知道该不该调用。我的经验是工具描述要写清楚三件事这个工具是干什么的、什么时候该用、参数是什么含义。别嫌啰嗦描述越清晰模型调用越准确。另一个坑是参数类型。模型有时候会把数字传成字符串或者把字符串传成数字。所以在工具函数里要做好类型转换和校验别直接信任模型传过来的参数。4.4 结构化输出的实现方式Agent 开发里经常需要模型输出结构化的数据比如 JSON。但模型天然输出的是自然语言直接让它输出 JSON有时候会多带一些解释性文字导致解析失败。LangChain 提供了几种方式来处理这个问题。一种是with_structured_output()直接指定输出的 schemafrom pydantic import BaseModel class WeatherInfo(BaseModel): city: str temperature: int condition: str structured_model model.with_structured_output(WeatherInfo) result structured_model.invoke([HumanMessage(content北京今天晴25度)])这样返回的就是一个WeatherInfo对象不用自己解析 JSON。底层实现上LangChain 会根据模型的能力选择不同的策略支持 function calling 的模型用 function calling不支持的用 Prompt 引导加解析。但要注意结构化输出不是 100% 可靠的。模型有时候会漏字段、填错类型或者干脆不按 schema 来。所以生产环境里解析失败的处理逻辑一定要有不能假设每次都成功。我踩过的一个坑是用某个模型做结构化输出测试的时候好好的上线之后偶尔失败。后来发现是模型在遇到某些边界输入时会输出一段解释文字再输出 JSON导致解析器报错。解决办法是在 Prompt 里明确要求“只输出 JSON不要任何其他文字”同时在解析失败时做一次重试。5. 常见问题与排查技巧实录5.1 模型调用失败的排查思路模型调用失败的原因很多我整理了一个排查顺序从最常见到最罕见现象可能原因排查方法401 认证失败API key 错误或过期检查环境变量、密钥是否有效404 找不到接口base_url 配置错误确认是否带/v1路径是否正确429 限流请求频率过高降低并发、加重试、联系提供方提额超时网络问题或服务负载高检查网络、增大 timeout、重试400 参数错误模型名不对或参数不支持核对模型名、检查参数是否在支持列表返回内容为空模型被内容过滤或参数设置问题检查输入内容、调整 temperature这个表我基本是背下来的因为出问题的时候按这个顺序查90% 的情况都能定位。有一个特殊情况值得单独说模型返回的内容被截断。这通常是max_tokens设太小导致的。模型输出到一半达到上限就停了。解决办法是增大max_tokens或者在 Prompt 里要求模型简洁回答。5.2 模型切换时的兼容性问题前面说了 LangChain 的抽象层能抹平大部分差异但实际切换模型的时候还是会遇到一些兼容性问题。我遇到过的主要有这几类第一类是消息角色支持差异。有些模型不支持 system 消息或者对 system 消息的处理方式和预期不同。解决办法是把 system 内容合并到第一条 user 消息里或者用模型支持的特定格式。第二类是工具调用格式差异。不同模型的工具调用返回格式不一样LangChain 会做适配但偶尔会有遗漏。如果切换模型后工具调用出问题先检查返回的tool_calls结构是否符合预期。第三类是特殊 token 差异。有些模型对某些特殊字符或 token 有特殊处理比如某些模型会把特定标记当成控制符。如果切换模型后输出异常检查一下输入里有没有特殊字符。我的做法是每次切换模型都跑一遍回归测试。测试用例覆盖普通对话、多轮对话、工具调用、结构化输出、长文本生成。跑通了再上线别直接切。5.3 成本控制的几个实用技巧模型调用是要花钱的Agent 场景因为调用频繁成本更容易失控。分享几个我常用的成本控制技巧第一缓存重复请求。如果同样的输入会被多次调用把结果缓存起来。LangChain 提供了set_llm_cache()接口可以接内存缓存或 Redis 缓存。对于 Agent 场景工具调用的结果、常见问题的回答都适合缓存。第二用小模型做路由。不是所有请求都需要大模型。可以用一个小模型先判断请求的复杂度简单的请求直接用小模型处理复杂的才转给大模型。这样能省不少钱。第三控制上下文长度。前面讲的滑动窗口和摘要压缩本质上都是在控制上下文长度。上下文越长每次调用的成本越高。所以别偷懒该压缩就压缩。第四设置预算上限。在代码里加一个 token 计数器超过预算就报警或降级。这个在多人协作的项目里特别重要防止某个人写了个死循环把预算烧光。5.4 那些文档里不写的坑最后分享几个我在实际项目里踩过的、文档里基本不会提的坑。坑一模型名写错但没报错。有些提供方对模型名的校验不严格你写错一个字母它不报错而是默默用一个默认模型。结果你以为在用 A 模型实际在用 B 模型行为完全不对。解决办法是初始化之后先发一个测试请求确认返回的模型名和你预期的一致。坑二并发调用导致限流。Agent 场景经常需要并发调用模型比如同时处理多个用户请求。如果并发数太高会触发限流。解决办法是加一个信号量或队列控制并发数。具体设多少看提供方的限流策略一般从 5 到 10 开始试。坑三流式输出的连接泄漏。用流式输出的时候如果客户端提前断开服务端的连接可能不会自动释放。时间长了会耗尽连接池。解决办法是在流式输出的循环里加异常处理确保连接被正确关闭。坑四模型返回的 JSON 里有非法字符。模型输出的 JSON 有时候会包含控制字符或未转义的引号导致解析失败。解决办法是用一个健壮的 JSON 解析库或者在解析前先做一次清洗。坑五环境变量没加载。这个听起来很蠢但真的很常见。尤其是在容器环境里环境变量没传进去导致 API key 为空。解决办法是在启动时检查关键环境变量是否存在不存在就直接报错退出别等到调用的时候才发现。6. 关于模型接入这件事我的一点个人体会写了这么多最后说点掏心窝的话。Model 接入这一层技术上不难但细节特别多。很多人学 Agent 开发急于往上走去看架构、看编排、看多智能体协作结果地基没打牢上面盖的东西一碰就塌。我的建议是在这一层多花点时间把每个参数都搞明白把每种失败情况都跑一遍。你不需要成为模型专家但你需要知道你的模型在什么情况下会出问题、出了问题怎么查。这种“手感”是看多少教程都换不来的。还有一点别迷信任何一个模型。模型迭代太快了今天最好的模型半年后可能就被超越了。所以你的代码要写得足够灵活换模型的时候改动越小越好。这也是我为什么一直坚持用 LangChain 的抽象层、坚持把配置和代码分离的原因。最后分享一个我自己的习惯每次接入一个新模型我都会写一个小的测试脚本把温度、max_tokens、流式、工具调用、结构化输出这些场景都跑一遍记录下每个场景的表现和坑点。这个脚本我攒了好几个换模型的时候直接跑几分钟就能摸清一个新模型的脾气。这个习惯帮我省了无数时间推荐你也试试。