llamaindex

LlamaIndex - 大模型应用数据框架

连接大模型与数据的领先框架。

何时使用 LlamaIndex

在以下情况下使用 LlamaIndex：

• 构建 RAG（检索增强生成）应用
• 需要基于私有数据进行文档问答
• 从多个来源导入数据（300+ 个连接器）
• 为大模型创建知识库
• 使用企业数据构建聊天机器人
• 需要从文档中提取结构化数据

指标：

• 23,000+ 个代码仓库在使用 LlamaIndex
• 300+ 个数据连接器（LlamaHub）
• 1,715+ 位贡献者
• v0.14.7（稳定版）

以下情况可改用其他方案：

• LangChain：用途更广，更适合 Agent
• Haystack：生产级搜索流水线
• txtai：轻量级语义搜索
• Chroma：仅需向量存储

快速入门

安装

# Starter package (recommended)
pip install llama-index

# Or minimal core + specific integrations
pip install llama-index-core
pip install llama-index-llms-openai
pip install llama-index-embeddings-openai

5 行 RAG 示例

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# Load documents
documents = SimpleDirectoryReader("data").load_data()

# Create index
index = VectorStoreIndex.from_documents(documents)

# Query
query_engine = index.as_query_engine()
response = query_engine.query("What did the author do growing up?")
print(response)

核心概念

1. 数据连接器 - 加载文档

from llama_index.core import SimpleDirectoryReader, Document
from llama_index.readers.web import SimpleWebPageReader
from llama_index.readers.github import GithubRepositoryReader

# Directory of files
documents = SimpleDirectoryReader("./data").load_data()

# Web pages
reader = SimpleWebPageReader()
documents = reader.load_data(["https://example.com"])

# GitHub repository
reader = GithubRepositoryReader(owner="user", repo="repo")
documents = reader.load_data(branch="main")

# Manual document creation
doc = Document(
    text="This is the document content",
    metadata={"source": "manual", "date": "2025-01-01"}
)

2. 索引 - 组织数据

from llama_index.core import VectorStoreIndex, ListIndex, TreeIndex

# Vector index (most common - semantic search)
vector_index = VectorStoreIndex.from_documents(documents)

# List index (sequential scan)
list_index = ListIndex.from_documents(documents)

# Tree index (hierarchical summary)
tree_index = TreeIndex.from_documents(documents)

# Save index
index.storage_context.persist(persist_dir="./storage")

# Load index
from llama_index.core import load_index_from_storage, StorageContext
storage_context = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage_context)

3. 查询引擎 - 提出问题

# Basic query
query_engine = index.as_query_engine()
response = query_engine.query("What is the main topic?")
print(response)

# Streaming response
query_engine = index.as_query_engine(streaming=True)
response = query_engine.query("Explain quantum computing")
for text in response.response_gen:
    print(text, end="", flush=True)

# Custom configuration
query_engine = index.as_query_engine(
    similarity_top_k=3,          # Return top 3 chunks
    response_mode="compact",     # Or "tree_summarize", "simple_summarize"
    verbose=True
)

4. 检索器 - 查找相关片段

# Vector retriever
retriever = index.as_retriever(similarity_top_k=5)
nodes = retriever.retrieve("machine learning")

# With filtering
retriever = index.as_retriever(
    similarity_top_k=3,
    filters={"metadata.category": "tutorial"}
)

# Custom retriever
from llama_index.core.retrievers import BaseRetriever

class CustomRetriever(BaseRetriever):
    def _retrieve(self, query_bundle):
        # Your custom retrieval logic
        return nodes

使用工具的 Agent

详细信息、代码示例和参数表：references/agents-with-tools.md。适用时请阅读。

高级 RAG 模式

详细信息、代码示例和参数表：references/advanced-rag-patterns.md。适用时请阅读。

数据导入模式

多种文件类型

# Load all supported formats
documents = SimpleDirectoryReader(
    "./data",
    recursive=True,
    required_exts=[".pdf", ".docx", ".txt", ".md"]
).load_data()

网页抓取

from llama_index.readers.web import BeautifulSoupWebReader

reader = BeautifulSoupWebReader()
documents = reader.load_data(urls=[
    "https://docs.python.org/3/tutorial/",
    "https://docs.python.org/3/library/"
])

数据库

from llama_index.readers.database import DatabaseReader

reader = DatabaseReader(
    sql_database_uri="postgresql://user:pass@localhost/db"
)
documents = reader.load_data(query="SELECT * FROM articles")

API 端点

from llama_index.readers.json import JSONReader

reader = JSONReader()
documents = reader.load_data("https://api.example.com/data.json")

向量存储集成

Chroma（本地）

from llama_index.vector_stores.chroma import ChromaVectorStore
import chromadb

# Initialize Chroma
db = chromadb.PersistentClient(path="./chroma_db")
collection = db.get_or_create_collection("my_collection")

# Create vector store
vector_store = ChromaVectorStore(chroma_collection=collection)

# Use in index
from llama_index.core import StorageContext
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
import pinecone

# Initialize Pinecone
pinecone.init(api_key="your-key", environment="us-west1-gcp")
pinecone_index = pinecone.Index("my-index")

# Create vector store
vector_store = PineconeVectorStore(pinecone_index=pinecone_index)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

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

FAISS（快速）

from llama_index.vector_stores.faiss import FaissVectorStore
import faiss

# Create FAISS index
d = 1536  # Dimension of embeddings
faiss_index = faiss.IndexFlatL2(d)

vector_store = FaissVectorStore(faiss_index=faiss_index)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

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

自定义

自定义大模型

from llama_index.llms.anthropic import Anthropic
from llama_index.core import Settings

# Set global LLM
Settings.llm = Anthropic(model="claude-sonnet-4-5-20250929")

# Now all queries use Anthropic
query_engine = index.as_query_engine()

自定义嵌入

from llama_index.embeddings.huggingface import HuggingFaceEmbedding

# Use HuggingFace embeddings
Settings.embed_model = HuggingFaceEmbedding(
    model_name="sentence-transformers/all-mpnet-base-v2"
)

index = VectorStoreIndex.from_documents(documents)

自定义提示词模板

from llama_index.core import PromptTemplate

qa_prompt = PromptTemplate(
    "Context: {context_str}\n"
    "Question: {query_str}\n"
    "Answer the question based only on the context. "
    "If the answer is not in the context, say 'I don't know'.\n"
    "Answer: "
)

query_engine = index.as_query_engine(text_qa_template=qa_prompt)

多模态 RAG

图像 + 文本

from llama_index.core import SimpleDirectoryReader
from llama_index.multi_modal_llms.openai import OpenAIMultiModal

# Load images and documents
documents = SimpleDirectoryReader(
    "./data",
    required_exts=[".jpg", ".png", ".pdf"]
).load_data()

# Multi-modal index
index = VectorStoreIndex.from_documents(documents)

# Query with multi-modal LLM
multi_modal_llm = OpenAIMultiModal(model="gpt-4o")
query_engine = index.as_query_engine(llm=multi_modal_llm)

response = query_engine.query("What is in the diagram on page 3?")

评估

响应质量

from llama_index.core.evaluation import RelevancyEvaluator, FaithfulnessEvaluator

# Evaluate relevance
relevancy = RelevancyEvaluator()
result = relevancy.evaluate_response(
    query="What is Python?",
    response=response
)
print(f"Relevancy: {result.passing}")

# Evaluate faithfulness (no hallucination)
faithfulness = FaithfulnessEvaluator()
result = faithfulness.evaluate_response(
    query="What is Python?",
    response=response
)
print(f"Faithfulness: {result.passing}")

最佳实践

1. 大多数情况下使用向量索引 - 性能最佳
2. 将索引保存到磁盘 - 避免重新建立索引
3. 合理拆分文档 - 最佳长度为 512-1024 个词元
4. 添加元数据 - 支持筛选和跟踪
5. 使用流式传输 - 长响应的用户体验更好
6. 开发期间启用详细日志 - 查看检索过程
7. 评估响应 - 检查相关性和忠实度
8. 对话时使用聊天引擎 - 内置记忆功能
9. 持久化存储 - 避免丢失索引
10. 监控成本 - 跟踪嵌入和大模型的用量

常见模式

文档问答系统

# Complete RAG pipeline
documents = SimpleDirectoryReader("docs").load_data()
index = VectorStoreIndex.from_documents(documents)
index.storage_context.persist(persist_dir="./storage")

# Query
query_engine = index.as_query_engine(
    similarity_top_k=3,
    response_mode="compact",
    verbose=True
)
response = query_engine.query("What is the main topic?")
print(response)
print(f"Sources: {[node.metadata['file_name'] for node in response.source_nodes]}")

带记忆的聊天机器人

# Conversational interface
chat_engine = index.as_chat_engine(
    chat_mode="condense_plus_context",
    verbose=True
)

# Multi-turn chat
while True:
    user_input = input("You: ")
    if user_input.lower() == "quit":
        break
    response = chat_engine.chat(user_input)
    print(f"Bot: {response}")

性能基准

操作	延迟	备注
为 100 份文档建立索引	~10-30s	一次性操作，可持久化
查询（向量）	~0.5-2s	检索 + 大模型
流式查询	首个词元约 ~0.5s	用户体验更好
使用工具的 Agent	~3-8s	多次调用工具

LlamaIndex 与 LangChain 对比

特性	LlamaIndex	LangChain
最适合	RAG、文档问答	Agent、通用大模型应用
数据连接器	300+（LlamaHub）	100+
RAG 侧重	核心功能	众多功能之一
学习曲线	对 RAG 更容易上手	更陡峭
自定义能力	高	很高
文档	优秀	良好

在以下情况下使用 LlamaIndex：

• 主要用例是 RAG
• 需要大量数据连接器
• 希望使用更简单的文档问答 API
• 正在构建知识检索系统

在以下情况下使用 LangChain：

• 正在构建复杂的 Agent
• 需要用途更广的工具
• 希望获得更高的灵活性
• 需要复杂的多步骤工作流

参考资料

• 查询引擎指南 - 查询模式、自定义、流式传输
• Agent 指南 - 工具创建、RAG Agent、多步骤推理
• 数据连接器指南 - 300+ 个连接器、自定义加载器

资源

• GitHub：https://github.com/run-llama/llama_index ⭐ 45,100+
• 文档：https://developers.llamaindex.ai/python/framework/
• LlamaHub：https://llamahub.ai（数据连接器）
• LlamaCloud：https://cloud.llamaindex.ai（企业版）
• Discord：https://discord.gg/dGcwcsnxhU
• 版本：0.14.7+
• 许可证：MIT

Agent 操作流程

1. 检查环境。 确认框架版本、模型提供商、API 密钥和速率限制。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会影响结果的值都应询问确认，不要猜测。
3. 先运行小规模版本。 使用已知输入测试单次调用或链，并检查原始输出。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 使用小型标注集进行评估；检查结构化输出是否符合其架构；记录提示词和响应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
输出与预期架构不符	添加验证和重试、收紧架构，或简化提示词。
这些说明中的函数、标志或端点在已安装版本中不存在	查看已安装版本自己的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 未经用户同意，切勿将私人或敏感数据发送到外部 API。
• 此处与特定版本相关的详情可能已过时：请对照已安装版本的官方文档进行确认。
• 涉及费用、占用共享 GPU 或云配额、接触个人或患者数据，或无法撤销的操作，均须事先征求同意。

相关技能

• langchain：用于构建由大模型驱动的应用程序的框架，支持 Agent、链和 RAG。
• chroma：用于 AI 应用的开源嵌入数据库。
• langsmith-observability：用于跟踪、评估和监控的大模型可观测性平台。