LlamaIndex 是一个开源的数据编排框架，专门用于构建基于检索增强生成（RAG）的 LLM 应用。它提供了一整套从数据接入、索引构建到高级检索和查询的全链路工具，是当前 RAG 领域最主流的两大框架之一（与 LangChain 并列）。
LlamaIndex（原名 GPT Index）是由 Jerry Liu 创建的开源 Python/TypeScript 框架，用于将 LLM 连接到外部数据源。它聚焦于解决 LLM 核心痛点——知识截止日期和缺乏私有数据访问能力——通过 RAG 模式将外部数据注入 LLM 上下文窗口。
与 LangChain 的通用 Agent 编排不同，LlamaIndex 的核心设计哲学是数据优先：它围绕数据的生命周期（加载 → 解析 → 索引 → 检索 → 生成）构建了完整的抽象层。
LlamaIndex 的设计围绕几个关键原则：
LlamaIndex 的架构分为几个核心层次：
┌─────────────────────────────────────────┐
│ Application Layer │
│ Query Engine · Chat Engine · Agent │
├─────────────────────────────────────────┤
│ Orchestration Layer │
│ Workflows · Pipeline · Router │
├─────────────────────────────────────────┤
│ Retrieval Layer │
│ Retriever · Node Parser · Postprocessor│
├─────────────────────────────────────────┤
│ Index Layer │
│ Vector Index · Summary Index · KG Index│
├─────────────────────────────────────────┤
│ Data Ingestion Layer │
│ Readers · Connectors · LlamaParse │
└─────────────────────────────────────────┘
LlamaIndex 中有两个核心数据抽象：
LlamaHub 是一个包含 160+ 数据连接器的注册中心，支持结构化、半结构化和非结构化数据：
from llama_index.readers.wikipedia import WikipediaReader
reader = WikipediaReader()
documents = reader.load_data(
pages=["LlamaIndex", "Retrieval-Augmented Generation"]
)
支持的连接器类型包括：
| 分类 | 示例 |
|---|---|
| 文件格式 | PDF、DOCX、PPTX、CSV、Markdown、HTML |
| 云存储 | Google Drive、Dropbox、OneDrive、S3 |
| 协作工具 | Notion、Confluence、Slack、Discourse |
| 数据库 | PostgreSQL、MySQL、MongoDB、SQLite |
| 代码仓库 | GitHub、GitLab |
| 多媒体 | YouTube、图片（OCR）、音频（Whisper） |
最简单的文档加载方式，从本地目录加载所有支持格式的文件：
from llama_index.core import SimpleDirectoryReader
documents = SimpleDirectoryReader(
input_dir="./data",
recursive=True, # 递归遍历子目录
required_exts=[".pdf", ".md"], # 过滤文件类型
filename_as_id=True # 使用文件名作为文档ID
).load_data()
LlamaParse 是 LlamaIndex 的旗舰产品，专为复杂文档格式设计：
from llama_parse import LlamaParse
parser = LlamaParse(
result_type="markdown", # 输出格式
parsing_instruction="专注于提取财务数据和表格",
premium_mode=True, # 启用高级解析
)
documents = parser.load_data("./report.pdf")
LlamaIndex 支持多种索引类型，适用于不同的数据形态和查询场景：
最常用的索引类型，适用于语义搜索：
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_documents(
documents,
embed_model="text-embedding-3-small",
show_progress=True
)
计算过程：对于查询 和文档集合 ，检索最相关的 个文档：
适用于需要对整个文档集合做总结的场景：
from llama_index.core import SummaryIndex
summary_index = SummaryIndex.from_documents(documents)
query_engine = summary_index.as_query_engine()
适用于需要理解实体间关系的场景：
from llama_index.core import KnowledgeGraphIndex
kg_index = KnowledgeGraphIndex.from_documents(
documents,
max_triplets_per_chunk=10, # 每个chunk抽取的实体关系三元组数
include_embeddings=True # 同时生成向量嵌入
)
2024年5月引入，基于知识图谱的增强索引：
适用于需要精确关键词匹配的场景：
| 索引类型 | 适用场景 | 检索方式 | 性能特点 |
|---|---|---|---|
| VectorStoreIndex | 语义搜索、开放域问答 | 向量相似度 | 中等延迟，高召回 |
| SummaryIndex | 文档总结、全局分析 | 全量传递 | 较高延迟 |
| KnowledgeGraphIndex | 实体关系推理 | 图遍历 + 向量 | 最高延迟，复杂查询 |
| PropertyGraphIndex | 属性图检索 | 混合检索 | 中等延迟 |
| KeywordTableIndex | 精确匹配 | 关键词查找 | 最低延迟 |
LlamaIndex 提供多种检索器（Retriever）实现：
基础检索器：
VectorIndexRetriever：基于向量相似度检索SummaryRetriever：检索所有节点后进行总结KeywordTableRetriever：基于关键词匹配检索高级检索器：
RecursiveRetriever：递归检索，对复杂文档逐层深入RouterRetriever：路由检索，根据查询类型选择不同的检索器FusionRetriever：融合检索，结合向量和关键词搜索（RRF 融合算法）1. Recursive Retrieval（递归检索）
对复杂文档采用粗到精的检索策略：
from llama_index.core.retrievers import RecursiveRetriever
# 先检索文档块
# 然后递归检索更细粒度的子块
retriever = RecursiveRetriever(
"vector",
retriever_dict={"vector": vector_retriever},
node_dict=all_nodes_dict,
verbose=True
)
2. Small-to-Big Retrieval（从小到大检索）
检索小块内容以获得更高精度，但返回大块上下文给 LLM：
3. Hybrid Search（混合检索）
结合向量搜索和关键词搜索：
from llama_index.core.retrievers import QueryFusionRetriever
retriever = QueryFusionRetriever(
[vector_retriever, keyword_retriever],
similarity_top_k=5,
num_queries=4, # 对每个查询生成4个变体
mode="reciprocal_rerank", # RRF 融合排序
)
RRF（Reciprocal Rank Fusion）融合公式：
其中 是所有检索结果的排名集合， 是常数（通常为60）。
4. Metadata Filtering（元数据过滤）
在检索前根据元数据过滤：
from llama_index.core.vector_stores import MetadataFilters, ExactMatchFilter
filters = MetadataFilters(
filters=[
ExactMatchFilter(key="author", value="Hugo Gu"),
]
)
query_engine = index.as_query_engine(
filters=filters
)
查询引擎是 LlamaIndex 的核心接口，负责将检索结果与 LLM 结合生成最终回答。
query_engine = index.as_query_engine(
similarity_top_k=5, # 检索 Top-5 文档
response_mode="compact" # 响应模式：compact / tree_summarize / refine
)
response = query_engine.query("LlamaIndex 的核心优势是什么？")
print(response)
print(f"来源: {response.source_nodes}")
print(f"元数据: {response.metadata}")
SubQuestionQueryEngine（子问题查询引擎）
将复杂查询分解为多个子问题，分别检索后合并结果：
from llama_index.core.query_engine import SubQuestionQueryEngine
query_engine = SubQuestionQueryEngine.from_defaults(
query_engine_tools=[
vector_tool,
summary_tool,
kg_tool
],
llm=llm,
verbose=True
)
response = query_engine.query(
"比较各季度的财务表现并分析主要影响因素"
)
# 自动分解为：
# - "第一季度财务指标是什么？"
# - "第二季度财务指标是什么？"
# - "第三季度财务指标是什么？"
# - "各季度差异的主要影响因素有哪些？"
RouterQueryEngine（路由查询引擎）
根据查询内容自动路由到最适合的查询引擎：
from llama_index.core.query_engine import RouterQueryEngine
from llama_index.core.tools import QueryEngineTool
vector_tool = QueryEngineTool.from_defaults(
query_engine=vector_query_engine,
description="用于语义搜索和开放域问答"
)
summary_tool = QueryEngineTool.from_defaults(
query_engine=summary_query_engine,
description="用于文档总结和全局分析"
)
router = RouterQueryEngine.from_defaults(
query_engine_tools=[vector_tool, summary_tool],
llm=llm,
verbose=True
)
PandasQueryEngine（数据框查询引擎）
对 pandas DataFrame 进行自然语言查询：
from llama_index.core.query_engine import PandasQueryEngine
df_query_engine = PandasQueryEngine(
df=sales_df,
llm=llm,
verbose=True
)
response = df_query_engine.query(
"哪个产品线的季度增长率最高？"
)
FLAREQueryEngine（主动检索查询引擎）
LLM 在生成过程中主动决定何时需要检索更多信息：
from llama_index.core.query_engine import FLAREInstructQueryEngine
flare_engine = FLAREInstructQueryEngine(
query_engine=base_query_engine,
max_iterations=7,
verbose=True
)
LlamaIndex 提供专为对话场景设计的 Chat Engine：
from llama_index.core.chat_engine import CondensePlusContextChatEngine
chat_engine = CondensePlusContextChatEngine.from_defaults(
retriever=index.as_retriever(),
llm=llm,
memory=memory # 对话记忆
)
支持的聊天模式：
LlamaIndex 提供了完整的 Agent 框架：
from llama_index.core.agent import ReActAgent
from llama_index.core.tools import QueryEngineTool, FunctionTool
tools = [
QueryEngineTool.from_defaults(
query_engine=vector_engine,
name="document_search",
description="搜索企业内部文档"
),
FunctionTool.from_defaults(
fn=calculate_kpi,
name="calculate",
description="计算关键业务指标"
)
]
agent = ReActAgent.from_tools(
tools=tools,
llm=llm,
verbose=True,
max_iterations=10
)
支持 Agent 类型：
2024年8月引入的 Workflows 是 LlamaIndex 最重要的架构升级之一，提供了一种声明式编排方式：
from llama_index.core.workflow import (
Workflow,
step,
Context,
StartEvent,
StopEvent
)
class MyRAGWorkflow(Workflow):
@step
async def ingest(self, ctx: Context, ev: StartEvent) -> IndexEvent:
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
return IndexEvent(index=index)
@step
async def retrieve(self, ctx: Context, ev: QueryEvent) -> RetrieveEvent:
index = await ctx.get("index")
retriever = index.as_retriever(similarity_top_k=5)
nodes = retriever.retrieve(ev.query)
return RetrieveEvent(nodes=nodes, query=ev.query)
@step
async def generate(self, ctx: Context, ev: RetrieveEvent) -> StopEvent:
context = "\n\n".join([n.text for n in ev.nodes])
response = await llm.apredict(
f"基于以下信息：\n{context}\n\n回答问题：{ev.query}"
)
return StopEvent(result=response)
Workflows 的优势：
在检索后、生成前对结果进行处理，提升质量：
from llama_index.core.postprocessor import SentenceTransformerRerank
rerank = SentenceTransformerRerank(
model="BAAI/bge-reranker-v2-m3",
top_n=3 # 保留最相关的3个结果
)
query_engine = index.as_query_engine(
similarity_top_k=10, # 先检索 Top-10
node_postprocessors=[rerank] # 再重排选 Top-3
)
from llama_index.core.postprocessor import LongLLMLinguaPostprocessor
compressor = LongLLMLinguaPostprocessor(
instruction_str="Given the context, please answer the final question",
target_token=300, # 压缩到300 tokens
rank_method="longllmlingua"
)
CohereRerank：基于 Cohere API 的重排序LLMFilter：用 LLM 过滤不相关节点SimilarityPostprocessor：基于相似度阈值的过滤KeywordNodePostprocessor：基于关键词的过滤PrevNextNodePostprocessor：添加前后节点以丰富上下文# 保存索引
index.storage_context.persist(persist_dir="./storage")
# 加载索引
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)
LlamaIndex 支持所有主流向量数据库：
| 向量数据库 | 特点 | 适用场景 |
|---|---|---|
| Chroma | 轻量级，本地运行 | 原型开发、小规模应用 |
| Pinecone | 托管服务，高可用 | 生产环境 |
| Weaviate | 开源，多模态支持 | 企业级应用 |
| Milvus | 高性能，分布式 | 大规模检索 |
| Qdrant | Rust 实现，低延迟 | 实时检索 |
| FAISS | 纯本地，零依赖 | 离线处理、低成本方案 |
| Elasticsearch | 混合搜索 | 已有 ELK 基础设施 |
from llama_index.vector_stores.chroma import ChromaVectorStore
import chromadb
db = chromadb.PersistentClient(path="./chroma_db")
chroma_collection = db.get_or_create_collection("documents")
vector_store = ChromaVectorStore(
chroma_collection=chroma_collection
)
index = VectorStoreIndex.from_documents(
documents,
storage_context=StorageContext.from_defaults(
vector_store=vector_store
)
)
避免重复的嵌入计算：
from llama_index.core.storage.docstore import SimpleDocumentStore
docstore = SimpleDocumentStore()
docstore.add_documents(documents)
# 检查文档是否已存在
if docstore.document_exists(doc_id):
# 跳过嵌入计算
pass
else:
# 创建新的嵌入
index = VectorStoreIndex.from_documents([doc])
LlamaIndex 内置了全面的评估工具：
from llama_index.core.evaluation import (
RelevancyEvaluator,
FaithfulnessEvaluator,
SemanticSimilarityEvaluator,
BatchEvalRunner,
)
# 相关性评估：检索的文档是否相关
relevancy_eval = RelevancyEvaluator()
# 忠实度评估：生成内容是否基于检索文档
faithfulness_eval = FaithfulnessEvaluator()
# 批量评估
runner = BatchEvalRunner({
"relevancy": relevancy_eval,
"faithfulness": faithfulness_eval,
}, workers=4)
eval_results = runner.evaluate_responses(
queries=test_queries,
responses=generated_responses
)
支持的测量维度：
| 维度 | 描述 | 评估方式 |
|---|---|---|
| Relevancy | 检索结果与查询的相关性 | LLM 评判 |
| Faithfulness | 生成内容是否忠实于检索结果 | LLM 评判 |
| Answer Relevancy | 回答是否针对问题 | LLM 评判 |
| Context Relevancy | 上下文是否充分 | LLM 评判 |
| Semantic Similarity | 回答与参考答案的语义相似度 | 嵌入相似度 |
2024年7月引入的 LlamaTrace 提供了全链路追踪：
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
documents = SimpleDirectoryReader("knowledge_base/").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("公司的远程办公政策是什么？")
class EnterpriseRAG:
def __init__(self):
self.llm = OpenAI(
model="gpt-4",
temperature=0.1,
max_tokens=2048
)
self.embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-large-zh-v1.5"
)
Settings.llm = self.llm
Settings.embed_model = self.embed_model
Settings.chunk_size = 512
Settings.chunk_overlap = 50
async def build(self):
# 1. 文档加载
documents = SimpleDirectoryReader(
input_dir="./enterprise_docs",
required_exts=[".pdf", ".docx", ".md"],
file_extractor={
".pdf": PDFExtractor(),
".docx": DocxExtractor(),
}
).load_data()
# 2. 索引构建
index = VectorStoreIndex.from_documents(
documents,
show_progress=True
)
# 3. 查询引擎（带重排）
rerank = SentenceTransformerRerank(
model="BAAI/bge-reranker-v2-m3",
top_n=3
)
self.query_engine = index.as_query_engine(
similarity_top_k=10,
node_postprocessors=[rerank],
response_mode="tree_summarize"
)
# 4. 对话引擎
self.chat_engine = CondensePlusContextChatEngine.from_defaults(
retriever=index.as_retriever(similarity_top_k=5),
llm=self.llm,
memory=ChatMemoryBuffer.from_defaults(
token_limit=2000
)
)
async def query(self, question: str) -> str:
response = await self.query_engine.aquery(question)
return {
"answer": str(response),
"sources": [
{"text": n.text[:200], "score": n.score}
for n in response.source_nodes
]
}
async def chat(self, message: str) -> str:
response = await self.chat_engine.achat(message)
return str(response)
from llama_index.core.agent import ReActAgent
from llama_index.core.tools import QueryEngineTool, ToolMetadata
def build_multi_document_agent(documents: dict):
"""
documents: { "doc_name": [Document], ... }
每个文档组创建一个子 Agent
"""
tools = []
for doc_name, doc_list in documents.items():
index = VectorStoreIndex.from_documents(doc_list)
query_engine = index.as_query_engine(similarity_top_k=3)
tool = QueryEngineTool(
query_engine=query_engine,
metadata=ToolMetadata(
name=f"query_{doc_name}",
description=f"搜索文档：{doc_name}",
)
)
tools.append(tool)
# 创建协调 Agent，自动选择调用哪个文档 Agent
top_agent = ReActAgent.from_tools(
tools=tools,
llm=OpenAI(model="gpt-4"),
verbose=True,
max_iterations=20
)
return top_agent
| 维度 | LlamaIndex | LangChain |
|---|---|---|
| 核心定位 | RAG 数据框架 | 通用 LLM 编排框架 |
| 数据接入 | 内置 160+ 连接器 | 依赖第三方集成 |
| 索引策略 | 5+ 种索引类型 | 基础向量索引 |
| 查询引擎 | 丰富（SubQuestion、Router、FLARE 等） | 链式调用 |
| Agent | 支持，偏数据操作 | 核心功能，偏通用编排 |
| Workflow | 声明式 Workflows | LangGraph |
| 文档解析 | LlamaParse（企业级） | 无内置能力 |
| 评估工具 | 内置全面评估 | 需集成外部工具 |
| 生产化 | LlamaCloud、LlamaTrace | LangSmith、LangServe |
| 学习曲线 | 中等 | 较陡 |
| 时间 | 发布 |
|---|---|
| 2024-01 | LlamaIndex CLI：RAG as one-liner |
| 2024-02 | LlamaParse 发布 |
| 2024-04 | create-llama：全栈 RAG 应用脚手架 |
| 2024-05 | Property Graph Index 引入 |
| 2024-06 | LlamaDeploy（原名 llama-agents）：Agent 微服务化 |
| 2024-07 | LlamaTrace：可观测性平台 |
| 2024-08 | Workflows 引入 |
| 2024-09 | LlamaParse Premium Mode |
| 2024-12 | LlamaReport：文档数据库到最终报告 |
| 2025-09 | v0.11：50+ 新数据连接器，改进混合搜索 |
| 2025-10 | 检索准确率提升 35% |
aquery() / achat() 支持高并发