核心架构 | LangChain 1.0 Python 知识文档

🔍 问题分类

💡 快速导航

根据错误类型快速跳转到对应的解决方案：

导入错误 - ModuleNotFoundError, ImportError
API 错误 - 认证失败、配额超限
模型错误 - 模型不支持、参数错误
工具错误 - 工具调用失败、参数验证
Agent 错误 - 无限循环、状态错误
内存错误 - Checkpointer、Store 问题
性能问题 - 响应慢、超时
调试工具 - LangSmith、日志配置

📦 导入错误

错误 1: ModuleNotFoundError: No module named 'langchain'

⚠️ 错误信息

ModuleNotFoundError: No module named 'langchain'

原因：未安装 LangChain 包

解决方案：

Bash

# 安装核心包
pip install langchain

# 安装特定提供商的包
pip install langchain-openai
pip install langchain-anthropic
pip install langchain-google-genai

错误 2: ImportError: cannot import name 'create_agent'

⚠️ 错误信息

ImportError: cannot import name 'create_agent' from 'langchain'

原因：导入路径错误或版本不匹配

解决方案：

Python

# ❌ 错误的导入
from langchain import create_agent

# ✅ 正确的导入
from langchain.agents import create_agent

# 确保版本正确
# pip install langchain>=1.0.0

错误 3: 使用了 langchain-classic 的 API

⚠️ 错误信息

AttributeError: module 'langchain' has no attribute 'LLMChain'

原因：使用了 0.x 版本的 API（已废弃）

解决方案：

Python

# ❌ 0.x 版本的 API（已废弃）
from langchain import LLMChain

# ✅ 1.0 版本推荐方式
from langchain.agents import create_agent

# 或者使用兼容包（不推荐）
from langchain_classic import LLMChain

🔑 API 错误

错误 4: AuthenticationError: Invalid API key

⚠️ 错误信息

AuthenticationError: Incorrect API key provided

原因：API 密钥未设置或错误

解决方案：

Python

import os

# 方式 1：环境变量（推荐）
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# 方式 2：直接传入
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="gpt-4o",
    api_key="your-api-key-here"
)

# 验证 API 密钥是否设置
print(os.getenv("OPENAI_API_KEY"))  # 应输出密钥（前几位）

错误 5: RateLimitError: Rate limit exceeded

⚠️ 错误信息

RateLimitError: You exceeded your current quota

原因：API 调用频率或配额超限

解决方案：

Python

import time
from tenacity import retry, stop_after_attempt, wait_exponential

# 添加重试逻辑
@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
def call_model_with_retry():
    return model.invoke("your query")

# 添加延迟
time.sleep(1)  # 每次调用间隔 1 秒

# 检查配额
# 访问：https://platform.openai.com/usage

错误 6: TimeoutError: Request timeout

⚠️ 错误信息

TimeoutError: Request timed out

原因：网络慢或请求超时

解决方案：

Python

from langchain_openai import ChatOpenAI

# 增加超时时间
model = ChatOpenAI(
    model="gpt-4o",
    timeout=60,  # 60 秒超时
    max_retries=3  # 最多重试 3 次
)

🤖 模型错误

错误 7: ValueError: Model not found

⚠️ 错误信息

ValueError: Model 'gpt-5' not found

原因：模型名称错误或不存在

解决方案：

Python

# ✅ 正确的模型名称（2025 年 1 月）
valid_models = [
    "gpt-4o",
    "gpt-4o-mini",
    "gpt-3.5-turbo",
    "claude-3-5-sonnet-20241022",
    "gemini-2.0-flash-exp"
]

# 使用 init_chat_model 自动验证
from langchain import init_chat_model

model = init_chat_model("gpt-4o", model_provider="openai")

错误 8: 模型不支持某些功能

⚠️ 错误信息

NotImplementedError: This model does not support tool calling

原因：使用了模型不支持的功能

解决方案：

功能	支持的模型	不支持的模型
工具调用	GPT-4, GPT-3.5-turbo, Claude 3+	早期模型
流式输出	所有主流模型	-
结构化输出	GPT-4o, Claude 3.5 Sonnet	GPT-3.5-turbo（部分）

Python

# 检查模型是否支持工具调用
from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-4o")

# 查看模型能力
if hasattr(model, "bind_tools"):
    print("支持工具调用")
else:
    print("不支持工具调用，请升级模型")

🔧 工具错误

错误 9: 工具调用失败

⚠️ 错误信息

ToolExecutionError: Tool 'my_tool' failed to execute

原因：工具函数内部出错

解决方案：

Python

from langchain.tools import tool

# ❌ 没有错误处理
@tool
def search_database(query: str) -> str:
    """搜索数据库"""
    result = database.query(query)  # 可能抛出异常
    return result

# ✅ 添加错误处理
@tool
def search_database(query: str) -> str:
    """搜索数据库"""
    try:
        result = database.query(query)
        return result
    except Exception as e:
        return f"搜索失败：{str(e)}"

错误 10: 工具参数验证失败

⚠️ 错误信息

ValidationError: Invalid tool arguments

原因：工具调用参数类型或值不正确

解决方案：

Python

from langchain.tools import tool
from typing import Literal

# 使用类型提示和验证
@tool
def set_status(
    status: Literal["active", "inactive", "pending"]
) -> str:
    """设置状态

    Args:
        status: 状态值，必须是 active, inactive, 或 pending
    """
    if status not in ["active", "inactive", "pending"]:
        return f"错误：无效的状态 '{status}'"

    return f"状态已设置为：{status}"

错误 11: Runtime 上下文缺失

⚠️ 错误信息

KeyError: 'user_id'

原因：工具需要 Runtime 上下文，但调用时未提供

解决方案：

Python

from langchain.tools import tool, ToolRuntime
from typing_extensions import TypedDict

class UserContext(TypedDict):
    user_id: str

@tool
def get_user_data(runtime: ToolRuntime[UserContext]) -> str:
    """获取用户数据"""
    user_id = runtime.context["user_id"]
    return f"用户数据：{user_id}"

# ❌ 错误：未提供上下文
result = agent.invoke({"messages": [...]})

# ✅ 正确：提供上下文
config = {
    "configurable": {"thread_id": "thread_001"},
    "context": {"user_id": "user_123"}
}
result = agent.invoke({"messages": [...]}, config=config)

🎯 Agent 错误

错误 12: Agent 无限循环

⚠️ 症状

Agent 一直调用工具，不停止

原因：Agent 陷入循环，无法判断任务完成

解决方案：

Python

# 1. 在 system_prompt 中明确终止条件
system_prompt = """
你是AI助手。

重要：完成任务后，直接给出最终答案，不要继续调用工具。
如果已经获得足够信息，请总结并回答用户。
"""

# 2. 使用 LangGraph 设置递归限制
from langgraph.graph import StateGraph

graph = StateGraph(MessagesState)
# ... 添加节点和边 ...

compiled = graph.compile(
    checkpointer=checkpointer,
    recursion_limit=25  # 最多执行 25 步
)

# 3. 监控执行步数
step_count = 0
for chunk in agent.stream({...}):
    step_count += 1
    if step_count > 20:
        print("警告：执行步数过多，可能陷入循环")
        break

错误 13: 状态更新失败

⚠️ 错误信息

KeyError: 'messages'

原因：状态字段名称错误或未初始化

解决方案：

Python

# ❌ 错误：字段名拼写错误
result = agent.invoke({"message": [...]})  # 应该是 messages

# ✅ 正确：使用正确的字段名
result = agent.invoke({"messages": [...]})

# 验证状态结构
from langgraph.graph import MessagesState

print(MessagesState.__annotations__)
# 输出：{'messages': ...}

💾 内存错误

错误 14: Checkpointer 连接失败

⚠️ 错误信息

OperationalError: could not connect to server

原因：PostgreSQL 数据库连接失败

解决方案：

Python

from langgraph.checkpoint.postgres import PostgresSaver

# 检查数据库连接
import psycopg2

try:
    conn = psycopg2.connect(
        "postgresql://user:pass@localhost:5432/langchain"
    )
    print("数据库连接成功")
    conn.close()
except Exception as e:
    print(f"数据库连接失败：{e}")

# 开发环境：使用内存 Checkpointer
from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()  # 不需要数据库

错误 15: Store 数据未找到

⚠️ 错误信息

AttributeError: 'NoneType' object has no attribute 'value'

原因：Store 中数据不存在

解决方案：

Python

from langchain.tools import tool, ToolRuntime

@tool
def get_preference(key: str, runtime: ToolRuntime) -> str:
    """获取用户偏好"""
    user_id = runtime.context["user_id"]
    store = runtime.store

    # ❌ 错误：直接访问可能不存在的数据
    # item = store.get(("users", user_id), key)
    # return item.value

    # ✅ 正确：检查数据是否存在
    item = store.get(("users", user_id), key)

    if item is None:
        return f"偏好 '{key}' 未设置"

    return f"{key} = {item.value}"

⚡ 性能问题

问题 1: 响应速度慢

症状：Agent 响应时间 > 10 秒

诊断步骤：

Python

import time

# 1. 测量各阶段耗时
start = time.time()

# 工具调用耗时
tool_start = time.time()
result = my_tool.invoke({"query": "test"})
print(f"工具调用耗时: {time.time() - tool_start:.2f}s")

# 模型调用耗时
model_start = time.time()
response = model.invoke("test")
print(f"模型调用耗时: {time.time() - model_start:.2f}s")

# 总耗时
print(f"总耗时: {time.time() - start:.2f}s")

优化方案：

瓶颈	优化方法	预期提升
工具调用慢	添加缓存、优化数据库查询	50-70%
模型调用慢	使用更快的模型、启用流式输出	30-50%
对话历史过长	使用 SummarizationMiddleware	40-60%
检索慢	使用向量索引、限制检索数量	60-80%

问题 2: 内存占用过高

症状：进程内存持续增长

解决方案：

Python

# 1. 限制对话历史长度
from langchain.agents.middleware import SummarizationMiddleware

summarization = SummarizationMiddleware(
    max_messages=10,  # 只保留最近 10 条消息
    summarize_older=True
)

# 2. 定期清理 Checkpointer（开发环境）
if isinstance(checkpointer, InMemorySaver):
    # 清理超过 1 小时的会话
    # checkpointer.clear_old_sessions(max_age=3600)
    pass

# 3. 使用 PostgreSQL（生产环境）
# PostgreSQL 会自动管理内存

🔬 调试工具

LangSmith 追踪

Python

import os

# 启用 LangSmith 追踪
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "your-langsmith-api-key"
os.environ["LANGCHAIN_PROJECT"] = "my-project"

# 所有 Agent 调用会自动追踪
result = agent.invoke({"messages": [...]})

# 访问 https://smith.langchain.com/ 查看追踪结果

详细日志配置

Python

import logging

# 配置日志级别
logging.basicConfig(
    level=logging.DEBUG,  # 显示所有日志
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# 只显示 LangChain 相关日志
logger = logging.getLogger("langchain")
logger.setLevel(logging.DEBUG)

# 禁用其他库的日志
logging.getLogger("httpx").setLevel(logging.WARNING)
logging.getLogger("openai").setLevel(logging.WARNING)

打印中间状态

Python

# 使用 stream_mode 查看执行过程
for stream_mode, chunk in agent.stream(
    {"messages": [...]},
    stream_mode=["messages", "updates", "values"]
):
    if stream_mode == "updates":
        print(f"\n节点更新: {chunk}")

    elif stream_mode == "values":
        print(f"\n当前状态: {chunk.keys()}")

    elif stream_mode == "messages":
        token, metadata = chunk
        if token:
            print(token, end="", flush=True)

诊断流程图

graph TB Start[遇到错误] --> CheckError{错误类型？} CheckError -->|导入错误| Import[检查包安装和版本] CheckError -->|API错误| API[检查API密钥和配额] CheckError -->|模型错误| Model[检查模型名称和能力] CheckError -->|工具错误| Tool[检查工具定义和参数] CheckError -->|性能问题| Perf[使用 LangSmith 追踪] Import --> Fix1[pip install 相关包] API --> Fix2[设置环境变量或检查配额] Model --> Fix3[使用支持的模型] Tool --> Fix4[添加错误处理] Perf --> Fix5[优化瓶颈环节] Fix1 --> Test[测试修复] Fix2 --> Test Fix3 --> Test Fix4 --> Test Fix5 --> Test Test --> Success{问题解决？} Success -->|是| End[完成] Success -->|否| Logs[查看详细日志] Logs --> LangSmith[使用 LangSmith] LangSmith --> Community[社区求助] style Start fill:#3b82f6,color:#fff style End fill:#10b981,color:#fff style CheckError fill:#f59e0b,color:#fff style Success fill:#f59e0b,color:#fff

❓ 常见问题 FAQ

Q1: 如何查看 Agent 的执行过程？

使用 stream_mode=["updates"] 查看每个节点的执行，或使用 LangSmith 可视化追踪。

Q2: Agent 一直不返回结果怎么办？

可能原因：

陷入无限循环 - 设置 recursion_limit
等待模型响应 - 检查网络连接和 API 配额
工具执行慢 - 优化工具或添加超时

Q3: 如何调试工具调用失败？

Python

# 1. 直接调用工具测试
result = my_tool.invoke({"param": "value"})
print(result)

# 2. 检查工具定义
print(my_tool.name)
print(my_tool.description)
print(my_tool.args_schema)

# 3. 查看 Agent 的工具调用
for msg in result["messages"]:
    if hasattr(msg, "tool_calls"):
        print(f"工具调用: {msg.tool_calls}")

Q4: 如何减少 Token 消耗？

精简系统提示词
使用 SummarizationMiddleware 摘要历史对话
限制工具返回的数据量
使用更小的 Embedding 模型

Q5: 生产环境应该监控哪些指标？

指标类型	具体指标	告警阈值
性能	P95 响应时间	> 5s
可靠性	错误率	> 1%
成本	每日 Token 消耗	超出预算
质量	用户满意度	< 4.0/5.0

📋 错误代码速查表

错误类型	常见错误	快速修复
ModuleNotFoundError	langchain 未安装	pip install langchain
ImportError	导入路径错误	检查导入语句
AuthenticationError	API 密钥无效	设置正确的环境变量
RateLimitError	API 配额超限	添加重试逻辑或升级计划
TimeoutError	请求超时	增加 timeout 参数
ValueError	参数值错误	检查参数类型和范围
KeyError	字段不存在	检查状态结构和上下文
ValidationError	工具参数验证失败	添加类型提示和验证

🐛 LangChain 1.0 故障排除指南

🔍 问题分类

📦 导入错误

错误 1: ModuleNotFoundError: No module named 'langchain'

错误 2: ImportError: cannot import name 'create_agent'

错误 3: 使用了 langchain-classic 的 API

🔑 API 错误

错误 4: AuthenticationError: Invalid API key

错误 5: RateLimitError: Rate limit exceeded

错误 6: TimeoutError: Request timeout

🤖 模型错误

错误 7: ValueError: Model not found

错误 8: 模型不支持某些功能

🔧 工具错误

错误 9: 工具调用失败

错误 10: 工具参数验证失败

错误 11: Runtime 上下文缺失

🎯 Agent 错误

错误 12: Agent 无限循环

错误 13: 状态更新失败

💾 内存错误

错误 14: Checkpointer 连接失败

错误 15: Store 数据未找到

⚡ 性能问题

问题 1: 响应速度慢

问题 2: 内存占用过高

🔬 调试工具

LangSmith 追踪

详细日志配置

打印中间状态

诊断流程图

❓ 常见问题 FAQ

Q1: 如何查看 Agent 的执行过程？

Q2: Agent 一直不返回结果怎么办？

Q3: 如何调试工具调用失败？

Q4: 如何减少 Token 消耗？

Q5: 生产环境应该监控哪些指标？

📋 错误代码速查表

📖 参考资源