LangChain
FAQ · 常见问题
常见报错与坑,按「现象 → 原因 → 处理」整理。
- LangChain
- FAQ
按「现象 → 原因 → 处理」整理的常见问题。
安装与导入
加载器导入报 ModuleNotFoundError,或导入时打弃用警告?
1.x 里加载器和 FAISS 从 langchain_community 导入:pip install langchain-community。从 langchain_classic 导入同名类也能用,但那是弃用转发层,每次导入都打警告,不要走。优化型 retriever(MultiQueryRetriever 等)和 OutputFixingParser 才是 langchain-classic 原生。
No module named 'langchain_text_splitters?
切分器是独立包:pip install langchain-text-splitters。
create_react_agent / AgentExecutor 找不到?
1.x 已移除这套 API。改用 create_agent(langchain 包),对照表见 Agent 的迁移小节。
.env 里的 Key 没生效?
load_dotenv() 必须在读取环境变量的代码之前执行。把它放在入口文件的最前面。确认 .env 在项目根目录、变量名拼写正确、文件没有提交到 git。
调用与组链
401 错误为什么不重试?
max_retries 只重试网络错误、429 限流、5xx。401 这类客户端错误重试没有意义。Key 无效要换 Key;服务整体故障用 with_fallbacks 挂备用模型。
as_retriever(k=2) 传了 k 却返回 4 条?
直接传 k=2 会被静默忽略。必须写 as_retriever(search_kwargs={"k": 2})。
format / invoke 抛 KeyError?
模板变量没传齐。PromptTemplate.format 缺任一变量、chain 的输入字典缺 prompt 需要的键,都会抛 KeyError。用 prompt.input_variables 核对需要哪些变量。
invoke 卡住很久,最后超时或手动中断?
看 traceback 是否停在 socket.create_connection:那是连不上 API 地址。ChatOpenAI 默认请求 api.openai.com,国内网络通常不可达。用 OpenAI 兼容服务(GLM、DeepSeek、Kimi 等)必须配套传 base_url、api_key、model 三个参数,只换 Key 不换地址就会卡在这里:
from langchain_openai import ChatOpenAI # OpenAI 聊天模型
import os # 读取环境变量
model = ChatOpenAI(
base_url="https://open.bigmodel.cn/api/paas/v4", # 智谱的 OpenAI 兼容地址
api_key=os.environ["GLM_API_KEY"],
model="glm-4-flash", # 模型名以智谱文档为准
)
模型输出怎么变成字符串?
invoke 返回 AIMessage 对象,文本在 .content。链尾接 StrOutputParser 可以直接输出字符串。
RAG
FAISS load_local 报 pickle 反序列化错误?
传 allow_dangerous_deserialization=True。这是加载 pickle 的安全确认开关,只加载自己构建的文件可放心开启。
换了 embedding 模型后检索结果变差?
load_local 必须传与构建时同一个 embedding 模型。不同模型的向量空间不一致,相似度计算没有意义。
每次启动都产生 embedding 费用?
InMemoryVectorStore 每次运行都重新向量化全量文档。改用 FAISS:独立脚本构建一次并 save_local,业务脚本只 load_local。
PyPDFLoader 想拿整本一个 Document?
Python 版没有关闭按页切分的开关,手动拼接:"\n\n".join(doc.page_content for doc in pdfs)。
WebBaseLoader 抓不到正文? 它只处理静态 HTML,不执行页面 JS。SPA 页面换 Playwright 等浏览器类方案。
chunk_size / chunk_overlap 怎么设? 1.x 默认 4000 / 200(0.x 旧教程写的 1000 / 200 已过时),用 ChunkViz 检查切分结果,跑通链路后按回答质量回调。链路没跑通前不要精调。
检索得到的内容和问题不相关? 两类典型失效:提问关键词与原文不一致(「下酒菜」原文里没有);需要多层语义转换(「谋生」到「抄书」)。对策见检索与优化:MultiQuery 改写查询、压缩检索、调 k 或按分数过滤。
旧教程的 ScoreThresholdRetriever 导入失败?
该类在 1.x 已移除,langchain-classic 和 langchain-community 里都没有。需要按相似度过滤时,用 vectorstore.similarity_search_with_score(query, k=...) 拿到分数自己过滤,见第 12 节。
工具与 Agent
原生 API 里 tool_calls 的 arguments 传给函数报 TypeError?
arguments 是 JSON 字符串不是对象,必须先 json.loads。LangChain 的 bind_tools 返回的 tool_call["args"] 已是对象,无此问题。
带 checkpointer 的 agent 调用报错缺 thread_id?
带 checkpointer 的调用必须传 {"configurable": {"thread_id": ...}},框架要靠它定位线程状态。没有它直接报错。
agent 重启后忘了之前的对话?
InMemorySaver 存在进程内存,重启即丢。生产环境换 PostgresSaver,create_agent 参数不变。
抛出 GraphRecursionError?
工具循环步数达到 recursion_limit(默认 25)。按预期最大工具轮数的两倍调大该值,并在调用侧捕获这个异常返回兜底文案。它与 configurable 平级,不要塞进 configurable。
模型一次返回多个工具调用,程序只处理了第一个? 并行 tool_calls 本身不稳定,不应依赖。按「一轮一个工具」设计兜底,批量需求靠函数参数(如接受数组)解决。
模型编造了非法的枚举值?
把参数注解写成 Literal["a", "b", "c"],pydantic 校验会拦下非法值并把错误信息回传给模型重试。固定事实数据外置到 JSON 文件,不要让模型生成。
其他
怎么知道每步的输入输出?
from langchain_core.globals import set_debug # 开全局调试日志
set_debug(True)
日志量很大,调试完移除。长期观测用 LangSmith,见配置。
中文 prompt 还是英文 prompt? 内置组件的内置 prompt 多为英文,跨语言理解可用。纯中文业务建议自写中文 prompt,按中文表达习惯调整。