排坑笔记：LangChain 1.x API 迁移：create_react_agent 与 ChatOllama 导入错误完整解决方案

📌 文章摘要

pip 安装 langchain 成功，但运行时报错 ImportError: cannot import name create_react_agent？根本原因是 LangChain 1.x 大版本升级，Agent 编排与 ChatOllama 等 API 发生了迁移与拆分。本文完整拆解两类易混淆报错的排查方法、两条 API 迁移路径，给出版本锁上下界 + 代码双路径兼容 + 依赖树冻结三套解决方案，实现跨版本可复现。

与既有笔记的关系 ：LangChain版本冲突避坑指南（163023034）讲的是怎么用虚拟环境把版本冲突隔离掉 ，解决「多项目互相打架」；本文讲大版本把 API 搬走了该怎么改代码，解决「环境隔离干净了，照旧跑不起来」。两篇互补，建议先读隔离那篇。

[第二层：1.x 到底搬走了什么](#第二层：1.x 到底搬走了什么)

[方案三：把验证过的依赖树冻结（交接 / CI 场景）](#方案三：把验证过的依赖树冻结（交接 / CI 场景）)

五、验证结果

六、预防措施

[📎 系列导航](#📎 系列导航)

[💣 评论区互动](#💣 评论区互动)

📋 快速自检：你是不是也遇到了这些问题？

▢ pip 安装成功，import 却报找不到符号？

▢ 旧代码复制过来跑不通，环境都是新的？

▢ 报错指向自己的代码，看不出和版本有关？

本文帮你一步定位根因。

一、问题现象

《智联工坊实战：工业数据质量自动检测方案》给一个本地模型 + ReAct Agent 的项目装依赖，pip install -r requirements.txt 全程绿灯，没有一个 WARN。跑起来第一行就炸：

bash 复制代码

ImportError: cannot import name 'create_react_agent' from 'langchain.agents'

按搜索结果改了导入路径，第二处接着炸：

bash 复制代码

ImportError: cannot import name 'ChatOllama' from 'langchain_community.chat_models'

我的第一反应是：这不科学啊...... 需求文件里写的就是 langchain>=0.2，条件满足、安装成功，报错指向的偏偏是我自己写的那行 import。代码从头到尾没动过，凭什么今天红、昨天绿？

📋 快速自检：你是不是也遇到了这些现象？

▢ pip install 成功、pip show 能查到包，但 import 报「找不到模块 / 找不到符号」

▢ 网上前几年的教程代码复制过来就是跑不通，作者环境却是好的

▢ 报错堆栈指向自己的代码文件，看不出跟依赖版本有关系

本文一次性解决以上所有问题。

二、影响范围

维度	影响
排查成本	报错指向业务文件，检索时容易在「是不是我写错了」上耗掉半天
团队协作	A 机器能跑、B 机器不能跑，差异只在依赖树，新人无法复现
交付节奏	昨天交付的环境，今天同事 clone 下来就红
隐性风险	装了新版本但只用到未迁移的 API，平时无感，等某天调用到迁移过的接口才集中爆发

三、排查过程

第一层：先分清「没装上」和「版本不对」

两类故障现象几乎一样，处理方式完全不同，一条命令就能分开：

bash 复制代码

python -c "import langchain, langchain_community, langchain_core; print(langchain.__version__, langchain_community.__version__)"

报 ModuleNotFoundError → 包真没装上（镜像源、包名拼写、Python 版本不匹配）
正常打印版本号，但导入某个符号报 ImportError → 包在，符号被搬走了，属于 API 迁移

这一步是本文最想帮你省下的时间：ImportError: cannot import name X 与 ModuleNotFoundError: No module named X 是两回事，前者查版本，后者查安装。分错方向，排查时间直接翻倍。

第二层：1.x 到底搬走了什么

本次实测装到的是 langchain 1.4.2 / langchain-community 0.4.2，两个炸点对应两条迁移路径：

炸点	旧路径	新路径	触发版本
Agent 编排	`from langchain.agents import create_react_agent, AgentExecutor`	`from langchain_classic.agents import ...`	langchain ≥ 1.0（独立包 `langchain-classic`）
ChatOllama	`from langchain_community.chat_models import ChatOllama`	`from langchain_ollama import ChatOllama`	langchain-community ≥ 0.4（独立包 `langchain-ollama`）

第二个坑更隐蔽：langchain-community 0.4 起把 ChatOllama 移出了。community 装上了、包也在、就是没有这个类，而 langchain-ollama 是后来才拆出来的独立包，不显式安装就一定没有。

第三层：为什么「代码没动」会突然坏

langchain>=0.2 的语义是「0.2 以上任意版本」，pip 每次安装都会解析到当前最新稳定版。故障点（我写的 import 语句）与根因（依赖版本）不在同一个文件里 ------这是环境漂移型故障最难定位的特征：报错永远指向你的代码，答案躺在 pip list 里。

四、解决方案

方案一：版本锁上下界（治本，先做）

bash 复制代码

# requirements.txt
langchain>=0.3,<2.0
langchain-core>=0.3,<2.0
langchain-community>=0.3,<0.5
langchain-classic>=1.0,<2.0      # 1.x 起 Agent 编排迁至此，0.3.x 下不会被安装
langchain-ollama>=0.2,<2.0       # ChatOllama 宿主包，community 0.4 起独立

三个动作：给 langchain 补上界；显式声明 langchain-classic 与 langchain-ollama；其余 langchain 系包统一带上界。

方案二：代码侧双路径兼容（防御，必须做）

python 复制代码

try:  # langchain < 1.0：Agent 编排在主包
    from langchain.agents import AgentExecutor, create_react_agent
except (ImportError, AttributeError):  # langchain >= 1.0 回退路径
    from langchain_classic.agents import (  # type: ignore[no-redef]
        AgentExecutor,
        create_react_agent,
    )

try:  # ChatOllama 已移出 community，独立包优先
    from langchain_ollama import ChatOllama
except ImportError:  # 旧环境回退
    from langchain_community.chat_models import ChatOllama  # type: ignore[no-redef]

except 里带上 AttributeError 有必要：部分过渡版本是「模块在、符号被摘走」，ImportError 接不住，只写它会漏掉这一类。

方案三：把验证过的依赖树冻结（交接 / CI 场景）

复制代码

pip freeze > requirements.lock     # 交付或交接时锁死整棵依赖树

适用：给同事交接环境、给 CI 装可复现环境。长期维护仍以方案一管理，方案三只是把「这次验证过的状态」冻结住。

💡 补充坑：版本锁了还是报错？缓存没清不注意会怎样：修改 requirements.txt 重新安装，pip 使用缓存的旧版本包，实际版本没变化，报错依旧。正确做法：安装时加上--force-reinstall参数，强制重新安装对应版本；或者执行pip cache purge清理缓存后再安装。

五、验证结果

双保险落地后实测：

bash 复制代码

pip install -r requirements.txt   # 按锁定区间安装，不再跳到裸最新版
python 02_test_cli.py             # Agent 正常构建、注册工具、调用模型

✅ 修复成功三大标志

✅ pip show langchain 版本落在锁定区间内，且 langchain-classic、langchain-ollama 均在列

✅ 启动不再出现 ImportError: cannot import name ...，Agent 全链路跑通

✅ 降级验证：把 langchain 退回 0.3.x 再跑，兼容导入走旧路径依然全通（两个版本环境都能跑，才叫双保险）
老蒋有感而发：做了二十多年开发，最烦的就是这种 "报错不说明原因，全靠自己踩坑" 的库。把排查逻辑讲清楚，把兼容方案做扎实，团队协作和环境复现才能少很多麻烦。

六、预防措施

怕你忘了，我再啰嗦一遍：langchain 1.x 搬走了 Agent 编排与 ChatOllama，只写下界的依赖声明会在某次 pip install 时把环境推过 breaking change。

落到具体操作上就是三条：

先分清两类 pip 故障 ：ModuleNotFoundError 查安装（可参考 pip 报 No matching distribution found？别怀疑包名，先查镜像源 403（165708407）），ImportError: cannot import name 查版本与 API。别对着已经装好的包反复重装。
langchain 系依赖一律锁上下界，新拆出来的包显式声明，别指望主包捎带。
版本锁 + 兼容导入双保险缺一不可：只锁版本，团队里总有人用旧环境；只做兼容导入，下次 2.x 再炸一次。两条一起上，环境才谈得上可复现。

适用范围：

本方案适用于所有 LangChain 0.3.x→1.x 版本迁移场景，同样的兼容导入思路可复用至其他大版本断裂的 Python 库；若为全新项目，建议直接使用 1.x 稳定版架构，无需向下兼容。尤其是「本地模型 + ReAct 编排」场景。方案二的兼容导入思路同样适用于 ChatTongyi、ChatZhipuAI 等 community 模型类：先查该类是否已拆出独立包，再决定兼容顺序。

标签：#Python #LangChain #排坑笔记 #依赖管理 #版本兼容 #ImportError #AI开发环境 #Agent开发

📎 系列导航

系列传送门：【制造业数据与AI落地实战】【AI赋能数据开发工程手册】【数据与AI工程排坑笔记】

本文问题源自： 智联工坊实战：工业数据质量自动检测方案 3σ 原则 + Agent 编排 + 分层容错完整实践

TOP2、还在翻 git log 写周报？WorkBuddy 一键生成结构化周报

TOP3、老攻城狮的AI开发环境搭建全记录：从零到跑通本地大模型（一日速通版）

TOP4、LangChain Agent 反复调用工具死循环？结构化返回 + Prompt 规则

TOP5、智联工坊实战：多工具协同Agent，让AI像人类一样规划与执行复杂任务

TOP6、代码审查不想得罪人？WorkBuddy 先做第一轮审查

💣 评论区互动

兄弟们，langchain 版本迁移的排坑指南更了，安装成功但 import 报错的经典坑讲透了，版本锁 + 兼容导入双保险方案都有。

整理好了可直接复用的兼容导入代码模板，评论区留 「langchain 排坑」 我发你。

你们用 langchain 还踩过什么离谱的坑？评论区聊聊，点赞高的我接着出排坑篇。