LlamaIndex：RAG数据框架安装与使用指南

LlamaIndex

官方信息

项目名称	LlamaIndex
仓库地址	https://github.com/run-llama/llama_index
官方网站	https://www.llamaindex.ai
最新更新时间	2026-10-23
Star 数	38k+
项目定位	结构化连接私有数据与大语言模型的 RAG 数据框架

项目背景

LlamaIndex 是目前最流行的 RAG 应用开发框架之一。它解决的核心问题是：大模型虽然知识渊博，但不知道你公司内部的文档、数据库、API 里有什么。LlamaIndex 就像一座桥梁，把你的私有数据（PDF、Notion、网页、数据库、API）结构化后，喂给大模型，让它基于你的数据回答问题。

和 LangChain 这种"全能框架"不同，LlamaIndex 的定位非常专注：它专门做数据接入、切分、索引、检索这一段。从最简单的"读一个 PDF 然后问问题"，到复杂的多级索引、路由检索、Rerank、Agentic RAG，LlamaIndex 提供了模块化的组件，开发者像搭积木一样组装自己的 RAG 管线。

LlamaIndex 生态非常丰富：官方提供了几百个数据连接器（PDF、Notion、Slack、Confluence、数据库、S3 等），支持所有主流向量数据库（Chroma、Qdrant、Pinecone、Weaviate），同时也有 JavaScript/TypeScript 版本。很多 RAG 产品底层都是用 LlamaIndex 构建的。

核心特性

丰富的数据连接器：内置 160+ Loader，支持 PDF、Word、网页、Notion、数据库、API、S3 等。
多种索引结构：VectorStoreIndex、SummaryIndex、KnowledgeGraphIndex、TreeIndex、KeywordTableIndex。
高级检索策略：混合检索、递归检索、路由检索、自动检索（Auto Retriever）、Rerank。
模块化设计：文档解析、切分、Embedding、向量存储、检索器、重排器全部可替换。
Agent 支持：内置 ReAct、Function Calling Agent，能调用工具和检索器。
LlamaHub：社区共享的 500+ 数据加载器和自定义组件，pip 直接装。
可视化：提供 LlamaIndex Studio 调试工具，可视化查看检索过程。

环境要求

项目	最低要求	推荐配置
操作系统	任意（Linux/macOS/Windows）	Ubuntu 22.04
Python	3.9	3.10 / 3.11
内存	4 GB	8 GB+
磁盘	5 GB	20 GB+
GPU	无（用 OpenAI API 时）	本地 Embedding 时可选

详细部署步骤

第一步：环境准备

conda create -n llamaindex python=3.10 -y
conda activate llamaindex

第二步：安装 LlamaIndex

方式一：pip 安装核心包

pip install llama-index

# 验证
python -c "import llama_index; print(llama_index.__version__)"

方式二：安装全功能（含所有集成）

# 安装常见集成
pip install llama-index-core llama-index-llms-openai llama-index-embeddings-openai
pip install llama-index-vector-stores-chroma llama-index-readers-file

方式三：源码安装

git clone https://github.com/run-llama/llama_index.git
cd llama_index
pip install -e .

第三步：设置 API Key

# OpenAI
export OPENAI_API_KEY=sk-xxxxxxxx

# 或用 DeepSeek（兼容 OpenAI 接口）
export OPENAI_API_KEY=sk-xxxxxxxx
export OPENAI_API_BASE=https://api.deepseek.com/v1

第四步：快速开始——5 行代码做 RAG

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 1. 加载 data/ 目录下所有文档
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)

第五步：使用本地 Embedding 模型（不用 OpenAI）

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings

# 设置本地 Embedding 模型（中文推荐 bge-small-zh）
Settings.embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-zh-v1.5"
)
Settings.chunk_size = 512

documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("什么是RAG？")
print(response)

第六步：持久化向量库（生产推荐）

import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import StorageContext

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

# 用 Chroma 作为向量存储
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 构建索引（数据会持久化到 ./chroma_db）
index = VectorStoreIndex.from_documents(
    documents, storage_context=storage_context
)

# 下次直接加载，不用重新 Embedding
index = VectorStoreIndex.from_vector_store(
    vector_store, storage_context=storage_context
)

第七步：高级检索——混合检索 + Rerank

from llama_index.core.retrievers import QueryFusionRetriever
from llama_index.core.postprocessor import SentenceTransformerRerank

# 混合检索（向量 + BM25）
retriever = QueryFusionRetriever(
    [index.as_retriever(similarity_top_k=5)],
    similarity_top_k=10,
    num_queries=4,  # 自动生成 4 个查询变体
    use_async=True,
)

# Rerank 重排序
rerank = SentenceTransformerRerank(
    model="cross-encoder/ms-marco-MiniLM-L-2-v2", top_n=3
)

query_engine = index.as_query_engine(
    retriever=retriever,
    node_postprocessors=[rerank]
)

第八步：部署为 API 服务

# 安装 FastAPI 工具
pip install llama-index-server

# 启动 API 服务
llamaindex-server serve ./storage

常见坑与解决

ImportError：LlamaIndex 拆分成了很多子包，缺少哪个就 pip install llama-index-xxx。
Embedding 慢：首次下载模型需要时间，预下载好 HuggingFace 模型。
检索不准：调整 chunk_size（512-1024），加 Rerank，用混合检索。
版本兼容：LlamaIndex 更新很快，升级前看 changelog，0.10 后 API 变化较大。

使用方法示例

最简流程：把 PDF 放进 data/ 目录，运行上面的 5 行代码，就能基于 PDF 提问。生产环境建议：用 Chroma/Qdrant 做向量持久化、加 Rerank、设置 chunk_size 512、中文用 bge 系列 Embedding。

常见问题 FAQ

Q1：LlamaIndex 和 LangChain 区别？
A：LlamaIndex 专注 RAG 数据管线，检索和索引能力更强；LangChain 是通用 LLM 框架，Agent 和工具调用更全。做知识库优先 LlamaIndex，做 Agent 优先 LangChain。

Q2：支持哪些向量数据库？
A：Chroma、Qdrant、Pinecone、Weaviate、Milvus、PGVector、Redis 等几十种。

Q3：能处理多少文档？
A：取决于向量数据库，Chroma 适合几万文档以内；生产百万级用 Qdrant/Milvus。

Q4：支持中文吗？
A：支持，但需要用中文 Embedding 模型（bge-zh 系列），不要用默认的 English 模型。

Q5：有 Node.js 版本吗？
A：有，TypeScript 版本叫 LlamaIndex.TS，API 和 Python 版对齐。

跳转链接

GitHub 仓库：https://github.com/run-llama/llama_index
官方文档：https://docs.llamaindex.ai
LlamaHub 组件库：https://llamahub.ai

LlamaIndex：RAG数据框架安装与使用指南

LlamaIndex：RAG数据框架安装与使用指南

官方信息

项目背景

核心特性

环境要求

详细部署步骤

第一步：环境准备

第二步：安装 LlamaIndex

第三步：设置 API Key

第四步：快速开始——5 行代码做 RAG

第五步：使用本地 Embedding 模型（不用 OpenAI）

第六步：持久化向量库（生产推荐）

第七步：高级检索——混合检索 + Rerank

第八步：部署为 API 服务

常见坑与解决

使用方法示例

常见问题 FAQ

跳转链接

周若琳

文章目录