Llamaindex

项目地址： https://github.com/run-llama/llama_index

官方文档： https://docs.llamaindex.ai/（2026 年起 301 重定向至 https://developers.llamaindex.ai/python/framework/）

许可证： MIT

最新版本： llama-index 0.14.25、llama-index-core 0.14.25（PyPI 实测，截至 2026-10；GitHub 最新 Release 标签为 v0.14.25，集成包按组件独立发版）

概述

LlamaIndex 是连接大语言模型与私有数据的 Python 框架，核心流程是把文档切分为节点（Node）、建立索引并对外暴露查询与对话接口。

• 数据加载：SimpleDirectoryReader 等 Reader 把 PDF / Markdown / Word / 网页等解析为 Document
• 切分：SentenceSplitter、TokenTextSplitter 等 Node Parser 把 Document 切成带元数据的 Node
• 索引：VectorStoreIndex 建立向量索引，另有 SummaryIndex、KeywordTableIndex 等
• 存储：StorageContext 统一挂载向量库、文档库、索引库，可持久化到磁盘或外部数据库
• 检索与合成：Retriever 召回节点，Response Synthesizer 按响应模式（response_mode）合成答案
• 上层接口：Query Engine（单轮）、Chat Engine（多轮）、Router（多路选择）、Workflows（事件驱动）、Agent（工具调用）

包拆分（2026-10，pip install llama-index 元包仅拉取以下四项）：

其余向量库、嵌入、LLM 集成均为独立包，按需安装。

环境准备

安装

bashCopy code
# 元包：含 core 与 OpenAI 集成，开箱即用（要求 Python >= 3.10）
pip install llama-index

pip install llama-index-core

# 常用集成（按需）
pip install llama-index-embeddings-huggingface      # 本地嵌入模型
pip install llama-index-llms-ollama                 # 本地 LLM
pip install llama-index-vector-stores-chroma        # Chroma
pip install llama-index-vector-stores-postgres      # PostgreSQL / pgvector
pip install llama-index-vector-stores-qdrant        # Qdrant

API Key 配置

bashCopy code
export OPENAI_API_KEY="sk-..."        # Linux / macOS
set OPENAI_API_KEY=sk-...             # Windows cmd

在代码中加载 .env（需 pip install python-dotenv）：

pythonCopy code
from dotenv import load_dotenv

load_dotenv()

验证安装

bashCopy code
python -c "import llama_index.core; print(llama_index.core.__version__)"

pythonCopy code
from llama_index.llms.openai import OpenAI

llm = OpenAI(model="gpt-4o-mini")
print(llm.complete("用一句话说明 LlamaIndex 是什么"))

核心 API/命令

全局设置（Settings）

Settings 是全局单例，统一配置 LLM、嵌入模型与切分器，未显式传入的组件会回退到这里的默认值：

pythonCopy code
from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core.node_parser import SentenceSplitter

Settings.llm = OpenAI(model="gpt-4o-mini", temperature=0)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
Settings.text_splitter = SentenceSplitter(chunk_size=1024, chunk_overlap=200)

本地模型替换（离线场景）：

pythonCopy code
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.llms.ollama import Ollama
from llama_index.core import Settings

Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-zh-v1.5")
Settings.llm = Ollama(model="qwen3:8b", request_timeout=120.0)

文档加载与切分

pythonCopy code
from llama_index.core import SimpleDirectoryReader, Document
from llama_index.core.node_parser import SentenceSplitter

# 加载整个目录（可用 input_files 指定文件）
documents = SimpleDirectoryReader("data").load_data()
documents = SimpleDirectoryReader(input_files=["gis_manual.pdf"]).load_data()

# 也可直接构造 Document
documents = [Document(text="...", metadata={"source": "spec.md"})]

# 切分为节点
parser = SentenceSplitter(chunk_size=1024, chunk_overlap=200)
nodes = parser.get_nodes_from_documents(documents)

要点：chunk_overlap 必须小于 chunk_size；中文文档建议减小 chunk_size 并按标点切分；保留 metadata 便于溯源。

索引构建与持久化

pythonCopy code
from llama_index.core import VectorStoreIndex, StorageContext, load_index_from_storage

index = VectorStoreIndex.from_documents(documents)
index.storage_context.persist("storage")          # 持久化到磁盘

# 下次直接加载，无需重新向量化
storage_context = StorageContext.from_defaults(persist_dir="storage")
index = load_index_from_storage(storage_context)

也可在构建时指定切分器：VectorStoreIndex.from_documents(documents, transformations=[SentenceSplitter(...)])。

向量库对接

内存向量库适合快速试验；生产环境把外部向量库挂到 StorageContext 即可，索引代码基本不变：

pythonCopy code
import chromadb
from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.vector_stores.chroma import ChromaVectorStore

client = chromadb.PersistentClient(path="./chroma_db")
collection = client.get_or_create_collection("gis_docs")
vector_store = ChromaVectorStore(chroma_collection=collection)

storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

pythonCopy code
from sqlalchemy import make_url
from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.vector_stores.postgres import PGVectorStore

url = make_url("postgresql://user:pass@localhost:5432")
vector_store = PGVectorStore.from_params(
    database="vector_db",
    host=url.host,
    port=url.port,
    user=url.username,
    password=url.password,
    table_name="gis_docs",
    embed_dim=1536,                                # 需与嵌入模型维度一致
    hybrid_search=True,                            # 向量 + 全文混合检索
    text_search_config="simple",
)
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

从已有向量库恢复索引：VectorStoreIndex.from_vector_store(vector_store=vector_store)。

embed_dim 必须与所选嵌入模型的输出维度一致（如 text-embedding-3-small 为 1536），否则写入报错。

查询引擎与响应模式

pythonCopy code
query_engine = index.as_query_engine()             # 默认 response_mode="compact"
response = query_engine.query("如何做栅格重投影？")
print(response)                                    # 答案文本
for node in response.source_nodes:
    print(node.metadata.get("source"), node.score)  # 溯源

常用响应模式：

pythonCopy code
# 流式输出
index.as_query_engine(streaming=True).query("总结这份规范").print_response_stream()
# 摘要场景
index.as_query_engine(response_mode="tree_summarize")

聊天引擎（多轮）

pythonCopy code
from llama_index.core.memory import ChatMemoryBuffer

memory = ChatMemoryBuffer.from_defaults(token_limit=3000)
chat_engine = index.as_chat_engine(
    chat_mode="condense_plus_context",             # 见下表
    memory=memory,
    verbose=True,
)
print(chat_engine.chat("这份数据用什么坐标系？"))
print(chat_engine.chat("那它的精度是多少？"))       # 保留上文
chat_engine.reset()                                # 清空历史

chat_mode 取值：best（自动选择）、condense_question、context、condense_plus_context（推荐默认）、simple（纯 LLM 对话）、react（ReAct Agent）、openai（OpenAI Agent）。

路由（RouterQueryEngine）

当存在多个数据源或多种检索方式时，用 LLM 选择器按工具描述路由：

pythonCopy code
from llama_index.core.query_engine import RouterQueryEngine
from llama_index.core.selectors import LLMSingleSelector, PydanticSingleSelector
from llama_index.core.tools import QueryEngineTool

spec_tool = QueryEngineTool.from_defaults(
    query_engine=spec_engine,
    description="查询测绘规范条款与术语定义，适合规范类问题",
)
catalog_tool = QueryEngineTool.from_defaults(
    query_engine=catalog_engine,
    description="查询空间数据目录与图层元数据，适合数据检索类问题",
)

router = RouterQueryEngine(
    selector=PydanticSingleSelector.from_defaults(),
    query_engine_tools=[spec_tool, catalog_tool],
)
print(router.query("2000 国家大地坐标系的定义是什么？"))

LLMSingleSelector 把选项以文本注入提示词；PydanticSingleSelector 走函数调用返回结构化结果。多选场景用 LLMMultiSelector / PydanticMultiSelector。

工作流（Workflows）

Workflows 是事件驱动、按步骤执行的编排模型：每个 @step 接收一个事件、返回一个事件，返回事件的类型决定下一个执行的步骤。

pythonCopy code
from llama_index.core.workflow import Workflow, step, Event, StartEvent, StopEvent

class ParsedEvent(Event):
    nodes_count: int

class IngestFlow(Workflow):
    @step
    async def parse(self, ev: StartEvent) -> ParsedEvent:
        docs = SimpleDirectoryReader(ev.data_dir).load_data()
        index = VectorStoreIndex.from_documents(docs)
        return ParsedEvent(nodes_count=len(docs))

    @step
    async def report(self, ev: ParsedEvent) -> StopEvent:
        return StopEvent(result=f"已索引 {ev.nodes_count} 个文档")

w = IngestFlow(timeout=120, verbose=True)
result = await w.run(data_dir="data")               # 关键字参数进入 StartEvent
print(result)

要点：StartEvent / StopEvent 由框架提供；自定义事件是 Pydantic 对象；Context（ctx.store、ctx.send_event）用于跨步骤共享状态与动态分发。

Agent 与工具

pythonCopy code
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import FunctionTool

def multiply(a: float, b: float) -> float:
    """Multiply two numbers and return the product."""
    return a * b

agent = FunctionAgent(
    tools=[multiply, FunctionTool.from_defaults(fn=multiply)],
    llm=Settings.llm,
    system_prompt="你是助手，需要计算时调用工具。",
)
response = await agent.run(user_msg="20 + 2 * 4 等于多少？")

FunctionAgent 依据工具名、参数、docstring 与类型注解选择工具；普通函数可直接传入，FunctionTool.from_defaults 可显式指定名称与描述。其余 Agent 实现包括 ReActAgent、CodeActAgent。

典型工作流

工作流一：最小 RAG 问答

pythonCopy code
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
print(query_engine.query("文档中提到的数据精度是多少？"))

工作流二：GIS 规范知识库 + 地理编码工具 Agent

把规范知识库封装成查询引擎工具，把地理编码封装成函数工具，交给 FunctionAgent 编排：

pythonCopy code
import requests
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import QueryEngineTool

spec_index = VectorStoreIndex.from_documents(SimpleDirectoryReader("specs").load_data())
spec_tool = QueryEngineTool.from_defaults(
    query_engine=spec_index.as_query_engine(),
    name="spec_search",
    description="查询测绘/GIS 规范条款与术语定义，回答规范类问题",
)

def geocode(address: str) -> str:
    """把中文地址解析为经纬度，返回 'lon,lat'。

    Args:
        address: 待解析的地址文本，如 "成都市天府广场"
    """
    resp = requests.get(
        "https://nominatim.openstreetmap.org/search",
        params={"q": address, "format": "json", "limit": 1},
        headers={"User-Agent": "gis-rag-demo"},
        timeout=15,
    )
    hits = resp.json()
    if not hits:
        return f"未找到：{address}"
    return f"{hits[0]['lon']},{hits[0]['lat']}"

agent = FunctionAgent(
    tools=[spec_tool, geocode],
    llm=Settings.llm,
    system_prompt=(
        "你是 GIS 助手：规范与术语问题调用 spec_search；"
        "地址转坐标调用 geocode。不要臆测坐标数值。"
    ),
)
response = await agent.run(user_msg="成都市天府广场的坐标是多少？坐标系的定义依据哪份规范？")
print(response)

要点：Agent 只负责编排，坐标换算与空间分析逻辑应写在工具函数内部，不要让模型心算坐标。

最佳实践

1. 统一走 Settings：LLM、嵌入模型、切分器集中在 Settings 配置，切换供应商只改一处；单索引需要差异化时再按调用参数覆盖
2. 先切分再建索引：显式设置 chunk_size / chunk_overlap（overlap < size），中文按标点切分并适当减小 chunk；保留 metadata（source、页码）便于溯源
3. 嵌入维度对齐：外部向量库的 embed_dim 必须与嵌入模型输出维度一致，换模型时需重建索引
4. 持久化避免重复计算：实验阶段用 index.storage_context.persist() 落盘；生产环境改用 Chroma / PGVector / Qdrant，通过 from_vector_store 恢复
5. 响应模式按场景选：事实问答用 compact，长文摘要用 tree_summarize，需要溯源用 no_text 先看 source_nodes
6. 多轮对话用 Chat Engine：单轮问答用 Query Engine；多轮用 as_chat_engine(chat_mode="condense_plus_context", memory=ChatMemoryBuffer.from_defaults(token_limit=...))，避免历史无限增长
7. 多数据源用 Router：工具 description 即路由依据，必须写清"何时选我"，否则选择器误判
8. 复杂流程用 Workflows：把解析、索引、校验拆成 @step，用类型化事件串联，天然支持超时与可观测
9. 工具即接口：Agent 工具用清晰的 docstring 与类型注解，外部调用加超时；工具内异常应自行捕获返回文本，而不是抛出中断整个 Agent
10. 安全边界：数据库工具只开只读连接并设 statement_timeout；命令类工具用白名单；不要用 shell=True

常见问题

AI 使用建议

推荐工作流

1. 先跑通最小链路：SimpleDirectoryReader → VectorStoreIndex.from_documents → as_query_engine().query()，确认数据与 Key 正常后再叠加向量库、路由与 Agent
2. 逐层加能力：单轮问答 → 持久化/外部向量库 → Chat Engine 多轮 → Router 多源 → Workflows/Agent，每层单独验证
3. 工具先行：Agent 工具先用普通 Python 调通（含参数校验、超时与异常处理），再包成 FunctionTool 或直接传入 FunctionAgent
4. GIS 场景拆解：规范/文档做成向量知识库（spec_search），空间数据目录做成独立索引，地理编码等外部能力封装为函数工具，空间计算写在工具内部
5. 版本敏感：LlamaIndex 迭代快（当前 0.14.25），文档已从 docs.llamaindex.ai 迁至 developers.llamaindex.ai；API 以官方文档与 llama_index.core 源码为准

关键模式与常见陷阱

• 导入路径分两段：核心一律从 llama_index.core.* 导入，各集成从 llama_index.<类型>.<供应商> 导入（如 llama_index.vector_stores.chroma），两者不可混用
• Settings 是全局单例：在进程早期设置一次即可；忘记设置 embed_model 时默认回退 OpenAI 嵌入，离线环境会因缺少 Key 报错
• 维度必须对齐：PGVectorStore.from_params(embed_dim=...) 与嵌入模型维度不一致会写入失败，换嵌入模型需重建索引
• 不要编造：向量库类名、from_params 参数、selector 与 Agent 类名均以官方文档为准，升级后优先查 developers.llamaindex.ai

相关技能

• langchain — LLM 应用框架，LCEL 链与 LangGraph Agent，与 LlamaIndex 索引能力可互补
• dify — 可视化 LLM 应用平台，无需编码即可搭建 RAG 知识库与工作流
• docutranslate — 基于 LLM 的多格式文件翻译，可作为 RAG 文档预处理环节
• ollama — 本地模型运行时，可为 LlamaIndex 提供离线 LLM 与嵌入后端

参考资源

• 官方文档（现址）：https://developers.llamaindex.ai/python/framework/
• 查询引擎与响应模式：https://developers.llamaindex.ai/python/framework/module_guides/deploying/query_engine/
• Workflows：https://developers.llamaindex.ai/python/framework/understanding/workflows/
• Agent：https://developers.llamaindex.ai/python/framework/understanding/agent/
• GitHub Releases：https://github.com/run-llama/llama_index/releases
• PyPI：https://pypi.org/project/llama-index/