LlamaIndex

LlamaIndex 快速入门

一句话卖点:让 AI 读懂你的数据 —— 从 PDF 到 SQL 数据库,LlamaIndex 是 LLM 和你的私有数据之间的桥梁。

这是什么?适合谁?

LlamaIndex 是 Jerarchy 团队 2022 年开源、专为 LLM 设计的数据框架 (Data Framework),主仓库 run-llama/llama_index。它跟 LangChain 最大的区别是:LlamaIndex 专注于「让 LLM 读懂数据」,而不是「让 LLM 调工具」。

核心能力:

• 数据连接器 (Loaders):PDF、Word、Notion、Slack、SQL、API 等上百种数据源一键加载;
• 索引 (Indexing):Vector Index(向量)、List Index(列表)、Keyword Index(关键词)、Tree Index(树) 等多种索引;
• 检索 (Retrieval):语义检索 + 关键词检索 + 混合检索 + 重排序;
• Agent 推理:基于 LlamaIndex 的 Workflow / Agent 引擎,可让 LLM 多步推理;
• 集成:原生支持 OpenAI、Anthropic、HuggingFace、Ollama 等数十家 LLM 提供商。

适合谁?一是做 RAG 应用的开发者(文档问答、知识库搜索、企业私域知识助手);二是企业数据团队,需要让 LLM 访问结构化数据(SQL、API)和非结构化数据(PDF、网页);三是多数据源 Agent 团队,用 LlamaIndex Workflow 编排复杂任务;四是研究/咨询行业,需要把成百上千份报告/论文喂给 LLM 做总结。

不适合:只需要简单对话(用 ChatGPT 即可)、不需要私有数据增强的通用 Agent(用 LangChain 更合适)、纯前端/无后端 场景。

准备工作

1. 环境:Python ≥ 3.10;
2. 安装:pip install llama-index (基础包),pip install llama-index-llms-openai(OpenAI 集成);
3. API Key:OpenAI / Anthropic / DeepSeek / Ollama 至少一个;
4. 数据:准备好文档(PDF、Markdown、网页、SQL 等);
5. 前置知识:Python 基础、向量数据库基本概念、LLM prompt 概念。

3 步快速上手

第 1 步:安装依赖

pip install llama-index llama-index-llms-openai llama-index-embeddings-openai
export OPENAI_API_KEY="sk-xxx"

第 2 步:加载文档并创建索引

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 把 my_docs/ 目录下所有 PDF/MD/Docx 等加载进来
documents = SimpleDirectoryReader("my_docs/").load_data()
print(f"加载了 {len(documents)} 个文档片段")

# 一行代码创建向量索引
index = VectorStoreIndex.from_documents(documents)

# 持久化(下次不用重新嵌入)
index.storage_context.persist(persist_dir="./storage")

第 3 步:查询 + 流式输出

# 非流式
query_engine = index.as_query_engine()
response = query_engine.query("这份合同的关键条款是什么?")
print(response)

# 流式
streaming_qe = index.as_query_engine(streaming=True)
streaming_response = streaming_qe.query("总结第二季度的销售趋势")
streaming_response.print_response_stream_buffer()

初级用法

• 多种索引:VectorStoreIndex(语义)、ListIndex(全文)、KeywordTableIndex(关键词) — 不同场景选不同索引;
• 自定义 Node Parser:用 SentenceSplitter(chunk_size=512, chunk_overlap=50) 控制分块粒度;
• 持久化索引:index.storage_context.persist(persist_dir) 后下次 load_index_from_storage() 即可;
• 简单 Chat Engine:index.as_chat_engine() 支持多轮对话,自动维护历史;
• 元数据过滤:query_engine.query("xxx", filters=MetadataFilters(...)) 根据 metadata 过滤检索范围。

高级玩法

• RAG Fusion / Hybrid Search:在 RetrieverQueryEngine 中加入 BM25 + 向量混合检索,比纯向量召回率提升 10~20%;
• 重排序 (Reranking):用 Cohere Rerank 或 BGE-Reranker 对初筛结果二次排序,显著提升长文档问答准确度;
• Self-RAG / Corrective-RAG:用 LlamaIndex Workflow 编排「检索→评估→补检索」循环,自动修正错误回答;
• Recursive Retrieval:让小索引指向大索引,适合大型文档树(法律条文、手册说明书);
• 多模态 RAG:用 MultiModalVectorStoreIndex 索引 PDF 里的图片 + 文本,实现「图表问答」;
• 生产部署:index.as_query_engine() 包装到 FastAPI,前面挂 Nginx 负载均衡即可;
• 成本优化:大文档预处理时用更便宜的嵌入模型(text-embedding-3-small),查询时再用大模型推理。

小技巧

1. 分块大小不是越大越好:chunk_size=1024 + chunk_overlap=50 是大多数文档的甜点,长问答场景可以试 2048;
2. 嵌入模型选 Stable 版本:text-embedding-3-large 比 text-embedding-3-small 检索精度高约 15%,但成本高 6 倍;
3. 预处理 PDF 时开 OCR:用 SimpleDirectoryReader 默认只取文本,扫描版 PDF 需装 pytesseract;
4. 元数据提前打标签:加载文档时 file_metadata=lambda f: {"category": "法律"},后面过滤检索事半功倍;
5. Streaming + Chat 组合:聊文档时用流式 + ChatMemory 体感最自然,比一次性返回体验好;
6. 用 Ollama 跑本地嵌入:pip install llama-index-embeddings-ollama,配合本地 bge-m3 模型零成本做 RAG;
7. 异步批量 ingest:asyncio.run(loader.aload_data()) 处理大文档集比同步快 5-10 倍。

常见踩坑

踩坑 1:嵌入模型 token 超限

• 症状:Token limit exceeded 或 BadRequestError: chunk too large
• 原因:文档太大,单次嵌入超过模型 token 限制(OpenAI text-embedding-3-large 是 8191 tokens)
• 解决:用 SentenceSplitter(chunk_size=1024) 分块,或在加载前过滤超长文档

踩坑 2:检索结果不相关

• 症状:AI 回答和文档内容无关,或者「一本正经胡说八道」
• 原因:嵌入模型选错、chunk 策略不合理、或 prompt 指令不清晰
• 解决:换嵌入模型(text-embedding-3-large)、调 chunk_size、加 hybrid search、加 reranker

踩坑 3:首次构建索引慢 / 烧钱

• 症状:1000 页 PDF 索引花 30 分钟,OpenAI 账单几百美元
• 原因:每页都调嵌入 API,量很大
• 解决:①先用 100 页测试确认效果;②用更便宜的嵌入模型;③构建前过滤重复内容

踩坑 4:重启后索引丢失

• 症状:代码重启后又要花半小时重新构建索引
• 原因:没调用 persist()
• 解决:构建完用 index.storage_context.persist(persist_dir="./storage"),下次用 load_index_from_storage 加载

踩坑 5:中文检索效果差

• 症状:中文文档检索准确率明显低于英文
• 原因:LlamaIndex 默认的 text-splitter 对中文分句不准确
• 解决:用中文专用分句器 SpacySentenceSplitter(配合 zh_core_web_sm 模型),或换 bge-zh 嵌入

踩坑 6:幻觉 (Hallucination) 严重

• 症状:LLM 编造文档里没有的内容
• 原因:prompt 没强调「只能基于文档回答」,或检索返回空时 LLM 自由发挥
• 解决:①自定义 text_qa_template 加「只引用文档内容」;②设置 similarity_top_k=3 限制来源;③用 refine 或 tree_summarize 响应合成模式

常见问题 FAQ

Q1: LlamaIndex 是免费的吗?

A: LlamaIndex Python 包是 MIT 开源免费。LlamaIndex 自家的云服务 LlamaCloud 提供托管的 RAG 管道,免费层每月 1 万页处理额度,超出按页计费($0.30/千页);Starter $50/月(10 万页)、Pro $500/月(100 万页)、Enterprise 定制。本地化部署 LlamaIndex 完全免费,只需自己付 LLM API 费用。

Q2: LlamaIndex 和 LangChain 怎么选?

A: 简单原则 —— 数据密集型选 LlamaIndex(RAG、文档问答、知识库);Agent/工具密集型选 LangChain(多步推理、API 工具调用)。两者可同时使用:LangChain 做 Agent 编排,内部用 LlamaIndex 检索文档。LlamaIndex 实际上也有 Workflow 和 agent 模块,但生态偏数据侧。

Q3: LlamaIndex 支持哪些数据源?

A: 原生支持 PDF(支持 OCR + 表格提取)、Word、Markdown、HTML、Notion、Slack、Discord、Twitter、YouTube 转录、SQL 数据库、Postgres、MongoDB、Stripe、GitHub、Jira、Confluence 等上百种。完整列表见 llama-index-readers-* 系列包。

Q4: 大量文档(>10万页)性能如何?

A: 单机 LlamaIndex 处理 10 万页文档需要:Qdrant / Weaviate / Milvus 等向量数据库作为后端(不要用内存版),配合 GPU 嵌入推理或批处理 API。LlamaCloud 商业版能处理百万页级,内置分片和分布式检索。生产场景建议提前压测。

Q5: LlamaIndex 支持本地 LLM 吗?

A: 支持。用 pip install llama-index-llms-ollama 或 llama-index-llms-huggingface,配合 Ollama 跑的 Qwen、DeepSeek、Llama 等模型。可以做到「完全本地 + 完全离线 + 完全免费」的 RAG 链路,适合数据敏感场景。

进阶学习建议

LlamaIndex 生态分三层,分层学比一次性通读文档高效得多。建议路径:

• 第 1 层:跑通基础 RAG(3~5 天):跑完本文 3 步上手 + as_chat_engine() 多轮对话 + persist/load 持久化。这一层能应付 80% 的简单文档问答场景;
• 第 2 层:索引策略选型(1~2 周):学习不同索引(Vector / List / Keyword / Tree)的适用场景,做小型 benchmark 决定用哪种;掌握自定义 Node Parser 和 Metadata Filters;
• 第 3 层:Workflow / Agent 编排(2~4 周):用 Workflow 类编排 Self-RAG、Corrective-RAG 等多步流程;学会画状态机、写 Event handlers、整合工具调用;
• 第 4 层:生产优化(持续):Hybrid search + Reranker、监控检索质量、prompt 迭代、成本治理(嵌入缓存/批处理)、多租户隔离。

关键参考资料:① LlamaIndex 官方文档 的 Learn 模块按主题分章节;② Cookbook 有上百个实战 notebook;③ RAG 方向论文(REALM、Self-RAG、Corrective-RAG);④ LlamaIndex 官方 Discord 和 GitHub Discussions(几乎每个问题都能找到答案)。建议每学完一层做一个完整项目:第 1 层做”内部 wiki 问答”、第 2 层做”论文库检索”、第 3 层做”多步研究助手”。

参考链接

• LlamaIndex 官网
• LlamaIndex GitHub
• LlamaIndex 文档
• LlamaCloud 托管服务
• Cookbook 实战示例

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测