拆解 LangChain 架构：core、classic 与 20 个 partner 包如何协作

打开 langchain-ai/langchain 仓库的第一眼，很多人会愣住：这不是一个 Python 项目，而是二十多个。libs/ 目录下并列着 core、langchain、langchain_v1、text-splitters、standard-tests、model-profiles，以及 partners/ 之下按 provider 拆分的 openai、anthropic、google_genai 等独立包。它们各自拥有独立的 pyproject.toml、独立发版、独立依赖树。

这种“看似臃肿”的 monorepo 结构，恰恰是 LangChain 能在两年内经历 API 地震式重构、仍然维持百万级周下载的原因。本文从模块划分、依赖方向和向后兼容策略三个维度，拆解这套架构的设计逻辑。

整体架构图：五层包结构与依赖方向

先把整个仓库的包结构画出来，依赖只能自上而下流动，任何反向引用都是架构违规：

从上到下依次是：

1. libs/langchain_v1：新一代高层 Agent API，面向终局形态设计，是官方定位中 "agent engineering platform" 的直接体现。
2. libs/langchain（langchain_classic）：承载历史版本的兼容层，把旧导入路径重定向到社区包。
3. libs/partners/：20+ 个独立可发布的集成包，每个 provider 一个包。
4. libs/core（langchain-core）：零第三方集成依赖的抽象内核，定义 Runnable、Message、VectorStore 等核心接口。
5. 支撑层：standard-tests、text-splitters、model-profiles 等工具与契约包。

关键的约束在于依赖方向：langchain-core 不依赖任何 partner 包；partner 包只依赖 core 和少量运行时依赖；langchain_classic 依赖所有 partner（因为它要提供统一入口）。这个单向依赖图使得 core 可以独立演进，partner 可以独立发版，两者互不阻塞。

langchain-core：零依赖的抽象内核

libs/core 的 README 里有一条几乎苛刻的纪律：核心包不引入任何第三方集成依赖。它只依赖 Pydantic、typing_extensions 这类基础库，不依赖 openai、不依赖任何向量库 SDK。

为什么这么严格？因为 core 是整个生态的“引力中心”。哪怕 core 多引入一个 provider SDK，下游所有 20+ 个 partner 包都会被迫连带这个依赖，版本冲突的爆炸半径会瞬间扩大。零依赖换来的是：任何 provider 集成出现问题时，用户只需替换 partner 包，core 接口纹丝不动。

core 内部有三个核心抽象：

• Runnable：所有组件的统一执行协议，串行组合、并行分支、流式输出都建立在这一个接口上；
• Messages：以 Pydantic 模型表示的对话消息体系，HumanMessage、AIMessage、ToolMessage 在所有模型之间统一传递；
• Callbacks：运行时的事件上报机制，为 tracing 和 observability 留下钩子。

一个内核级的性能细节同样值得注意。core 大量使用 PEP 562 的模块级 __getattr__ 做惰性导入，避免包加载时把所有子模块拉进内存：

_DYNAMIC_IMPORTS = {
    "messages": ("langchain_core", "messages"),
    "AIMessage": ("langchain_core.messages", "AIMessage"),
    "runnables": ("langchain_core", "runnables"),
}

def __getattr__(name: str):
    if name in _DYNAMIC_IMPORTS:
        module_path, attr = _DYNAMIC_IMPORTS[name]
        return getattr(import_module(module_path), attr)
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

这张表驱动的映射让 import langchain_core 的耗时大幅下降，同时也天然规避了模块间的循环依赖——只有真正被访问的属性才会触发导入。对一个被几乎所有集成包依赖的内核来说，导入速度就是生态的启动速度。

partner 集成体系与 standard-tests 契约测试

libs/partners/ 下的每个集成包都是一个独立项目：独立的版本号、独立的 CHANGELOG、独立的发布流水线。langchain-openai 升级到 0.3 不会迫使 langchain-anthropic 跟着动。

这种解耦的前提是“集成包之间不能互相依赖”，那如何保证所有集成行为一致？答案是 standard-tests 包。它定义了一套契约化的标准测试基类：任何 ChatModel 集成都必须通过同一组关于消息格式、tool calling、流式行为、异常类型的验收测试。

这是典型的“继承即契约”模式：partner 包的测试类继承 standard-tests 中的基类，CI 逐项跑完即视为通过契约验收。好处是双向的——

• 对上游：core 可以放心修改内部实现，因为契约测试会暴露所有不兼容的 partner；
• 对下游：用户可以确信任何通过验收的 ChatModel，在 tool calling、streaming 等行为上表现一致。

与之配套的是测试工程中的 mock robot server——一个本地起的服务，模拟真实的 LLM API 响应，覆盖 prompt injection、递归 schema、密钥依赖等真实场景。集成测试不依赖真实 API key，CI 才能做到快速、稳定、免费。

langchain_classic 的兼容层与导入重定向机制

架构里最有趣的一层是 libs/langchain。注意它的包名：导入名叫 langchain，但代码模块实际叫 langchain_classic。这是官方对历史包袱的坦诚态度——“classic”二字直接写进了模块名。

这一层的使命只有一个：让老用户写的 from langchain.chains import LLMChain 在新版本里依然能跑。它的实现手段是动态导入重定向，分析材料中描述的 create_importer 机制会在模块级 __getattr__ 里拦截旧路径，把请求转发到 langchain_community：

# langchain_classic 内部：旧导入路径 → langchain_community 的动态重定向
importer = create_importer(
    __package__,
    module_lookups={
        "LLMChain": "langchain_community.chains",
        "Pinecone": "langchain_community.vectorstores",
    },
)

def __getattr__(name: str):
    return importer(name)

用户访问一个旧符号时，真实实现已经迁到 langchain_community，但导入路径无需修改。这条重定向链配合 deprecated 警告，构成了一个完整的迁移路径：旧代码先能跑，再逐步提示废弃，最后在未来的 major 版本移除。

兼容层最容易被写成“一堆复制粘贴的旧代码”，LangChain 的做法是让兼容层保持零实现——它只包含重定向和弃用声明，真正的实现统一收敛在 community 包里。维护成本被压到最低，这正是“优雅承接历史包袱”的含义。

langchain_v1：下一代 Agent 架构

libs/langchain_v1 代表官方对终局形态的判断。如果说 classic 时代的关键词是 chains（链式编排），v1 的关键词就是 agent：模型驱动的循环、原生 tool calling、内置的持久化与中断恢复能力。

它构建在 core 的 Runnable 抽象之上，但刻意收窄了 API 表面积——暴露给用户的入口越少，向后兼容的负担越轻。这也是对 v0.x 教训的直接回应：当年过度灵活的组合式 API 让文档、测试和迁移全部付出了代价。

Callbacks/Runnables 的运行时数据流

最后把视角拉到运行时，看一次 Agent 调用的完整数据流：

用户代码只面对 agent.invoke() 一个入口，内部经过回调分发器，所有事件同步广播给 tracing 系统与用户注册的 handler。这解释了 LangChain 可观测性生态为何繁荣：LangSmith、Langfuse 等平台只需要实现 CallbackHandler 协议，就能无侵入地接入任何应用，因为事件分发是内核内建的能力，而不是集成层的可选功能。

写在最后

回看这套架构，真正值得记住的不是五层包的名字，而是三条设计原则：

1. 依赖单向、内核零依赖——用严格的依赖方向换取各层的独立演进速度；
2. 契约测试替代集中管控——不用强制版本统一，用 standard-tests 保证行为一致；
3. 兼容层零实现——历史包袱用重定向承接，而不是用复制粘贴固化。

框架代码会过时，但这些应对“大规模 API 演进”的架构手段，放在任何一个需要长期维护的 Python 项目里都成立。