LangChain 1.0 模型接入实战：DeepSeek、OpenAI、通义千问统一切换

如果你是从 LangChain 0.2、0.3 一路用上来的，升到 1.0 之后最直观的感受一定是：import 路径又变了，以前顺手写的那套 ChatOpenAI 代码在新版本里要么报错、要么提示推荐用新的统一入口。这一篇不聊虚的，只干活。我会用同一套业务场景，把 DeepSeek、OpenAI、通义千问三个模型的接入分别跑通，再把它们封装成一套可以随时切换的调用入口。整个过程会标注版本号、环境变量、依赖包，以及我在真实项目里踩过的坑。适不适合新手？适合，只要你装好了 Python 3.10 以上环境，跟着敲一遍就能跑。已经有 LangChain 基础的朋友可以跳过第一部分，直接看模型接入部分。

1. 先看清 1.0 的接入层变化

1.1 为什么你的旧代码跑不起来了

LangChain 1.0 之前，模型接入的典型写法是这种：

from langchain.chat_models import ChatOpenAI

或者走社区包：

from langchain_community.chat_models import ChatOpenAI

到了 1.0，这两个路径都不再是主推方向。官方把“模型接入”做成了统一协议，每个模型供应商对应一个独立扩展包，比如langchain-openai、langchain-deepseek、langchain-dashscope。主包只保留统一接口和编排能力，不直接绑定某个模型的具体实现。这么改，表面上是路径变了，底层其实是两个原因：第一，社区包质量参差不齐，把模型接入分散到官方维护的扩展包，能保证每个供应商的适配及时跟进模型接口变化；第二，调用侧协议统一之后，业务代码不需要感知底层 HTTP 请求的差异，切换模型时改动量能控制在很小范围。

我碰到的第一个坑就是升级后直接pip install -U langchain，然后旧项目里报ModuleNotFoundError: langchain_community。这不是包没装，而是langchain_community里的模型实现被逐步移出，需要按需安装对应厂商扩展包。解决办法很简单，缺哪个装哪个，装完之后接口要改成新写法。

1.0 中所有模型调用都统一走invoke、stream、batch这些标准方法，不再推荐旧的__call__方式。你写的任何代码，只要接入层用的是这组标准方法，上游换模型基本无感。

1.2 init_chat_model 到底解决了什么问题

init_chat_model是 1.0 推荐的统一模型初始化入口。它做的事情很简单：根据你传入的model和model_provider两个参数，自动找到对应的实现类并实例化。比如这句：

from langchain.chat_models import init_chat_model llm = init_chat_model( model="gpt-4o-mini", model_provider="openai", )

它会自动读取OPENAI_API_KEY，创建一个 OpenAI 的聊天模型实例。换一个供应商也一样：

llm = init_chat_model( model="deepseek-chat", model_provider="deepseek", )

这条 API 表面上只是省了几行代码，实际解决的是一个很痛的维护问题：以前不同模型的初始化参数不统一，有的叫model_name，有的叫model，有的要传endpoint，有的要传base_url。项目里如果同时接三个模型，你会写三套初始化逻辑，还容易在切换时漏参数。init_chat_model把参数名统一成一套，把差异收敛到model_provider这一个维度上。

它的另一个价值在于：如果没有对应供应商的官方 provider，你仍然可以借助 OpenAI 兼容协议来接。很多模型平台都提供 OpenAI 兼容的 REST 接口，比如通义千问的兼容模式。遇到这种情况，init_chat_model可能没法直接覆盖，那就退一步用langchain_openai.ChatOpenAI配合base_url来实例化。

我建议新项目一律从init_chat_model起步，因为它强制你先把模型和供应商拆开。后面要换模型、做灰度、做多模型路由，代码结构上都会顺手很多。

2. 环境初始化与密钥管理

2.1 依赖安装与版本确认

先创建虚拟环境，我习惯用 venv，干净且不污染系统 Python：

python -m venv .venv source .venv/bin/activate

然后一次性装齐本文需要的包：

pip install -U langchain langchain-openai langchain-deepseek langchain-dashscope python-dotenv

装完确认版本，避免后续接口对不上：

import langchain print(langchain.__version__)

我实测时用的是 1.0.x 版本，如果你看到的大版本是 0.3.x，说明没装上最新的，需要检查是不是 pip 源缓存了旧版本，可以加--upgrade强制更新。

这里有一个很多人忽略的点：langchain-openai和openaiSDK 是两个东西。langchain-openai是 LangChain 对 OpenAI 的适配层，它底层会依赖openai库，但你不能只装openai就在 LangChain 里调ChatOpenAI。同理，langchain-deepseek、langchain-dashscope也是适配层，必须装。

2.2 三套 API Key 的配置与加载

三个模型对应三个 Key，统一放到项目根目录的.env文件里：

DEEPSEEK_API_KEY=sk-xxxxxxxx OPENAI_API_KEY=sk-xxxxxxxx DASHSCOPE_API_KEY=sk-xxxxxxxx

.env文件不是 Python 代码，不要在里面加引号，也不要带分号，直接键=值就行。然后在入口文件里加载：

import os from dotenv import load_dotenv load_dotenv()

这里有个实际开发中特别容易踩的坑：load_dotenv()默认会从当前工作目录找.env。如果你在 IDE 里运行脚本，工作目录可能不是项目根目录，导致加载不到 Key。解决方式是显式指定路径：

from pathlib import Path from dotenv import load_dotenv env_path = Path(__file__).resolve().parent / ".env" load_dotenv(dotenv_path=env_path)

还有一点，不要把 Key 写进代码再提交到 Git。我见过不止一次 Key 被提交到仓库，然后被爬虫抓走刷爆额度的例子。正确做法是.env加入.gitignore，仓库里只留一个.env.example模板，写清需要哪些环境变量，不填真实值。

如果你在服务器上跑，建议用进程环境变量或者密钥管理服务，比.env更安全。本地开发倒是无所谓，.env足够方便。

3. DeepSeek 接入实战

3.1 用官方扩展包快速接入

DeepSeek 的官方 LangChain 扩展包是langchain-deepseek，安装之后直接用init_chat_model接入：

from langchain.chat_models import init_chat_model llm = init_chat_model( model="deepseek-chat", model_provider="deepseek", temperature=0.7, max_tokens=2048, ) response = llm.invoke("用一句话解释什么是上下文窗口") print(response.content)

跑通之后你会看到类似输出：

上下文窗口是模型在生成回复时能同时参考的最大 token 数量，就像工作台能铺开多少张便签纸。

这个包会自动读取DEEPSEEK_API_KEY，不需要手动传api_key。如果你的环境变量名不是这个，也可以用api_key参数显式传：

llm = init_chat_model( model="deepseek-chat", model_provider="deepseek", api_key="sk-xxxx", )

不过我建议不要走显式传参路线，统一交给环境变量管理，后面切配置时只改.env，代码零变动。

3.2 DeepSeek 的参数习惯和实测要点

DeepSeek 有两个常用模型名，一个是deepseek-chat，一个是deepseek-reasoner。前者是通用对话模型，适合大部分业务场景；后者是推理增强模型，会先进行内部推理再给最终答案，适合数学、逻辑、代码这类任务。实测中我用deepseek-reasoner做复杂问题拆解，效果明显比普通模式更稳，但响应时间会变长，你需要评估业务是否能接受。

关于temperature，DeepSeek 官方范围是 0 到 2。我自己的经验是：代码生成、数据抽取、结构化输出这类任务，设置在 0.1 到 0.3 之间，减少幻觉；创意写作、头脑风暴，设置在 0.7 到 0.9，能明显感受到多样化；超过 1.0 之后，回答可能会开始出现不连贯，不建议常规使用。

max_tokens控制的是生成的最大 token 数，而不是总上下文长度。如果你需要模型输出很长的结果，务必调高这个值，否则会被截断。我之前做文档摘要时就吃过这个亏，默认 1024 直接把长文后半段截没了，摘要看起来像是烂尾。

实际项目中，DeepSeek 的接入成本低、中文理解好，尤其适合做知识库问答、文案生成、意图识别这类中文密集型的任务。它唯一的短板在我看来是工具调用生态没有 OpenAI 那么丰富，但基础 Function Calling 是支持的，简单 Agent 场景没问题。

4. OpenAI 接入实战

4.1 最小可用链路

OpenAI 的接入分两条路。一条是用init_chat_model统一入口：

llm = init_chat_model( model="gpt-4o-mini", model_provider="openai", temperature=0.3, )

另一条是直接用langchain_openai.ChatOpenAI：

from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="gpt-4o-mini", temperature=0.3, )

两条路最终拿到的都是BaseChatModel的子类，调用方式一致。区别在于init_chat_model更强调 provider 抽象，ChatOpenAI则保留了 OpenAI 系特有的参数透传能力。

我建议基础场景用init_chat_model，但是如果你的代码里已经写了一批基于ChatOpenAI的逻辑，且暂时不想重构，直接用ChatOpenAI也完全没问题。LangChain 1.0 没有强制你必须换 API，只是给了更推荐的入口。

4.2 结构化输出：让模型按 Schema 返回

OpenAI 的强项之一就是结构化输出和函数调用。在 LangChain 里做结构化输出最方便的方式是结合 Pydantic：

from pydantic import BaseModel, Field from langchain.chat_models import init_chat_model class MovieReview(BaseModel): name: str = Field(description="电影名称") score: int = Field(description="1到10分的评分") reason: str = Field(description="评分理由") llm = init_chat_model( model="gpt-4o-mini", model_provider="openai", temperature=0.2, ) structured_llm = llm.with_structured_output(MovieReview) result = structured_llm.invoke("评价一部最近上映的科幻电影") print(result.name, result.score, result.reason)

with_structured_output是 LangChain 提供的便捷方法，底层会根据模型能力自动选择 JSON mode、函数调用或工具调用，然后帮你把模型输出解析成 Pydantic 对象。这样你拿到的就不是一个自由文本，而是一个可以直接取字段的对象，后续下游逻辑干干净净。

这里要注意，结构化输出对模型版本有要求，别用太老的模型名。如果你用的是某个不支持 JSON mode 的模型，with_structured_output会退化成提示词解析，准确性会打折扣。实测下来，OpenAI 的gpt-4o系在结构化输出上最稳，DeepSeek 和千问也支持，但偶尔需要多试几次。

5. 通义千问接入实战

5.1 官方 DashScope 包

通义千问的官方 LangChain 扩展包是langchain-dashscope，安装后通过model_provider="dashscope"接入：

from langchain.chat_models import init_chat_model llm = init_chat_model( model="qwen-plus", model_provider="dashscope", temperature=0.6, ) response = llm.invoke("写一段电商客服欢迎语，语气亲和") print(response.content)

它会自动读取DASHSCOPE_API_KEY。千问的模型名主要有qwen-turbo、qwen-plus、qwen-max几个档位，turbo便宜快速，plus均衡，max更强但更贵。还有一个qwen-long专门处理超长文本，如果你做百万 token 级别的文档分析，可以优先看它。

实测中，千问在中文理解、中文知识问答上表现很稳，特别是涉及中文文化、习惯用语、口语化表达时，回答的自然度比很多海外模型好。它的响应速度也快，大批量调用时成本控制有明显优势。

5.2 OpenAI 兼容模式与 base_url

除了官方包，通义千问还提供了 OpenAI 兼容接口。这意味着你可以只用langchain_openai，不装langchain-dashscope，直接切换base_url就能接上千问：

import os from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="qwen-plus", api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", ) response = llm.invoke("你好，介绍一下你自己") print(response.content)

这种方式的爽点在于：你以前如果是一套ChatOpenAI写到底的代码，切到千问只需要把base_url换掉，业务逻辑一行都不用动。对于已经有大量 OpenAI 兼容代码的团队，这是最小成本的迁移方案。

两种方式怎么选？我的建议是：新建项目优先用官方包langchain-dashscope，因为它和 LangChain 的抽象集成得更深；存量项目用 OpenAI 兼容模式，改造量最小。不管用哪种，都建议在代码里加一层配置开关，别在多个文件里硬编码模型名和 base_url。

6. 统一封装与模型切换

6.1 做一个 get_llm 工厂函数

三个模型都跑通之后，下一步就是把它们统一到一个入口。我习惯的做法是写一个工厂函数，用配置项决定当前用哪个模型：

import os from langchain.chat_models import init_chat_model from langchain_openai import ChatOpenAI def get_llm(provider: str, model: str, temperature: float = 0.3): if provider == "openai": return init_chat_model( model=model, model_provider="openai", temperature=temperature, ) if provider == "deepseek": return init_chat_model( model=model, model_provider="deepseek", temperature=temperature, ) if provider == "qwen": # 优先走 OpenAI 兼容模式，方便统一维护 return ChatOpenAI( model=model, api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", temperature=temperature, ) raise ValueError(f"Unsupported provider: {provider}")

使用的时候，配置项一份文件管住：

llm = get_llm( provider=os.getenv("LLM_PROVIDER", "deepseek"), model=os.getenv("LLM_MODEL", "deepseek-chat"), )

这样一来，业务代码里只有一个llm对象，不存在散落的模型初始化逻辑。切换模型时只改.env里的LLM_PROVIDER和LLM_MODEL，或者在调参数时改调用侧配置，不需要碰业务代码。

我在实际项目里还会再加一层缓存，比如用functools.lru_cache把已初始化的模型实例缓存住，避免每次调用都重新初始化，省去不必要的握手开销。

6.2 三个模型的实测对比与取舍

把三个模型放在同一个场景里轮换测试了几轮之后，我的感受是这样的：

如果你做的是中文知识库问答、文本摘要、内容生成，DeepSeek 和千问都能打；如果做复杂 Agent、多步推理、需要频繁工具调用的系统，OpenAI 的稳定性暂时还是最优解。

我的习惯是：项目里默认 DeepSeek 跑快速验证，验证通过后线上长期运行用千问，因为成本更可控。OpenAI 更多用来做评测基准——拿同一批问题跑三个模型，输出对比一下，很快能看出差异。

6.3 超时与重试策略

模型接入还有一个容易被忽略但线上一定会遇到的点：超时和重试。默认配置下，如果模型服务暂时不可用或者请求量过大，你的代码可能直接抛异常，体验很不好。

ChatOpenAI和init_chat_model都支持传入timeout和max_retries：

llm = init_chat_model( model="gpt-4o-mini", model_provider="openai", timeout=60, max_retries=2, )

timeout单位是秒，设置的是单次请求的超时上限。max_retries是在遇到网络错误、5xx错误、连接超时时自动重试的次数。注意它不会对 429 限流无限重试，429 的处理主要靠指数退避，OpenAI 的 SDK 内部已经有基础重试，LangChain 这层主要兜住连接层的问题。

我在生产环境里还会再包一层异常捕获，把模型不可用、超时、限流这些情况统一转成业务侧可读的提示，而不是直接把堆栈抛给用户。

7. 常见问题速查表

7.1 API 错误与模型参数问题

7.2 容易踩的版本与路径细节

还有一个高频问题：把model写成model_name。新版本统一用model，但很多旧资料还在写model_name，直接搬过来会报不认识的参数。如果你看到 Type 相关报错，第一件事检查是不是参数名写错了。

langchain_community里的模型类在 1.0 中不再是主力，别指望装一个langchain全功能包就什么模型都能接。供应商对应的扩展包必须单独装：OpenAI 用langchain-openai，DeepSeek 用langchain-deepseek，千问用langchain-dashscope。装错了包，init_chat_model会在初始化时直接告诉你找不到对应 provider。

如果你用的是公司内部网关，自建模型服务，且它提供 OpenAI 兼容接口，那ChatOpenAI配合自定义base_url是你唯一需要掌握的姿势。这一点对所有兼容 OpenAI 协议的服务都通用，学会了就是一通百通。

最后再分享一个个人习惯

模型接入这件事，很多人只做到“能跑通”就停了，但我建议你一定要做到“能切换”。哪怕你现在只用一个模型，也把工厂函数和配置项结构搭好。原因很简单：模型市场变化太快，今天的最优解可能三个月后就变了。接口统一了，切换成本低了，你才有更多试错空间。

另外一个小技巧：无论用哪个模型，保存一个“标准测试集”，里面放几十条覆盖不同业务场景的问题。每次接入新模型、改模型版本、调参数，先用这套测试集跑一遍批量回归，对比输出质量，比自己零散地试几个问题靠谱得多。这个办法救了我很多次，希望也能帮到你。