🦙 LlamaIndex 完全入门指南
写给小白的RAG框架教程
📖 目录
🤔 从一个生活问题开始
想象一下这个场景：
你的老板给了你1000份公司的技术文档，然后问你："去年Q3我们的销售策略是什么？"
你会怎么做？
- ❌ 一份一份手动翻看？（估计要找一整天）
- ❌ 用Ctrl+F搜关键词？（可能遗漏相关信息）
- ✅ 用LlamaIndex！（几秒钟搞定）
这就是LlamaIndex的价值——让AI帮你从海量文档中快速找到答案。
🦙 什么是LlamaIndex？
简单定义
LlamaIndex = 智能文档管理员 + 知识检索专家 + AI回答助手
它是一个Python框架，专门用来：
- 把你的文档（PDF、Word、网页...）整理成"可搜索的知识库"
- 当你提问时，快速找到相关内容
- 用AI（如ChatGPT）把找到的内容整理成答案
核心概念：RAG
RAG = Retrieval-Augmented Generation（检索增强生成）
传统AI对话 → 只能回答训练时学到的知识
RAG系统（LlamaIndex） → 能回答你自己文档里的内容！
生活比喻：
- 普通ChatGPT = 博学的朋友（但不知道你公司的事）
- LlamaIndex + ChatGPT = 看过你所有公司文档的秘书
📚 核心原理：图书馆的故事
让我们用图书馆来理解LlamaIndex的工作流程：
🏛️ 完整流程图解
┌─────────────────────────────────────────────────────────────┐
│ LlamaIndex 工作流程 │
└─────────────────────────────────────────────────────────────┘
第一步：收集书籍（数据加载）
┌─────────┐ ┌─────────┐ ┌─────────┐
│ PDF文档 │ │ Word文档│ │ 网页 │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└────────────┼────────────┘
↓
┌────────────────┐
│ 数据连接器 │ ← 图书馆采购部
└────────┬───────┘
↓
【原始文档数组】
第二步：整理编目（文档切片）
┌────────────────┐
│ 长文档 │
│ (5000字) │
└────────┬───────┘
↓
┌────────────────┐
│ 文本分割器 │ ← 图书馆编目员
└────────┬───────┘
↓
┌──────┐ ┌──────┐ ┌──────┐
│片段1 │ │片段2 │ │片段3 │ ← 把大书拆成章节
│500字│ │500字│ │500字│
└──────┘ └──────┘ └──────┘
第三步：建立索引（向量化）
┌──────────────────────────────┐
│ 片段1："产品A在去年销售..." │
└──────────┬───────────────────┘
↓
┌──────────────────────────┐
│ 嵌入模型（Embedding） │ ← 把文字变成数字密码
└──────────┬───────────────┘
↓
[0.23, -0.45, 0.67, ...] ← 向量（512维数字）
↓
┌──────────────────────────┐
│ 向量索引数据库 │ ← 图书馆索引卡片柜
│ 存储所有向量+原文 │
└──────────────────────────┘
第四步：用户提问（查询）
┌────────────────┐
│ 用户问题： │
│ "去年销售如何？"│
└────────┬───────┘
↓
┌────────────────┐
│ 问题也向量化 │
└────────┬───────┘
↓
[0.21, -0.43, ...] ← 问题的向量
第五步：相似度匹配（检索）
┌─────────────────────────────────┐
│ 向量索引数据库 │
│ │
│ 片段1向量: [0.23, -0.45, ...] │ ← 相似度: 92% ✓
│ 片段2向量: [0.11, 0.32, ...] │ ← 相似度: 15% ✗
│ 片段3向量: [0.22, -0.41, ...] │ ← 相似度: 88% ✓
└─────────────────────────────────┘
↓
找到最相关的2个片段
第六步：生成答案（LLM回答）
┌─────────────────────────────────┐
│ 大语言模型（如ChatGPT） │
│ │
│ 输入： │
│ - 用户问题 │
│ - 相关文档片段1 │
│ - 相关文档片段2 │
│ │
│ 输出： │
│ "根据文档，去年销售额增长了..."│
└─────────────────────────────────┘
🎯 关键要点
| 步骤 | 做什么 | 生活比喻 |
|---|---|---|
| 数据加载 | 读取各种文档 | 图书馆进货新书 |
| 文档切片 | 把长文档切成小段 | 把厚书拆成章节 |
| 向量化 | 把文字变成数字 | 给每本书编号分类 |
| 建索引 | 存储到数据库 | 建立索引卡片柜 |
| 查询 | 问题也转成数字 | 读者来找书 |
| 检索 | 找相似的片段 | 查卡片找到书架位置 |
| 生成答案 | AI整理成回答 | 图书管理员总结给你听 |
🔧 五大核心组件详解
1️⃣ 数据连接器（Data Connectors）
作用：把各种格式的文件读进来
生活比喻：就像快递员，不管你买的是书、衣服还是电子产品，都能送到你家门口。
# 示例：从文件夹读取所有文档
from llama_index.core import SimpleDirectoryReader
# 一行代码读取整个文件夹！
documents = SimpleDirectoryReader('我的文档文件夹').load_data()
支持的格式：
- 📄 文本文件：.txt, .md
- 📑 办公文档：.pdf, .docx, .pptx
- 🌐 网页：HTML
- 📊 表格：.csv, .xlsx
- 💾 数据库：SQL, MongoDB
- 🔗 在线服务：Google Docs, Notion, 维基百科...
2️⃣ 文档节点（Nodes）
作用：把长文档切成小块
为什么要切？
- ❌ 整篇文章太长，AI看不过来
- ✅ 切成小段，精准定位相关部分
生活比喻：就像吃大西瓜，你不能一口吃掉，要切成小块才好入口。
from llama_index.core.node_parser import SimpleNodeParser
# 创建切片器：每500字切一段
parser = SimpleNodeParser.from_defaults(chunk_size=500, chunk_overlap=50)
# 切片！
nodes = parser.get_nodes_from_documents(documents)
关键参数：
chunk_size=500：每块500字chunk_overlap=50：相邻块重叠50字（避免切断上下文）
示意图：
┌────────────────────────────────────────┐
│ 原文（1000字） │
└────────────────────────────────────────┘
↓ 切片
┌──────────────┐
│ 块1 (500字) │
└──────────────┘
┌──────────────┐
│ 块2 (500字) │ ← 和块1重叠50字
└──────────────┘
3️⃣ 索引结构（Indexes）
作用：组织数据，让检索更快
核心类型对比：
| 索引类型 | 原理 | 速度 | 适用场景 | 生活比喻 |
|---|---|---|---|---|
| VectorStoreIndex | 语义相似度 | ⭐⭐⭐⭐⭐ | 最常用，适合问答 | 智能书架，自动把相关书放一起 |
| ListIndex | 线性扫描 | ⭐ | 文档少时 | 书堆成一摞 |
| TreeIndex | 树形结构 | ⭐⭐⭐ | 长文档总结 | 目录树 |
| KeywordTableIndex | 关键词匹配 | ⭐⭐⭐⭐ | 精确搜索 | 按关键词索引的卡片 |
推荐使用：VectorStoreIndex（90%的场景都够用）
from llama_index.core import VectorStoreIndex
# 构建向量索引（最智能！）
index = VectorStoreIndex.from_documents(documents)
4️⃣ 检索器（Retrievers）
作用：根据问题找到最相关的文档片段
工作原理：
你的问题："去年销售情况如何？"
↓ 转成向量
[0.21, -0.43, 0.65, ...]
↓ 在索引中比对
找到相似度最高的3个片段：
1. "2023年Q4销售额..." (相似度: 95%)
2. "去年全年销售..." (相似度: 88%)
3. "销售部门报告..." (相似度: 82%)
# 创建检索器，只返回最相关的2个片段
retriever = index.as_retriever(similarity_top_k=2)
# 检索！
nodes = retriever.retrieve("去年销售情况如何？")
5️⃣ 查询引擎（Query Engines）
作用：整合检索+生成，直接返回答案
三种模式：
# ① 标准问答模式（最常用）
query_engine = index.as_query_engine()
response = query_engine.query("去年销售如何？")
print(response) # → AI整理好的完整答案
# ② 聊天模式（支持多轮对话）
chat_engine = index.as_chat_engine()
chat_engine.chat("你好！")
chat_engine.chat("去年销售如何？") # ← 能记住上下文
chat_engine.chat("那今年呢？") # ← 知道你在问销售
# ③ 智能代理模式（能调用工具）
from llama_index.core.agent import ReActAgent
agent = ReActAgent.from_tools(tools, llm=llm)
agent.chat("帮我分析销售数据并生成图表") # ← 能自动调用计算器、画图工具等
🚀 实战教程：10分钟上手
前置准备
# 1. 安装LlamaIndex
pip install llama-index
# 2. 安装OpenAI库（默认使用GPT）
pip install openai
# 3. 设置API密钥
export OPENAI_API_KEY='你的密钥' # Mac/Linux
set OPENAI_API_KEY=你的密钥 # Windows
案例：建立公司文档问答系统
目录结构：
my_project/
├── data/ # 存放你的文档
│ ├── 产品手册.pdf
│ ├── 销售报告.docx
│ └── 技术文档.txt
└── main.py # 主程序
📝 完整代码（含详细注释）
# main.py
# ==================== 第1步：导入库 ====================
from llama_index.core import (
SimpleDirectoryReader, # 文档加载器
VectorStoreIndex, # 向量索引
Settings # 全局设置
)
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.llms.openai import OpenAI
# ==================== 第2步：配置模型 ====================
Settings.llm = OpenAI(model="gpt-3.5-turbo", temperature=0.1)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# ==================== 第3步：加载文档 ====================
print("📖 正在加载文档...")
documents = SimpleDirectoryReader('data').load_data()
print(f"✅ 成功加载 {len(documents)} 份文档")
# ==================== 第4步：构建索引 ====================
print("🔨 正在构建索引（第一次会慢一点）...")
index = VectorStoreIndex.from_documents(documents, show_progress=True)
print("✅ 索引构建完成！")
# ==================== 第5步：创建查询引擎 ====================
query_engine = index.as_query_engine(
similarity_top_k=3, # 返回最相关的3个片段
response_mode="compact" # 紧凑模式，答案更简洁
)
# ==================== 第6步：开始提问 ====================
print("\n" + "="*50)
print("🤖 AI助手已就绪！输入'退出'结束对话")
print("="*50 + "\n")
while True:
question = input("👤 你的问题: ")
if question.lower() in ['退出', 'quit', 'exit']:
print("👋 再见！")
break
print("🤔 思考中...")
response = query_engine.query(question)
print(f"\n🤖 AI回答:\n{response}\n")
print("-"*50 + "\n")
🎯 运行效果
📖 正在加载文档...
✅ 成功加载 3 份文档
🔨 正在构建索引...
100%|████████████████████| 3/3 [00:02<00:00]
✅ 索引构建完成！
==================================================
🤖 AI助手已就绪！输入'退出'结束对话
==================================================
👤 你的问题: 我们公司主要产品是什么？
🤔 思考中...
🤖 AI回答:
根据产品手册，公司主要产品包括：
1. 企业级管理软件（占比45%）
2. 数据分析平台（占比30%）
3. 云存储服务（占比25%）
--------------------------------------------------
👤 你的问题: 去年销售额多少？
🤔 思考中...
🤖 AI回答:
根据销售报告显示，2023年全年销售额为2.3亿元，
同比增长18%，其中Q4单季度突破7000万元。
--------------------------------------------------
🎓 进阶技巧
技巧1：持久化索引（避免重复构建）
# 第一次：构建并保存
index = VectorStoreIndex.from_documents(documents)
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)
技巧2：自定义切片策略
from llama_index.core.node_parser import SentenceSplitter
# 按句子切分，每块3个句子
splitter = SentenceSplitter(chunk_size=3, chunk_overlap=1)
nodes = splitter.get_nodes_from_documents(documents)
技巧3：使用本地模型（免费！）
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
# 使用本地Ollama（需先安装Ollama）
Settings.llm = Ollama(model="llama2")
# 使用本地嵌入模型
Settings.embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-small-zh-v1.5" # 中文模型
)
技巧4：流式输出（像ChatGPT那样逐字显示）
query_engine = index.as_query_engine(streaming=True)
response = query_engine.query("介绍一下产品")
# 逐字打印
for text in response.response_gen:
print(text, end="", flush=True)
技巧5：添加元数据过滤
from llama_index.core import Document
# 加载时添加元数据
doc1 = Document(text="...", metadata={"部门": "销售", "年份": 2023})
doc2 = Document(text="...", metadata={"部门": "技术", "年份": 2023})
# 查询时过滤
from llama_index.core.vector_stores import MetadataFilters, ExactMatchFilter
filters = MetadataFilters(filters=[
ExactMatchFilter(key="部门", value="销售")
])
query_engine = index.as_query_engine(filters=filters)
response = query_engine.query("销售情况") # 只在销售部门文档里找
🔥 性能优化建议
速度对比表
| 优化手段 | 效果 | 难度 |
|---|---|---|
| 持久化索引 | 构建时间 100x ↓ | ⭐ |
| 减少chunk_size | 查询速度 2x ↑ | ⭐ |
| 使用本地嵌入模型 | 成本 100% ↓ | ⭐⭐ |
| 添加元数据过滤 | 准确度 30% ↑ | ⭐⭐ |
| 使用GPU加速 | 向量化速度 10x ↑ | ⭐⭐⭐ |
推荐配置
# 平衡配置（适合大多数场景）
Settings.chunk_size = 512 # 每块512字符
Settings.chunk_overlap = 50 # 重叠50字符
Settings.similarity_top_k = 3 # 返回3个相关片段
# 高速配置（牺牲一点准确度）
Settings.chunk_size = 256
Settings.similarity_top_k = 2
# 高精度配置（速度会慢一点）
Settings.chunk_size = 1024
Settings.chunk_overlap = 100
Settings.similarity_top_k = 5
❓ 常见问题解答
Q1: 文档太大怎么办？
A: 分批处理或使用元数据过滤
# 方法1：分批构建索引
from llama_index.core import SimpleDirectoryReader
docs_batch1 = SimpleDirectoryReader('data/2023').load_data()
docs_batch2 = SimpleDirectoryReader('data/2024').load_data()
index1 = VectorStoreIndex.from_documents(docs_batch1)
index2 = VectorStoreIndex.from_documents(docs_batch2)
# 方法2：查询时指定目录
query_engine = index1.as_query_engine() # 只查2023年的
Q2: 答案不准确怎么办？
A: 调整以下参数
- 增加返回片段数：
similarity_top_k=5 - 减小chunk_size：更精细的切分
- 调整提示词：
from llama_index.core import PromptTemplate
template = (
"你是专业的文档分析助手。\n"
"请根据以下内容回答问题，如果不确定就说不知道。\n\n"
"文档内容：{context_str}\n\n"
"问题：{query_str}\n\n"
"答案："
)
query_engine = index.as_query_engine(
text_qa_template=PromptTemplate(template)
)
Q3: 支持中文吗？
A: 完全支持！推荐使用中文嵌入模型
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
# 中文模型推荐
Settings.embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-large-zh-v1.5" # 最佳
# 或 "shibing624/text2vec-base-chinese" # 备选
)
Q4: 能处理PDF、Word吗？
A: 需要安装额外依赖
pip install pypdf # PDF支持
pip install docx2txt # Word支持
pip install llama-index-readers-file # 文件读取器
Q5: 如何调试查看检索到的原文？
A: 查看source_nodes
response = query_engine.query("问题")
# 打印AI答案
print(response)
# 查看引用的原文片段
for i, node in enumerate(response.source_nodes, 1):
print(f"\n片段{i}（相似度: {node.score:.2f}）:")
print(node.text[:200]) # 打印前200字
Q6: 花费多少钱？
A: 成本估算（使用OpenAI）
- 嵌入（构建索引）：$0.0001 / 1K tokens
- 1万字文档 ≈ 15K tokens ≈ $0.0015（约￥0.01）
- 生成答案：$0.002 / 1K tokens（GPT-3.5）
- 每次查询 ≈ 2K tokens ≈ $0.004（约￥0.03）
节省成本方法：
- 使用本地模型（Ollama）→ 完全免费
- 持久化索引 → 避免重复构建
- 使用更小的嵌入模型
📊 架构全景图
┌───────────────────────────────────────────────────────────────┐
│ LlamaIndex 完整架构 │
└───────────────────────────────────────────────────────────────┘
【数据源层】
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ PDF │ │ Word │ │ 网页 │ │ 数据库 │
└─────┬────┘ └─────┬────┘ └─────┬────┘ └─────┬────┘
└─────────────┴──────────────┴─────────────┘
↓
┌──────────────────┐
│ 数据连接器层 │
│ (Readers/Loaders)│
└─────────┬────────┘
↓
【Document对象】
↓
┌──────────────────┐
│ 文档解析器层 │
│ (Node Parsers) │
│ - 文本切片 │
│ - 元数据提取 │
└─────────┬────────┘
↓
【Node对象数组】
↓
┌──────────────────┐
│ 嵌入模型层 │
│ (Embed Models) │
│ - OpenAI │
│ - HuggingFace │
└─────────┬────────┘
↓
【向量数组】
↓
┌──────────────────┐
│ 索引存储层 │
│ (Vector Stores) │
│ - 内存 │
│ - Chroma │
│ - Pinecone │
└─────────┬────────┘
↓
╔═══════════════════════════════════╗
║ 【索引 Index】 ║
║ 可持久化、可查询的知识库 ║
╚═══════════════════════════════════╝
↓
┌──────────────────┴──────────────────┐
↓ ↓
┌──────────────┐ ┌──────────────┐
│ 检索器层 │ │ 查询引擎层 │
│ (Retrievers) │ │(Query Engine)│
│ - 向量检索 │ │- QA模式 │
│ - 关键词检索 │ │- Chat模式 │
│ - 混合检索 │ │- Agent模式 │
└──────┬───────┘ └──────┬───────┘
└────────────┬───────────────────┘
↓
┌──────────────┐
│ LLM层 │
│ (语言模型) │
│ - OpenAI │
│ - Ollama │
└──────┬───────┘
↓
【最终答案】
🎯 总结与学习路线
核心要点回顾
-
LlamaIndex = 智能文档助手
- 把你的文档变成可查询的知识库
- 用AI理解问题并生成答案
-
三步走
documents = SimpleDirectoryReader('data').load_data() # 加载 index = VectorStoreIndex.from_documents(documents) # 索引 response = index.as_query_engine().query("问题") # 查询 -
核心技术
- 向量化（把文字变数字）
- 相似度检索（找最相关的内容）
- LLM生成（整理成答案）
学习路线图
第1周：入门
├─ 理解RAG概念
├─ 跑通基础示例
└─ 处理自己的文档
第2周：进阶
├─ 尝试不同索引类型
├─ 调整参数优化效果
└─ 添加元数据过滤
第3周：实战
├─ 使用本地模型
├─ 持久化索引
└─ 构建聊天界面
第4周：高级
├─ 自定义提示词
├─ 多索引查询
└─ 接入生产环境
推荐资源
- 官方文档：docs.llamaindex.ai/
- GitHub：github.com/run-llama/l…
- 中文社区：www.llamaindex.ai/zh-Hans
🎉 结语
恭喜你！现在你已经掌握了LlamaIndex的核心知识。
记住这个比喻：
LlamaIndex = 智能图书馆系统
- 你负责提供书籍（文档）
- 它负责整理和检索
- AI负责总结答案
从现在开始，你可以：
- ✅ 把公司文档变成智能问答系统
- ✅ 快速从论文中提取信息
- ✅ 构建个人知识库助手
- ✅ 开发行业垂直领域应用
最后的建议：不要只看教程，动手实践才是王道！
💡 立即行动：找3份你的文档，用10分钟跑通第一个示例吧！
📧 有问题？欢迎交流！
Made with ❤️ for AI Learners
