第二篇：LangChain 1.0 模块化架构与依赖管理

🎉 开始学习 LangChain 1.0 模块化架构与依赖管理

欢迎继续学习 LangChain 1.0！在本篇中，我们将深入探讨 LangChain 1.0 的模块化架构设计和依赖管理策略。理解这些内容将帮助你更好地组织代码、管理依赖，并构建可维护、可扩展的 AI 应用。

2.1 为什么需要模块化架构？

在 LangChain 1.0 之前，开发者面临的主要挑战包括：

单一庞大的依赖包导致安装缓慢，不必要的依赖占用资源
第三方集成质量参差不齐，难以保证生产环境的稳定性
核心 API 与特定厂商实现耦合过紧，难以灵活切换不同模型提供商
向后兼容性问题难以处理，升级版本常常需要大量代码修改

LangChain 1.0 通过模块化架构创新性地解决了这些问题，将"核心抽象"与"具体实现/第三方集成/历史实现"拆分成多个独立的包，实现了：

更清晰的 API 边界：每个包职责明确，易于理解和维护
更小的核心包体积：按需安装，减少资源占用和冲突
更好的维护性：社区贡献与厂商集成模块化管理
平稳的迁移路径：为旧版本用户提供无缝过渡方案

这种设计让 LangChain 既能保持核心的稳定性，又能灵活扩展各种功能，真正实现了核心更稳定、可维护；集成可按需安装的目标。

2.2 LangChain 1.0 核心依赖包全景图

LangChain 1.0 将整个生态划分为五个核心层，每层都有明确的职责和定位：

依赖包名称	核心作用	详细功能介绍	安装优先级
langchain-core	核心抽象层和 LCEL	定义所有组件（模型、消息、提示词模板、工具、运行环境）的标准接口和基本抽象。包含 LangChain 表达式语言 (LCEL) ，是构建链式应用的基础。这是一个轻量级、不含第三方集成的基石包。	🔴 必须
langchain	应用认知架构（主包）	包含构建 LLM 应用的通用高阶逻辑，如 Agents (create_agent() 函数)、Chains 和通用的检索策略。建立在 langchain-core 之上，是用于组合核心组件的"胶水"层。	🔴 必须
langchain-community	社区第三方集成	包含由 LangChain 社区维护的非核心或不太流行的第三方集成，如文档加载器、向量存储、特定厂商的 LLM 集成等。为了保持包的轻量，所有依赖项都是可选的。	🟡 按需
langchain-openai langchain-[厂商名]	特定厂商深度集成	针对关键合作伙伴的集成包（如 langchain-openai、langchain-anthropic）。它们被单独分离出来，以提供更好的支持、可靠性和更轻量级的依赖。它们只依赖于 langchain-core。	🟢 推荐
langchain-classic	旧版本兼容	包含 LangChain v0.x 版本中的已弃用 (deprecated) 或旧版功能，如旧的 LLMChain、旧版 Retrievers、Indexing API 和 Hub 模块。主要作用是为用户提供平稳的迁移期。	⚫ 临时

2.3 各模块深度解析与最佳实践

1. langchain-core：构建生态的基石

定位：最小公共底座，定义"契约"而非实现

核心特性：

包含所有组件的核心抽象与接口：LLM/ChatModel 抽象、Prompt 抽象、Chain/Agent 基类、消息格式等
不包含具体厂商的实现（如没有 OpenAI client 的封装）
定义了"合同（interfaces）"，其他包在此基础上实现具体功能
包含了 LangChain 表达式语言 (LCEL)，是构建链式应用的基础

python 复制代码

# 基础示例：使用 langchain-core 的核心抽象
from langchain_core.prompts import PromptTemplate
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.tools import tool

# 定义提示词模板：为不同行业生成公司名称建议
prompt_template = PromptTemplate.from_template(
    "请为{industry}行业的一家初创公司提供3个有创意且适合国际化的中文名称。"
)

# 创建消息对象：构建专业咨询对话
system_msg = SystemMessage("你是一位经验丰富的品牌战略顾问，专注于科技和消费领域。")
human_msg = HumanMessage("我们正在为一家专注于AI医疗影像分析的创业公司寻找品牌名称。")

# 定义工具：检查商标注册状态
@tool
def check_trademark_status(name: str) -> str:
    """检查中文商标名称的注册状态"""
    # 这里可以连接商标数据库API
    # 简化示例：模拟检查结果
    if "智能" in name or "AI" in name.upper():
        return f"商标'{name}'可能已被注册，建议调整"
    else:
        return f"商标'{name}'暂未发现冲突，建议进一步查询"

2. langchain 主包：开箱即用的开发体验

定位：对外的主入口，快速上手的"瑞士军刀"

核心特性：

把 langchain-core 的核心抽象与"常用实现"组合在一起
在 v1.0 中，命名空间被显著精简，只保留构建 agent 的关键 API
官方建议大多数用户直接使用此主包以获得"开箱即用"的体验

模块	核心内容	使用场景
`langchain.agents`	`create_agent`, `AgentState`	智能体创建核心
`langchain.messages`	`AIMessage`, `HumanMessage`, `trim_messages`	消息管理
`langchain.tools`	`@tool`, `BaseTool`	工具定义与使用
`langchain.chat_models`	`init_chat_model`, `BaseChatModel`	统一模型初始化
`langchain.embeddings`	`init_embeddings`	嵌入模型管理

python 复制代码

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model

# 使用 init_chat_model 统一初始化不同厂商的模型
model = init_chat_model("gpt-5-nano", model_provider="openai")

# 创建智能体
agent_executor = create_agent(llm=model, tools=[])

result = agent_executor.invoke({
    "messages": [{
        "role": "user",
        "content": "给我介绍一下深度学习，讲一下Transformer在深度学习中的应用"
    }]
})

3. langchain-community：功能扩展的宝库

定位：社区驱动的功能扩展层

核心价值：通过社区贡献的非官方集成组件显著扩展主包的功能边界，体现在两大维度：

工具类组件（RAG 技术基础）

DirectoryLoader：文档加载器，支持 PDF、文本等多格式文件批量导入
RecursiveCharacterTextSplitter：文本分割器，按语义边界将文档切分为检索友好的 Chunk
PGVector：PostgreSQL 生态的向量数据库适配
HuggingFaceEmbeddings：本地部署模型的向量化能力

平台集成

支持与 DeepSeek、阿里云通义千问等模型的对接
通过 langchain_community.chat_models.ChatTongyi 初始化通义千问模型
利用 Ollama 类调用本地部署的 DeepSeek-R1 模型

python 复制代码

# 安装：pip install langchain-community
from langchain_community.document_loaders import NotionDBLoader
from langchain_community.chat_models import ChatTongyi

# 从 Notion 数据库加载文档
loader = NotionDBLoader(
    integration_token="secret_...",
    database_id="your-db-id"
)
documents = loader.load()
print(f"加载了 {len(documents)} 条文档")

# 使用社区集成的通义千问模型
model = ChatTongyi()  # 默认 qwen-turbo 模型

特点与注意事项：

质量参差不齐：社区贡献，需自行验证稳定性
更新滞后：依赖社区维护，响应速度慢于官方包
功能丰富：覆盖 95% 的第三方服务集成需求
包含内容广泛：数据库连接器、存储服务、工具集成、向量数据库、文档加载器等

4. langchain-openai（厂商特定集成包）：生产级选择

定位：官方深度集成，生产环境首选

核心价值：通过封装 API 细节，为开发者提供"零适配成本"的模型对接方案，使开发者能够直接使用厂商特有功能。

以 langchain-openai 为例，其关键组件包括：

模型客户端 ：ChatOpenAI、OpenAIEmbeddings
工具调用适配：支持 OpenAI 的 function calling
多模型支持：GPT-4o、GPT-4 Turbo、GPT-3.5 等全系列

python 复制代码

# 安装：pip install langchain-openai
from langchain_openai import ChatOpenAI

# 初始化 OpenAI 模型
model = ChatOpenAI(
    model="gpt-5-nano",
    temperature=0.7,
    max_tokens=1500
)

question = "你好，介绍一下你自己。"
result = model.invoke(question)
print(result.content)

主流厂商包列表：

langchain-openai：OpenAI, Azure OpenAI
langchain-anthropic：Claude 系列
langchain-google：Gemini, Vertex AI
langchain-deepseek：DeepSeek 模型
langchain-ollama：本地 Ollama 部署

厂商包 vs 社区包关键区别：

维度	langchain-openai	langchain-community 中的 OpenAI
维护方	OpenAI官方 + LangChain团队	社区维护
更新频率	即时跟进 API 更新	延迟数周
功能完整性	支持所有新特性（音频、视觉等）	仅基础功能
生产可用性	✅ 强烈推荐	⚠️ 谨慎使用
技术支持	官方技术支持	社区互助

为什么单独拆出厂商包？

让 langchain 主包保持轻量（不强制安装所有厂商 SDK）
用户按需安装对应厂商，例如你只用 OpenAI，就只装 langchain-openai
厂商可以更灵活地维护自己的集成，快速响应 API 变化

5. langchain-classic：平稳过渡的桥梁

定位：兼容包 / 迁移包，为 v0.x 用户提供过渡期

核心功能：

把 LangChain v0.x 中的"老 API / legacy 功能"搬到单独包里
保持 v1.0 的精简性，同时提供向后兼容的迁移通道
包含如：老的 Chain 实现、旧版 retrievers、索引 API、hub 模块等被标记为"legacy"的功能

python 复制代码

# 安装：pip install langchain-classic
from langchain_classic.chat_models import ChatOpenAI

# 使用旧版 API（与 v0.x 兼容）
model = ChatOpenAI(model="gpt-5-nano")
res = model.invoke("请介绍一下你自己")

2.4 最佳实践与决策指南

安装策略金字塔

复制代码

        ┌─────────────────┐
        │  langchain-core │ ← 必须安装，所有应用的基础
        └─────────────────┘
                 │
        ┌─────────────────┐
        │    langchain    │ ← 必须安装，主要开发接口
        └─────────────────┘
                 │
        ┌─────────────────────────────────────┐
        │  langchain-openai / langchain-[厂商] │ ← 生产推荐，按需选择
        └─────────────────────────────────────┘
                 │
        ┌─────────────────┐
        │ langchain-classic│ ← 迁移期间临时使用
        └─────────────────┘

具体场景的包选择策略

场景1：生产环境使用 OpenAI

bash 复制代码

# 生产环境最佳组合
pip install langchain-core langchain langchain-openai

场景2：快速原型开发，需要多种集成

bash 复制代码

# 开发环境，快速验证各种功能
pip install langchain-core langchain langchain-community

场景3：从 v0.x 迁移到 v1.0

bash 复制代码

# 迁移期间同时安装
pip install langchain-core langchain langchain-classic

# 逐步替换导入语句，最后移除 langchain-classic

场景4：多厂商支持的应用

python 复制代码

# 使用 init_chat_model 实现多厂商无缝切换
from langchain.chat_models import init_chat_model

# 业务代码保持不变，只需修改初始化参数
def get_model(provider="openai", model_name="gpt-5-nano"):
    return init_chat_model(model_name, model_provider=provider)

# 切换厂商时零代码修改
openai_model = get_model("openai", "gpt-5-nano")
deepseek_model = get_model("deepseek", "deepseek-chat")
anthropic_model = get_model("anthropic", "claude-3-5-sonnet")

厂商包选择决策矩阵

复制代码

是否需要最新功能？ → 是 → 选择厂商包 (langchain-openai 等)
              ↓
              否
              ↓
是否用于生产环境？ → 是 → 选择厂商包
              ↓
              否
              ↓
是否愿意承担稳定性风险？ → 是 → 可选择社区包
                    ↓
                    否
                    ↓
                选择厂商包

2.5 常见问题与解决方案

Q1：我应该安装哪些包？安装顺序是什么？

A：按照以下顺序和优先级：

必须：langchain-core（基础）+ langchain（主接口）
推荐：对应服务商的厂商包（如 langchain-openai）
按需：langchain-community（特定社区集成）
临时：langchain-classic（迁移期间）

Q2：遇到导入错误 "ModuleNotFoundError" 怎么办？

python 复制代码

# 错误：ModuleNotFoundError: No module named 'langchain_openai'
# 解决：pip install langchain-openai

# 错误：ImportError: cannot import name 'create_agent' from 'langchain'
# 解决：确保安装了 langchain 主包，而不是仅 langchain-core
# 正确：pip install langchain
# 错误：pip install langchain-core  # 缺少高级 API

Q3：如何从 v0.x 平滑迁移到 v1.0？

四步迁移法：

并行安装 ：同时安装 v1.0 和 langchain-classic
逐步替换：逐个模块更新导入语句和 API 调用
功能验证：确保每个功能在 v1.0 中正常工作
清理移除 ：确认无误后移除 langchain-classic 依赖

Q4：如何处理版本冲突和依赖问题？

bash 复制代码

# 最佳实践：使用虚拟环境
python -m venv langchain-env

# Linux/Mac
source langchain-env/bin/activate

# Windows
langchain-env\Scripts\activate

# 然后精确安装所需版本
pip install langchain-core==1.0.5 langchain==1.0.7 langchain-openai==1.0.3

Q5：如何选择合适的厂商包或社区包？

决策指南：

生产环境：始终选择厂商包（更稳定、功能更全）
快速验证：可使用社区包快速测试想法
特殊需求：某些小众服务可能只有社区包支持
长期维护：考虑包的维护活跃度和更新频率

🎯 总结与下一步建议

通过本篇学习，你已经掌握了 LangChain 1.0 模块化架构的核心思想和各包的具体职责。记住这些关键要点：

理解分层架构 ：core → 主包 → 厂商包/社区包 → classic 的清晰分层
掌握各包定位：每个包都有明确的职责和使用场景
遵循最佳实践 ：生产环境优先使用厂商包，利用 init_chat_model 实现灵活性
规划迁移路径：为旧版本用户提供平滑的升级体验

下一步建议：

动手实践环境配置：根据你的项目需求，创建虚拟环境并安装合适的包组合
尝试多厂商切换 ：使用 init_chat_model 体验在不同模型提供商间无缝切换
探索社区集成 ：安装 langchain-community，了解丰富的第三方集成功能
准备下一篇学习：下一篇我们将深入核心概念与组件，包括模型调用、消息管理、提示词模板等实际开发技能

模块化架构是 LangChain 1.0 的重要创新，它不仅解决了技术债问题，更为未来的扩展奠定了坚实基础。掌握这些依赖管理技巧，你就能构建出既稳定又可扩展的 AI 应用。

🙌 致谢与反馈

感谢你花费时间学习本教程！如果你在学习过程中遇到问题、有建议或想分享你的实践案例，欢迎通过以下方式联系我们：

📧 邮箱：[angelevil.xue@qq.com]
🌐 GitHub：[待开放]
💬 社区论坛：[正在构建]

祝愿你在智能体开发的道路上越走越远，构建出真正智能、有用、可靠的新一代 AI 应用！

教程作者 ：[曦紫沐]
最后更新 ：2025年12月
适用版本：LangChain ≥ 1.0, Python ≥ 3.10

本文为原创内容，版权归作者所有