核心概念 #
概念总览 #
text
┌─────────────────────────────────────────────────────────────┐
│ LlamaIndex 核心概念 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 数据层 │ │
│ │ Document ──→ Node ──→ Embedding │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 索引层 │ │
│ │ VectorStoreIndex / SummaryIndex / TreeIndex │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 检索层 │ │
│ │ Retriever ──→ Node Postprocessor │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 响应层 │ │
│ │ Response Synthesizer ──→ Query Engine │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Document（文档） #
什么是 Document？ #
Document 是 LlamaIndex 中数据的顶层容器，代表一个完整的文档源。
python
from llama_index.core import Document
doc = Document(
text="这是文档的完整文本内容...",
metadata={
"source": "example.pdf",
"author": "张三",
"date": "2024-01-01",
"category": "技术文档",
},
doc_id="doc_001",
)
Document 属性 #
text
┌─────────────────────────────────────────────────────────────┐
│ Document 结构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Document │
│ ├── text: str 文档的完整文本内容 │
│ ├── metadata: dict 文档的元数据 │
│ │ ├── source 来源文件 │
│ │ ├── author 作者 │
│ │ ├── date 日期 │
│ │ └── ... 其他自定义字段 │
│ ├── doc_id: str 文档唯一标识 │
│ └── relationships: dict 与其他节点的关系 │
│ │
└─────────────────────────────────────────────────────────────┘
创建 Document #
python
from llama_index.core import Document
doc = Document(text="直接创建的文档")
doc = Document(
text="带元数据的文档",
metadata={"source": "manual", "type": "example"},
)
from llama_index.core import SimpleDirectoryReader
documents = SimpleDirectoryReader("./data").load_data()
Document 元数据 #
python
doc = Document(
text="文档内容",
metadata={
"filename": "report.pdf",
"page": 1,
"category": "financial",
"tags": ["report", "2024"],
},
)
print(doc.metadata["filename"])
print(doc.get_metadata_str())
Node（节点） #
什么是 Node？ #
Node 是 Document 的子块，是索引和检索的基本单位。一个 Document 可以被分割成多个 Node。
python
from llama_index.core import TextNode
node = TextNode(
text="这是一个文本节点的内容",
metadata={"source": "example.pdf", "page": 1},
node_id="node_001",
)
Node 类型 #
text
┌─────────────────────────────────────────────────────────────┐
│ Node 类型 │
├─────────────────────────────────────────────────────────────┤
│ │
│ TextNode │
│ ├── 最常用的节点类型 │
│ └── 包含文本内容 │
│ │
│ ImageNode │
│ ├── 图像节点 │
│ └── 包含图像路径或 URL │
│ │
│ IndexNode │
│ ├── 索引节点 │
│ └── 引用其他节点或索引 │
│ │
└─────────────────────────────────────────────────────────────┘
Node 分割 #
python
from llama_index.core import Document
from llama_index.core.node_parser import SentenceSplitter
doc = Document(text="很长的文档内容..." * 100)
splitter = SentenceSplitter(
chunk_size=512,
chunk_overlap=50,
)
nodes = splitter.get_nodes_from_documents([doc])
print(f"分割成 {len(nodes)} 个节点")
for node in nodes:
print(f"节点 ID: {node.node_id}")
print(f"文本长度: {len(node.text)}")
print(f"元数据: {node.metadata}")
Node 解析器 #
python
from llama_index.core.node_parser import (
SentenceSplitter,
TokenTextSplitter,
MarkdownNodeParser,
CodeSplitter,
)
splitter = SentenceSplitter(
chunk_size=1024,
chunk_overlap=100,
)
token_splitter = TokenTextSplitter(
chunk_size=512,
chunk_overlap=50,
)
md_parser = MarkdownNodeParser()
code_splitter = CodeSplitter(
language="python",
chunk_lines=40,
chunk_lines_overlap=15,
)
Node 关系 #
python
from llama_index.core import Document
from llama_index.core.node_parser import SentenceSplitter
doc = Document(text="第一句。第二句。第三句。第四句。")
nodes = SentenceSplitter().get_nodes_from_documents([doc])
for node in nodes:
print(f"节点: {node.node_id[:8]}...")
if node.prev_node:
print(f" 前节点: {node.prev_node.node_id[:8]}...")
if node.next_node:
print(f" 后节点: {node.next_node.node_id[:8]}...")
print(f" 父文档: {node.ref_doc_id[:8] if node.ref_doc_id else 'None'}")
Index（索引） #
什么是 Index？ #
Index 是组织和检索数据的结构，它将 Node 以特定方式组织起来，支持高效查询。
text
┌─────────────────────────────────────────────────────────────┐
│ 索引类型 │
├─────────────────────────────────────────────────────────────┤
│ │
│ VectorStoreIndex（向量索引） │
│ ├── 最常用的索引类型 │
│ ├── 基于 Embedding 相似度检索 │
│ ├── 适合语义搜索和问答 │
│ └── 需要 Embedding 模型 │
│ │
│ SummaryIndex（摘要索引） │
│ ├── 遍历所有节点 │
│ ├── 适合文档总结 │
│ └── 不需要 Embedding │
│ │
│ TreeIndex（树索引） │
│ ├── 层级结构 │
│ ├── 从根到叶查询 │
│ └── 适合大型文档集 │
│ │
│ KeywordTableIndex（关键词索引） │
│ ├── 提取关键词 │
│ ├── 精确匹配 │
│ └── 适合关键词搜索 │
│ │
└─────────────────────────────────────────────────────────────┘
VectorStoreIndex #
python
from llama_index.core import VectorStoreIndex, Document
documents = [Document(text="文档内容...")]
index = VectorStoreIndex.from_documents(documents)
index = VectorStoreIndex(nodes)
query_engine = index.as_query_engine()
response = query_engine.query("你的问题")
SummaryIndex #
python
from llama_index.core import SummaryIndex, Document
documents = [Document(text="很长的文档内容...")]
index = SummaryIndex.from_documents(documents)
query_engine = index.as_query_engine(response_mode="tree_summarize")
response = query_engine.query("总结这篇文档的主要内容")
TreeIndex #
python
from llama_index.core import TreeIndex, Document
documents = [
Document(text="文档1内容..."),
Document(text="文档2内容..."),
Document(text="文档3内容..."),
]
index = TreeIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("查询问题")
KeywordTableIndex #
python
from llama_index.core import KeywordTableIndex, Document
documents = [Document(text="Python 是一种编程语言...")]
index = KeywordTableIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("Python 编程")
Retriever（检索器） #
什么是 Retriever？ #
Retriever 负责从索引中检索相关节点，是查询引擎的核心组件。
python
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_documents(documents)
retriever = index.as_retriever(
similarity_top_k=3
)
nodes = retriever.retrieve("你的查询")
for node in nodes:
print(f"相似度: {node.score:.4f}")
print(f"内容: {node.text[:100]}")
Retriever 类型 #
text
┌─────────────────────────────────────────────────────────────┐
│ Retriever 类型 │
├─────────────────────────────────────────────────────────────┤
│ │
│ VectorIndexRetriever │
│ ├── 向量相似度检索 │
│ └── 最常用的检索器 │
│ │
│ SummaryIndexRetriever │
│ ├── 返回所有节点 │
│ └── 适合总结任务 │
│ │
│ TreeIndexRetriever │
│ ├── 从根到叶检索 │
│ └── 层级遍历 │
│ │
│ KeywordTableRetriever │
│ ├── 关键词匹配 │
│ └── 精确搜索 │
│ │
│ RouterRetriever │
│ ├── 路由选择 │
│ └── 组合多个检索器 │
│ │
└─────────────────────────────────────────────────────────────┘
自定义 Retriever #
python
from llama_index.core import VectorStoreIndex
from llama_index.core.retrievers import VectorIndexRetriever
index = VectorStoreIndex.from_documents(documents)
retriever = VectorIndexRetriever(
index=index,
similarity_top_k=5,
)
nodes = retriever.retrieve("查询内容")
组合检索器 #
python
from llama_index.core import VectorStoreIndex, KeywordTableIndex
from llama_index.core.retrievers import (
VectorIndexRetriever,
KeywordTableSimpleRetriever,
RouterRetriever,
)
from llama_index.core.tools import RetrieverTool
vector_index = VectorStoreIndex.from_documents(documents)
keyword_index = KeywordTableIndex.from_documents(documents)
vector_retriever = VectorIndexRetriever(
index=vector_index,
similarity_top_k=3,
)
keyword_retriever = KeywordTableSimpleRetriever(
index=keyword_index,
)
retriever = RouterRetriever(
retrievers=[
RetrieverTool.from_defaults(
retriever=vector_retriever,
description="适合语义搜索",
),
RetrieverTool.from_defaults(
retriever=keyword_retriever,
description="适合关键词搜索",
),
],
)
nodes = retriever.retrieve("查询内容")
Response Synthesizer（响应合成器） #
什么是 Response Synthesizer？ #
Response Synthesizer 负责将检索到的节点合成为最终回答。
python
from llama_index.core import VectorStoreIndex, get_response_synthesizer
index = VectorStoreIndex.from_documents(documents)
response_synthesizer = get_response_synthesizer(
response_mode="compact",
)
query_engine = index.as_query_engine(
response_synthesizer=response_synthesizer,
)
响应模式 #
text
┌─────────────────────────────────────────────────────────────┐
│ 响应模式 │
├─────────────────────────────────────────────────────────────┤
│ │
│ compact（默认） │
│ ├── 合并节点后一次性生成 │
│ └── 适合大多数场景 │
│ │
│ refine │
│ ├── 逐个节点迭代优化回答 │
│ └── 适合需要精细回答的场景 │
│ │
│ tree_summarize │
│ ├── 分层总结后合并 │
│ └── 适合文档总结 │
│ │
│ simple_summarize │
│ ├── 简单拼接后生成 │
│ └── 快速但可能丢失细节 │
│ │
│ no_text │
│ ├── 不生成回答，只返回节点 │
│ └── 适合只需要检索结果的场景 │
│ │
│ accumulate │
│ ├── 对每个节点单独生成回答 │
│ └── 适合并行处理 │
│ │
└─────────────────────────────────────────────────────────────┘
使用不同模式 #
python
from llama_index.core import VectorStoreIndex, get_response_synthesizer
index = VectorStoreIndex.from_documents(documents)
compact_synthesizer = get_response_synthesizer(response_mode="compact")
refine_synthesizer = get_response_synthesizer(response_mode="refine")
tree_synthesizer = get_response_synthesizer(response_mode="tree_summarize")
query_engine = index.as_query_engine(
response_synthesizer=refine_synthesizer,
)
Query Engine（查询引擎） #
什么是 Query Engine？ #
Query Engine 是端到端的查询接口，整合了检索器和响应合成器。
python
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("你的问题")
print(response)
查询引擎配置 #
python
query_engine = index.as_query_engine(
similarity_top_k=3,
response_mode="compact",
streaming=True,
)
query_engine = index.as_query_engine(
retriever=custom_retriever,
response_synthesizer=custom_synthesizer,
node_postprocessors=[postprocessor],
)
查询引擎类型 #
text
┌─────────────────────────────────────────────────────────────┐
│ 查询引擎类型 │
├─────────────────────────────────────────────────────────────┤
│ │
│ RetrieverQueryEngine │
│ ├── 基础查询引擎 │
│ └── 检索 + 合成 │
│ │
│ MultiStepQueryEngine │
│ ├── 多步查询 │
│ └── 迭代检索 │
│ │
│ RetryQueryEngine │
│ ├── 重试查询 │
│ └── 检测并重试 │
│ │
│ RouterQueryEngine │
│ ├── 路由查询 │
│ └── 选择合适的查询引擎 │
│ │
│ SubQuestionQueryEngine │
│ ├── 子问题查询 │
│ └── 分解复杂问题 │
│ │
└─────────────────────────────────────────────────────────────┘
多步查询引擎 #
python
from llama_index.core import VectorStoreIndex
from llama_index.core.query_engine import MultiStepQueryEngine
index = VectorStoreIndex.from_documents(documents)
query_engine = MultiStepQueryEngine(
query_engine=index.as_query_engine(),
num_steps=3,
)
response = query_engine.query("复杂问题")
子问题查询引擎 #
python
from llama_index.core import VectorStoreIndex
from llama_index.core.query_engine import SubQuestionQueryEngine
from llama_index.core.tools import QueryEngineTool
index = VectorStoreIndex.from_documents(documents)
query_engine_tools = [
QueryEngineTool.from_defaults(
query_engine=index.as_query_engine(),
name="knowledge_base",
description="知识库查询",
),
]
query_engine = SubQuestionQueryEngine.from_defaults(
query_engine_tools=query_engine_tools,
)
response = query_engine.query("比较文档 A 和文档 B 的异同")
Node Postprocessor（节点后处理器） #
什么是 Node Postprocessor？ #
Node Postprocessor 在检索后对节点进行处理，如重排序、过滤等。
python
from llama_index.core import VectorStoreIndex
from llama_index.postprocessor.cohere_rerank import CohereRerank
index = VectorStoreIndex.from_documents(documents)
cohere_rerank = CohereRerank(
api_key="your-cohere-key",
top_n=3,
)
query_engine = index.as_query_engine(
similarity_top_k=10,
node_postprocessors=[cohere_rerank],
)
常用后处理器 #
python
from llama_index.postprocessor.sentence_transformer_rerank import (
SentenceTransformerRerank,
)
from llama_index.postprocessor.long_context_reorder import LongContextReorder
from llama_index.core.postprocessor import (
SimilarityPostprocessor,
KeywordNodePostprocessor,
)
similarity_processor = SimilarityPostprocessor(
similarity_cutoff=0.7
)
keyword_processor = KeywordNodePostprocessor(
required_keywords=["Python"],
exclude_keywords=["Java"],
)
reorder_processor = LongContextReorder()
rerank_processor = SentenceTransformerRerank(
model="cross-encoder/ms-marco-MiniLM-L-6-v2",
top_n=3,
)
query_engine = index.as_query_engine(
similarity_top_k=10,
node_postprocessors=[
similarity_processor,
rerank_processor,
],
)
数据流转图 #
text
┌─────────────────────────────────────────────────────────────┐
│ 完整数据流转 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 数据加载 │
│ 数据源 ──→ SimpleDirectoryReader ──→ Documents │
│ │
│ 2. 文档分割 │
│ Documents ──→ NodeParser ──→ Nodes │
│ │
│ 3. 向量化 │
│ Nodes ──→ Embedding Model ──→ Embeddings │
│ │
│ 4. 索引构建 │
│ Nodes + Embeddings ──→ Index │
│ │
│ 5. 查询处理 │
│ Query ──→ Retriever ──→ Nodes │
│ ──→ Postprocessor ──→ Filtered Nodes │
│ ──→ Synthesizer ──→ Response │
│ │
└─────────────────────────────────────────────────────────────┘
下一步 #
理解核心概念后，接下来学习 数据连接器 了解如何加载各种数据源！
最后更新：2026-03-30