LlamaIndex 使用指南

• 1. LlamaIndex 简介
  • 1.1 什么是 LlamaIndex
  • 1.2 为什么需要 LlamaIndex
• 2. LlamaIndex 核心功能
  • 2.1 数据连接器（Data Connectors）
  • 2.2 数据索引（Data Indexes）
  • 2.3 引擎（Engines）
  • 2.4 数据代理（Data Agents）
  • 2.5 应用集成（Application Integrations）
• 3. 快速开始
  • 3.1 安装
  • 3.2 基本使用示例
  • 4.1 实现目标
  • 4.2 技术方案
  • 4.3 待实现功能
• 5. 高级功能
  • 5.1 流式响应
  • 5.2 多文档查询
  • 5.3 持久化索引
• 6. 最佳实践
  • 6.1 文档预处理
  • 6.2 索引优化
  • 6.3 性能优化
• 7. 参考资源

1. LlamaIndex 简介

1.1 什么是 LlamaIndex

LlamaIndex 是一个用于 LLM（大型语言模型）应用程序的数据框架，用于注入、结构化并访问私有或特定领域数据。它提供了一套完整的工具链，帮助开发者构建基于 LLM 的应用。

1.2 为什么需要 LlamaIndex

在本质上，LLM（如 GPT）为人类和推断出的数据提供了基于自然语言的交互接口。广泛可用的大模型通常在大量公开可用的数据上进行预训练，包括来自维基百科、邮件列表、书籍和源代码等。

然而，构建在 LLM 模型之上的应用程序通常需要使用私有或特定领域数据来增强这些模型。不幸的是，这些数据可能分布在不同的应用程序和数据存储中：

• 存在于 API 之后
• 保存在 SQL 数据库中
• 存储在 PDF 文件中
• 分散在幻灯片和文档中

LlamaIndex 就是为了解决这些问题而设计的。

2. LlamaIndex 核心功能

LlamaIndex 提供五大核心工具：

2.1 数据连接器（Data Connectors）

数据连接器支持将各种数据源注入到 LlamaIndex 中：

• API 接口：连接外部 API 获取数据
• 文档文件：PDF、Word、Markdown 等
• 数据库：SQL、NoSQL 数据库
• 网页内容：爬取网页数据
• 其他格式：CSV、JSON、XML 等

2.2 数据索引（Data Indexes）

用于将数据转换为 LLM 容易理解和消费的数据格式。支持多种索引类型：

• 向量索引（Vector Store Index）：将文档转换为向量进行相似度检索
• 摘要索引（Summary Index）：生成文档摘要
• 树形索引（Tree Index）：构建层次化的文档结构
• 关键词索引（Keyword Table Index）：基于关键词的快速检索

2.3 引擎（Engines）

提供查询、对话等主要功能：

• 查询引擎（Query Engine）：执行自然语言查询
• 对话引擎（Chat Engine）：支持多轮对话
• 数据增强：结合外部数据增强回答质量

2.4 数据代理（Data Agents）

智能代理可以自主决策和执行任务：

• 自动选择合适的工具
• 链式调用多个操作
• 处理复杂的多步骤任务

2.5 应用集成（Application Integrations）

对接生态中的其他框架和工具：

• LangChain：与 LangChain 无缝集成
• Flask/FastAPI：快速构建 Web 服务
• ChatGPT：与 OpenAI API 集成
• Streamlit：构建交互式应用界面

3. 快速开始

3.1 安装

使用 pip 安装 LlamaIndex：

pip install llama-index

3.2 基本使用示例

from llama_index import VectorStoreIndex, SimpleDirectoryReader

# 加载文档
documents = SimpleDirectoryReader('data').load_data()

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

# 创建查询引擎
query_engine = index.as_query_engine()

# 执行查询
response = query_engine.query("文档的主要内容是什么？")
print(response)

4.1 实现目标

构建一个完全离线的知识库系统，具备以下特点：

• ✅ 完全离线，无外部 API 依赖
• ✅ 细粒度问答搜索
• ✅ 多模态数据索引
• ✅ 更好的中文支持

4.2 技术方案

4.2.1 自定义 Embedding

使用本地 Embedding 模型替代 OpenAI API：

from llama_index.embeddings import HuggingFaceEmbedding
from llama_index import ServiceContext, VectorStoreIndex

# 使用本地中文 Embedding 模型
embed_model = HuggingFaceEmbedding(
    model_name="BAAI/bge-small-zh-v1.5"
)

# 创建服务上下文
service_context = ServiceContext.from_defaults(
    embed_model=embed_model,
    llm=None  # 使用本地 LLM
)

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

参考文档：https://docs.llamaindex.ai/en/stable/examples/embeddings/custom_embeddings/

4.2.2 自定义 Query Engine

实现对话检索并给出搜索来源：

from llama_index.query_engine import RetrieverQueryEngine
from llama_index.response_synthesizers import get_response_synthesizer

# 创建检索器
retriever = index.as_retriever(similarity_top_k=3)

# 创建响应合成器
response_synthesizer = get_response_synthesizer(
    response_mode="compact",
    service_context=service_context
)

# 创建查询引擎
query_engine = RetrieverQueryEngine(
    retriever=retriever,
    response_synthesizer=response_synthesizer,
)

# 执行查询并获取来源
response = query_engine.query("问题？")
print(f"回答: {response}")
print(f"来源: {response.source_nodes}")

4.3 待实现功能

• 使用自定义 Embedding 连接本地 Embedding 服务
• 实现自定义 Query Engine 支持来源追踪
• 添加中文分词和优化
• 支持多模态数据（图片、表格等）
• 实现对话历史管理

5. 高级功能

5.1 流式响应

支持流式输出，提升用户体验：

streaming_response = query_engine.query("问题？")
for text in streaming_response.response_gen:
    print(text, end="")

5.2 多文档查询

同时查询多个索引：

from llama_index.tools import QueryEngineTool
from llama_index.query_engine import SubQuestionQueryEngine

# 创建多个查询工具
query_engine_tools = [
    QueryEngineTool.from_defaults(
        query_engine=index1.as_query_engine(),
        description="关于主题 A 的文档"
    ),
    QueryEngineTool.from_defaults(
        query_engine=index2.as_query_engine(),
        description="关于主题 B 的文档"
    ),
]

# 创建子问题查询引擎
query_engine = SubQuestionQueryEngine.from_defaults(
    query_engine_tools=query_engine_tools
)

5.3 持久化索引

保存和加载索引以提升性能：

# 保存索引
index.storage_context.persist(persist_dir="./storage")

# 加载索引
from llama_index import StorageContext, load_index_from_storage

storage_context = StorageContext.from_defaults(
    persist_dir="./storage"
)
index = load_index_from_storage(storage_context)

6. 最佳实践

6.1 文档预处理

1. 清洗数据：去除无关内容和噪音
2. 分块策略：合理设置文档块大小（chunk_size）
3. 元数据管理：添加文档元数据便于检索

6.2 索引优化

1. 选择合适的索引类型：根据数据特点选择
2. 调整检索参数：优化 similarity_top_k 等参数
3. 定期更新索引：保持数据的时效性

6.3 性能优化

1. 使用缓存：缓存 Embedding 结果
2. 批量处理：批量加载和索引文档
3. 异步处理：使用异步 API 提升并发性能

7. 参考资源

• https://docs.llamaindex.ai/ - LlamaIndex 官方文档（英文）
• https://llama-index.readthedocs.io/zh/latest/ - 非官方中文文档
• https://llamahub.ai/ - LlamaHub 社区
• https://github.com/run-llama/llama_index - GitHub 仓库
• https://docs.llamaindex.ai/en/stable/examples/ - 官方示例