排错与迁移

排错与迁移：LangChain 旧教程升级 v1 与报错原文速查

网上多数 LangChain 教程写于 0.1 到 0.3 时期，照着在 v1 上运行，常常第一行就报错。先判断你面对的是旧教程、旧项目，还是一行具体报错，再按对应方法处理。

先选你的情况

不确定自己属于哪种，先看环境里装的是哪个版本：运行 pip show langchain，看输出里的 Version。

以 0. 开头：在验证过的 0.3.27 里，旧教程常见的 import 全部能导入，只是部分会打印弃用警告。计划升级时，再回到这里；
以 1. 开头：在验证过的 1.4.7 里，langchain.chains、langchain.memory、langchain.prompts 这类旧 import 会直接报错，先看旧教程迁移对照。

从旧教程的写法出发，一步步升级到 v1，并且每一步都留好回滚点。

LangChain 旧教程迁移到 v1：导入、调用与报错对照速查 · 更新于 2026-10-26
对着旧教程，把 import、调用方式和参数名逐条换成 v1 写法。
LangChain 从 v0.x 升级到 v1：分步迁移与回滚 Runbook · 更新于 2026-10-25
先用 langchain-classic 零行为变更地换 import，再迁到 create_agent，每一步都有可回滚的检查点。
旧 RAG 入库代码升级到 v1：加载、切分、向量库怎么换，结果变不变指南 · 更新于 2026-10-27
换完入库代码的 import，确认块数、块内容和检索顺序没变，并决定停止维护的 langchain-community 里哪些环节要换掉。
RetrievalQA 与 LLMChain 迁移到 LCEL：保持结果一致 Runbook · 更新于 2026-10-26
迁移前后量出消息内容、返回值形状、模型调用次数和检索为空时的差异，调用方不用改。
ConversationBufferMemory 迁移到 v1：thread_id、持久化与历史裁剪 Runbook · 更新于 2026-10-26
迁移对话记忆，并确认不同 thread_id 之间互相隔离、没有静默失忆。

拿报错原文或症状对号入座，再进入对应的实验定位原因。

LangChain 生产故障速查：13 类报错的原因与处理速查 · 更新于 2026-10-25
按报错原文或症状找到条目，并跳到对应的详细实验。
工具调用 schema 排障：docstring、参数校验与异常处理速查 · 更新于 2026-10-26
定位并修好工具 schema 与参数校验导致的调用失败。

症状	从这里开始
照着旧教程敲代码，第一行 import 就报错	v1 迁移与旧写法对照
升级 `langchain` 之后出现 `ModuleNotFoundError`	导入兼容矩阵，再按迁移 Runbook操作
项目里还在用 `AgentExecutor`、`LLMChain`	迁移 Runbook
旧的 RAG 入库代码（`TextLoader`、`RecursiveCharacterTextSplitter`、`FAISS`）要升级，或者担心升级后入库结果变了	旧 RAG 入库代码升级到 v1
旧的 `RetrievalQA` 要迁到 LCEL	RetrievalQA 与 LLMChain 迁移到 LCEL
对话历史丢了，或者不同用户的会话串线	对话记忆迁移
手里只有一行报错原文	生产故障速查
模型给工具传错了参数，或者工具抛异常后 Agent 的行为不符合预期	工具调用 schema 排障
设了 `LANGSMITH_TRACING=false` 还有 trace，或者设了 `true` 却没有 trace	追踪环境变量：新旧变量并存时谁生效

只需查询某个 import 或变量优先级时，直接使用参考手册。v0.1 / v0.2 的内容仅用于维护旧项目，不适合作为 v1 实现依据，保存在历史版本，只为让旧链接继续可用。

最后更新于 2026-10-27