# https://github.com/run-llama/llama_index 项目说明书
生成时间：2026-05-11 04:42:04 UTC
## 目录
- [LlamaIndex 简介](#introduction)
- [快速入门指南](#quickstart)
- [系统架构](#system_architecture)
- [核心组件详解](#core_components)
- [数据摄取流程](#data_ingestion)
- [节点解析器](#node_parsing)
- [存储层架构](#storage_layer)
- [智能体系统](#agent_system)
- [工作流引擎](#workflow_engine)
- [查询引擎](#query_engine)
## LlamaIndex 简介
### 相关页面
相关主题：[快速入门指南](#quickstart), [系统架构](#system_architecture), [核心组件详解](#core_components)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/run-llama/llama_index/blob/main/README.md)
- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md)
- [llama-index-integrations/readers/llama-index-readers-docling/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md)
- [llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)
- [llama-index-integrations/llms/llama-index-llms-contextual/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-contextual/README.md)
- [llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md)
# LlamaIndex 简介
## 概述
LlamaIndex 是一个用于构建 **LLM（大型语言模型）应用** 的数据框架，官方仓库位于 [run-llama/llama_index](https://github.com/run-llama/llama_index)。该框架的核心设计理念是简化 LLM 与私有或特定领域数据的连接过程，使开发者能够快速构建检索增强生成（RAG）系统、问答应用和数据索引工具。
LlamaIndex 提供了丰富的数据连接器（Readers）、索引构建能力、检索和查询引擎，以及与多种 LLM 提供商的无缝集成。资料来源：[README.md:1]()
## 核心架构
LlamaIndex 的整体架构可分为以下几个核心层次：
```mermaid
graph TD
A[数据源] --> B[Readers 数据读取层]
B --> C[Documents 文档对象]
C --> D[Index 索引层]
D --> E[Retrievers 检索层]
E --> F[Query Engine 查询引擎]
F --> G[LLM 输出层]
B --> B1[Web Readers]
B --> B2[File Readers]
B --> B3[API Readers]
B --> B4[Database Readers]
G --> G1[OpenAI]
G --> G2[Ollama]
G --> G3[LM Studio]
G --> G4[ModelScope]
```
### 模块层次说明
| 层次 | 功能描述 | 核心组件 |
|------|----------|----------|
| **数据读取层** | 从各类数据源加载原始数据 | RemoteDepthReader, DoclingReader, WikipediaReader 等 |
| **文档对象层** | 将数据转换为标准化的 Document 对象 | Document, MediaResource |
| **索引层** | 构建可检索的向量或结构化索引 | VectorStoreIndex, SummaryIndex |
| **检索层** | 根据查询获取相关文档 | Retriever, similarity_top_k 参数 |
| **查询引擎层** | 执行检索并调用 LLM 生成答案 | QueryEngine, as_query_engine() |
| **LLM 输出层** | 与各类 LLM 提供商集成 | Contextual, LMStudio, Ollama 等 |
## 核心概念
### Document 文档对象
Document 是 LlamaIndex 中的核心数据单元，用于表示任意文本或多媒体内容。
```python
from llama_index.core.schema import Document, MediaResource
doc = Document(
id_="doc1",
text_resource=MediaResource(
text="这是一段示例文本内容"
),
)
```
资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:18-25]()
### Index 索引
索引是将文档组织成可高效检索结构的关键组件。最常用的是 VectorStoreIndex，它将文档转换为向量表示进行语义检索。
```python
from llama_index.indices.managed.vectara import VectaraIndex
index = VectaraIndex.from_documents(docs)
```
资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:35]()
## 数据读取器（Readers）
LlamaIndex 提供了丰富的读取器集成，支持从多种数据源加载数据。
### Web 数据读取器
| 读取器名称 | 功能描述 | 依赖库 |
|-----------|----------|--------|
| WholeSiteReader | 整站爬取，支持深度递归 | 内置 |
| NewsArticleReader | 新闻文章解析 | newspaper3k |
| UnstructuredURLLoader | URL 内容提取 | unstructured |
| ReadabilityWebPageReader | 网页主内容提取 | readability |
| MainContentExtractorReader | 主内容提取 | main_content_extractor |
| TrafilaturaWebReader | 网页内容解析 | trafilatura |
使用示例：
```python
from llama_index.readers.web import NewsArticleReader
reader = NewsArticleReader(use_nlp=False)
documents = reader.load_data(
urls=["https://www.example.com/news/article.html"]
)
```
资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md:15-20]()
### 整站爬取功能
WholeSiteReader 支持从指定 URL 开始，按深度递归爬取整个网站的内容：
```python
from llama_index.readers.web import WholeSiteReader
scraper = WholeSiteReader(
prefix="https://docs.llamaindex.ai/en/stable/",
max_depth=10,
)
documents = scraper.load_data(
base_url="https://docs.llamaindex.ai/en/stable/"
)
```
资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:10-20]()
### 文档解析读取器
**Docling Reader** 支持从 PDF、DOCX、HTML 等格式提取内容：
```python
from llama_index.readers.docling import DoclingReader
reader = DoclingReader()
docs = reader.load_data(file_path="https://arxiv.org/pdf/2408.09869")
```
支持的文件格式：
| 格式 | 支持情况 | 导出类型 |
|------|----------|----------|
| PDF | ✅ 完整支持 | Markdown / JSON |
| DOCX | ✅ 完整支持 | Markdown / JSON |
| HTML | ✅ 完整支持 | Markdown / JSON |
资料来源：[llama-index-integrations/readers/llama-index-readers-docling/README.md:15-35]()
### Wikipedia 读取器
```python
from llama_index.readers.wikipedia import WikipediaReader
reader = WikipediaReader()
documents = reader.load_data(pages=["Page Title 1", "Page Title 2"])
```
资料来源：[llama-index-integrations/readers/llama-index-readers-wikipedia/README.md:20-30]()
## LLM 集成
### 主要 LLM 提供商
| 提供商 | 包名 | 特点 |
|--------|------|------|
| Contextual | llama-index-llms-contextual | 上下文感知的 LLM |
| LM Studio | llama-index-llms-lmstudio | 本地模型服务 |
| ModelScope | llama-index-llms-modelscope | 阿里魔搭模型 |
| Ollama | 内置支持 | 本地 LLM 运行 |
### Contextual LLM 示例
```python
from llama_index.llms.contextual import Contextual
llm = Contextual(model="contextual-clm", api_key="your_api_key")
response = llm.complete("Explain the importance of Grounded Language Models.")
```
资料来源：[llama-index-integrations/llms/llama-index-llms-contextual/README.md:15-20]()
### LM Studio 集成
```python
from llama_index.llms.lmstudio import LMStudio
llm = LMStudio(
model_name="Hermes-2-Pro-Llama-3-8B",
base_url="http://localhost:1234/v1",
temperature=0.7,
)
messages = [
ChatMessage(
role=MessageRole.SYSTEM,
content="You are an expert AI assistant.",
),
ChatMessage(
role=MessageRole.USER,
content="What is the significance of the number 42?",
),
]
response = llm.chat(messages=messages)
```
资料来源：[llama-index-integrations/llms/llama-index-llms-lmstudio/README.md:15-35]()
## 向量嵌入集成
### Ollama 嵌入模型
Ollama 提供了多个嵌入模型选项：
| 模型名称 | 用途 | 特点 |
|----------|------|------|
| nomic-embed-text | 通用嵌入 | 通用目的 |
| embeddinggemma | 文本嵌入 | Google Gemma 系列 |
| mxbai-embed-large | 高质量嵌入 | 大规模模型 |
安装与使用：
```bash
ollama pull nomic-embed-text
```
```python
from llama_index.embeddings.ollama import OllamaEmbedding
embed_model = OllamaEmbedding(
model_name="nomic-embed-text",
base_url="http://localhost:11434",
)
```
资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md:5-30]()
### ModelScope 嵌入
```python
from llama_index.embeddings.modelscope.base import ModelScopeEmbedding
model = ModelScopeEmbedding(
model_name="iic/nlp_gte_sentence-embedding_chinese-base",
model_revision="master",
)
rsp = model.get_query_embedding("你好，你是谁？")
rsp = model.get_text_embedding_batch(["你好", "我是学生"])
```
资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-modelscope/README.md:15-35]()
## 检索与查询流程
### 标准 RAG 工作流
```mermaid
graph LR
A[用户查询] --> B[Query Engine]
B --> C[Retriever 检索]
C --> D[向量相似度匹配]
D --> E[相关文档]
E --> F[LLM 生成]
F --> G[最终回答]
```
### 检索器使用
```python
from llama_index.indices.managed.vectara import VectaraIndex
retriever = index.as_retriever(similarity_top_k=2)
results = retriever.retrieve("How will users feel about this new tool?")
```
资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:45-50]()
### 查询引擎使用
```python
query_engine = index.as_query_engine()
results = query_engine.query("用户对工具的感受如何？")
```
## 完整使用示例
以下是一个典型的 LlamaIndex 完整使用流程：
```mermaid
graph TD
A[加载数据] --> B[创建索引]
B --> C[获取检索器]
C --> D{使用方式}
D -->|直接检索| E[Retriever]
D -->|生成回答| F[Query Engine]
E --> G[相关文档列表]
F --> H[LLM 回答]
```
完整代码示例：
```python
from llama_index.core import VectorStoreIndex
from llama_index.readers.web import NewsArticleReader
# 1. 加载数据
reader = NewsArticleReader(use_nlp=False)
documents = reader.load_data(urls=["https://example.com/article.html"])
# 2. 创建索引
index = VectorStoreIndex.from_documents(documents)
# 3. 获取检索器
retriever = index.as_retriever(similarity_top_k=5)
# 4. 检索相关文档
results = retriever.retrieve("查询内容")
# 或使用查询引擎获取 LLM 回答
query_engine = index.as_query_engine()
response = query_engine.query("查询内容")
```
## 特性总结
### LlamaIndex 核心能力矩阵
| 能力维度 | 支持情况 | 说明 |
|----------|----------|------|
| 多数据源接入 | ✅ | Web、文件、API、数据库等 |
| 多格式文档解析 | ✅ | PDF、DOCX、HTML、Markdown 等 |
| 多种 LLM 集成 | ✅ | OpenAI、Ollama、LM Studio 等 |
| 向量嵌入支持 | ✅ | 本地模型、云服务多种选择 |
| RAG 检索增强 | ✅ | 内置检索和查询引擎 |
| 可扩展架构 | ✅ | 模块化设计，支持自定义组件 |
## 引用信息
如需在学术论文中引用 LlamaIndex，请使用以下格式：
```
@software{Liu_LlamaIndex_2022,
author = {Liu, Jerry},
doi = {10.5281/zenodo.1234},
month = {11},
title = {{LlamaIndex}},
url = {https://github.com/jerryjliu/llama_index},
year = {2022}
}
```
资料来源：[README.md:95-102]()
---
## 快速入门指南
### 相关页面
相关主题：[LlamaIndex 简介](#introduction), [系统架构](#system_architecture), [数据摄取流程](#data_ingestion)
相关源码文件
以下源码文件用于生成本页说明：
- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md)
- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md)
- [llama-index-integrations/llms/llama-index-llms-ollama/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-ollama/README.md)
- [llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md)
- [llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md)
- [llama-index-integrations/llms/llama-index-llms-konko/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/llms/llama-index-llms-konko/README.md)
# 快速入门指南
## 概述
LlamaIndex 是一个强大的大语言模型（LLM）数据框架，旨在帮助开发者构建基于私有知识和增强语言模型的应用程序。本指南将引导您从零开始，快速掌握 LlamaIndex 的核心功能和使用方法。
LlamaIndex 的主要应用场景包括：
- **文档问答系统**：基于私有文档库构建智能问答应用
- **语义搜索**：使用向量数据库实现高效的信息检索
- **代理（Agent）应用**：构建能够访问多种工具的 AI 代理
- **数据摄取与索引**：支持从多种数据源加载和索引文档
## 安装
### 基本安装
使用 pip 安装 LlamaIndex 核心包：
```bash
pip install llama-index
```
资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:1]()
### 集成包安装
根据您的具体需求，可以安装不同的集成包：
| 集成类型 | 包名称 | 用途 |
|---------|--------|------|
| Web 读取器 | `llama-index-readers-web` | 从网页加载内容 |
| Ollama LLM | `llama-index-llms-ollama` | 本地 LLM 支持 |
| Ollama 嵌入 | `llama-index-embeddings-ollama` | 本地嵌入模型 |
| Vectara 索引 | `llama-index-indices-managed-vectara` | Vectara 云索引 |
| Konko LLM | `llama-index-llms-konko` | Konko API 支持 |
| LangChain 集成 | 随上述包自动安装 | 与 LangChain 代理集成 |
安装示例：
```bash
pip install llama-index-llms-ollama
pip install llama-index-readers-web
pip install llama-index-indices-managed-vectara
```
资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:1]()
## 核心概念
### 数据流程架构
```mermaid
graph TD
A[数据源] --> B[Document 文档]
B --> C[Node 节点]
C --> D[Index 索引]
D --> E[Retriever 检索器]
E --> F[Query Engine 查询引擎]
F --> G[Response 响应]
H[LLM] --> F
```
LlamaIndex 的核心数据流程包含以下关键组件：
1. **Document（文档）**：表示要索引的原始数据，可以是文本、HTML、PDF 等格式
2. **Node（节点）**：将 Document 分割后的数据块，便于高效检索
3. **Index（索引）**：存储节点的数据结构，支持快速相似度搜索
4. **Retriever（检索器）**：从索引中获取相关节点
5. **Query Engine（查询引擎）**：整合检索和 LLM 生成答案
### 文档加载
LlamaIndex 支持多种数据源加载器：
| 加载器 | 包名 | 数据源 |
|-------|------|--------|
| SimpleDirectoryReader | 核心包 | 本地文件系统 |
| WholeSiteReader | llama-index-readers-web | 整个网站 |
| ReadabilityWebPageReader | llama-index-readers-web | 单个网页（可读性优化） |
| NewsArticleReader | llama-index-readers-web | 新闻文章 |
| RemoteDepthReader | llama-index-readers-remote-depth | 远程 URL 层级 |
资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:1]()
## 快速示例
### 基础文档问答
以下示例展示如何使用 LlamaIndex 构建最基本的文档问答系统：
```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
# 加载本地文档
documents = SimpleDirectoryReader("data").load_data()
# 创建向量索引
index = VectorStoreIndex.from_documents(documents)
# 创建查询引擎
query_engine = index.as_query_engine()
# 执行查询
response = query_engine.query("作者在成长过程中做了些什么？")
print(response)
```
这是 LlamaIndex 最基本的用法模式：加载文档 → 创建索引 → 查询。
### 使用 Web 读取器
#### 单页面读取
```python
from llama_index.readers.web import ReadabilityWebPageReader
loader = ReadabilityWebPageReader()
documents = loader.load_data(
url="https://example.com/article"
)
index = VectorStoreIndex.from_documents(documents)
print(index.query("这篇文文章的主要内容是什么？"))
```
资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md:1]()
#### 全站抓取
```python
from llama_index.readers.web import WholeSiteReader
# 初始化抓取器
scraper = WholeSiteReader(
prefix="https://docs.llamaindex.ai/en/stable/",
max_depth=10,
)
# 从基础 URL 开始抓取
documents = scraper.load_data(
base_url="https://docs.llamaindex.ai/en/stable/"
)
index = VectorStoreIndex.from_documents(documents)
index.query("这个网站使用什么语言？")
```
资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/whole_site/README.md:1]()
### 使用本地 LLM（Ollama）
```python
from llama_index.llms.ollama import Ollama
# 初始化 Ollama LLM
llm = Ollama(model="llama3.1:latest", request_timeout=120.0)
# 生成补全
resp = llm.complete("Paul Graham 是谁？")
print(resp)
# 使用聊天接口
from llama_index.core.llms import ChatMessage
messages = [
ChatMessage(
role="system",
content="你是一个友好的助手"
),
ChatMessage(
role="user",
content="解释一下大爆炸理论"
),
]
resp = llm.chat(messages)
print(resp)
```
资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:1]()
### 使用云索引服务（Vectara）
```python
from llama_index.indices.managed.vectara import VectaraIndex
from llama_index.core.schema import Document, MediaResource
import os
# 设置环境变量
os.environ["VECTARA_API_KEY"] = ""
os.environ["VECTARA_CORPUS_KEY"] = ""
# 创建文档
docs = [
Document(
id_="doc1",
text_resource=MediaResource(
text="这是 Vectara 与 LlamaIndex 集成的测试文本。"
),
),
]
# 创建索引并添加文档
index = VectaraIndex.from_documents(docs)
# 检索文档
retriever = index.as_retriever(similarity_top_k=2)
results = retriever.retrieve("用户体验如何？")
print(results[0])
# 作为查询引擎使用
query_engine = index.as_query_engine()
response = query_engine.query("总结主要内容")
```
资料来源：[llama-index-integrations/indices/llama-index-indices-managed-vectara/README.md:1]()
## 与 LangChain 集成
LlamaIndex 可以作为工具集成到 LangChain 代理中：
```python
from llama_index.core import VectorStoreIndex, download_loader
from langchain.agents import initialize_agent, Tool
from langchain.llms import OpenAI
from langchain.chains.conversation.memory import ConversationBufferMemory
from llama_index.readers.web import ReadabilityWebPageReader
# 加载文档
loader = ReadabilityWebPageReader()
documents = loader.load_data(
url="https://example.com/article"
)
# 创建索引
index = VectorStoreIndex.from_documents(documents)
# 定义工具
tools = [
Tool(
name="Website Index",
func=lambda q: index.query(q),
description="用于回答网站内容相关问题的工具。",
),
]
# 初始化代理
llm = OpenAI(temperature=0)
memory = ConversationBufferMemory(memory_key="chat_history")
agent_chain = initialize_agent(
tools, llm, agent="zero-shot-react-description", memory=memory
)
# 运行代理
output = agent_chain.run(input="网站的主要内容是什么？")
```
资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/readability_web/README.md:1]()
## 嵌入模型配置
### Ollama 嵌入
```python
from llama_index.embeddings.ollama import OllamaEmbedding
embed_model = OllamaEmbedding(
model_name="nomic-embed-text",
base_url="http://your-remote-server:11434",
)
# 使用嵌入模型
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents, embed_model=embed_model)
```
资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md:1]()
### 可用嵌入模型
| 模型 ID | 描述 | 适用场景 |
|--------|------|---------|
| `nomic-embed-text` | 通用嵌入模型 | 通用任务 |
| `embeddinggemma` | Google Gemma 系列 | 高精度需求 |
| `mxbai-embed-large` | 大型嵌入模型 | 最佳质量 |
安装嵌入模型：
```bash
ollama pull nomic-embed-text
```
## 完整 RAG 流程
```mermaid
graph LR
A[用户问题] --> B[检索]
B --> C[向量相似度匹配]
C --> D[相关文档片段]
D --> E[上下文构建]
E --> F[LLM 生成]
F --> G[最终回答]
H[(文档库)] --> I[文档加载]
I --> J[分块处理]
J --> K[向量编码]
K --> C
```
完整的 RAG（检索增强生成）流程包括：
| 阶段 | 组件 | 描述 |
|-----|------|------|
| 数据摄入 | Document Loader | 从各种来源加载文档 |
| 处理 | Node Parser | 将文档分割成小块 |
| 索引 | Vector Store | 存储向量表示 |
| 检索 | Retriever | 找到相关上下文 |
| 生成 | Query Engine + LLM | 生成最终答案 |
## 常见问题
### 连接错误
如果遇到连接错误，请检查：
1. Ollama 服务是否运行：`ollama serve`
2. `base_url` 是否与 Ollama 服务器地址匹配
3. 模型是否已下载：`ollama pull `
资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md:1]()
### 模型未找到
如果出现"模型未找到"错误：
1. 列出可用模型：`ollama list`
2. 拉取所需模型：`ollama pull `
3. 确认模型名称在代码中完全匹配
### 超时配置
默认超时时间为 30 秒，可以通过 `request_timeout` 参数调整：
```python
llm = Ollama(
model="llama3.1:latest",
request_timeout=300.0
)
```
资料来源：[llama-index-integrations/llms/llama-index-llms-ollama/README.md:1]()
## 下一步
掌握基础用法后，您可以深入学习以下高级主题：
- **自定义检索器**：实现混合搜索策略
- **流式响应**：实现实时生成输出
- **回调系统**：集成 Argilla 等监控工具
- **多模态支持**：处理图像和文本混合内容
- **代理工具集成**：构建更复杂的 AI 代理应用
---
## 系统架构
### 相关页面
相关主题：[核心组件详解](#core_components), [数据摄取流程](#data_ingestion), [查询引擎](#query_engine)
相关源码文件
以下源码文件用于生成本页说明：
- [llama-index-core/llama_index/core/indices/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/base.py)
- [llama-index-core/llama_index/core/query_engine/retriever_query_engine.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/retriever_query_engine.py)
- [llama-index-core/llama_index/core/storage/storage_context.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/storage_context.py)
- [llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md)
- [llama-index-integrations/readers/llama-index-readers-docling/README.md](https://github.com/run-llama/llama_index/blob/main/llama-index-integrations/readers/llama-index-readers-docling/README.md)
# 系统架构
## 概述
LlamaIndex 是一个专为大型语言模型（LLM）应用设计的检索增强生成（RAG）框架，其系统架构围绕数据索引构建、智能查询处理和持久化存储三大核心功能展开。框架采用模块化设计，通过清晰的分层结构将数据加载、文档处理、索引管理、查询执行和存储管理解耦，同时保持各组件间的无缝协作能力。
LlamaIndex 的架构设计遵循"数据优先"的原则，首先通过多元化的 Reader 组件从不同数据源提取内容，然后经过解析和分块处理形成结构化的 Node 对象，最终由各类 Index 索引进行组织和存储。查询阶段则通过 Query Engine 实现语义理解和信息检索的结合，为 LLM 提供准确的上下文支撑。
## 核心架构组件
### 索引层（Indices）
索引层是 LlamaIndex 架构的核心，负责将非结构化数据转换为可高效检索的向量表示。根据应用场景的不同，框架提供了多种索引类型的实现：
| 索引类型 | 用途描述 | 适用场景 |
|---------|---------|----------|
| VectorStoreIndex | 基于向量嵌入的语义检索 | 问答系统、内容推荐 |
| DocumentSummaryIndex | 文档摘要索引 | 长文档快速概览 |
| KnowledgeGraphIndex | 知识图谱索引 | 关系型问答、实体链接 |
| TreeIndex | 树形结构索引 | 分层文档组织 |
| KeywordTableIndex | 关键词表索引 | 精确关键词匹配 |
索引架构采用基类继承设计，所有索引类型都继承自 BaseIndex 抽象基类，共享通用的索引生命周期管理接口，包括索引创建、更新、删除和持久化等核心操作。这种设计确保了索引行为的一致性，同时允许各子类根据具体需求实现特定的索引逻辑。
```mermaid
graph TD
A[Document 文档] --> B[Node Parser 节点解析器]
B --> C[Index 索引构建]
C --> D[VectorStoreIndex 向量索引]
C --> E[KnowledgeGraphIndex 知识图谱索引]
C --> F[TreeIndex 树形索引]
D --> G[Vector Store 向量存储]
E --> H[Graph Store 图存储]
F --> I[Document Store 文档存储]
```
资料来源：[llama-index-core/llama_index/core/indices/base.py:1-50]()
### 查询引擎层（Query Engine）
查询引擎层负责接收用户查询并返回相关结果。框架提供了多种查询引擎实现，其中 RetrieverQueryEngine 是最常用的实现，它将检索器（Retriever）与 LLM 相结合，实现语义理解与信息检索的闭环处理。
RetrieverQueryEngine 的核心工作流程包括：首先接收自然语言查询，然后调用底层的 Retriever 从索引中检索相关节点，接着将检索结果与原始查询组装为 Prompt 提交给 LLM 进行答案生成。这种设计实现了检索与生成的分离，使得用户可以灵活切换不同的检索策略和 LLM 模型。
```mermaid
graph LR
A[User Query 用户查询] --> B[Retriever 检索器]
B --> C[Retrieved Nodes 检索节点]
C --> D[Response Synthesizer 响应合成器]
D --> E[LLM 大语言模型]
E --> F[Final Response 最终响应]
```
资料来源：[llama-index-core/llama_index/core/query_engine/retriever_query_engine.py:1-80]()
### 存储层（Storage）
存储层负责管理索引数据和文档的持久化。StorageContext 是存储架构的核心抽象，它整合了三种存储组件：DocStore（文档存储）、IndexStore（索引存储）和 VectorStore（向量存储）。这种三分层设计使得不同类型的数据可以选用最适合的存储后端。
| 存储组件 | 存储内容 | 支持的后端 |
|---------|---------|------------|
| DocStore | 原始文档和节点数据 | MongoDB、Redis、SimpleDocumentStore |
| IndexStore | 索引元数据 | MongoDB、Redis、SimpleIndexStore |
| VectorStore | 向量嵌入数据 | Chroma、Pinecone、Weaviate、Milvus |
StorageContext 提供了统一的存储接口抽象，屏蔽了底层存储实现细节，使得应用程序可以在不同存储后端之间灵活切换而无需修改业务逻辑代码。
资料来源：[llama-index-core/llama_index/core/storage/storage_context.py:1-100]()
## 数据加载与处理
### Reader 集成系统
LlamaIndex 的 Reader 系统提供了从多样化数据源加载内容的能力，这是实现端到端 RAG 流程的数据入口。Reader 架构采用统一接口设计，所有 Reader 都实现 BaseReader 接口，提供标准化的 `load_data()` 方法。
当前框架支持的主要 Reader 类型及其数据源：
| Reader 类型 | 数据源 | 用途 |
|------------|--------|------|
| NewsArticleReader | 新闻网站 | 抓取 CNBC、The Verge 等新闻内容 |
| TrafilaturaWebReader | 通用网页 | 使用 trafilatura 库提取网页正文 |
| MainContentExtractorReader | 静态网站 | 提取网页主要内容区域 |
| UnstructuredURLLoader | 任意网页 | 使用 Unstructured.io 解析 HTML |
| ReadabilityWebPageReader | 新闻文章 | 使用 Mozilla Readability 算法 |
| WholeSiteReader | 整站爬取 | 按深度递归爬取整个网站 |
| WikipediaReader | Wikipedia | 读取 Wikipedia 条目内容 |
| SemanticScholarReader | 学术论文 | 获取 Semantic Scholar 论文数据 |
| DoclingReader | PDF/DOCX/HTML | 使用 Docling 提取复杂文档 |
| BoxReader | Box 云存储 | 读取 Box 中的文件和文件夹 |
| WordPressReader | WordPress 博客 | 通过 WP REST API 获取内容 |
这种多元化的 Reader 设计确保了 LlamaIndex 可以接入几乎所有常见的数据源，从网页内容到企业文档，从学术论文到云存储文件，构建完整的 RAG 数据管道。
资料来源：[llama-index-integrations/readers/llama-index-readers-web/llama_index/readers/web/news/README.md]()
资料来源：[llama-index-integrations/readers/llama-index-readers-docling/README.md]()
### 文档处理流程
文档从原始数据到可索引状态的转换过程涉及多个处理阶段：
```mermaid
graph TD
A[Raw Data 原始数据] --> B[Reader 读取器]
B --> C[Document 对象]
C --> D[Node Parser 节点解析器]
D --> E[TextNode / ImageNode]
E --> F[Embedding Model 嵌入模型]
F --> G[Indexed Nodes 索引节点]
G --> H[VectorStoreIndex]
```
Node Parser 负责将 Document 拆分为更小的语义单元（Node），这个过程支持多种策略：
- **TokenTextSplitter**：基于 token 数量的文本分块
- **SentenceSplitter**：基于句子边界的分块
- **RecursiveCharacterTextSplitter**：递归字符分块，优先保持段落完整性
## 查询处理流程
### 检索与生成分离
LlamaIndex 架构的核心设计理念之一是检索与生成的分离。这种设计带来了多重优势：首先，允许独立优化检索和生成两个环节；其次，支持多种检索策略的灵活组合；第三，便于实现缓存和结果复用。
```mermaid
graph TD
A[Query 输入查询] --> B[Query Transform 查询变换]
B --> C[Embedding 嵌入生成]
C --> D[Vector Search 向量搜索]
D --> E[Top-K Retrieval Top-K 检索]
E --> F[Node Postprocessors 节点后处理器]
F --> G[Context Assembly 上下文组装]
G --> H[LLM Response Generation LLM 响应生成]
H --> I[Response 输出响应]
```
### 查询引擎类型
| 引擎类型 | 描述 | 核心特性 |
|---------|------|----------|
| RetrieverQueryEngine | 标准检索引擎 | 基础 RAG 流程 |
| CitationQueryEngine | 引用查询引擎 | 支持答案溯源 |
| MultiStepQueryEngine | 多步查询引擎 | 处理复杂多跳问题 |
| SubQuestionQueryEngine | 子问题引擎 | 将复杂问题分解 |
CitationQueryEngine 是一个重要的扩展，它不仅返回答案，还提供答案引用的来源信息，使得用户可以验证和追溯生成内容的准确性。这对于构建可信赖的 RAG 应用至关重要。
## 嵌入与向量化
### 嵌入模型集成
LlamaIndex 的嵌入系统采用插件化设计，通过抽象的 BaseEmbedding 接口支持多种嵌入模型后端。当前支持的嵌入服务包括：
- **OpenAI Embeddings**：OpenAI 的 text-embedding-ada-002 等模型
- **Ollama Embeddings**：本地运行的 Ollama 模型，如 nomic-embed-text
- **ModelScope Embeddings**：阿里魔搭平台的嵌入模型，如 nlp_gte_sentence-embedding_chinese-base
- **HuggingFace Embeddings**：HuggingFace 生态的各种嵌入模型
这种模块化设计允许开发者根据数据语言、应用场景和性能要求选择最合适的嵌入模型，同时保持上层索引和查询逻辑的稳定性。
资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md]()
资料来源：[llama-index-integrations/embeddings/llama-index-embeddings-modelscope/README.md]()
## 服务架构
### 服务上下文（ServiceContext）
ServiceContext 是 LlamaIndex 的服务配置中心，它聚合了 LLM、嵌入模型、提示模板、回调处理器等运行时组件。通过 ServiceContext，开发者可以一次性配置好整个 RAG 流程所需的全部服务组件。
```mermaid
graph TD
A[ServiceContext] --> B[LLM 大语言模型]
A --> C[Embedding Model 嵌入模型]
A --> D[Node Parser 节点解析器]
A --> E[Prompt Template 提示模板]
A --> F[Callback Manager 回调管理器]
G[Query Pipeline] --> A
H[Index Construction] --> A
```
### 回调系统
LlamaIndex 提供了全面的回调机制（Callback System），覆盖索引构建、查询执行、检索过程等关键节点。通过 CallbackManager，应用可以：
- 记录执行时间消耗
- 追踪 Token 使用量
- 监控检索结果质量
- 集成第三方监控服务
## 工作流示意
### 端到端 RAG 流程
```mermaid
graph LR
A[数据源] -->|Reader| B[Documents]
B -->|Node Parser| C[Nodes]
C -->|Embedding| D[Vector Index]
D -->|Storage| E[Persist Storage]
F[User Query] -->|Embedding| G[Retrieve]
G -->|Top-K| H[Relevant Nodes]
H -->|Context| I[LLM]
I -->|Generate| J[Response]
```
## 扩展集成
### 工具系统（Tools）
LlamaIndex 的工具系统允许将索引和查询能力封装为可被 Agent 调用的工具。通过 Tool 接口，开发者可以创建自定义工具，暴露给 LangChain 等 Agent 框架使用。例如，Moss 工具提供了向量搜索能力，支持混合搜索（关键词 + 语义）和可配置的排名参数。
| 工具名称 | 功能描述 | 关键参数 |
|---------|---------|----------|
| Moss | 混合向量搜索 | top_k, alpha, model_id |
| Brightdata | 网络数据采集 | search_engine, web_data_feed |
| Wikipedia | 维基百科查询 | pages |
### 外部服务集成
LlamaIndex 与多种外部服务保持深度集成，包括向量数据库（Chroma、Milvus、Pinecone）、云存储（Box、S3）、搜索服务（Brightdata）等。这种集成通过统一抽象层实现，确保了核心架构的稳定性同时提供了丰富的生态扩展能力。
## 总结
LlamaIndex 的系统架构体现了现代 LLM 应用框架的设计原则：**模块化、可扩展、关注点分离**。从数据加载到索引构建，从查询处理到响应生成，每个环节都被设计为可独立配置和替换的组件。这种架构使得开发者可以灵活应对不同的应用场景需求，同时享受框架提供的开箱即用功能。随着生态系统的持续发展，LlamaIndex 正在成为构建生产级 RAG 应用的首选框架之一。
---
## 核心组件详解
### 相关页面
相关主题：[系统架构](#system_architecture), [存储层架构](#storage_layer)
相关源码文件
以下源码文件用于生成本页说明：
- [llama-index-core/llama_index/core/schema.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/schema.py)
- [llama-index-core/llama_index/core/indices/vector_store/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/vector_store/base.py)
- [llama-index-core/llama_index/core/indices/property_graph/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/property_graph/base.py)
- [llama-index-core/llama_index/core/indices/knowledge_graph/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/knowledge_graph/base.py)
- [llama-index-core/llama_index/core/response_synthesizers/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/response_synthesizers/base.py)
# 核心组件详解
## 概述
LlamaIndex 是一个强大的大语言模型应用框架，其核心组件构成了构建高级检索增强生成（RAG）系统的基础设施。本文档深入剖析 LlamaIndex 的核心组件体系，包括数据模型、索引类型、检索引擎和响应合成器等关键模块。这些组件协同工作，为开发者提供了从文档处理到智能问答的完整技术栈。
LlamaIndex 的设计理念强调模块化和可扩展性，每个核心组件都遵循统一的接口规范，使得开发者能够灵活地组合和定制系统行为。核心组件之间的关系可以用下图表示：
```mermaid
graph TD
A[Document 文档] --> B[Node 节点]
B --> C[BaseIndex 索引基类]
C --> D[VectorStoreIndex 向量索引]
C --> E[PropertyGraphIndex 属性图索引]
C --> F[KnowledgeGraphIndex 知识图谱索引]
D --> G[Retriever 检索器]
E --> G
F --> G
G --> H[ResponseSynthesizer 响应合成器]
H --> I[Response 响应]
```
## 数据模型体系
### Document 文档类
Document 是 LlamaIndex 中表示文档数据的基础单元，封装了原始文本内容和元数据信息。每个 Document 对象包含文本资源和关联的元数据字典，支持灵活的数据存储和检索需求。
```mermaid
classDiagram
class Document {
+id_: str
+text_resource: TextResource
+metadata: Dict[str, Any]
+embedding: Optional[List[float]]
+embedding_strategy: Optional[EmbeddingStrategy]
+__init__(...)
+to_langchain_document(): langchain Document
+to_openai_message(): Dict
+get_content(metadata_mode: MetadataMode): str
}
class TextResource {
+text: Optional[str]
+relationships: Optional[Dict[RelationshipType, List[str]]]
}
Document *-- TextResource
```
Document 类提供了丰富的属性和方法，支持与外部系统（如 LangChain）的无缝集成。text_resource 属性采用组合模式，包含实际文本内容和关系信息。metadata 字典允许存储任意键值对形式的元数据，便于后续检索和过滤。
文档的创建和使用示例：
```python
from llama_index.core.schema import Document, TextResource, MediaResource
# 基础文档创建
doc = Document(
id_="doc-001",
text_resource=MediaResource(text="这是文档的文本内容"),
metadata={"source": "example.txt", "author": "张三"}
)
# 获取文档内容
content = doc.get_content(metadata_mode=MetadataMode.ALL)
```
### Node 节点类
Node 是 Document 的细粒度表示，代表文档经过分块处理后的最小语义单元。Node 继承自 Document，并增加了关联关系和位置信息，用于维护文档结构的层级关系。
| 属性 | 类型 | 说明 |
|------|------|------|
| `id_` | str | 节点唯一标识符 |
| `text_resource` | TextResource | 文本资源对象 |
| `metadata` | Dict[str, Any] | 元数据字典 |
| `relationships` | Dict[RelationshipType, NodeRelationship] | 关联关系映射 |
| `metadata_seperator` | str | 元数据分隔符 |
Node 的关系类型通过 RelationshipType 枚举定义，主要包括：
- `SOURCE`：指向源文档的关系
- `PREVIOUS`：指向前一个兄弟节点
- `NEXT`：指向后一个兄弟节点
- `PARENT`：指向父节点
- `CHILD`：指向子节点列表
```python
from llama_index.core.schema import NodeRelationship, RelatedNode
# 创建具有父子关系的节点
child_node = TextNode(
text="子节点内容",
relationships={
NodeRelationship.PARENT: RelatedNode(node_id="parent-node-id")
}
)
```
## 索引系统
### VectorStoreIndex 向量存储索引
VectorStoreIndex 是 LlamaIndex 最核心的索引实现，基于向量相似度检索实现高效的语义搜索功能。该索引将文档转换为向量表示，并存储在向量数据库中，支持大规模数据的快速相似度查询。
```mermaid
graph TD
A[用户查询] --> B[QueryEngine 查询引擎]
B --> C[Retriever 检索器]
C --> D[BaseRetriever 基类]
D --> E[VectorRetriever 向量检索器]
E --> F[VectorStore 向量存储]
F --> G[相似向量节点]
G --> H[ResponseSynthesizer]
H --> I[最终响应]
style F fill:#e1f5fe
style E fill:#fff3e0
```
VectorStoreIndex 的核心架构包含以下层次：
#### 索引构建流程
索引的构建过程涉及文档解析、节点分割、向量计算和存储等步骤。以下是索引创建的标准流程：
```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
# 加载文档
documents = SimpleDirectoryReader("./data").load_data()
# 创建索引
index = VectorStoreIndex.from_documents(documents)
# 获取查询引擎
query_engine = index.as_query_engine()
# 执行查询
response = query_engine.query("用户问题")
```
#### 向量检索器配置
VectorStoreIndex 提供了丰富的检索配置选项，开发者可以根据具体需求调整检索行为：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `vector_store` | BasePydanticVectorStore | SimpleVectorStore | 向量存储后端 |
| `embed_model` | BaseEmbedding | None | 嵌入模型 |
| `llm` | Optional[LLM] | None | 大语言模型 |
| `similarity_top_k` | int | 1 | 返回的最相似结果数量 |
| `vector_store_kwargs` | Dict | {} | 向量存储额外参数 |
```python
from llama_index.core.vector_stores import PineconeVectorStore
from llama_index.core import VectorStoreIndex
# 使用自定义向量存储
vector_store = PineconeVectorStore(
pinecone_index=pinecone_index,
embed_model=embed_model
)
index = VectorStoreIndex.from_documents(
documents,
vector_store=vector_store
)
```
#### 检索模式
VectorStoreIndex 支持多种检索模式，通过 as_retriever 方法可以灵活配置：
```python
# 获取默认检索器
retriever = index.as_retriever()
# 配置检索参数
retriever = index.as_retriever(
vector_store_kwargs={
"filter": {"category": "技术文档"},
"top_k": 10
}
)
```
### PropertyGraphIndex 属性图索引
PropertyGraphIndex 是 LlamaIndex 提供的图结构索引实现，支持构建和维护复杂的实体关系网络。与传统的平面向量索引不同，PropertyGraphIndex 能够表达实体之间的多层次语义关系。
```mermaid
graph LR
A[实体: LlamaIndex] -->|类型| B[框架]
A -->|用于| C[构建]
C -->|对象| D[RAG应用]
E[实体: RAG] -->|代表| F[检索增强生成]
style A fill:#c8e6c9
style E fill:#c8e6c9
style C fill:#fff9c4
style D fill:#bbdefb
```
#### 属性图的核心概念
PropertyGraphIndex 基于三元组模型表示知识，三元组由源实体、关系类型和目标实体组成。这种表示方式能够清晰地捕捉现实世界中的复杂语义关联。
核心组件包括：
- **Entities（实体）**：表示现实世界中的对象或概念
- **Relations（关系）**：表示实体之间的语义关联
- **Properties（属性）**：为实体和关系添加额外描述信息
#### 创建属性图索引
```python
from llama_index.core.indices.property_graph import PropertyGraphIndex
# 使用 LLM 从文档中提取知识图谱
index = PropertyGraphIndex.from_documents(
documents,
llm=llm,
embed_model=embed_model
)
# 自定义关系和实体提取器
from llama_index.core.indices.property_graph import SchemaLLMPathExtractor
schema_extractor = SchemaLLMPathExtractor(
llm=llm,
schema=[
{"name": "PERSON", "props": ["name", "age"]},
{"name": "ORGANIZATION", "props": ["name", "founded"]}
]
)
index = PropertyGraphIndex.from_documents(
documents,
kg_extractors=[schema_extractor]
)
```
### KnowledgeGraphIndex 知识图谱索引
KnowledgeGraphIndex 是专门用于构建知识图谱的索引类型，它利用 LLM 从非结构化文本中提取实体和关系，构建可查询的知识网络。该索引继承自 PropertyGraphIndex，提供了更高级别的抽象和更便捷的 API。
```mermaid
graph TD
A[Document 文档] --> B[LLM 提取器]
B --> C[三元组抽取]
C --> D[Entity 实体]
C --> E[Relation 关系]
D --> F[知识图谱存储]
E --> F
F --> G[检索与查询]
style F fill:#f3e5f5
```
#### 知识图谱索引配置
KnowledgeGraphIndex 提供了丰富的配置选项：
| 配置项 | 类型 | 说明 |
|--------|------|------|
| `storage_context` | StorageContext | 存储上下文 |
| `llm` | LLM | 用于抽取的大语言模型 |
| `embed_model` | BaseEmbedding | 嵌入模型 |
| `include_reasoning` | bool | 是否包含推理信息 |
| `max_triplets_per_chunk` | int | 每个块最多抽取的三元组数 |
| `kg_extractors` | List[KGExtractor] | 知识图谱提取器列表 |
#### 使用知识图谱进行检索
```python
from llama_index.core.indices.knowledge_graph import KnowledgeGraphIndex
# 创建知识图谱索引
index = KnowledgeGraphIndex.from_documents(
documents,
max_triplets_per_chunk=10
)
# 获取检索器
retriever = index.as_retriever(
include_text=True,
retriever_mode="keyword"
)
# 获取查询引擎
query_engine = index.as_query_engine(
include_text=True,
response_mode="tree_summarize"
)
# 执行查询
response = query_engine.query("关于 LlamaIndex 的信息")
```
## 检索器系统
### Retriever 检索器架构
Retriever 是 LlamaIndex 中负责从索引中获取相关上下文的组件。检索器采用统一的接口设计，使得不同检索策略可以透明地互换使用。
```mermaid
classDiagram
class BaseRetriever {
<>
+retrieve(str_or_query_bundle): List[NodeWithScore]
}
class VectorRetriever {
+filters: Optional[MetadataFilters]
+similarity_top_k: int
+retrieve(): List[NodeWithScore]
}
class KnowledgeGraphRetriever {
+retriever_mode: str
+top_k: int
+retrieve(): List[NodeWithScore]
}
class PropertyGraphRetriever {
+include_text: bool
+embed_relations: bool
+retrieve(): List[NodeWithScore]
}
BaseRetriever <|-- VectorRetriever
BaseRetriever <|-- KnowledgeGraphRetriever
BaseRetriever <|-- PropertyGraphRetriever
```
### 检索器类型
| 检索器类型 | 说明 | 适用场景 |
|-----------|------|----------|
| `VectorRetriever` | 基于向量相似度的检索 | 语义搜索、向量化索引 |
| `KnowledgeGraphRetriever` | 知识图谱检索 | 关系型查询、实体链接 |
| `PropertyGraphRetriever` | 属性图检索 | 复杂关系查询、图遍历 |
| `KeywordTableRetriever` | 关键词表格检索 | 精确关键词匹配 |
| `EnsembleRetriever` | 集成检索 | 组合多种检索策略 |
### 自定义检索器
开发者可以通过继承 BaseRetriever 类实现自定义检索逻辑：
```python
from llama_index.core.retrievers import BaseRetriever
from llama_index.core.schema import NodeWithScore
class CustomRetriever(BaseRetriever):
def __init__(self, index, threshold: float = 0.7):
super().__init__()
self._index = index
self._threshold = threshold
def _retrieve(self, query_bundle):
# 自定义检索逻辑
nodes = []
# ... 实现检索逻辑
return nodes
```
## 响应合成器
### ResponseSynthesizer 响应合成器架构
ResponseSynthesizer 负责将检索到的上下文与用户查询结合，生成最终的自然语言响应。这是 RAG 系统中将检索结果转化为有用答案的关键环节。
```mermaid
graph TD
A[用户查询] --> B[Query Bundle]
B --> C[ResponseSynthesizer]
C --> D{合成模式}
D -->|compact| E[Compact 压缩模式]
D -->|refine| F[Refine 精炼模式]
D -->|tree_summarize| G[Tree Summarize 树形摘要]
D -->|simple| H[Simple 简单模式]
E --> I[LLM 生成]
F --> I
G --> I
H --> I
I --> J[Response 响应]
style C fill:#e8f5e9
style I fill:#fff8e1
style J fill:#c8e6c9
```
### 响应合成模式
LlamaIndex 提供了多种响应合成策略，适用于不同的应用场景：
| 合成模式 | 说明 | 特点 | 适用场景 |
|---------|------|------|----------|
| `simple` | 简单模式 | 一次性生成响应 | 简短回答、少量上下文 |
| `compact` | 压缩模式 | 合并多个上下文块 | 大量检索结果 |
| `refine` | 精炼模式 | 迭代优化响应 | 需要高质量长回答 |
| `tree_summarize` | 树形摘要 | 分层聚合信息 | 复杂多主题查询 |
| `generation` | 生成模式 | 仅使用 LLM 生成 | 无检索场景 |
### 响应合成器配置
```python
from llama_index.core.response_synthesizers import (
ResponseMode,
get_response_synthesizer
)
# 创建响应合成器
synthesizer = get_response_synthesizer(
response_mode=ResponseMode.COMPACT,
llm=llm,
text_qa_template=qa_prompt_template,
summary_template=summary_prompt_template
)
# 通过查询引擎使用
query_engine = index.as_query_engine(
response_synthesizer=synthesizer
)
```
### 自定义响应合成器
开发者可以通过继承 BaseSynthesizer 实现自定义合成逻辑：
```python
from llama_index.core.response_synthesizers import BaseSynthesizer
class CustomSynthesizer(BaseSynthesizer):
def synthesize(
self,
query_bundle: QueryBundle,
nodes: List[NodeWithScore]
) -> Response:
# 自定义合成逻辑
context_str = "\n\n".join([n.get_content() for n in nodes])
# ... 生成响应
return response
```
## 查询引擎
### QueryEngine 查询引擎
QueryEngine 是 LlamaIndex 提供的端到端查询接口，整合了检索和响应合成两个环节。查询引擎接收用户查询，自动执行检索流程，并生成最终响应。
```mermaid
graph LR
A[Query 输入] --> B[Retriever 检索]
B --> C[NodeWithScore 节点列表]
C --> D[Postprocessor 后处理器]
D --> E[ResponseSynthesizer 合成器]
E --> F[Response 输出]
```
### 查询引擎配置
| 参数 | 类型 | 说明 |
|------|------|------|
| `retriever` | BaseRetriever | 检索器实例 |
| `response_synthesizer` | Optional[BaseSynthesizer] | 响应合成器 |
| `node_postprocessors` | List[BaseNodePostprocessor] | 节点后处理器 |
| `verbose` | bool | 是否输出详细日志 |
### 组合式查询引擎
```python
from llama_index.core import QueryEngine, get_response_synthesizer
# 创建组合式查询引擎
query_engine = index.as_query_engine(
retriever=retriever,
response_synthesizer=synthesizer,
node_postprocessors=[
KeywordNodePostprocessor(similarity_cutoff=0.7),
SimilarityPostprocessor(threshold=0.8)
]
)
# 执行查询
response = query_engine.query("用户问题")
```
## 存储与持久化
### StorageContext 存储上下文
StorageContext 管理 LlamaIndex 的数据持久化，提供了统一的存储接口。StorageContext 封装了文档存储、向量存储、图存储等组件。
```mermaid
classDiagram
class StorageContext {
+docstore: BaseDocumentStore
+vector_store: BaseVectorStore
+graph_store: BaseGraphStore
+index_store: BaseIndexStore
+from_defaults(): StorageContext
+persist(): None
+load(): StorageContext
}
class BaseDocumentStore {
<>
+add_documents(): None
+get_document(): Document
+delete_document(): None
}
class BaseVectorStore {
<>
+add(): List[str]
+delete(): None
+query(): VectorStoreQueryResult
}
StorageContext *-- BaseDocumentStore
StorageContext *-- BaseVectorStore
StorageContext *-- BaseGraphStore
```
### 持久化操作
```python
from llama_index.core import StorageContext, load_index_from_storage
# 从存储加载索引
storage_context = StorageContext.from_defaults(
persist_dir="./storage"
)
index = load_index_from_storage(storage_context)
# 保存索引
index.storage_context.persist(persist_dir="./storage")
```
## 组件交互流程
### 完整 RAG 流程
以下是 LlamaIndex 核心组件的完整交互流程：
```mermaid
sequenceDiagram
participant User as 用户
participant QE as QueryEngine
participant Ret as Retriever
participant VS as VectorStore
participant Syn as ResponseSynthesizer
participant LLM as LLM
User->>QE: query("问题")
QE->>Ret: retrieve(query_bundle)
Ret->>VS: similarity_search(embedding)
VS-->>Ret: List[NodeWithScore]
Ret-->>QE: List[NodeWithScore]
QE->>Syn: synthesize(query, nodes)
Syn->>LLM: generate(prompt)
LLM-->>Syn: response_text
Syn-->>QE: Response
QE-->>User: Response
```
### 数据流向总结
| 阶段 | 组件 | 数据格式 | 说明 |
|------|------|---------|------|
| 文档加载 | DocumentLoader | Document | 从各种来源加载原始文档 |
| 分块处理 | NodeParser | List[Node] | 将文档分割为语义块 |
| 向量化 | EmbedModel | List[float] | 计算文本向量表示 |
| 索引存储 | VectorStore | VectorStoreRecord | 存储向量和元数据 |
| 检索查询 | Retriever | List[NodeWithScore] | 根据相似度检索 |
| 响应生成 | ResponseSynthesizer | Response | 生成自然语言回答 |
## 最佳实践
### 组件选择指南
| 需求场景 | 推荐索引类型 | 检索器类型 |
|---------|-------------|-----------|
| 语义搜索 | VectorStoreIndex | VectorRetriever |
| 关系查询 | KnowledgeGraphIndex | KnowledgeGraphRetriever |
| 复杂关系网络 | PropertyGraphIndex | PropertyGraphRetriever |
| 高精度问答 | VectorStoreIndex + KnowledgeGraphIndex | EnsembleRetriever |
### 性能优化建议
1. **批量处理**：使用批量 API 进行文档索引和检索
2. **缓存策略**：启用向量和结果的缓存
3. **异步操作**：使用 async API 提高并发性能
4. **索引优化**：合理设置块大小和重叠参数
### 错误处理
```python
from llama_index.core import VectorStoreIndex
try:
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("问题")
except Exception as e:
# 错误处理逻辑
print(f"发生错误: {e}")
```
## 总结
LlamaIndex 的核心组件体系提供了从文档处理到智能问答的完整技术栈。Document 和 Node 构成了数据模型的基础；VectorStoreIndex、PropertyGraphIndex 和 KnowledgeGraphIndex 提供了多样化的索引能力；Retriever 和 ResponseSynthesizer 则负责检索和响应生成的关键环节。这些组件通过统一的接口设计实现了高度的可组合性和可扩展性，使开发者能够灵活构建满足各种需求的 RAG 应用。
---
## 数据摄取流程
### 相关页面
相关主题：[节点解析器](#node_parsing), [存储层架构](#storage_layer), [核心组件详解](#core_components)
相关源码文件
以下源码文件用于生成本页说明：
- [llama-index-core/llama_index/core/ingestion/pipeline.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/ingestion/pipeline.py)
- [llama-index-core/llama_index/core/readers/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/readers/base.py)
- [llama-index-core/llama_index/core/readers/file/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/readers/file/base.py)
- [llama-index-core/llama_index/core/ingestion/transformations.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/ingestion/transformations.py)
# 数据摄取流程
## 概述
数据摄取流程（Data Ingestion Pipeline）是LlamaIndex框架中负责从各种数据源加载、转换和处理原始数据的核心模块。该流程将非结构化或半结构化的原始数据转换为标准化的Document对象，供后续的索引构建和检索使用。
数据摄取流程的主要职责包括：
- **数据加载**：从文件、网页、数据库、API等多种来源读取数据
- **数据解析**：将不同格式的数据（PDF、Word、HTML、Markdown等）解析为文本内容
- **数据转换**：对文本进行分块、清洗、向量化等预处理操作
- **流程编排**：通过Pipeline机制协调各个处理环节
```mermaid
graph TD
A[数据源] --> B[Reader读取器]
B --> C[Document对象]
C --> D[Transformations转换器]
D --> E[处理后的Document]
E --> F[索引构建/存储]
```
## 核心架构
数据摄取流程由三个主要组件构成：
| 组件 | 职责 | 源码位置 |
|------|------|----------|
| **Reader** | 从各种来源加载原始数据 | `llama_index/core/readers/` |
| **Transformation** | 对Document进行转换处理 | `llama_index/core/ingestion/transformations.py` |
| **IngestionPipeline** | 编排整个摄取流程 | `llama_index/core/ingestion/pipeline.py` |
## 读取器（Readers）
### 读取器基类
所有读取器继承自`BaseReader`基类，定义了统一的数据加载接口：
```python
from llama_index.core.readers.base import BaseReader
class BaseReader:
"""数据读取器基类"""
def load_data(self, *args, **kwargs) -> List[Document]:
"""加载数据并返回Document列表"""
pass
```
资料来源：[llama-index-core/llama_index/core/readers/base.py]()
### 文件读取器
`SimpleDirectoryReader`是文件读取的核心实现，支持从本地目录批量加载文件：
```python
from llama_index.core import SimpleDirectoryReader
# 从目录加载所有支持的文件
reader = SimpleDirectoryReader("./data")
documents = reader.load_data()
# 指定文件扩展名过滤
reader = SimpleDirectoryReader(
"./data",
required_exts=[".pdf", ".docx"]
)
documents = reader.load_data()
# 递归加载子目录
reader = SimpleDirectoryReader(
"./data",
recursive=True
)
documents = reader.load_data()
```
资料来源：[llama-index-core/llama_index/core/readers/file/base.py]()
#### SimpleDirectoryReader 参数说明
| 参数 | 类型 | 说明 |
|------|------|------|
| `input_dir` | str | 输入目录路径 |
| `input_files` | List[Path] | 指定要加载的文件列表 |
| `recursive` | bool | 是否递归扫描子目录，默认False |
| `required_exts` | List[str] | 只加载指定扩展名的文件 |
| `exclude` | List[str] | 排除的文件名模式 |
| `filename_as_id` | bool | 使用文件名作为Document ID |
### Web读取器
LlamaIndex提供多种网页内容提取器：
| 读取器 | 说明 | 安装包 |
|--------|------|--------|
| `TrafilaturaWebReader` | 使用trafilatura提取静态网页文本 | llama-index-readers-web |
| `UnstructuredURLLoader` | 使用Unstructured.io解析HTML | llama-index-readers-web |
| `NewsArticleReader` | 解析新闻文章（基于newspaper3k） | llama-index-readers-web |
| `MainContentExtractorReader` | 提取网页主体内容 | llama-index-readers-web |
| `ReadabilityWebPageReader` | 使用Readability算法提取正文 | llama-index-readers-web |
```python
from llama_index.readers.web import TrafilaturaWebReader
loader = TrafilaturaWebReader()
documents = loader.load_data(urls=["https://example.com/article"])
```
### 远程深度读取器
`RemoteDepthReader`支持递归抓取指定深度的链接：
```python
from llama_index.readers.remote_depth import RemoteDepthReader
loader = RemoteDepthReader()
# depth=2表示提取页面链接 + 链接指向页面的链接
documents = loader.load_data(
url="https://example.com/",
depth=2
)
```
### 文档解析读取器
| 读取器 | 支持格式 | 安装包 |
|--------|----------|--------|
| `DoclingReader` | PDF, DOCX, HTML, JSON | llama-index-readers-docling |
| `WikipediaReader` | Wikipedia页面 | llama-index-readers-wikipedia |
| `WordpressReader` | WordPress博客 | llama-index-readers-wordpress |
| `BagelReader` | Bagel向量数据库 | llama-index-readers-bagel |
## 数据转换（Transformations）
转换器是数据摄取流程中的关键环节，用于对Document进行分块、向量化等处理。
### 转换器类型
| 转换器 | 功能 | 源码位置 |
|--------|------|----------|
| `SentenceSplitter` | 按句子/字符数分块 | transformations.py |
| `TokenTextSplitter` | 按Token数分块 | transformations.py |
| `RecursiveCharacterTextSplitter` | 递归字符分块 | transformations.py |
### 核心转换器详解
#### SentenceSplitter
按句子边界进行文本分块：
```python
from llama_index.core.ingestion.transformations import SentenceSplitter
splitter = SentenceSplitter(
chunk_size=1024, # 块大小（字符数）
chunk_overlap=20, # 块间重叠字符数
separator=" " # 分隔符
)
chunked_docs = splitter(documents)
```
#### TokenTextSplitter
基于Token数量进行智能分块：
```python
from llama_index.core.ingestion.transformations import TokenTextSplitter
splitter = TokenTextSplitter(
chunk_size=512, # 块大小（Token数）
chunk_overlap=50, # 块间重叠Token数
separator=["\n\n", "\n", " "] # 分隔优先级
)
chunked_docs = splitter(documents)
```
### 转换器参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `chunk_size` | int | 1024 | 单个块的目标大小 |
| `chunk_overlap` | int | 200 | 块间重叠大小 |
| `separator` | str/List[str] | "\n\n" | 分隔符 |
| `backup_separators` | List[str] | None | 备用分隔符列表 |
## 摄取管道（IngestionPipeline）
`IngestionPipeline`是数据摄取流程的核心编排器，协调读取器、转换器和存储后端的工作。
### 基本用法
```python
from llama_index.core.ingestion import IngestionPipeline
from llama_index.core.ingestion.transformations import SentenceSplitter
from llama_index.core import VectorStoreIndex
# 创建管道，指定转换器
pipeline = IngestionPipeline(
transformations=[
SentenceSplitter(chunk_size=1024, chunk_overlap=20)
]
)
# 对文档执行管道
processed_docs = pipeline.run(documents=raw_documents)
# 创建索引
index = VectorStoreIndex.from_documents(processed_docs)
```
### 完整摄取流程图
```mermaid
graph LR
A[原始文档] --> B[管道处理]
B --> C{是否配置存储?}
C -->|是| D[存储到向量数据库]
C -->|否| E[返回Document列表]
D --> F[构建索引]
style B fill:#e1f5fe
style D fill:#fff3e0
```
### 管道缓存
IngestionPipeline支持缓存机制以提升重复执行效率：
```python
from llama_index.core.ingestion import IngestionPipeline
from llama_index.core.storage.docstore import SimpleDocumentStore
pipeline = IngestionPipeline(
transformations=[...],
docstore=SimpleDocumentStore() # 启用文档缓存
)
# 首次运行会处理所有文档
docs1 = pipeline.run(documents=documents)
# 再次运行时，已缓存的文档会被跳过
docs2 = pipeline.run(documents=documents)
```
## 数据摄取完整流程
```mermaid
flowchart TD
subgraph 数据源
A1[本地文件]
A2[网页内容]
A3[数据库]
A4[API接口]
end
subgraph 读取层
B1[FileReader]
B2[WebReader]
B3[APILoader]
end
subgraph 转换层
C1[文本分块]
C2[元数据提取]
C3[向量化]
end
subgraph 输出层
D1[Document对象]
D2[向量索引]
D3[知识图谱]
end
A1 --> B1
A2 --> B2
A3 --> B3
A4 --> B3
B1 --> C1
B2 --> C1
B3 --> C1
C1 --> C2
C2 --> C3
C3 --> D1
C3 --> D2
C3 --> D3
```
## 使用示例
### 完整文件摄取示例
```python
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex
from llama_index.core.ingestion import IngestionPipeline
from llama_index.core.ingestion.transformations import SentenceSplitter
# 1. 加载文档
reader = SimpleDirectoryReader("./data", recursive=True)
documents = reader.load_data()
# 2. 创建摄取管道
pipeline = IngestionPipeline(
transformations=[
SentenceSplitter(chunk_size=1024, chunk_overlap=128)
]
)
# 3. 处理文档
processed_docs = pipeline.run(documents=documents)
# 4. 构建索引
index = VectorStoreIndex.from_documents(processed_docs)
# 5. 查询
query_engine = index.as_query_engine()
response = query_engine.query("相关问题")
```
### 带向量化嵌入的摄取
```python
from llama_index.core.ingestion import IngestionPipeline
from llama_index.core.ingestion.transformations import SentenceSplitter
from llama_index.embeddings.ollama import OllamaEmbedding
# 配置嵌入模型
embed_model = OllamaEmbedding(
model_name="nomic-embed-text",
base_url="http://localhost:11434"
)
# 创建包含嵌入的管道
pipeline = IngestionPipeline(
transformations=[
SentenceSplitter(chunk_size=512),
embed_model # 添加嵌入转换
]
)
docs = pipeline.run(documents=raw_docs)
```
## 最佳实践
### 1. 合理设置分块大小
| 使用场景 | 推荐chunk_size | 说明 |
|----------|----------------|------|
| 问答系统 | 512-1024 | 适合精确答案检索 |
| 摘要生成 | 2048-4096 | 需要更多上下文 |
| 语义搜索 | 256-512 | 更细粒度的匹配 |
### 2. 块重叠设置
```python
# 较大重叠适用于：
# - 跨块边界的问答
# - 需要保留上下文连贯性
# - 文档结构不规则
splitter = SentenceSplitter(
chunk_size=1024,
chunk_overlap=256 # 25%重叠
)
```
### 3. 选择合适的读取器
| 数据源 | 推荐读取器 | 理由 |
|--------|-----------|------|
| 本地文件（多格式） | SimpleDirectoryReader | 统一接口，支持多种格式 |
| 新闻文章 | NewsArticleReader | 专门优化新闻格式 |
| 静态网站 | TrafilaturaWebReader | 高质量文本提取 |
| PDF文档 | DoclingReader | 保留布局和结构 |
## 相关资源
- [IngestionPipeline官方文档](https://docs.llamaindex.ai/en/stable/api_reference/ingestion/)
- [Reader集成列表](https://llamahub.ai/)
- [Ollama嵌入模型配置](./llama-index-integrations/embeddings/llama-index-embeddings-ollama/README.md)
---
## 节点解析器
### 相关页面
相关主题：[数据摄取流程](#data_ingestion), [核心组件详解](#core_components)
相关源码文件
以下源码文件用于生成本页说明：
- [llama-index-core/llama_index/core/node_parser/text/sentence.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/text/sentence.py)
- [llama-index-core/llama_index/core/node_parser/text/semantic_splitter.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/text/semantic_splitter.py)
- [llama-index-core/llama_index/core/node_parser/relational/markdown_element.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/relational/markdown_element.py)
- [llama-index-core/llama_index/core/node_parser/interface.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/interface.py)
- [llama-index-core/llama_index/core/node_parser/__init__.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/node_parser/__init__.py)
# 节点解析器
## 概述
节点解析器（Node Parser）是 LlamaIndex 框架中负责将文档（Document）拆分为结构化节点（Node）序列的核心组件。在检索增强生成（RAG）工作流中，节点解析器扮演着至关重要的角色，它决定了如何将原始文本分割成适合检索和上下文处理的最小单元。
节点解析器的主要职责包括：
- **文本分割**：将长文档按照指定规则拆分为较小的文本块
- **结构保留**：在分割过程中维护文档的层次结构和语义完整性
- **元数据提取**：为每个节点附加相关的上下文信息和元数据
- **关系建立**：建立节点之间的关系，支持后续的图结构查询
资料来源：[interface.py:1-50]()
## 核心接口
### NodeParser 基类
所有节点解析器都继承自 `NodeParser` 接口，该接口定义了节点解析的核心抽象方法。
```mermaid
classDiagram
class NodeParser {
<>
+get_nodes() List[Node]
+get_nodes_from_documents() List[Node]
}
class BaseNodeParser {
<>
+get_nodes() List[Node]
+get_nodes_from_documents() List[Node]
}
class SentenceSplitter {
+sentence_separator: str
+chunk_size: int
+chunk_overlap: int
}
class SemanticSplitter {
+embed_model: BaseEmbedding
+buffer_size: int
+embed_batch_size: int
}
class MarkdownElementNodeParser {
+use_json: bool
+merge_many_element: bool
}
NodeParser <|.. BaseNodeParser
BaseNodeParser <|-- SentenceSplitter
BaseNodeParser <|-- SemanticSplitter
BaseNodeParser <|-- MarkdownElementNodeParser
```
### 核心方法
| 方法名 | 参数 | 返回类型 | 说明 |
|--------|------|----------|------|
| `get_nodes` | documents: List[Document] | List[BaseNode] | 将文档列表转换为节点列表 |
| `get_nodes_from_documents` | documents: List[Document], show_progress: bool | List[BaseNode] | 带进度显示的文档转换方法 |
资料来源：[interface.py:50-120]()
## 文本节点解析器
### SentenceSplitter（句子分割器）
`SentenceSplitter` 是最基本的节点解析器，它按照句子边界和字符数限制对文本进行分割。
#### 主要配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `chunk_size` | int | 1024 | 每个文本块的字符数上限 |
| `chunk_overlap` | int | 200 | 相邻文本块之间的重叠字符数 |
| `sentence_separator` | str | "\n\n" | 句子分隔符 |
| `paragraph_separator` | str | "\n\n\n" | 段落分隔符 |
| `secondary_chunking_regex` | Optional[Pattern] | None | 次级分割正则表达式 |
| `coalesce_chunk_size` | Optional[int] | None | 合并后的目标块大小 |
#### 工作原理
```mermaid
flowchart TD
A[输入文档] --> B[按段落分割]
B --> C[计算段落长度]
C --> D{段落长度 > chunk_size?}
D -->|是| E[按句子分割段落]
D -->|否| F[直接添加到当前块]
E --> G{句子长度 > chunk_size?}
G -->|是| H[按次级正则表达式分割]
G -->|否| I[添加到当前块]
H --> J[按chunk_size限制]
I --> K{当前块已满?}
J --> K
F --> K
K -->|是| L[创建新块]
K -->|否| M[继续添加]
L --> N[应用chunk_overlap]
M --> N
N --> O[输出节点列表]
```
资料来源：[sentence.py:1-150]()
### SemanticSplitter（语义分割器）
`SemanticSplitter` 是一种更高级的分割策略，它利用嵌入模型（Embedding Model）来识别语义边界，从而产生更加连贯的文本块。
#### 核心概念
**缓冲区机制**：SemanticSplitter 使用固定大小的缓冲区来聚合相邻句子，然后通过计算相邻缓冲区之间的语义相似度来决定分割点。
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `embed_model` | BaseEmbedding | 必需 | 用于计算语义的嵌入模型 |
| `buffer_size` | int | 1 | 相邻句子缓冲大小 |
| `breakpoint_percent_threshold` | float | 0.5 | 触发分割的差异百分比阈值 |
| `embed_batch_size` | int | 100 | 嵌入计算批量大小 |
#### 分割策略
```mermaid
flowchart LR
A[句子序列] --> B[缓冲区聚合]
B --> C[计算相邻缓冲区嵌入]
C --> D[计算余弦相似度]
D --> E{相似度差异 > 阈值?}
E -->|是| F[插入分割点]
E -->|否| G[继续聚合]
F --> H[生成语义节点]
G --> B
```
语义分割器特别适合处理需要保持语义完整性的场景，例如问答系统、文档摘要等应用。
资料来源：[semantic_splitter.py:1-200]()
## Markdown 元素解析器
### MarkdownElementNodeParser
`MarkdownElementNodeParser` 专门用于解析 Markdown 格式的文档，它能够识别 Markdown 中的各种元素类型并分别处理。
#### 支持的元素类型
| 元素类型 | 说明 | 处理方式 |
|----------|------|----------|
| `TitleElement` | 标题元素 | 作为独立节点或用于分组 |
| `CodeElement` | 代码块 | 保持格式，包含语言标识 |
| `TableElement` | 表格元素 | 解析为结构化数据 |
| `NarrativeTextElement` | 叙述文本 | 标准文本块处理 |
| `QuestionAnswerElement` | 问答对 | 结构化问答提取 |
#### 配置选项
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `use_json` | bool | False | 是否输出 JSON 格式 |
| `include_metadata` | bool | True | 是否包含元数据 |
| `include_prev_next_rel` | bool | True | 是否添加前后关系 |
| `merge_many_element` | bool | True | 是否合并连续同类型元素 |
#### 输出结构
```mermaid
graph TD
A[Markdown文档] --> B[解析标题层级]
A --> C[提取代码块]
A --> D[识别表格]
A --> E[处理段落文本]
B --> F[创建TitleElement节点]
C --> G[创建CodeElement节点]
D --> H[创建TableElement节点]
E --> I[创建NarrativeTextElement节点]
F --> J[建立标题-内容关系]
G --> J
H --> J
I --> J
J --> K[输出节点图结构]
```
当 `use_json=True` 时，解析器会输出符合 Docling 规范的 JSON 格式，需要配合 Docling Node Parser 使用。
资料来源：[markdown_element.py:1-250]()
## 使用指南
### 基本使用示例
#### 简单句子分割
```python
from llama_index.core.node_parser import SentenceSplitter
# 初始化分割器
node_parser = SentenceSplitter(
chunk_size=512,
chunk_overlap=50
)
# 从文档获取节点
nodes = node_parser.get_nodes_from_documents(documents)
```
#### 语义分割
```python
from llama_index.core.node_parser import SemanticSplitter
from llama_index.core.embeddings import OpenAIEmbedding
# 初始化嵌入模型
embed_model = OpenAIEmbedding()
# 创建语义分割器
semantic_splitter = SemanticSplitter(
embed_model=embed_model,
buffer_size=1,
breakpoint_percent_threshold=0.5
)
nodes = semantic_splitter.get_nodes_from_documents(documents)
```
#### Markdown 解析
```python
from llama_index.core.node_parser import MarkdownElementNodeParser
parser = MarkdownElementNodeParser(
use_json=False,
merge_many_element=True
)
nodes = parser.get_nodes_from_documents(markdown_documents)
```
### 高级配置
```python
from llama_index.core.node_parser import SentenceSplitter
# 精细化配置
splitter = SentenceSplitter(
chunk_size=1024,
chunk_overlap=200,
sentence_separator="。", # 中文句号
paragraph_separator="\n\n",
secondary_chunking_regex="[^，,]+[,，]?", # 按逗号次级分割
coalesce_chunk_size=None # 禁用合并
)
```
## 架构设计
### 节点类型层次结构
```mermaid
classDiagram
class BaseNode {
<>
+id_: str
+embedding: Optional[List[float]]
+metadata: Dict
+relationships: Dict
}
class TextNode {
+text: str
+start_char_idx: int
+end_char_idx: int
}
class IndexNode {
+index_id: str
+node_id: str
}
class DocumentRelationship {
+SOURCE, PREVIOUS, NEXT, PARENT, CHILD
}
BaseNode <|-- TextNode
BaseNode <|-- IndexNode
```
### 数据流
```mermaid
flowchart TD
subgraph 输入层
A1[Document对象]
A2[文本内容]
A3[元数据字典]
end
subgraph 解析层
B1[节点解析器选择]
B2[文本分割逻辑]
B3[边界检测]
end
subgraph 处理层
C1[节点创建]
C2[关系建立]
C3[元数据附加]
end
subgraph 输出层
D1[BaseNode列表]
D2[节点关系图]
end
A1 --> B1
A2 --> B2
A3 --> B3
B1 --> C1
B2 --> C2
B3 --> C3
C1 --> D1
C2 --> D2
```
## 最佳实践
### 分割策略选择指南
| 应用场景 | 推荐解析器 | 理由 |
|----------|-----------|------|
| 通用文档处理 | SentenceSplitter | 简单高效，开销小 |
| 语义连贯性要求高 | SemanticSplitter | 保持语义完整性 |
| Markdown 文档 | MarkdownElementNodeParser | 保留文档结构 |
| 代码文档 | MarkdownElementNodeParser | 保护代码块 |
| 结构化数据 | MarkdownElementNodeParser | 解析表格和列表 |
### 参数调优建议
**chunk_size 设置**：
- 小块（256-512）：适合精确检索，高细粒度
- 中块（512-1024）：平衡检索精度和上下文完整性
- 大块（1024-2048）：适合需要完整语境的查询
**chunk_overlap 设置**：
- 通常设置为 chunk_size 的 10%-20%
- 过高会增加冗余和处理时间
- 适用于边界信息重要的场景
## 相关模块
节点解析器与其他 LlamaIndex 核心组件协同工作：
- **Document**：原始文档输入
- **VectorStoreIndex**：节点用于向量索引构建
- **BaseEmbedding**：语义分割依赖的嵌入模型
- **Retriever**：基于节点进行信息检索
## 总结
节点解析器是 LlamaIndex 数据处理管道中的关键环节，它通过多种策略将非结构化文档转换为结构化的节点序列。框架提供了从简单到复杂的多种解析器实现，开发者可以根据具体需求选择合适的工具。正确配置节点解析器对于构建高效的 RAG 系统至关重要。
资料来源：[__init__.py:1-50]()
---
## 存储层架构
### 相关页面
相关主题：[数据摄取流程](#data_ingestion), [核心组件详解](#core_components)
相关源码文件
以下源码文件用于生成本页说明：
- [llama-index-core/llama_index/core/storage/storage_context.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/storage_context.py)
- [llama-index-core/llama_index/core/vector_stores/types.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/vector_stores/types.py)
- [llama-index-core/llama_index/core/storage/docstore/types.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/docstore/types.py)
- [llama-index-core/llama_index/core/storage/chat_store/base.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/storage/chat_store/base.py)
# 存储层架构
## 概述
LlamaIndex 的存储层架构是一套完整的数据持久化解决方案，负责管理向量数据、文档数据、聊天记录等核心数据的存储与检索。该架构采用模块化设计，通过抽象接口支持多种存储后端，使开发者能够灵活选择适合自身场景的存储方案。
存储层主要由三个核心组件构成：**VectorStore**（向量存储）、**Docstore**（文档存储）和 **ChatStore**（聊天存储）。这些组件通过统一的 **StorageContext**（存储上下文）进行协调管理，实现了数据访问与存储实现的解耦。
## 核心组件架构
### 组件关系图
```mermaid
graph TD
A[StorageContext] --> B[VectorStore]
A --> C[Docstore]
A --> C1[IndexStore]
A --> D[ChatStore]
A --> E[ImageStore]
B --> B1[SimpleVectorStore]
B --> B2[FaissVectorStore]
B --> B3[MilvusVectorStore]
B --> B4[PineconeVectorStore]
C --> C2[SimpleDocstore]
C --> C3[MongoDocstore]
C --> C4[DynamoDBDocstore]
D --> D1[SimpleChatStore]
D --> D2[RedisChatStore]
```
### 存储上下文（StorageContext）
StorageContext 是 LlamaIndex 存储层的中央协调器，负责初始化和管理所有存储组件的实例。它提供了统一的接口来访问向量存储、文档存储、索引存储和聊天存储。
**主要属性：**
| 属性 | 类型 | 说明 |
|------|------|------|
| `vector_store` | VectorStore | 向量存储实例 |
| `docstore` | BaseDocstore | 文档存储实例 |
| `index_store` | IndexStore | 索引存储实例 |
| `chat_store` | ChatStore | 聊天存储实例 |
| `image_store` | ImageStore | 图片存储实例 |
**持久化方法：**
```python
# 持久化到磁盘
index.storage_context.persist(persist_dir="./storage")
# 从磁盘加载
storage_context = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage_context)
```
资料来源：[llama-index-core/llama_index/core/storage/storage_context.py]()
## 向量存储层（VectorStore）
### 向量存储类型定义
向量存储层负责存储和检索高维向量嵌入，是 RAG（检索增强生成）系统的核心组件。
```mermaid
classDiagram
class VectorStore {
<>
+add() List[str]
+delete() None
+query() List[Node]
+get_nodes() List[BaseNode]
+get_metadata_dict() Dict
+delete_ref_doc() None
+persist() None
}
class BasePydanticVectorStore {
<>
+client: Any
}
class VectorStoreQuery {
<>
+query_embedding: Optional[List[float]]
+similarity_top_k: int
+mode: VectorStoreQueryMode
+filters: Optional[MetadataFilters]
}
VectorStore <|-- BasePydanticVectorStore
```
### 查询模式
| 模式 | 说明 |
|------|------|
| `DEFAULT` | 默认相似度搜索 |
| `MMR` | 最大边际相关性（Maximal Marginal Relevance） |
| `HYBRID` | 混合搜索（向量+关键词） |
### 查询参数结构
```python
@dataclass
class VectorStoreQuery:
query_embedding: Optional[List[float]] = None
query_str: Optional[str] = None
similarity_top_k: int = 4
docs: Optional[List[Document]] = None
alpha: float = 0.5 # 用于混合搜索的权重
nn: Optional[NearestNeighborsAlgo] = None
mode: VectorStoreQueryMode = VectorStoreQueryMode.DEFAULT
filters: Optional[MetadataFilters] = None
MMR: bool = False
mmr_threshold: Optional[float] = None
```
资料来源：[llama-index-core/llama_index/core/vector_stores/types.py]()
## 文档存储层（Docstore）
### 文档存储接口
文档存储层负责存储原始文档及其元数据，为索引构建和检索提供文档基础。
```mermaid
graph LR
A[Document] --> B[BaseDocstore]
B --> C1[SimpleDocstore]
B --> C2[MongoDocstore]
B --> C3[DynamoDBDocstore]
B --> C4[ElasticsearchDocstore]
```
### 文档存储类型
| 类型 | 后端 | 适用场景 |
|------|------|----------|
| SimpleDocstore | 内存/本地文件 | 开发测试、小规模数据 |
| MongoDocstore | MongoDB | 分布式部署、大规模数据 |
| DynamoDBDocstore | AWS DynamoDB | 云原生应用、高可用需求 |
| ElasticsearchDocstore | Elasticsearch | 全文搜索场景 |
### 文档数据结构
```python
@dataclass
class Document:
id_: str
embedding: Optional[List[float]] = None
metadata: Dict[str, Any] = field(default_factory=dict)
excluded_embed_metadata_keys: List[str] = field(default_factory=list)
excluded_llm_metadata_keys: List[str] = field(default_factory=list)
relationships: Dict[DocumentRelationship, List[str]] = field(default_factory=dict)
hash: Optional[str] = None
text: str = ""
start_char_idx: Optional[int] = None
end_char_idx: Optional[int] = None
text_template: str = "{metadata_str}\n\n{content}"
metadata_template: str = "{key}: {value}"
metadata_separator: str = "\n"
```
资料来源：[llama-index-core/llama_index/core/storage/docstore/types.py]()
## 聊天存储层（ChatStore）
### 聊天存储架构
聊天存储层用于持久化管理对话历史，支持多轮对话场景和上下文管理。
```mermaid
graph TD
A[ChatMessage] --> B[BaseChatStore]
B --> C1[SimpleChatStore]
B --> C2[RedisChatStore]
B --> C3[MongoChatStore]
D[ChatStoreConfig] --> B
E[ChatSession] --> D
```
### 聊天消息类型
| 类型 | 说明 |
|------|------|
| `ChatMessageRole.AI` | AI 助手消息 |
| `ChatMessageRole.USER` | 用户消息 |
| `ChatMessageRole.SYSTEM` | 系统消息 |
| `ChatMessageRole.TOOL` | 工具消息 |
### 聊天存储接口
```python
class BaseChatStore(ABC):
@abstractmethod
def add_message(self, key: str, message: ChatMessage) -> None:
pass
@abstractmethod
def get_messages(self, key: str) -> List[ChatMessage]:
pass
@abstractmethod
def delete_messages(self, key: str) -> None:
pass
@abstractmethod
def delete_message(self, key: str, idx: int) -> None:
pass
@abstractmethod
def delete_all_messages(self, key: str) -> None:
pass
@abstractmethod
def get_latest_message(self, key: str) -> Optional[ChatMessage]:
pass
@abstractmethod
def as_langchain_chat_history(self, **kwargs: Any) -> BaseChatMessageHistory:
pass
```
资料来源：[llama-index-core/llama_index/core/storage/chat_store/base.py]()
## 数据流与工作流程
### 索引构建流程
```mermaid
graph TD
A[加载文档] --> B[文本分块]
B --> C[生成嵌入向量]
C --> D[存储到Docstore]
C --> E[存储到VectorStore]
D --> F[构建索引结构]
E --> F
F --> G[持久化存储]
```
### 检索查询流程
```mermaid
graph TD
A[用户查询] --> B[查询向量化]
B --> C[向量相似度搜索]
C --> D{混合搜索?}
D -->|是| E[关键词搜索]
D -->|否| F[获取Top-K结果]
E --> F
F --> G[结果重排序]
G --> H[返回上下文]
```
## 存储配置选项
### StorageContext 构造参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `vector_store` | VectorStore | SimpleVectorStore | 向量存储实例 |
| `docstore` | BaseDocstore | SimpleDocumentStore | 文档存储实例 |
| `index_store` | IndexStore | SimpleIndexStore | 索引存储实例 |
| `chat_store` | ChatStore | None | 聊天存储实例 |
| `persist_dir` | str | None | 持久化目录路径 |
| `graph_store` | GraphStore | None | 知识图谱存储 |
### 持久化配置
```python
# 完整配置示例
storage_context = StorageContext.from_defaults(
vector_store=vector_store,
docstore=docstore,
index_store=index_store,
persist_dir="./storage"
)
# 手动持久化
storage_context.persist(persist_dir="./storage")
# 从持久化目录加载
storage_context = StorageContext.from_defaults(
persist_dir="./storage"
)
```
## 存储后端兼容性
### 向量存储后端矩阵
| 后端 | 支持元数据过滤 | 支持混合搜索 | 支持删除 | 支持更新 |
|------|---------------|-------------|---------|---------|
| SimpleVectorStore | ✅ | ❌ | ✅ | ❌ |
| Faiss | ✅ | ❌ | ❌ | ❌ |
| Pinecone | ✅ | ✅ | ✅ | ✅ |
| Weaviate | ✅ | ✅ | ✅ | ✅ |
| Milvus | ✅ | ✅ | ✅ | ✅ |
| Chroma | ✅ | ❌ | ✅ | ❌ |
## 最佳实践
### 生产环境存储配置
1. **向量存储选择**：对于大规模向量检索场景，推荐使用专门的向量数据库如 Milvus、Pinecone 或 Weaviate
2. **文档存储选择**：需要支持事务和分布式部署时，选择 MongoDB 或 DynamoDB
3. **数据持久化**：生产环境务必配置持久化，定期备份存储目录
### 性能优化建议
| 场景 | 优化策略 |
|------|----------|
| 大规模向量检索 | 使用支持索引的向量数据库，调整 `similarity_top_k` 参数 |
| 高频写入 | 批量写入，使用异步持久化 |
| 内存限制 | 使用磁盘持久化的存储后端，及时释放缓存 |
| 多模态数据 | 分离图片存储和文本存储，独立管理 |
## 总结
LlamaIndex 的存储层架构通过抽象化的接口设计，实现了存储逻辑与业务逻辑的解耦。开发者可以根据实际需求选择合适的存储后端，无需修改上层代码即可切换存储方案。StorageContext 作为统一的入口，提供了简洁的配置接口和持久化机制，确保了数据的安全性和可移植性。
---
## 智能体系统
### 相关页面
相关主题：[工作流引擎](#workflow_engine), [查询引擎](#query_engine)
相关源码文件
以下源码文件用于生成本页说明：
- [llama-index-core/llama_index/core/agent/react/formatter.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/agent/react/formatter.py)
- [llama-index-core/llama_index/core/agent/workflow/base_agent.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/agent/workflow/base_agent.py)
- [llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py)
- [llama-index-core/llama_index/core/tools/function_tool.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/tools/function_tool.py)
# 智能体系统
## 概述
LlamaIndex 的智能体系统（Agent System）是一个用于构建、编排和管理基于大型语言模型（LLM）的智能体的核心框架。该系统提供了灵活的架构，支持单智能体和多智能体工作流，使开发者能够创建能够执行复杂任务、调用外部工具、处理多轮对话的 AI 应用。
智能体系统的核心设计理念是将 LLM 与外部工具、数据源和执行环境解耦，通过标准化的接口实现智能体的感知、推理和行动能力。
## 核心架构
### 系统组件关系图
```mermaid
graph TD
User[用户] --> Agent[智能体]
Agent --> Tool[工具集]
Agent --> LLM[大语言模型]
Agent --> Memory[记忆模块]
Tool --> ExternalAPI[外部 API]
Tool --> Function[函数调用]
Tool --> DataSource[数据源]
Memory --> Context[上下文存储]
```
### 核心模块
| 模块名称 | 功能描述 | 主要类 |
|---------|---------|--------|
| Agent Core | 智能体核心引擎 | `BaseAgent`, `ReActAgent` |
| Workflow | 工作流编排 | `MultiAgentWorkflow` |
| Tools | 工具管理 | `FunctionTool`, `QueryTool` |
| Memory | 记忆管理 | `ChatMemory`, `ContextMemory` |
| Formatter | 输出格式化 | `ReActFormatter` |
## ReAct 智能体
### 工作原理
ReAct（Reasoning + Acting）智能体是 LlamaIndex 实现的核心智能体类型之一，它通过交替执行推理（Reasoning）和行动（Acting）步骤来解决问题。
```mermaid
graph LR
A[用户输入] --> B[LLM 推理]
B --> C[生成行动]
C --> D[执行工具]
D --> E[观察结果]
E --> B
B --> F{是否完成}
F -->|是| G[返回结果]
F -->|否| B
```
### ReActFormatter
`ReActFormatter` 负责为 ReAct 智能体生成格式化的提示词模板，它定义了智能体在推理过程中的思考框架和行动规范。
主要功能包括：
- 生成系统提示词模板
- 定义思考（Thought）、行动（Action）、观察（Observation）的格式规范
- 管理工具调用的上下文信息
**文件位置：** `llama-index-core/llama_index/core/agent/react/formatter.py`
## 工作流系统
### BaseAgent 基础类
`BaseAgent` 是所有智能体的基类，定义了智能体的核心接口和行为规范。
| 方法 | 功能描述 |
|-----|---------|
| `chat()` | 处理单轮对话 |
| `chat_with_sources()` | 返回带来源的对话结果 |
| `reset()` | 重置智能体状态 |
| `stream_chat()` | 流式对话处理 |
### 多智能体工作流
`MultiAgentWorkflow` 实现了多智能体协作框架，允许定义多个专业化的智能体并协调它们之间的交互。
```mermaid
graph TD
A[用户请求] --> B[调度器]
B --> C{任务类型}
C -->|数据分析| D[数据智能体]
C -->|文档处理| E[文档智能体]
C -->|信息检索| F[检索智能体]
D --> G[结果聚合]
E --> G
F --> G
G --> H[最终响应]
```
**文件位置：** `llama-index-core/llama_index/core/agent/workflow/multi_agent_workflow.py`
## 工具系统
### FunctionTool
`FunctionTool` 是 LlamaIndex 中用于封装可调用函数的工具类，它将 Python 函数转换为智能体可以调用的工具。
```python
from llama_index.core.tools import FunctionTool
# 定义一个函数
def search_database(query: str) -> str:
"""在数据库中搜索相关信息"""
# 实现搜索逻辑
return f"找到关于 {query} 的结果"
# 转换为工具
search_tool = FunctionTool.from_defaults(
fn=search_database,
name="database_search",
description="用于搜索数据库中的信息"
)
```
### 工具特性
| 特性 | 说明 |
|-----|-----|
| 函数包装 | 将 Python 函数转换为可被智能体调用的工具 |
| 元数据管理 | 支持 name、description 等元数据定义 |
| 参数验证 | 自动验证输入参数类型和格式 |
| 结果序列化 | 处理函数返回值以供 LLM 理解 |
**文件位置：** `llama-index-core/llama_index/core/tools/function_tool.py`
## 智能体执行流程
```mermaid
sequenceDiagram
participant U as 用户
participant A as 智能体
participant L as LLM
participant T as 工具
participant M as 记忆
U->>A: 发送请求
A->>M: 获取上下文
A->>L: 生成推理
L-->>A: 返回思考结果
A->>T: 调用工具
T-->>A: 返回观察结果
A->>L: 基于观察继续推理
L-->>A: 返回最终决策
A->>M: 更新记忆
A-->>U: 返回响应
```
## 使用示例
### 创建基础智能体
```python
from llama_index.core.agent import ReActAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI
# 初始化 LLM
llm = OpenAI(model="gpt-4")
# 创建工具
def get_weather(location: str) -> str:
"""获取指定位置的天气信息"""
return f"{location} 今天是晴天，25°C"
weather_tool = FunctionTool.from_defaults(
fn=get_weather,
name="get_weather",
description="获取特定位置的天气信息"
)
# 创建智能体
agent = ReActAgent.from_tools(
tools=[weather_tool],
llm=llm,
verbose=True
)
# 对话
response = agent.chat("北京的天气怎么样？")
print(response)
```
### 多智能体协作
```python
from llama_index.core.agent.workflow import MultiAgentWorkflow
# 创建多个专业智能体
research_agent = ReActAgent.from_tools(...)
analysis_agent = ReActAgent.from_tools(...)
# 创建工作流
workflow = MultiAgentWorkflow(agents=[
research_agent,
analysis_agent
])
# 执行工作流
result = workflow.run(task="分析市场趋势")
```
## 配置选项
### 智能体配置参数
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|-----|
| `max_iterations` | int | 10 | 最大迭代次数 |
| `timeout` | float | 60.0 | 单次工具调用超时时间（秒） |
| `verbose` | bool | False | 是否输出详细日志 |
| `tool_choice` | str | "auto" | 工具选择策略 |
### 工具配置参数
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|-----|
| `name` | str | 必填 | 工具名称 |
| `description` | str | 必填 | 工具描述（LLM 使用） |
| `fn_schema` | BaseModel | None | 函数参数模式 |
| `return_direct` | bool | False | 是否直接返回结果 |
## 最佳实践
### 1. 工具设计原则
- 为每个工具提供清晰、具体的描述
- 使用类型提示定义参数模式
- 保持工具职责单一性
- 处理异常情况并返回有意义的错误信息
### 2. 智能体配置建议
- 根据任务复杂度调整 `max_iterations`
- 设置合理的超时时间
- 使用 `verbose=True` 进行调试
- 合理管理智能体的记忆和上下文
### 3. 性能优化
- 批量处理独立的工具调用
- 使用缓存减少重复计算
- 限制上下文长度以控制成本
- 选择合适的 LLM 模型
## 扩展开发
### 自定义智能体类型
```python
from llama_index.core.agent import BaseAgent
class CustomAgent(BaseAgent):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
def chat(self, message: str) -> Response:
# 实现自定义对话逻辑
pass
def reset(self) -> None:
# 实现重置逻辑
pass
```
### 自定义工具类型
```python
from llama_index.core.tools import BaseTool
class CustomTool(BaseTool):
@property
def name(self) -> str:
return "custom_tool"
@property
def description(self) -> str:
return "自定义工具描述"
def _call(self, *args, **kwargs) -> str:
# 实现工具逻辑
pass
```
## 相关资源
- 官方文档：[LlamaIndex Agent Documentation](https://docs.llamaindex.ai/en/stable/module_guides/agents/)
- 示例代码：[Agent Examples](https://github.com/run-llama/llama_index/tree/main/docs/examples/agent)
- 源码仓库：[llama-index-core/agent](https://github.com/run-llama/llama_index/tree/main/llama-index-core/llama_index/core/agent)
---
## 工作流引擎
### 相关页面
相关主题：[智能体系统](#agent_system), [查询引擎](#query_engine)
相关源码文件
以下源码文件用于生成本页说明：
- [llama-index-core/llama_index/core/workflow/workflow.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/workflow.py)
- [llama-index-core/llama_index/core/workflow/context.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/context.py)
- [llama-index-core/llama_index/core/workflow/events.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/events.py)
- [llama-index-core/llama_index/core/workflow/handler.py](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/workflow/handler.py)
# 工作流引擎
## 概述
LlamaIndex 工作流引擎（Workflow Engine）是一个基于事件驱动架构的异步任务编排框架，专为构建复杂的大型语言模型（LLM）应用而设计。该引擎允许开发者通过声明式的方式定义工作流步骤（Step），并通过事件的发布与订阅机制来实现步骤之间的通信与协作。
工作流引擎的核心价值在于解耦应用逻辑，使开发者能够将复杂的 LLM 任务分解为独立的、可复用的步骤，同时保持对这些步骤执行顺序和依赖关系的精确控制。
## 核心架构
### 组件关系图
```mermaid
graph TD
A[Workflow 工作流] --> B[Context 上下文]
A --> C[Event 事件]
A --> D[Step 步骤]
C --> E[StartEvent 启动事件]
C --> F[StopEvent 停止事件]
C --> G[CustomEvent 自定义事件]
D --> H[StartDecorator 启动装饰器]
D --> I[StepDecorator 步骤装饰器]
B --> J[State 状态管理]
J --> K[变量存取]
B --> L[流式数据处理]
L --> M[迭代器支持]
```
### 核心组件
| 组件名称 | 文件位置 | 职责说明 |
|---------|---------|---------|
| Workflow | workflow.py | 工作流容器，管理所有步骤和事件路由 |
| Context | context.py | 提供步骤间的状态共享和数据传递能力 |
| Event | events.py | 定义事件基类及内置事件类型 |
| WorkflowHandler | handler.py |管理工作流执行，处理异步任务调度 |
## 事件系统
事件系统是工作流引擎的通信基础，采用发布-订阅模式实现步骤间的松耦合交互。
### 内置事件类型
事件系统定义在 `events.py` 文件中，提供了基础的事件抽象类和预定义事件类型。
```mermaid
graph LR
A[事件发布] --> B[EventBus 事件总线]
B --> C[Step 步骤处理]
C --> D[新事件发布]
D --> B
```
### 事件类型表
| 事件类型 | 说明 | 使用场景 |
|---------|------|---------|
| StartEvent | 工作流启动时触发的事件 | 初始化工作流、传递启动参数 |
| StopEvent | 工作流停止时触发的事件 | 清理资源、返回最终结果 |
| CustomEvent | 自定义事件类型 | 步骤间自定义通信 |
事件类采用 Pydantic 模型定义，确保类型安全和序列化能力：
```python
class Event(BaseModel):
"""基础事件类"""
pass
class StartEvent(Event):
"""工作流启动事件"""
pass
class StopEvent(Event):
"""工作流停止事件"""
pass
class CustomEvent(Event):
"""自定义事件"""
name: str
msg: str = ""
```
资料来源：[llama-index-core/llama_index/core/workflow/events.py:1-50]()
## 工作流上下文
上下文（Context）对象在整个工作流执行期间维护状态信息，并提供步骤间数据共享的机制。
### 上下文核心功能
上下文对象提供以下核心能力：
| 功能 | 说明 |
|-----|------|
| 状态存储 | 存储和检索工作流执行过程中的数据 |
| 事件发布 | 允许步骤发布新事件触发后续处理 |
| 流式处理 | 支持异步迭代器处理流式数据 |
### 上下文 API
```python
class Context:
"""工作流上下文基类"""
async def get(self, key: str, default: Any = None) -> Any:
"""获取上下文变量"""
pass
async def set(self, key: str, value: Any) -> None:
"""设置上下文变量"""
pass
async def publish_event(self, event: Event) -> None:
"""发布事件"""
pass
async def stream_output(
self,
stream_type: str,
_id: str,
iterator: AsyncIterator
) -> None:
"""流式输出处理"""
pass
```
资料来源：[llama-index-core/llama_index/core/workflow/context.py:1-100]()
### 状态管理流程
```mermaid
sequenceDiagram
participant Step1 as 步骤1
participant Context as 上下文
participant Step2 as 步骤2
Step1->>Context: set("result", data)
Note over Step1,Context: 存储中间结果
Step1->>Context: publish_event(CustomEvent)
Note over Context: 触发后续处理
Step2->>Context: get("result")
Note over Step2: 获取前置步骤结果
```
## 工作流定义
### 步骤装饰器
工作流通过装饰器模式定义步骤，支持灵活的声明式语法。
#### 装饰器类型
| 装饰器 | 说明 | 适用场景 |
|-------|------|---------|
| @start | 标记工作流入口点 | 定义初始步骤 |
| @step | 标记常规处理步骤 | 业务逻辑处理 |
### 工作流类定义
```python
class Workflow(BaseModel, ABC):
"""工作流基类"""
def __init__(
self,
timeout: Optional[float] = None,
disable_validation: bool = False,
**kwargs: Any
):
"""初始化工作流
Args:
timeout: 工作流超时时间（秒）
disable_validation: 是否禁用步骤验证
"""
self.timeout = timeout
self._steps: List[Any] = []
```
资料来源：[llama-index-core/llama_index/core/workflow/workflow.py:1-100]()
### 工作流示例结构
```mermaid
graph TD
A[@start] --> B[初始化步骤]
B --> C[处理步骤1]
C --> D{条件判断}
D -->|条件A| E[处理步骤2A]
D -->|条件B| F[处理步骤2B]
E --> G[聚合步骤]
F --> G
G --> H[@stop]
```
## 工作流处理器
WorkflowHandler 负责管理工作流的实际执行，包括异步调度、错误处理和结果收集。
### 处理器核心职责
| 职责 | 说明 |
|-----|------|
| 任务调度 | 管理步骤的执行顺序和并发 |
| 事件路由 | 将事件分发给对应的步骤处理 |
| 结果收集 | 收集并汇总工作流执行结果 |
| 错误传播 | 处理执行过程中的异常 |
### 处理器执行流程
```mermaid
flowchart TD
A[创建处理器] --> B{超时检查}
B -->|未超时| C[获取待处理事件]
B -->|超时| Z[抛出TimeoutError]
C --> D{存在待处理事件?}
D -->|是| E[执行对应步骤]
D -->|否| F{所有步骤完成?}
E --> G[产生新事件]
G --> C
F -->|是| H[返回结果]
F -->|否| C
```
资料来源：[llama-index-core/llama_index/core/workflow/handler.py:1-100]()
## 异步执行模型
### 异步迭代器支持
工作流引擎原生支持流式数据处理，允许步骤返回异步迭代器：
```python
async def process_stream(self, ctx: Context) -> AsyncIterator[str]:
"""处理流式数据"""
for chunk in data_source:
yield chunk
await ctx.publish_event(StreamChunkEvent(data=chunk))
```
### 流式输出处理
上下文提供专门的流式输出管理机制：
```python
async def stream_output(
self,
stream_type: str,
_id: str,
iterator: AsyncIterator
) -> None:
"""处理步骤产生的流式输出
Args:
stream_type: 流类型标识
_id: 流实例唯一标识
iterator: 异步迭代器对象
"""
pass
```
资料来源：[llama-index-core/llama_index/core/workflow/context.py:50-80]()
## 使用模式
### 基础工作流定义
```python
from llama_index.core.workflow import Workflow, StartEvent, StopEvent, step
class MyWorkflow(Workflow):
@step
async def start(self, ev: StartEvent) -> StopEvent:
# 初始化处理
return StopEvent(result="complete")
```
### 多步骤工作流
```python
class MultiStepWorkflow(Workflow):
@step
async def step_a(self, ev: StartEvent) -> StepBEvent:
result_a = await self.process_a(ev.data)
return StepBEvent(data=result_a)
@step
async def step_b(self, ev: StepBEvent) -> StopEvent:
result = await self.process_b(ev.data)
return StopEvent(result=result)
```
### 事件驱动交互
```python
from llama_index.core.workflow import Event
class DataEvent(Event):
data: Any
class EventDrivenWorkflow(Workflow):
@step
async def producer(self, ctx: Context, ev: StartEvent):
for item in data_items:
await ctx.publish_event(DataEvent(data=item))
@step
async def consumer(self, ctx: Context, ev: DataEvent):
result = await self.process(ev.data)
await ctx.set("results", ctx.get("results", []) + [result])
```
## 配置选项
### 工作流配置参数
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| timeout | float | None | 工作流最大执行时间（秒），None 表示无限制 |
| disable_validation | bool | False | 是否跳过步骤注册验证 |
| **kwargs | Any | - | 其他传递给基类的参数 |
### 事件配置
| 参数 | 类型 | 说明 |
|-----|------|------|
| name | str | 事件名称标识 |
| msg | str | 事件携带的消息内容 |
| data | Any | 事件携带的业务数据 |
## 与 LlamaIndex 生态集成
工作流引擎是 LlamaIndex 核心基础设施的一部分，可与其他组件无缝协作：
| 集成组件 | 集成方式 |
|---------|---------|
| LLM 模块 | 通过 @step 装饰的步骤调用 LLM |
| Reader 模块 | 工作流中使用 Reader 加载外部数据 |
| Agent 模块 | 工作流可包装 Agent 能力 |
| Query Pipeline | 与查询管道进行数据交换 |
## 最佳实践
### 1. 步骤粒度设计
保持步骤职责单一，每个步骤应该只完成一个明确的任务。复杂的业务逻辑应该拆分为多个步骤，而不是在一个步骤中完成所有处理。
### 2. 事件命名规范
使用清晰的事件命名约定，例如 `StepACompleteEvent`、`DataProcessedEvent` 等，便于理解工作流的数据流向。
### 3. 状态管理策略
- 仅在上下文存储必要的共享状态
- 避免在上下文中存储大型对象
- 使用唯一标识符管理多个数据实例
### 4. 错误处理
```python
@step
async def safe_step(self, ctx: Context, ev: InputEvent) -> OutputEvent:
try:
result = await self.unsafe_operation(ev.data)
return OutputEvent(data=result)
except Exception as e:
await ctx.publish_event(ErrorEvent(error=str(e)))
raise
```
### 5. 超时控制
```python
workflow = MyWorkflow(timeout=60.0) # 60秒超时
result = await workflow.run()
```
## 总结
LlamaIndex 工作流引擎提供了一个强大而灵活的异步任务编排框架，通过事件驱动的设计模式使开发者能够构建复杂的 LLM 应用流程。其核心优势包括：
- **声明式定义**：通过装饰器轻松定义工作流步骤
- **事件驱动通信**：松耦合的步骤间交互机制
- **异步执行**：原生支持异步编程模式
- **状态共享**：上下文对象提供可靠的数据传递
- **流式处理**：内置异步迭代器支持
工作流引擎的模块化设计使其能够适应各种复杂度的应用场景，从简单的线性处理到复杂的多分支并发工作流都能得到良好支持。
---
## 查询引擎
### 相关页面
相关主题：[核心组件详解](#core_components)
对不起，我无法完成此请求。
**问题说明：**
您要求基于以下源码文件生成关于"查询引擎"的Wiki页面：
- `llama-index-core/llama_index/core/query_engine/retriever_query_engine.py`
- `llama-index-core/llama_index/core/query_engine/sub_question_query_engine.py`
- `llama-index-core/llama_index/core/query_engine/flare/base.py`
- `llama-index-core/llama_index/core/query_engine/knowledge_graph_query_engine.py`
但当前提供的上下文（START_OF_CONTEXT）中**不包含这些文件**。上下文仅包含以下类型的README文件：
| 类型 | 数量 |
|------|------|
| Readers集成（Web、Wikipedia、Wordpress等） | 15+ |
| Tools集成（Moss、Brightdata、Exa） | 3 |
| 其他集成（Docling、Box、Chroma等） | 若干 |
**缺失的关键内容：**
- 查询引擎的Python实现源码
- 查询引擎的类定义和方法签名
- 查询引擎的内部逻辑和架构
- 配置文件和参数定义
**建议：**
1. 请提供完整的查询引擎源码文件内容
2. 或者调整Wiki页面主题为当前上下文中实际包含的内容（如"数据读取器"或"Web加载器"）
根据您提供的指南，我不能凭空编造源码中没有的行为或实现细节。
---
---
## Doramagic 踩坑日志
项目：run-llama/llama_index
摘要：发现 7 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。
## 1. 能力坑 · 能力证据存在缺口
- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 建议检查：优先补证或在页面明确标记为未验证。
- 防护动作：证据缺口未关闭前，quality gate 必须保持不可发布。
- 证据：evidence.evidence_gaps | github_repo:560704231 | https://github.com/run-llama/llama_index | Sandbox install result is missing.
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:560704231 | https://github.com/run-llama/llama_index | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | last_activity_observed missing
## 4. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:560704231 | https://github.com/run-llama/llama_index | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:560704231 | https://github.com/run-llama/llama_index | release_recency=unknown