系列：问题解决方案库（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
  • [ ] 安装对应的子模块包
  • [ ] 查看官方迁移指南

错误2：API调用超时

❌ 错误现象

llm = ChatOpenAI(model="gpt-3.5-turbo")
response = llm.invoke("你好")
# TimeoutError: Request timed out

🔍 原因分析

  • 网络不稳定
  • API服务器响应慢
  • 未设置超时参数

✅ 解决方案

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-3.5-turbo",
    timeout=30,           # 设置超时时间（秒）
    max_retries=3,        # 重试次数
    request_timeout=60    # 请求超时
)

优化建议：

  • 生产环境必须设置超时和重试
  • 使用异步调用提升性能
  • 考虑添加缓存机制

错误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(
    llm=llm,
    memory=memory,  # ← 关键：必须传递给Chain
    verbose=True
)

# 多轮对话
chain.run("我叫小明")
chain.run("我今年25岁")
chain.run("我叫什么名字？")  # AI会回答"小明"

进阶方案：持久化存储

from langchain.memory import ConversationBufferWindowMemory

# 只保留最近5轮对话，避免上下文过长
memory = ConversationBufferWindowMemory(k=5)

# 或使用Redis持久化
from langchain.memory import RedisChatMessageHistory
memory = ConversationBufferMemory(
    chat_memory=RedisChatMessageHistory(session_id="user_123")
)

错误4：工具定义不规范

❌ 错误现象

from langchain.tools import Tool

# 工具描述不清晰，Agent无法正确使用
tool = Tool(
    name="calculator",
    func=lambda 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(
    name="Calculator",
    func=calculate,
    description=(
        "用于执行数学计算。"
        "输入应为有效的数学表达式，如 '2 + 2' 或 '3 * (4 + 5)'。"
        "支持加减乘除、括号、幂运算等。"
    )
)

最佳实践：

  • 工具名称使用驼峰命名
  • 描述包含：用途、输入格式、输出格式、示例
  • 添加完善的错误处理

错误5：Prompt格式错误

❌ 错误现象

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_name="history"),
    ("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(model="text-embedding-ada-002")

# 首次创建
vectorstore = Chroma.from_documents(
    documents=documents,
    embedding=embeddings,
    collection_name="my_collection",  # ← 指定集合名
    persist_directory="./chroma_db"
)

# 后续加载（必须使用相同的嵌入模型）
vectorstore = Chroma(
    collection_name="my_collection",
    embedding_function=embeddings,
    persist_directory="./chroma_db"
)

注意事项：

  • 嵌入模型一旦确定，不要更换
  • 不同集合可以使用不同的嵌入模型
  • 定期备份向量数据库

错误7：链式调用错误

❌ 错误现象

from langchain.chains import LLMChain

chain = LLMChain(llm=llm, prompt=prompt)

# 调用方式错误
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(model="gpt-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 langchain==0.1.12
pip install langchain-openai==0.0.8

# 查看当前版本
pip show langchain

# 代码中添加版本检查
import langchain
print(f"LangChain version: {langchain.__version__}")

升级建议：

  • 先在测试环境验证
  • 阅读发布说明
  • 逐步升级，不要跨大版本

错误10：性能优化不足

❌ 错误现象

  • 响应速度慢（>5秒）
  • 内存占用高
  • 并发能力差

🔍 原因分析

  • 未使用缓存
  • 每次都重新构建索引
  • 同步串行处理

✅ 解决方案

优化1：缓存

from functools import lru_cache

@lru_cache(maxsize=1000)
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="", flush=True)

优化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个常见陷阱》，敬请期待！

相关链接

Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

[Dify x EdgeOne] 哄睡童话机——用 Dify + EdgeOne Pages 给娃造一个会现挂的 AI 睡前故事神器

avatar AtomGit开源社区
cover

PP-OCRv5 ONNX部署但使用OnnxOCR

avatar AtomGit开源社区

MCP（Model Context Protocol）技术深度解析：AI Agent的标准化接口革命

AI技术的发展路径清晰展现了从对话机器人(Chatbot)→辅助决策助手(Copilot)→自主执行Agent的演进轨迹。随着AI在任务中参与度的不断提升，对**丰富的任务上下文(Context)和执行行动所需的工具(Tool)**的需求也日益增长。平台依赖性强：OpenAI、Google等不同LLM平台的Function Call API实现差异巨大开发耦合度高：工具开发者需要深入了解Agent

avatar AtomGit开源社区