1. 引言：大模型的阿喀琉斯之踵

大语言模型（LLM）如 GPT-4、Claude 3.5 拥有令人惊叹的通用知识和推理能力，但它们存在两个关键局限：

· 知识截止日期：模型训练数据有截止时间，无法知晓最新的信息。
· 缺乏私有上下文：它们不了解你的企业内部文档、个人笔记、产品手册或项目代码库。

直接将这些敏感数据放入 prompt（提示词）作为上下文，不仅受限于模型的上下文窗口大小，成本高昂，且在海量数据中难以精准定位相关信息。这就是检索增强生成（Retrieval-Augmented Generation, RAG）要解决的核心问题，而 LlamaIndex 正是构建 RAG 系统最强大的数据框架之一。本文将带你从零开始，掌握使用 LlamaIndex 让大模型“读懂”私有数据的方法。

2. LlamaIndex 是什么？

LlamaIndex（前身为 GPT Index）是一个专为 LLM 应用设计的数据编排框架。它像一座桥梁，将大模型与你分散在不同数据源中的私有数据连接起来，提供了一套从数据摄取、索引构建到高级查询的完整工具链。

核心概念

· 数据连接器 (Data Connectors)：从 PDF、Markdown、数据库、Notion、Slack 等 160+ 种数据源中摄取数据。
· 节点 (Nodes)：原始文档被解析和切割后的最小单元，每个节点包含文本块和元数据。
· 索引 (Indexes)：将节点组织为易于检索的数据结构，如向量索引、树索引、关键词索引等。
· 查询引擎 (Query Engine)：接收自然语言问题，通过检索相关节点并交给 LLM 合成答案，是一个端到端的问答流水线。
· 聊天引擎 (Chat Engine)：在查询引擎基础上，增加了对话历史和上下文管理，支持多轮交互。
· 代理 (Agents)：由 LLM 自主决策，动态选择调用哪个工具（如查询引擎、计算器、API）来完成复杂任务。

典型工作流

1. 加载数据：用数据连接器将各类文档加载进内存。
2. 构建索引：将文档解析为节点，并基于这些节点构建索引结构。
3. 查询/对话：使用自然语言发起查询，系统返回带源引用的精准答案。

下图展示了一个基于 LlamaIndex 的简单问答流程：

3. 环境准备

在开始之前，请确保你安装了 Python 3.9+，并设置好 OpenAI API 密钥（或使用其他兼容模型）。

pip install llama-index openai

如果你想使用本地模型，可搭配 Ollama 或 HuggingFace 并安装相应依赖，本文以 OpenAI 示例为主。

在代码中设置 API 密钥：

import os
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

4. 快速上手：5 分钟构建文档问答

让我们通过一个最小化的例子体验完整流程。假设你有一个名为 data 的文件夹，里面存放了一份产品手册 manual.txt。

目录结构：

project/
├── data/
│   └── manual.txt
└── app.py

manual.txt 示例内容：

智能咖啡机-银河X1 使用指南

产品特性：
- 支持冷热双萃，可一键制作冷萃咖啡和意式浓缩。
- 内置智能研磨系统，支持30档粗细调节。
- 水箱容量2.5L，豆仓容量250g。

清洁与维护：
- 建议每制作200杯后运行除垢程序。
- 萃取器每周需取出用清水冲洗，晾干后放回。
- 机身外壳请用微湿软布擦拭，严禁使用酒精或腐蚀性清洁剂。

保修信息：
- 整机保修2年，加热核心保修5年。
- 非人为损坏免费维修，人为损坏需支付零件费。

代码实现

# app.py
from llama_index.core import (
    VectorStoreIndex,
    SimpleDirectoryReader,
    Settings
)
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

# 1. 配置全局大模型和嵌入模型
# 使用 gpt-3.5-turbo 以平衡速度和成本
Settings.llm = OpenAI(model="gpt-3.5-turbo", temperature=0)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")

# 2. 加载文档
# SimpleDirectoryReader 会自动读取 data 目录下的所有 .txt 文件
documents = SimpleDirectoryReader("data").load_data()
print(f"成功加载 {len(documents)} 份文档")

# 3. 构建索引
# 这一步会：解析文档→切割为节点→向量化→存入内存向量索引
index = VectorStoreIndex.from_documents(documents)

# 4. 创建查询引擎并提问
query_engine = index.as_query_engine()

# 第一条问题：提取具体参数
response_1 = query_engine.query("这款咖啡机的水箱容量是多少？")
print(f"Q: 这款咖啡机的水箱容量是多少？\nA: {response_1}\n")

# 第二条问题：需要理解维护流程
response_2 = query_engine.query("如何正确清洁萃取器？")
print(f"Q: 如何正确清洁萃取器？\nA: {response_2}\n")

# 第三条问题：涉及保修条款
response_3 = query_engine.query("如果我不小心摔坏了机器，保修能覆盖吗？")
print(f"Q: 如果我不小心摔坏了机器，保修能覆盖吗？\nA: {response_3}")

预期输出：

成功加载 1 份文档
Q: 这款咖啡机的水箱容量是多少？
A: 水箱容量为2.5L。

Q: 如何正确清洁萃取器？
A: 萃取器每周需取出用清水冲洗，晾干后放回。

Q: 如果我不小心摔坏了机器，保修能覆盖吗？
A: 不能，人为损坏需支付零件费。

至此，你已拥有了一个完全基于私有数据的智能问答系统。

5. 深入索引：控制文档解析与切割

上述示例使用了默认的分块策略，但在生产环境中，我们经常需要调整分块大小和重叠量以适应不同类型的文档。

LlamaIndex 将文档切割为 节点，你可以通过 SentenceSplitter 或 TokenTextSplitter 进行精细控制。

from llama_index.core import SimpleDirectoryReader, VectorStoreIndex, Settings
from llama_index.core.node_parser import SentenceSplitter
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

# 配置全局设置
Settings.llm = OpenAI(model="gpt-3.5-turbo", temperature=0)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")

# 自定义文本分割器
# chunk_size=512: 每个节点约含512个token
# chunk_overlap=50: 相邻节点之间重叠50个token，避免关键信息被切断
text_splitter = SentenceSplitter(chunk_size=512, chunk_overlap=50)

# 加载时直接指定分割器，或使用 ingest pipeline
documents = SimpleDirectoryReader("data").load_data()

# 构建索引时传入 transformations（转换流水线）
# LlamaIndex 会自动执行 解析 → 分块 → 向量化
index = VectorStoreIndex.from_documents(
    documents,
    transformations=[text_splitter, Settings.embed_model],  # 指定分块器与嵌入模型
)

query_engine = index.as_query_engine()
response = query_engine.query("咖啡机支持哪些萃取方式？")
print(response)

提示：如果你要处理 PDF，请安装 pip install pypdf，SimpleDirectoryReader 会自动处理 PDF 文件，无需修改代码。

6. 持久化索引：避免重复构建

向量化和索引构建耗时且消耗API费用。你可以将构建好的索引保存到磁盘，下次直接加载。

import os
from llama_index.core import (
    VectorStoreIndex,
    SimpleDirectoryReader,
    StorageContext,
    load_index_from_storage,
    Settings,
)
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

Settings.llm = OpenAI(model="gpt-3.5-turbo")
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")

PERSIST_DIR = "./storage"  # 索引持久化目录

# 检查持久化目录是否存在
if not os.path.exists(PERSIST_DIR):
    print("首次运行，构建索引并保存...")
    # 加载文档并构建索引
    documents = SimpleDirectoryReader("data").load_data()
    index = VectorStoreIndex.from_documents(documents)
    # 保存索引到磁盘
    index.storage_context.persist(persist_dir=PERSIST_DIR)
else:
    print("从磁盘加载已有索引...")
    # 重建存储上下文并加载索引
    storage_context = StorageContext.from_defaults(persist_dir=PERSIST_DIR)
    index = load_index_from_storage(storage_context)

# 正常使用查询引擎
query_engine = index.as_query_engine()
response = query_engine.query("除垢程序应该在什么时候运行？")
print(response)

这样，你的索引文件会保存在 storage 文件夹中，后续重启无需重新嵌入计算。

7. 多轮对话：构建聊天引擎

查询引擎是无状态的，每次提问独立。若要实现带记忆的连续对话，需使用 ChatEngine。

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core.memory import ChatMemoryBuffer

Settings.llm = OpenAI(model="gpt-3.5-turbo", temperature=0.7)  # 对话可适当提高温度
Settings.embed_model = OpenAIEmbedding()

documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)

# 创建带记忆缓冲的聊天引擎
# token_limit=3000: 保留最近3000个token的对话历史
memory = ChatMemoryBuffer.from_defaults(token_limit=3000)
chat_engine = index.as_chat_engine(
    chat_mode="condense_question",  # 模式：将对话历史凝练为独立问题
    memory=memory,
    verbose=True,  # 打印中间步骤，方便调试
)

# 模拟多轮对话
response_1 = chat_engine.chat("我的咖啡机是什么型号？")
print(f"用户: 我的咖啡机是什么型号？\n助手: {response_1}\n")

response_2 = chat_engine.chat("它的水箱容量是多大？")
print(f"用户: 它的水箱容量是多大？\n助手: {response_2}\n")

response_3 = chat_engine.chat("我该如何清洁那个可拆卸的零件？")
print(f"用户: 我该如何清洁那个可拆卸的零件？\n助手: {response_3}")

condense_question 模式会将 “它的水箱” 这样的指代，结合对话历史重写为 “智能咖啡机-银河X1的水箱容量”，从而确保检索准确。

8. 高级检索策略：融合多种索引

对于复杂场景，单一向量索引可能不够。LlamaIndex 支持组合多个索引，并使用路由或递归方式查询。

示例：结合摘要索引与向量索引

假设你有大量文档，可以先为每个文档生成摘要，当问题较为宽泛时路由到摘要索引，细节问题则路由到向量索引。这里展示一个简化版的多索引构建概念。

from llama_index.core import (
    VectorStoreIndex,
    SummaryIndex,
    SimpleDirectoryReader,
    Settings,
)
from llama_index.core.tools import QueryEngineTool, ToolMetadata
from llama_index.core.query_engine import RouterQueryEngine
from llama_index.core.selectors import LLMSingleSelector
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

Settings.llm = OpenAI(model="gpt-3.5-turbo")
Settings.embed_model = OpenAIEmbedding()

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

# 1. 构建向量索引：适合事实性、细节问题
vector_index = VectorStoreIndex.from_documents(documents)
vector_query_engine = vector_index.as_query_engine()

# 2. 构建摘要索引：适合“总结”、“概述”类问题
# SummaryIndex 会存储所有节点，默认按顺序取顶部节点交给LLM总结
summary_index = SummaryIndex.from_documents(documents)
summary_query_engine = summary_index.as_query_engine(response_mode="tree_summarize")

# 3. 包装为工具，并赋予描述
vector_tool = QueryEngineTool(
    query_engine=vector_query_engine,
    metadata=ToolMetadata(
        name="vector_search",
        description="用于查询具体的细节问题，比如尺寸、参数、日期、步骤。",
    ),
)
summary_tool = QueryEngineTool(
    query_engine=summary_query_engine,
    metadata=ToolMetadata(
        name="summary_search",
        description="用于回答需要概括、总结、整体描述的问题。",
    ),
)

# 4. 创建路由查询引擎，由 LLM 自动选择工具
router_engine = RouterQueryEngine(
    selector=LLMSingleSelector.from_defaults(),
    query_engine_tools=[vector_tool, summary_tool],
)

# 测试路由
print(router_engine.query("请概括这份文档的主要内容。"))  # 期望路由到 summary_search
print(router_engine.query("水箱容量精确值是多少？"))  # 期望路由到 vector_search

9. 生产环境最佳实践

· 元数据过滤：在加载文档时，通过 file_metadata 函数为每个节点附加文件名、日期、类别等元数据。查询时，使用 MetadataFilters 进行预过滤，显著提升准确率和速度。
· 混合检索：结合向量检索（语义匹配）和关键词检索（BM25）的混合模式，使用 HybridSearch 来覆盖精准术语查询。
· 成本控制：使用本地嵌入模型（如 BAAI/bge-small-en）替代 OpenAI Embedding；使用缓存（Settings.callback_manager 配合缓存处理器）避免重复 LLM 调用。
· 流式输出：调用 query_engine.query_stream() 或 chat_engine.stream_chat() 实现打字机效果，提升用户体验。

10. 与 LangChain 的协作

许多开发者会问：“应该选 LlamaIndex 还是 LangChain？” 答案并非二选一。LangChain 是一个通用的 LLM 应用框架，擅长链式调用、Agent 和复杂工作流编排；LlamaIndex 则聚焦数据索引与检索，在 RAG 领域提供了更强大、更开箱即用的工具。最佳实践是将 LlamaIndex 的查询引擎作为 LangChain 的一个 Tool 来使用：

from langchain.agents import initialize_agent, Tool
from langchain_openai import ChatOpenAI

# 假设已经构建好 llama_query_engine
def query_llama_index(query: str) -> str:
    return str(llama_query_engine.query(query))

tool = Tool(
    name="Knowledge Base",
    func=query_llama_index,
    description="用于查询公司内部知识库，涵盖产品手册、规章制度。"
)

langchain_agent = initialize_agent(
    [tool],
    ChatOpenAI(model="gpt-4", temperature=0),
    agent="zero-shot-react-description",
    verbose=True
)

langchain_agent.run("根据知识库，最新的差旅报销标准是什么？顺便换算成欧元是多少？")

这样，LlamaIndex 专注私有数据问答，LangChain 负责调用外部 API（如汇率计算）和多步推理，各司其职。

11. 总结

通过本文，你已经掌握了从零开始使用 LlamaIndex 构建私有数据问答系统的核心技能：

1. 使用 SimpleDirectoryReader 加载数据。
2. 通过 VectorStoreIndex 快速构建可查询的索引。
3. 利用 自定义分块 优化检索粒度。
4. 持久化索引，加速后续启动。
5. 用 ChatEngine 实现多轮对话。
6. 通过 路由查询引擎 组合多种索引策略。

LlamaIndex 的能力远不止于此，它还支持结构化数据（SQL）、多模态检索、递归检索等高级特性。当你有海量私有数据需要与大模型深度集成时，LlamaIndex 是一个可靠且高效的选择。现在，动手为你的文档建立一个智能助手吧！