跳转到内容
AI Agent 教程 AI Agent 教程

01 - 插件式架构：核心 + 集成包设计

01 - 插件式架构：核心 + 集成包设计

学习目标

本章将带你分析 LlamaIndex 的插件式架构设计。你将学到：

  • Core 与 Integrations 的分离动机
  • 命名空间约定与导入路径规范
  • 插件注册机制（条件导入 + 自动注册）
  • 300+ 集成包的独立版本管理策略
  • 集成包加载流程与依赖隔离

项目实践

Monorepo 目录结构

LlamaIndex 是一个 monorepo，包含多个独立可发布的包：

llama_index/
├── llama-index-core/              # 核心包 (llama-index-core, v0.14.22)
├── llama-index-instrumentation/   # 可观测性独立包
├── llama-index-integrations/      # 300+ 集成包
│   ├── llms/                      # LLM 集成 (openai, anthropic, ollama...)
│   ├── embeddings/                # 嵌入模型集成
│   ├── vector_stores/             # 向量存储集成 (chroma, pinecone...)
│   ├── readers/                   # 数据读取器集成
│   ├── tools/                     # 工具集成
│   └── ...                        # 20+ 个集成类别
├── llama-index-utils/             # 工具库
└── docs/                          # 文档

每个子目录是一个独立的 Python 包，有自己的 pyproject.toml，独立发布到 PyPI。

为什么拆分为核心 + 集成包

设计动机：

  1. 减少依赖体积：安装 llama-index-core 只包含核心依赖，不需要安装所有 300+ 集成的依赖
  2. 按需安装：用户只需要安装自己用到的集成包（如 pip install llama-index-llms-openai）
  3. 独立版本管理：集成包可以独立更新版本，不需要等待核心包发布
  4. 降低依赖冲突：不同集成包的依赖版本互不干扰

与 LangChain 的对比：LangChain 采用单体大包设计（langchain + langchain-community），启动时需要加载大量模块。LlamaIndex 的微包设计启动更快，但用户需要手动管理多个包的安装。

命名空间约定

LlamaIndex 的包命名遵循严格的约定，通过命名空间即可区分核心与集成：

# 核心包 — 命名空间包含 "core"
from llama_index.core.llms import LLM              # core 子模块
from llama_index.core import VectorStoreIndex       # core 顶层类
from llama_index.core.workflow import Workflow      # core 子模块


# 集成包 — 命名空间不含 "core"
from llama_index.llms.openai import OpenAI          # openai 集成
from llama_index.embeddings.huggingface import HuggingFaceEmbedding  # huggingface 集成
from llama_index.vector_stores.chroma import ChromaVectorStore      # chroma 集成

规则：

  • llama_index.core.xxx → 核心功能
  • llama_index.xxx.yyy → yyy 集成，用于 xxx 子模块

插件注册机制

Core 包通过条件导入实现插件注册，只在安装了相应包时才注册对应的 LLM 类：

# llama-index-core/llama_index/core/llms/loading.py 的简化逻辑
RECOGNIZED_LLMS = {}


# 核心包只预装这几个
try:
    from llama_index.llms.openai import OpenAI
    RECOGNIZED_LLMS["openai"] = OpenAI
except ImportError:
    pass


try:
    from llama_index.llms.mock import MockLLM
    RECOGNIZED_LLMS["mock"] = MockLLM
except ImportError:
    pass

其余 300+ 模型通过独立集成包在各自的 loading.py 中注册。Core 包不感知这些集成——它们在安装时自动注册到全局注册表中。

典型集成包结构

每个集成包遵循统一的结构：

llama-index-integrations/llms/llama-index-llms-openai/
├── pyproject.toml              # 独立版本声明
├── llama_index/
│   └── llms/
│       └── openai/
│           ├── __init__.py     # 导出 OpenAI 类
│           ├── base.py         # 核心实现
│           └── loading.py      # 注册到全局注册表
└── tests/

loading.py 的职责：在包导入时将 LLM 类注册到 RECOGNIZED_LLMs 字典，使 resolve_llm("openai") 能自动找到对应类。

问题与规避

陷阱对策
ImportError 导入集成类确认已安装对应集成包（如 pip install llama-index-llms-anthropic）
安装 llama-index 元包后依赖冲突改用 llama-index-core + 按需安装集成包
resolve_llm("xxx") 找不到模型确认集成包已安装且 loading.py 已执行
集成包版本与 core 不兼容使用 uv.lock 锁定整个 monorepo 的依赖

设计取舍

微包 vs 单体包

维度微包 (LlamaIndex)单体包 (LangChain)
安装体积小（按需安装）大（包含所有依赖）
启动速度快（少导入）慢（加载所有模块）
依赖管理复杂（多包版本）简单（单一版本）
更新频率独立（集成包可单独发版）统一（全量发版）
新手友好低（需要知道装哪些包）高（pip install langchain 即可）

核心设计原则：LlamaIndex 选择”核心稳定、集成灵活”——核心包保证 API 稳定，集成包可以快速迭代和实验新功能。

参考来源

版本信息

📅 2026-05-27 🏷️ v0.14.22 🔀 f027669

标签

architecturepluginmonorepopackage-designlazy-loading