run-llama/llama_index · 上手攻略

  • 仓库：run-llama/llama_index
  • 链接：https://github.com/run-llama/llama_index
  • 分类：ai
  • 作者：Jay
  • 更新：2026-07-10

一、是什么

LlamaIndex 是一个开源框架，用于构建 Agentic（智能体）应用。它最初以"RAG（检索增强生成）框架"闻名，随着大模型 Agent 概念的兴起，已逐步演进为覆盖文档解析、索引构建、知识库问答、Agent 编排的完整技术栈。

核心组件：

组件 定位
LlamaParse 文档解析平台（Agentic OCR），支持 130+ 格式文档提取
LlamaAgents 可部署的文档 Agent 运行时
Extract 从非结构化文档中做结构化数据抽取
Index 数据摄取、RAG 索引管道

项目配套有商业平台 LlamaCloud，提供企业级解析、存储服务。开源框架本身完全免费。

二、解决什么问题

  1. 文档解析乱码/结构丢失 — 传统 OCR 对 PDF/PPT/Word 效果差，LlamaParse 专门解决多格式复杂文档的结构化解析。
  2. RAG 管道搭建繁琐 — 自行实现分块、向量化、检索、注入链路容易踩坑，LlamaIndex 提供开箱即用的抽象层。
  3. 多 Agent 协作缺乏框架 — LlamaAgents 提供多 Agent 之间的任务分发与结果聚合机制。
  4. 300+ 集成生态碎片化 — LlamaHub 提供统一的集成接口，切换 LLM / Embedding / VectorStore 无需重写业务代码。

三、快速安装

方式一：Starter 包（推荐新手）

包含核心库 + 常用集成包（OpenAI、Chroma、Pinecone 等）：

pip install llama-index

方式二：自定义精简安装

只装核心，按需从 LlamaHub 追加集成包：

pip install llama-index-core
# 按需追加集成，例如：
pip install llama-index-llms-openai
pip install llama-index-vector-stores-chroma
pip install llama-index-embeddings-huggingface

环境依赖

  • Python ≥ 3.9（建议 3.10+）
  • 部分功能需要 Node.js（如 LlamaAgents Web 界面）

四、核心用法

4.1 基础 RAG 问答（5 行代码）

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai import OpenAI

# 1. 加载文档（支持 PDF、MD、TXT、CSV 等）
documents = SimpleDirectoryReader("./data").load_data()

# 2. 选 LLM
llm = OpenAI(model="gpt-4o-mini", api_key="your-api-key")

# 3. 构建索引
index = VectorStoreIndex.from_documents(documents)

# 4. 查询
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("这份文档的核心结论是什么？")
print(response)

4.2 使用本地模型（Ollama）

from llama_index.llms.ollama import Ollama
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

llm = Ollama(model="qwen2.5:7b", request_timeout=120)

documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("总结主要观点")

4.3 文档解析（LlamaParse）

LlamaParse 需要 LlamaCloud API Key，有免费额度。

from llama_parse import LlamaParse
from llama_index.core import VectorStoreIndex

# 设置 API Key（环境变量）
import os
os.environ["LLAMA_CLOUD_API_KEY"] = "your-llamacloud-key"

# 解析 PDF，返回结构化文档对象
parser = LlamaParse(result_type="markdown")
documents = parser.load_data("./report.pdf")

index = VectorStoreIndex.from_documents(documents)

4.4 高级检索（Hybrid Search + Rerank）

from llama_index.core import VectorStoreIndex
from llama_index.core.retrievers import VectorIndexRetriever
from llama_index.postprocessor.cohere_rerank import CohereRerank

# 构建索引
index = VectorStoreIndex.from_documents(documents)

# 配置向量检索 + 重排
retriever = VectorIndexRetriever(index=index, similarity_top_k=20)
reranker = CohereRerank(api_key="your-cohere-key", top_n=5)

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

4.5 LlamaAgents（多 Agent 编排）

from llama_index.core.agent import AgentRunner
from llama_index.llms.openai import OpenAI
from llama_index.tools.tavily import TavilyToolSpec

llm = OpenAI(model="gpt-4o")
tools = TavilyToolSpec(api_key="your-tavily-key").to_tool_list()

agent = AgentRunner.from_tools(tools, llm=llm)
response = agent.chat("帮我查询 2026 年 AI Agent 领域的最新进展")

五、典型适用场景

场景 推荐组合
企业内部知识库问答 LlamaParse + Milvus/Qdrant + GPT-4o
合同/报告结构化抽取 LlamaParse + Extract + OpenAI
私域文档 RAG llama-index + Ollama/本地 Embedding
多 Agent 协作（搜索+分析+报告） LlamaAgents + Tavily + 代码执行工具
客服机器人（带知识库） LlamaIndex + VectorStore + History

六、坑与注意

⚠️ 版本分裂问题

LlamaIndex 存在较长时间的版本迭代，早期代码示例可能使用旧 API（如 VectorStoreIndex.from_dict）。建议以官方最新文档为准，本攻略基于 2026 年中最新版。

⚠️ Token 成本

  • llama-index starter 包默认包含多个 LLM 集成，容易在不知觉中调用付费 API
  • 使用本地模型前确保 Ollama 已启动：ollama serve

⚠️ Embedding 模型选择

  • 默认有时会尝试调用 OpenAI Embedding，需要显式指定本地模型： python from llama_index.embeddings.huggingface import HuggingFaceEmbedding embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-m3") index = VectorStoreIndex.from_documents(documents, embed_model=embed_model)

⚠️ LlamaParse 是付费服务

免费额度有限，生产环境建议评估 LlamaCloud 定价。

⚠️ 性能提示

  • 大文档集分批处理：batch_size 参数控制
  • 生产环境使用异步 API：ainject、arun 系列

七、与同类对比

特性 LlamaIndex LangChain Haystack (deepset)
RAG 抽象层 ✅ 成熟 ✅ 成熟 ✅ 成熟
文档解析（OCR） ✅ LlamaParse 强 ❌ 弱 ❌ 弱
Agent 编排 ✅ LlamaAgents ✅ LCEL ⚪ 较弱
集成数量 300+ 100+ 较少
本地模型支持 ✅ 好 ✅ 好 ✅ 好
上手难度 中等 中等偏高 中等
维护活跃度 非常活跃 非常活跃 活跃

结论：如果核心需求是文档解析 + RAG + Agent 链路，LlamaIndex 是当前最完整的开源选择；如果已在用 LangChain 生态，可以继续用 LangChain 的 RAG 模块。

八、一句话结论

LlamaIndex 是目前最完整的开源 Agentic 应用框架，从文档解析到 RAG 再到多 Agent 编排一站式搞定，是构建企业级知识库和 AI 应用的首选底座之一。

来源

  • GitHub README: https://github.com/run-llama/llama_index
  • LlamaIndex 官方文档: https://developers.llamaindex.ai/
  • LlamaCloud: https://cloud.llamaindex.ai