系列问题解决方案库1/5难度⭐⭐ 初级预计阅读时间10分钟适用人群LangChain初学者、遇到问题的开发者持续更新欢迎留言补充你遇到的错误引言LangChain是目前最流行的LLM应用开发框架但学习曲线较陡。根据GitHub Issues和论坛反馈我总结了新手最容易犯的10个错误。如果你正在学习LangChain这篇文章能帮你节省大量调试时间错误1模块导入失败❌ 错误现象from langchain.chat_models import ChatOpenAI # ModuleNotFoundError: No module named langchain.chat_models 原因分析LangChain在0.1.0版本后进行了模块化拆分langchain→ 核心功能langchain-openai→ OpenAI集成langchain-chroma→ Chroma向量数据库langchain-community→ 社区贡献的组件✅ 解决方案# 安装正确的包 pip install langchain langchain-openai langchain-chroma# 使用新的导入路径 from langchain_openai import ChatOpenAI from langchain_chroma import Chroma检查清单[ ] 确认LangChain版本 0.1.0[ ] 安装对应的子模块包[ ] 查看官方迁移指南错误2API调用超时❌ 错误现象llm ChatOpenAI(modelgpt-3.5-turbo) response llm.invoke(你好) # TimeoutError: Request timed out 原因分析网络不稳定API服务器响应慢未设置超时参数✅ 解决方案from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-3.5-turbo, timeout30, # 设置超时时间秒 max_retries3, # 重试次数 request_timeout60 # 请求超时 )优化建议生产环境必须设置超时和重试使用异步调用提升性能考虑添加缓存机制错误3记忆丢失❌ 错误现象from langchain.memory import ConversationBufferMemory memory ConversationBufferMemory() memory.save_context({input: 我叫小明}, {output: 你好小明}) # 下次对话时AI不记得之前的内容 原因分析Memory对象未正确传递给Chain使用了错误的Memory类型未持久化存储✅ 解决方案from langchain.chains import ConversationChain from langchain.memory import ConversationBufferMemory memory ConversationBufferMemory() chain ConversationChain( llmllm, memorymemory, # ← 关键必须传递给Chain verboseTrue ) # 多轮对话 chain.run(我叫小明) chain.run(我今年25岁) chain.run(我叫什么名字) # AI会回答小明进阶方案持久化存储from langchain.memory import ConversationBufferWindowMemory # 只保留最近5轮对话避免上下文过长 memory ConversationBufferWindowMemory(k5) # 或使用Redis持久化 from langchain.memory import RedisChatMessageHistory memory ConversationBufferMemory( chat_memoryRedisChatMessageHistory(session_iduser_123) )错误4工具定义不规范❌ 错误现象from langchain.tools import Tool # 工具描述不清晰Agent无法正确使用 tool Tool( namecalculator, funclambda x: eval(x), description计算 # ← 描述太简单 ) 原因分析Agent依赖工具描述来决定何时调用工具。描述不清会导致Agent不调用工具传入错误参数无限循环调用✅ 解决方案from langchain.tools import Tool def calculate(expression: str) - str: 安全计算数学表达式 try: return str(eval(expression, {__builtins__: {}}, {})) except Exception as e: return f计算错误: {str(e)} tool Tool( nameCalculator, funccalculate, description( 用于执行数学计算。 输入应为有效的数学表达式如 2 2 或 3 * (4 5)。 支持加减乘除、括号、幂运算等。 ) )最佳实践工具名称使用驼峰命名描述包含用途、输入格式、输出格式、示例添加完善的错误处理错误5Prompt格式错误❌ 错误现象from langchain.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_template( 你是一个助手。 用户问题{question} ) # 使用时忘记提供变量 prompt.format() # KeyError: question 原因分析模板变量与实际传入不匹配使用了错误的占位符语法特殊字符未转义✅ 解决方案from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder # 方法1简单模板 prompt ChatPromptTemplate.from_template( 你是一个{role}。用户问题{question} ) formatted prompt.format(role助手, question你好) # 方法2聊天模板推荐 prompt ChatPromptTemplate.from_messages([ (system, 你是一个有用的助手), (human, {question}), ]) # 方法3带历史消息 prompt ChatPromptTemplate.from_messages([ (system, 你是一个助手), MessagesPlaceholder(variable_namehistory), (human, {question}), ])调试技巧# 打印格式化后的Prompt print(prompt.format(question测试))错误6向量存储配置错误❌ 错误现象from langchain.vectorstores import Chroma # 嵌入维度不匹配 vectorstore Chroma.from_documents(documents, embeddings) # ValueError: Embedding dimension mismatch 原因分析嵌入模型与向量数据库维度不一致首次创建后后续加载使用了不同的嵌入模型未指定集合名称✅ 解决方案from langchain_openai import OpenAIEmbeddings from langchain_chroma import Chroma embeddings OpenAIEmbeddings(modeltext-embedding-ada-002) # 首次创建 vectorstore Chroma.from_documents( documentsdocuments, embeddingembeddings, collection_namemy_collection, # ← 指定集合名 persist_directory./chroma_db ) # 后续加载必须使用相同的嵌入模型 vectorstore Chroma( collection_namemy_collection, embedding_functionembeddings, persist_directory./chroma_db )注意事项嵌入模型一旦确定不要更换不同集合可以使用不同的嵌入模型定期备份向量数据库错误7链式调用错误❌ 错误现象from langchain.chains import LLMChain chain LLMChain(llmllm, promptprompt) # 调用方式错误 result chain(你好) # TypeError 原因分析Chain的调用方式因版本而异旧版chain.run()新版chain.invoke()✅ 解决方案# 推荐方式新版API result chain.invoke({question: 你好}) # 兼容方式 result chain.run(question你好) # 批量处理 results chain.batch([ {question: 问题1}, {question: 问题2}, ])异步调用提升性能import asyncio async def main(): result await chain.ainvoke({question: 你好}) print(result) asyncio.run(main())错误8异步处理问题❌ 错误现象# 在同步函数中调用异步方法 def my_function(): result llm.ainvoke(你好) # RuntimeWarning 原因分析混用同步和异步代码未在协程中调用异步方法事件循环冲突✅ 解决方案import asyncio from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-3.5-turbo) # 方法1使用async/await async def chat_async(): result await llm.ainvoke(你好) return result result asyncio.run(chat_async()) # 方法2在FastAPI中自动处理异步 from fastapi import FastAPI app FastAPI() app.post(/chat) async def chat(question: str): result await llm.ainvoke(question) return {answer: result.content}错误9版本兼容性❌ 错误现象DeprecationWarning: This feature is deprecated and will be removed in future versions. 原因分析LangChain迭代快速API经常变化0.0.x → 0.1.x重大重构小版本也可能有Breaking Changes✅ 解决方案# 固定版本生产环境 pip install langchain0.1.12 pip install langchain-openai0.0.8 # 查看当前版本 pip show langchain# 代码中添加版本检查 import langchain print(fLangChain version: {langchain.__version__})升级建议先在测试环境验证阅读发布说明逐步升级不要跨大版本错误10性能优化不足❌ 错误现象响应速度慢5秒内存占用高并发能力差 原因分析未使用缓存每次都重新构建索引同步串行处理✅ 解决方案优化1缓存from functools import lru_cache lru_cache(maxsize1000) def cached_query(question: str): return chain.invoke({question: question})优化2批量处理# 串行慢 for q in questions: chain.invoke({question: q}) # 并行快 results chain.batch([{question: q} for q in questions])优化3流式输出for chunk in llm.stream(写一首诗): print(chunk.content, end, flushTrue)优化4异步并发import asyncio async def process_questions(questions): tasks [chain.ainvoke({question: q}) for q in questions] results await asyncio.gather(*tasks) return results总结错误关键解决优先级模块导入安装子模块包⭐⭐⭐⭐⭐API超时设置timeout和retries⭐⭐⭐⭐⭐记忆丢失正确传递Memory对象⭐⭐⭐⭐工具定义详细描述错误处理⭐⭐⭐⭐Prompt格式使用MessagesPlaceholder⭐⭐⭐⭐向量存储固定嵌入模型集合名⭐⭐⭐⭐⭐链式调用使用invoke()而非run()⭐⭐⭐异步处理async/await正确使用⭐⭐⭐版本兼容固定版本号⭐⭐⭐⭐性能优化缓存批量异步⭐⭐⭐⭐ 互动环节投票你遇到过哪些错误[ ] 模块导入失败[ ] API调用超时[ ] 记忆丢失[ ] 其他留言说明留言你还遇到了哪些LangChain的错误留言告诉我我会持续更新这篇文章预告下一篇《Agent开发10个常见陷阱》敬请期待相关链接LangChain官方文档