🦙 专注RAG的最佳框架

LlamaIndex 完整教程

用最简单的方式构建强大的数据驱动LLM应用

⭐ 37K+ Stars 📚 专注RAG 🎯 简单易用 🚀 5分钟上手

💎 为什么选择 LlamaIndex?

🎯

专注RAG

专为数据索引和检索优化,比LangChain更简单直接。

开箱即用

5行代码构建RAG应用,提供丰富的预设模板。

🔌

集成丰富

支持100+ 数据源、向量数据库、LLM模型。

🆚 LlamaIndex vs LangChain

特性 LlamaIndex LangChain
核心定位 数据索引与检索 通用LLM应用框架
学习曲线 简单(5分钟上手) 中等(需要理解概念)
RAG应用 ⭐⭐⭐⭐⭐ 专长 ⭐⭐⭐⭐ 功能全
Agent支持 ⭐⭐⭐ 基础 ⭐⭐⭐⭐⭐ 强大
代码简洁度 ⭐⭐⭐⭐⭐ 非常简洁 ⭐⭐⭐⭐ 较简洁
适用场景 知识库、问答、搜索 所有LLM应用

💡 结论:RAG应用优先选LlamaIndex,复杂Agent应用选LangChain,也可以组合使用

🚀 5分钟快速开始

📦 1. 安装 LlamaIndex

# 核心库
pip install llama-index

# 或者安装完整版
pip install llama-index-core
pip install llama-index-llms-openai
pip install llama-index-embeddings-openai
pip install llama-index-vector-stores-qdrant

2. 最简单的RAG应用(5行代码)

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 1. 加载文档(自动识别txt、pdf、docx等)
documents = SimpleDirectoryReader("./data").load_data()

# 2. 创建索引(自动分块、embedding、存储)
index = VectorStoreIndex.from_documents(documents)

# 3. 创建查询引擎
query_engine = index.as_query_engine()

# 4. 提问
response = query_engine.query("文档的主要内容是什么?")
print(response)

🎉 就这么简单!

LlamaIndex自动处理了:文档加载、文本分块、向量化、存储、检索、生成。 你只需要关注业务逻辑。

🔑 3. 配置API Key

import os

# 方法1:环境变量
os.environ["OPENAI_API_KEY"] = "your-api-key"

# 方法2:Settings全局配置
from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

Settings.llm = OpenAI(model="gpt-4", temperature=0.1)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
Settings.chunk_size = 512
Settings.chunk_overlap = 50

🧩 LlamaIndex核心概念

📄 Documents

数据的容器,包含文本内容和元数据

🧩 Nodes

文档分块后的基本单元,带有关系信息

📊 Index

数据结构,存储和组织Nodes,支持高效检索

🔍 Retriever

从Index中检索相关Nodes

Query Engine

端到端的问答接口:问题 → 检索 → 生成 → 答案

💬 Chat Engine

支持多轮对话的引擎,自动管理上下文

🔄 LlamaIndex工作流程

1. 加载数据

Documents

2. 分块

Nodes

3. 建立索引

Index

4. 查询

Query/Chat

📂 数据加载与处理

加载不同格式的文件

from llama_index.core import SimpleDirectoryReader

# 自动识别所有支持的格式
documents = SimpleDirectoryReader(
    input_dir="./data",
    recursive=True  # 递归子目录
).load_data()

# 指定文件类型
documents = SimpleDirectoryReader(
    input_files=["doc1.pdf", "doc2.docx", "doc3.md"]
).load_data()

# 添加元数据
documents = SimpleDirectoryReader(
    input_dir="./data",
    file_metadata=lambda filename: {"source": filename}
).load_data()

print(f"加载了 {len(documents)} 个文档")
print(f"第一个文档:{documents[0].text[:200]}...")

支持的数据源

📚 文档格式

# PDF
from llama_index.readers.file import PDFReader
docs = PDFReader().load_data("file.pdf")

# Word
from llama_index.readers.file import DocxReader
docs = DocxReader().load_data("file.docx")

# Markdown
from llama_index.readers.file import MarkdownReader
docs = MarkdownReader().load_data("file.md")

# Notion
from llama_index.readers.notion import NotionPageReader
docs = NotionPageReader(notion_token).load_data()

🌐 在线数据

# 网页
from llama_index.readers.web import SimpleWebPageReader
docs = SimpleWebPageReader().load_data(
    ["https://example.com"]
)

# GitHub
from llama_index.readers.github import GithubRepositoryReader
docs = GithubRepositoryReader(
    owner="user",
    repo="repo"
).load_data()

# Google Drive
from llama_index.readers.google import GoogleDriveReader
docs = GoogleDriveReader().load_data()

📊 索引类型与选择

🔵 VectorStoreIndex(最常用)

基于向量相似度的检索,适合大多数场景

from llama_index.core import VectorStoreIndex

# 使用内存存储(测试)
index = VectorStoreIndex.from_documents(documents)

# 使用持久化存储(生产)
from llama_index.vector_stores.qdrant import QdrantVectorStore
import qdrant_client

client = qdrant_client.QdrantClient(path="./qdrant_db")
vector_store = QdrantVectorStore(client=client, collection_name="my_collection")

index = VectorStoreIndex.from_documents(
    documents,
    vector_store=vector_store
)

💡 适用场景:知识库问答、语义搜索、文档检索

🟢 SummaryIndex

按顺序处理所有文档,适合总结任务

from llama_index.core import SummaryIndex

index = SummaryIndex.from_documents(documents)

# 总结所有文档
query_engine = index.as_query_engine(
    response_mode="tree_summarize"
)

response = query_engine.query("总结所有文档的核心内容")

💡 适用场景:文档总结、全局分析

🟣 TreeIndex

构建层级树结构,适合大规模文档

from llama_index.core import TreeIndex

index = TreeIndex.from_documents(documents)

# 自底向上查询
query_engine = index.as_query_engine()

💡 适用场景:超大文档集、层级化内容

🟠 KeywordTableIndex

基于关键词的检索,补充向量检索

from llama_index.core import KeywordTableIndex

index = KeywordTableIndex.from_documents(documents)

# 关键词检索
query_engine = index.as_query_engine()

💡 适用场景:精确匹配、术语检索

🔍 查询引擎详解

查询响应模式

1. compact(默认)

填充尽可能多的文本到上下文窗口

query_engine = index.as_query_engine(
    response_mode="compact"
)

2. tree_summarize

层级总结,适合多文档总结

query_engine = index.as_query_engine(
    response_mode="tree_summarize"
)

3. refine

迭代优化答案

query_engine = index.as_query_engine(
    response_mode="refine"
)

4. simple_summarize

简单拼接所有文本

query_engine = index.as_query_engine(
    response_mode="simple_summarize"
)

⚙️ 查询引擎高级配置

query_engine = index.as_query_engine(
    # 响应模式
    response_mode="compact",
    
    # 检索参数
    similarity_top_k=5,  # 返回最相关的5个chunks
    
    # 流式输出
    streaming=True,
    
    # 自定义提示词
    text_qa_template="基于以下内容回答问题:\n{context_str}\n\n问题:{query_str}\n答案:",
    
    # 节点后处理器
    node_postprocessors=[
        SimilarityPostprocessor(similarity_cutoff=0.7)
    ],
    
    # 使用不同的LLM
    llm=OpenAI(model="gpt-4"),
)

# 流式查询
streaming_response = query_engine.query("什么是LlamaIndex?")
streaming_response.print_response_stream()

💬 对话引擎(Chat Engine)

支持多轮对话的查询

from llama_index.core.memory import ChatMemoryBuffer

# 创建聊天引擎
chat_engine = index.as_chat_engine(
    chat_mode="condense_plus_context",  # 压缩历史对话
    memory=ChatMemoryBuffer.from_defaults(token_limit=3000),
    system_prompt="你是一个专业的文档助手,基于提供的文档回答问题"
)

# 多轮对话
response1 = chat_engine.chat("LlamaIndex是什么?")
print(response1)

response2 = chat_engine.chat("它有哪些优势?")  # 理解"它"指代LlamaIndex
print(response2)

response3 = chat_engine.chat("给我举个例子")
print(response3)

# 重置对话
chat_engine.reset()

聊天模式对比

simple

简单模式,不处理对话历史

condense_question

将对话历史压缩到问题中

condense_plus_context(推荐)

压缩历史 + 检索增强

🗄️ 向量数据库集成

⚡ Qdrant(推荐)

from llama_index.vector_stores.qdrant import QdrantVectorStore
import qdrant_client

# 创建Qdrant客户端
client = qdrant_client.QdrantClient(
    path="./qdrant_db"  # 本地存储
    # url="http://localhost:6333"  # 或服务器
)

# 创建向量存储
vector_store = QdrantVectorStore(
    client=client,
    collection_name="my_documents"
)

# 从向量存储创建索引
from llama_index.core import StorageContext

storage_context = StorageContext.from_defaults(
    vector_store=vector_store
)

index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context
)

🎨 Chroma(轻量)

from llama_index.vector_stores.chroma import ChromaVectorStore
import chromadb

# 创建Chroma客户端
db = chromadb.PersistentClient(path="./chroma_db")
collection = db.get_or_create_collection("my_docs")

# 创建向量存储
vector_store = ChromaVectorStore(chroma_collection=collection)

storage_context = StorageContext.from_defaults(
    vector_store=vector_store
)

index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context
)

📌 Pinecone(托管)

from llama_index.vector_stores.pinecone import PineconeVectorStore
from pinecone import Pinecone

# 初始化Pinecone
pc = Pinecone(api_key="your-api-key")
index_name = "llamaindex-demo"

# 创建索引(如果不存在)
if index_name not in pc.list_indexes().names():
    pc.create_index(
        name=index_name,
        dimension=1536,  # OpenAI embedding维度
        metric="cosine"
    )

# 创建向量存储
vector_store = PineconeVectorStore(
    pinecone_index=pc.Index(index_name)
)

index = VectorStoreIndex.from_documents(
    documents,
    storage_context=StorageContext.from_defaults(
        vector_store=vector_store
    )
)

💾 本地持久化

# 保存索引
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)

🚀 高级检索技术

🔀 混合检索(Vector + BM25)

from llama_index.core.retrievers import VectorIndexRetriever
from llama_index.retrievers.bm25 import BM25Retriever
from llama_index.core.retrievers import QueryFusionRetriever

# 向量检索器
vector_retriever = VectorIndexRetriever(
    index=index,
    similarity_top_k=10
)

# BM25检索器
bm25_retriever = BM25Retriever.from_defaults(
    index=index,
    similarity_top_k=10
)

# 混合检索器
retriever = QueryFusionRetriever(
    retrievers=[vector_retriever, bm25_retriever],
    similarity_top_k=5,
    num_queries=1,  # 生成查询变体数量
    mode="reciprocal_rerank"  # 重排序模式
)

# 使用混合检索
nodes = retriever.retrieve("LlamaIndex的核心优势")

🎯 重排序(Reranking)

检索后重新排序,提升Top结果的相关性

from llama_index.postprocessor.cohere_rerank import CohereRerank

# Cohere重排序(效果最好)
rerank = CohereRerank(
    api_key="your-cohere-key",
    top_n=3
)

query_engine = index.as_query_engine(
    similarity_top_k=10,  # 先检索10个
    node_postprocessors=[rerank]  # 重排序后保留3个
)

# 也可以使用本地重排序模型
from llama_index.postprocessor.flag_embedding_reranker import FlagEmbeddingReranker

reranker = FlagEmbeddingReranker(
    model="BAAI/bge-reranker-large",
    top_n=3
)

🔄 查询转换(Query Transform)

HyDE(假设性文档)

from llama_index.core.indices.query.query_transform import HyDEQueryTransform

# 先生成假设的答案,用答案去检索
hyde = HyDEQueryTransform(include_original=True)

query_engine = index.as_query_engine(
    query_transform=hyde
)

# 效果:提升检索准确率15-25%

Multi-Step查询

from llama_index.core.query_engine import MultiStepQueryEngine

# 多步骤查询分解
query_engine = MultiStepQueryEngine(
    query_engine=index.as_query_engine(),
    query_transform=StepDecomposeQueryTransform(),
    num_steps=3
)

# 复杂问题 → 分解为子问题 → 逐步回答

💼 实战案例

案例1:企业文档问答系统

完整的企业知识库实现,包含增量更新、权限控制、来源追踪。

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.vector_stores.qdrant import QdrantVectorStore
import qdrant_client

class EnterpriseKnowledgeBase:
    def __init__(self, collection_name="company_docs"):
        # 全局配置
        Settings.llm = OpenAI(model="gpt-4", temperature=0)
        Settings.embed_model = OpenAIEmbedding()
        Settings.chunk_size = 512
        Settings.chunk_overlap = 50
        
        # 向量数据库
        self.client = qdrant_client.QdrantClient(path="./qdrant_data")
        self.vector_store = QdrantVectorStore(
            client=self.client,
            collection_name=collection_name
        )
        
    def index_documents(self, directory):
        """索引文档目录"""
        # 加载文档
        documents = SimpleDirectoryReader(
            input_dir=directory,
            recursive=True,
            required_exts=[".pdf", ".docx", ".txt", ".md"]
        ).load_data()
        
        print(f"加载 {len(documents)} 个文档")
        
        # 创建索引
        from llama_index.core import StorageContext
        
        storage_context = StorageContext.from_defaults(
            vector_store=self.vector_store
        )
        
        self.index = VectorStoreIndex.from_documents(
            documents,
            storage_context=storage_context,
            show_progress=True
        )
        
        print("索引创建完成")
        return self.index
    
    def create_query_engine(self):
        """创建查询引擎"""
        from llama_index.postprocessor.cohere_rerank import CohereRerank
        
        query_engine = self.index.as_query_engine(
            similarity_top_k=10,
            node_postprocessors=[
                CohereRerank(top_n=3)  # 重排序
            ],
            response_mode="compact",
            streaming=True
        )
        
        return query_engine
    
    def create_chat_engine(self):
        """创建对话引擎"""
        from llama_index.core.memory import ChatMemoryBuffer
        
        chat_engine = self.index.as_chat_engine(
            chat_mode="condense_plus_context",
            memory=ChatMemoryBuffer.from_defaults(token_limit=3000),
            system_prompt="""你是公司的智能助手,负责回答员工的问题。
            
【规则】
1. 必须基于公司文档回答
2. 标注信息来源
3. 信息不足时明确说明
4. 保持专业和友好的语气"""
        )
        
        return chat_engine

# 使用示例
kb = EnterpriseKnowledgeBase()
kb.index_documents("./company_docs")

# 问答模式
query_engine = kb.create_query_engine()
response = query_engine.query("公司的休假政策是什么?")

# 对话模式
chat_engine = kb.create_chat_engine()
response = chat_engine.chat("你好,请问年假有多少天?")

案例2:多文档对比分析

对比不同产品、方案或版本的差异。

from llama_index.core.tools import QueryEngineTool
from llama_index.core.query_engine import SubQuestionQueryEngine

# 为每个文档创建独立索引
doc1_index = VectorStoreIndex.from_documents(product_a_docs)
doc2_index = VectorStoreIndex.from_documents(product_b_docs)

# 创建工具
tools = [
    QueryEngineTool.from_defaults(
        query_engine=doc1_index.as_query_engine(),
        name="产品A资料",
        description="包含产品A的功能、价格、优势等信息"
    ),
    QueryEngineTool.from_defaults(
        query_engine=doc2_index.as_query_engine(),
        name="产品B资料",
        description="包含产品B的功能、价格、优势等信息"
    )
]

# 子问题查询引擎
query_engine = SubQuestionQueryEngine.from_defaults(
    query_engine_tools=tools,
    verbose=True
)

# 对比查询
response = query_engine.query(
    "对比产品A和产品B的功能差异和价格"
)
print(response)

⚡ 性能优化指南

🎯 参数调优

分块参数

Settings.chunk_size = 512  # 256-1024
Settings.chunk_overlap = 50  # 10-20%

# 中文优化分隔符
from llama_index.core.node_parser import SentenceSplitter

splitter = SentenceSplitter(
    chunk_size=512,
    chunk_overlap=50,
    separator="。"  # 中文句号
)

检索参数

query_engine = index.as_query_engine(
    similarity_top_k=5,  # 3-10
    similarity_cutoff=0.7  # 过滤低分结果
)

💰 成本优化

缓存机制

from llama_index.core import set_global_handler

# 启用缓存
set_global_handler("simple")

使用更小的模型

# Embedding用小模型
Settings.embed_model = OpenAIEmbedding(
    model="text-embedding-3-small"  # 便宜5倍
)

# LLM分级使用
Settings.llm = OpenAI(model="gpt-4o-mini")

❓ 常见问题

Q1: LlamaIndex如何处理中文文档?

需要针对中文优化:

  • • 使用中文Embedding模型:bge-large-zh-v1.5
  • • 设置中文分隔符:"。"、"!"、"?"
  • • 使用支持中文的LLM:gpt-4、Claude、Qwen

Q2: 如何更新已索引的文档?

# 增量插入
new_docs = SimpleDirectoryReader("./new_data").load_data()
index.insert_nodes(new_docs)

# 刷新特定文档
index.refresh_ref_docs(documents)

# 删除文档
index.delete_ref_doc(doc_id)

Q3: 检索质量不好怎么办?

多管齐下优化:

  • ✓ 使用混合检索(Vector + BM25)
  • ✓ 添加Reranker重排序
  • ✓ 调整chunk_size和overlap
  • ✓ 更换更好的Embedding模型
  • ✓ 使用HyDE查询转换

Q4: 如何评估RAG系统效果?

from llama_index.core.evaluation import (
    FaithfulnessEvaluator,
    RelevancyEvaluator
)

# 忠实度评估(是否基于文档回答)
faithfulness = FaithfulnessEvaluator()
result = faithfulness.evaluate_response(response=response)

# 相关性评估
relevancy = RelevancyEvaluator()
result = relevancy.evaluate_response(
    query=query,
    response=response
)

📚 学习资源

📖

官方文档

  • • 完整的API参考
  • • 逐步教程
  • • 示例代码
查看文档
🎓

视频课程

  • • DeepLearning.AI课程
  • • YouTube教程
  • • 实战Workshop
免费课程
💬

社区支持

  • • Discord社区
  • • GitHub Discussions
  • • 示例项目库
加入Discord

🎯 30分钟快速入门路径

1. 安装LlamaIndex 2. 运行第一个例子 3. 集成向量数据库 4. 优化检索质量

继续探索