深入理解 LlamaIndex：RAG 框架核心概念与实践

1. LlamaIndex 介绍

官网标题：「 Build AI Knowledge Assistants over your enterprise data 」

LlamaIndex 是一个为开发「知识增强」的大语言模型应用的框架。知识增强，泛指任何在私有或特定领域数据基础上应用大语言模型的情况。例如：

在这里补充一张图。

• Question-Answering Chatbots(也就是 RAG)
• Document Understanding and Extraction（文档理解与信息抽取）
• Autonomous Agentsthat can perform research and take actions （智能体应用）
• Workflow orchestratingsingle and multi-agent (编排单个或多个智能体形成工作流）

LlamaIndex 有 Python 和 Typescript 两个版本，Python 版的文档相对更完善。

• Python 文档地址：docs.llamaindex.ai/en/stable/
• Python API 接口文档：docs.llamaindex.ai/en/stable/a…
• TS 文档地址：ts.llamaindex.ai/
• Github 链接：github.com/run-llama

LlamaIndex 的核心模块

2. 安装 LlamaIndex

pip install llama-index

2.1 核心概念

在深入学习 LlamaIndex 之前，我们先了解几个核心概念：

• Document（文档）：

LlamaIndex 中的基本数据单元，代表一个完整的文档（如 PDF、网页、文本文件等）。每个 Document 包含文本内容以及可选的元数据（metadata）。

• Node（节点）：

Document 被切分后的文本片段，是检索和索引的基本单位。每个 Node 包含文本内容、元数据以及与其他 Node 的关系信息。

• Index（索引）：

为了快速检索而构建的数据结构。LlamaIndex 支持多种索引类型，如向量索引、关键词索引等。

• Retriever（检索器）：

负责从索引中检索相关 Node 的组件，根据查询返回最相关的文档片段。

• Query Engine（查询引擎）：

结合检索器和 LLM，根据检索到的上下文生成最终答案。

• Chat Engine（对话引擎）：

支持多轮对话的查询引擎，能够维护对话历史上下文。

数据流转过程：

Document → Node → Index → Retriever → Query/Chat Engine → Response

3. 数据加载（Loading）

3.1、加载本地数据

SimpleDirectoryReader是一个简单的本地文件加载器。它会遍历指定目录，并根据文件扩展名自动加载文件（文本内容）。

支持的文件类型：

• .csv- comma-separated values
• .docx- Microsoft Word
• .epub- EPUB ebook format
• .hwp- Hangul Word Processor
• .ipynb- Jupyter Notebook
• .jpeg,.jpg- JPEG image
• .mbox- MBOX email archive
• .md- Markdown
• .mp3,.mp4- audio and video
• .pdf- Portable Document Format
• .png- Portable Network Graphics
• .ppt,.pptm,.pptx- Microsoft PowerPoint

# 辅助函数：用于格式化展示 JSON 数据
import json
from pydantic.v1 import BaseModel

def show_json(data):
    """用于展示json数据"""
    if isinstance(data, str):
        obj = json.loads(data)
        print(json.dumps(obj, indent=4, ensure_ascii=False))
    elif isinstance(data, dict) or isinstance(data, list):
        print(json.dumps(data, indent=4, ensure_ascii=False))
    elif issubclass(type(data), BaseModel):
        print(json.dumps(data.dict(), indent=4, ensure_ascii=False))

def show_list_obj(data):
    """用于展示一组对象"""
    if isinstance(data, list):
        for item in data:
            show_json(item)
    else:
        raise ValueError("Input is not a list")

from llama_index.core import SimpleDirectoryReader

# 创建目录读取器
# input_dir: 要读取的目录路径
# recursive: 是否递归读取子目录（True/False）
# required_exts: 可选，指定只读取特定扩展名的文件
reader = SimpleDirectoryReader(
        input_dir="./data", 
        recursive=False, 
        required_exts=[".pdf"] 
    )

# 加载文档，返回 Document 对象列表
documents = reader.load_data()

print(documents[0].text)
show_json(documents[0].json())

默认的PDFReader效果并不理想，我们可以更换文件加载器

LlamaParse

首先，登录并从 cloud.llamaindex.ai ↗ 注册并获取 api-key 。

然后，安装该包：

pip install llama-cloud-services

# 在系统环境变量里配置 LLAMA_CLOUD_API_KEY=XXX
# 或使用 .env 文件配置（推荐）

from llama_cloud_services import LlamaParse
from llama_index.core import SimpleDirectoryReader
import nest_asyncio
from dotenv import load_dotenv

# 只在 Jupyter 环境中需要，解决异步事件循环问题
nest_asyncio.apply()

# 从 .env 文件加载环境变量
load_dotenv()

# 创建 LlamaParse 解析器
# result_type: 输出格式，"markdown" 或 "text"
parser = LlamaParse(result_type="markdown")

# 将 PDF 文件的解析器指定为 LlamaParse
file_extractor = {".pdf": parser}

# 使用自定义解析器加载文档
documents = SimpleDirectoryReader(
    input_dir="./data", 
    required_exts=[".pdf"], 
    file_extractor=file_extractor
).load_data()

print(documents[0].text)

3.2、Data Connectors

用于处理更丰富的数据类型，并将其读取为Document的形式。

例如：直接读取网页

pip install llama-index-readers-web

from llama_index.readers.web import SimpleWebPageReader

documents = SimpleWebPageReader(html_to_text=True).load_data(
    ["https://edu.guangjuke.com/tx/"]
)

print(documents[0].text)

️ 4. 文本切分与解析（Chunking）

为方便检索，我们通常把Document切分为Node。

在 LlamaIndex 中，Node被定义为一个文本的「chunk」。

️ 4.1、使用 TextSplitters 对文本做切分

例如：TokenTextSplitter按指定 token 数切分文本

from llama_index.core import Document
from llama_index.core.node_parser import TokenTextSplitter

# 创建文本切分器
# chunk_size: 每个 chunk 的最大 token 数（建议 256-1024，根据模型上下文窗口调整）
# chunk_overlap: chunk 之间的重叠 token 数（建议为 chunk_size 的 10-20%，保证上下文连续性）
node_parser = TokenTextSplitter(
    chunk_size=512,  
    chunk_overlap=200
)

# 将 Document 切分为 Node 列表
# show_progress: 是否显示进度条（处理大量文档时有用）
nodes = node_parser.get_nodes_from_documents(
    documents, 
    show_progress=False
)

# 查看切分后的 Node 结构
show_json(nodes[1].json())
show_json(nodes[2].json())

LlamaIndex 提供了丰富的TextSplitter，例如：

• SentenceSplitter：在切分指定长度的 chunk 同时尽量保证句子边界不被切断；
• CodeSplitter：根据 AST（编译器的抽象句法树）切分代码，保证代码功能片段完整；
• SemanticSplitterNodeParser：根据语义相关性对将文本切分为片段。

4.2、使用 NodeParsers 对有结构的文档做解析

例如：HTMLNodeParser解析 HTML 文档

from llama_index.core.node_parser import HTMLNodeParser
from llama_index.readers.web import SimpleWebPageReader

documents = SimpleWebPageReader(html_to_text=False).load_data(
    ["https://www.baidu.com/"]
)

# 默认解析 ["p", "h1", "h2", "h3", "h4", "h5", "h6", "li", "b", "i", "u", "section"]
parser = HTMLNodeParser(tags=["span"])  # 可以自定义解析哪些标签
nodes = parser.get_nodes_from_documents(documents)

for node in nodes:
    print(node.text+"n")

更多的NodeParser包括MarkdownNodeParser，JSONNodeParser等等。

4.3 文本切分最佳实践

Chunk Size 选择建议：

• 小文档（< 1000 字）：

chunk_size=256-512，chunk_overlap=50-100

• 中等文档（1000-10000 字）：

chunk_size=512-1024，chunk_overlap=100-200

• 大文档（> 10000 字）：

chunk_size=1024-2048，chunk_overlap=200-400

注意事项：

• Chunk size 需要根据 LLM 的上下文窗口大小调整（如 GPT-4 支持 128K，但实际使用时建议单个 chunk 不超过 2048 tokens）
• Overlap 过小可能导致上下文断裂，过大则增加存储和计算成本
• 对于代码文档，建议使用CodeSplitter保持代码块完整性
• 对于结构化文档（HTML、Markdown），优先使用对应的NodeParser而非简单切分

5. 索引（Indexing）与检索（Retrieval）

基础概念：

在「检索」相关的上下文中，「索引」即index， 通常是指为了实现快速检索而设计的特定「数据结构」。

索引的具体原理与实现不是本课程的教学重点，感兴趣的同学可以参考：传统索引、向量索引

5.1、向量检索

1. VectorStoreIndex直接在内存中构建一个 Vector Store 并建索引

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.node_parser import TokenTextSplitter, SentenceSplitter

# 1. 加载 PDF 文档
documents = SimpleDirectoryReader(
    "./data", 
    required_exts=[".pdf"],
).load_data()

# 2. 定义 Node Parser 用于切分文档
node_parser = TokenTextSplitter(chunk_size=512, chunk_overlap=200)

# 3. 将文档切分为 Node
nodes = node_parser.get_nodes_from_documents(documents)

# 4. 构建向量索引（默认在内存中，适合小规模数据）
# 构建过程会自动调用 Embedding 模型为每个 Node 生成向量
index = VectorStoreIndex(nodes)

# 方式二：直接从 Document 构建（会自动应用 transformations）
# index = VectorStoreIndex.from_documents(
#     documents=documents, 
#     transformations=[SentenceSplitter(chunk_size=512)]
# )

# 5. 持久化索引到本地（可选，用于后续复用）
# index.storage_context.persist(persist_dir="./doc_emb")

# 6. 创建检索器
# similarity_top_k: 返回最相似的前 k 个结果（建议 3-10，根据需求调整）
vector_retriever = index.as_retriever(
    similarity_top_k=2
)

# 7. 执行检索
# 检索过程：将查询文本转换为向量 → 在向量空间中搜索相似 Node → 返回结果
results = vector_retriever.retrieve("deepseek v3数学能力怎么样？")

# 8. 查看检索结果
print(results[0].text)

1. 使用自定义的 Vector Store，以Qdrant为例：

pip install llama-index-vector-stores-qdrant

from llama_index.core.indices.vector_store.base import VectorStoreIndex
from llama_index.vector_stores.qdrant import QdrantVectorStore
from llama_index.core import StorageContext

from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance

# 1. 创建 Qdrant 客户端
# location=":memory:": 内存模式（重启后数据丢失）
# location="./qdrant_db": 持久化到本地目录（推荐生产环境使用）
client = QdrantClient(location=":memory:")

# 2. 创建向量集合（Collection）
collection_name = "demo"
# size: 向量维度，需与 Embedding 模型输出维度一致（如 OpenAI text-embedding-3-small 为 1536）
# distance: 距离度量方式，COSINE（余弦相似度）适合文本检索
collection = client.create_collection(
    collection_name=collection_name,
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE)
)

# 3. 创建 Qdrant Vector Store
vector_store = QdrantVectorStore(client=client, collection_name=collection_name)

# 4. 创建存储上下文，关联自定义的 Vector Store
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 5. 使用自定义 Vector Store 创建索引
# 数据会存储在 Qdrant 中，而非内存
index = VectorStoreIndex(nodes, storage_context=storage_context)

# 6. 创建检索器
vector_retriever = index.as_retriever(similarity_top_k=1)

# 7. 执行检索
results = vector_retriever.retrieve("deepseek v3数学能力怎么样")

print(results[0])

5.2、更多索引与检索方式

LlamaIndex 内置了丰富的检索机制，例如：

• 关键字检索
• RAG-FusionQueryFusionRetriever
• 还支持 KnowledgeGraph、SQL、Text-to-SQL 等等

5.3、检索后处理

LlamaIndex 的Node Postprocessors提供了一系列检索后处理模块。

例如：我们可以用不同模型对检索后的Nodes做重排序

# 获取 retriever
vector_retriever = index.as_retriever(similarity_top_k=5)

# 检索
nodes = vector_retriever.retrieve("deepseek v3有多少参数?")

for i, node in enumerate(nodes):
    print(f"[{i}] {node.text}n")

from llama_index.core.postprocessor import LLMRerank

postprocessor = LLMRerank(top_n=2)

nodes = postprocessor.postprocess_nodes(nodes, query_str="deepseek v3有多少参数?")

for i, node in enumerate(nodes):
    print(f"[{i}] {node.text}")

更多的 Rerank 及其它后处理方法，参考官方文档：Node Postprocessor Modules

5.4 索引与检索最佳实践

内存 vs 持久化存储选择：

• 内存存储：适合小规模数据（< 1000 文档）、快速原型开发、一次性查询
• 持久化存储：适合生产环境、大规模数据、需要长期保存索引的场景

检索策略选择：

• 向量检索：适合语义搜索、相似度查询、多语言场景
• 关键词检索（BM25）：适合精确匹配、术语查询、代码搜索
• 混合检索：结合向量和关键词检索，通常效果最好（可用QueryFusionRetriever）

Embedding 模型选择：

• 中文场景：推荐使用支持中文的模型，如text-embedding-v3（DashScope）、bge-large-zh-v1.5（HuggingFace）
• 多语言场景：推荐text-embedding-3-small/large（OpenAI）、multilingual-e5-large
• 成本考虑：开源模型可本地部署，API 模型按调用次数收费

6. 生成回复（QA & Chat）

6.1 单轮问答（Query Engine）

# 创建查询引擎（单轮问答）
# Query Engine 内部流程：检索相关 Node → 构建 Prompt → 调用 LLM 生成回答
qa_engine = index.as_query_engine()

# 执行查询
response = qa_engine.query("deepseek v3数学能力怎么样?")

# 输出结果
print(response)

流式输出

# 启用流式输出，适合实时交互场景
qa_engine = index.as_query_engine(streaming=True)
response = qa_engine.query("deepseek v3数学能力怎么样?")

# 方式一：使用内置方法打印流式输出
response.print_response_stream()

# 方式二：手动控制输出（更灵活）
# for token in response.response_gen:
#     print(token, end="", flush=True)

6.2 多轮对话（Chat Engine）

chat_engine = index.as_chat_engine()
response = chat_engine.chat("deepseek v3数学能力怎么样?")
print(response)

response = chat_engine.chat("代码能力呢?")
print(response)

流式输出

chat_engine = index.as_chat_engine()

# 流式对话，逐 token 输出
streaming_response = chat_engine.stream_chat("deepseek v3数学能力怎么样?")

# 方式一：使用内置方法
# streaming_response.print_response_stream()

# 方式二：手动控制输出（推荐，可自定义格式）
for token in streaming_response.response_gen:
    print(token, end="", flush=True)

6.3 Query Engine vs Chat Engine

Query Engine（单轮问答）：

• 每次查询都是独立的，不保留历史对话
• 适合：一次性问答、文档查询、信息检索
• 性能：更快，资源消耗更少

Chat Engine（多轮对话）：

• 维护对话历史，支持上下文理解
• 适合：交互式对话、需要理解前文的问题（如"它呢？"、"详细说明一下"）
• 性能：需要存储历史，资源消耗更多

选择建议：

• 简单问答场景 → Query Engine
• 需要上下文理解 → Chat Engine
• 生产环境建议根据实际需求选择，避免不必要的资源消耗

️ 7. 底层接口：Prompt、LLM 与 Embedding

7.1 Prompt 模板

PromptTemplate定义提示词模板

from llama_index.core import PromptTemplate

# 创建提示词模板，使用 {变量名} 作为占位符
prompt = PromptTemplate("写一个关于{topic}的笑话")

# 格式化模板，替换占位符
result = prompt.format(topic="小明")
print(result)
# 输出：'写一个关于小明的笑话'

ChatPromptTemplate定义多轮消息模板

from llama_index.core.llms import ChatMessage, MessageRole
from llama_index.core import ChatPromptTemplate

chat_text_qa_msgs = [
    ChatMessage(
        role=MessageRole.SYSTEM,
        content="你叫{name}，你必须根据用户提供的上下文回答问题。",
    ),
    ChatMessage(
        role=MessageRole.USER, 
        content=(
            "已知上下文：n" 
            "{context}nn" 
            "问题：{question}"
        )
    ),
]
text_qa_template = ChatPromptTemplate(chat_text_qa_msgs)

print(
    text_qa_template.format(
        name="小明",
        context="这是一个测试",
        question="这是什么"
    )
)

system: 你叫小明，你必须根据用户提供的上下文回答问题。 user: 已知上下文： 这是一个测试

问题：这是什么 assistant:

7.2 语言模型

from llama_index.llms.openai import OpenAI

llm = OpenAI(temperature=0, model="gpt-4o")

response = llm.complete(prompt.format(topic="小明"))

print(response.text)

response = llm.complete(
    text_qa_template.format(
        name="小明",
        context="这是一个测试",
        question="你是谁，我们在干嘛"
    )
)

print(response.text)

连接DeepSeek

pip install llama-index-llms-deepseek

import os
from llama_index.llms.deepseek import DeepSeek

llm = DeepSeek(model="deepseek-chat", api_key=os.getenv("DEEPSEEK_API_KEY"), temperature=1.5)

response = llm.complete("写个笑话")
print(response)

设置全局使用的语言模型

from llama_index.core import Settings

Settings.llm = DeepSeek(model="deepseek-chat", api_key=os.getenv("DEEPSEEK_API_KEY"), temperature=1.5)

除 OpenAI 外，LlamaIndex 已集成多个大语言模型，包括云服务 API 和本地部署 API，详见官方文档：Available LLM integrations

7.3 Embedding 模型

from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core import Settings

# 全局设定 Embedding 模型
# model: 模型名称
# dimensions: 向量维度（可选，某些模型支持自定义维度以节省成本）
Settings.embed_model = OpenAIEmbedding(
    model="text-embedding-3-small", 
    dimensions=512  # 降低维度可节省存储和计算成本，但可能影响精度
)

LlamaIndex 同样集成了多种 Embedding 模型，包括云服务 API 和开源模型（HuggingFace）等，详见官方文档。

7.4 模型配置最佳实践

LLM 选择建议：

• 开发测试：使用成本较低的模型（如 GPT-3.5-turbo、DeepSeek）
• 生产环境：根据任务复杂度选择，简单任务用轻量模型，复杂任务用强模型
• 本地部署：考虑使用开源模型（如 Llama、Qwen）降低成本

Temperature 参数调整：

• 0-0.3：确定性输出，适合事实性问答、代码生成
• 0.5-0.7：平衡创造性和准确性，适合一般对话
• 0.8-1.5：高创造性，适合创意写作、头脑风暴

Embedding 模型选择：

• 确保向量维度与向量数据库配置一致
• 中文场景优先选择支持中文的模型
• 考虑成本：开源模型可本地部署，API 模型按调用收费

️ 8. 基于 LlamaIndex 实现一个功能较完整的 RAG 系统

功能要求：

• 加载指定目录的文件
• 支持 RAG-Fusion
• 使用 Qdrant 向量数据库，并持久化到本地
• 支持检索后排序
• 支持多轮对话

from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance

EMBEDDING_DIM = 1536
COLLECTION_NAME = "full_demo"
PATH = "./qdrant_db"

client = QdrantClient(path=PATH)

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, get_response_synthesizer
from llama_index.vector_stores.qdrant import QdrantVectorStore
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.response_synthesizers import ResponseMode
from llama_index.core.ingestion import IngestionPipeline
from llama_index.core import Settings
from llama_index.core import StorageContext
from llama_index.core.postprocessor import LLMRerank, SimilarityPostprocessor
from llama_index.core.retrievers import QueryFusionRetriever
from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.chat_engine import CondenseQuestionChatEngine
from llama_index.llms.dashscope import DashScope, DashScopeGenerationModels
from llama_index.embeddings.dashscope import DashScopeEmbedding, DashScopeTextEmbeddingModels
import os

# ========== 第一步：配置全局模型 ==========
# 1. 设置 LLM（用于生成回答）
Settings.llm = DashScope(
    model_name=DashScopeGenerationModels.QWEN_MAX,
    api_key=os.getenv("DASHSCOPE_API_KEY")
)

# 2. 设置 Embedding 模型（用于生成向量）
Settings.embed_model = DashScopeEmbedding(
    model_name=DashScopeTextEmbeddingModels.TEXT_EMBEDDING_V1
)

# 3. 设置全局文档处理管道（自动应用于所有文档）
Settings.transformations = [
    SentenceSplitter(chunk_size=512, chunk_overlap=200)
]

# ========== 第二步：加载和索引文档 ==========
# 4. 加载本地文档
documents = SimpleDirectoryReader("./data").load_data()

# 5. 清理已存在的集合（可选，用于重新构建索引）
if client.collection_exists(collection_name=COLLECTION_NAME):
    client.delete_collection(collection_name=COLLECTION_NAME)

# 6. 创建 Qdrant 集合
client.create_collection(
    collection_name=COLLECTION_NAME,
    vectors_config=VectorParams(size=EMBEDDING_DIM, distance=Distance.COSINE)
)

# 7. 创建 Vector Store 并关联到 Qdrant
vector_store = QdrantVectorStore(client=client, collection_name=COLLECTION_NAME)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 8. 构建索引（会自动应用 Settings.transformations 切分文档）
index = VectorStoreIndex.from_documents(
    documents, 
    storage_context=storage_context
)

# ========== 第三步：配置检索和排序 ==========
# 9. 定义检索后处理器
# LLMRerank: 使用 LLM 对检索结果重新排序，提高准确性（但会增加延迟和成本）
reranker = LLMRerank(top_n=2)

# SimilarityPostprocessor: 过滤相似度低于阈值的文档（未使用，仅作示例）
# sp = SimilarityPostprocessor(similarity_cutoff=0.6)

# 10. 创建 RAG-Fusion 检索器
# RAG-Fusion 原理：将原始查询扩展为多个相关查询，分别检索后合并结果
fusion_retriever = QueryFusionRetriever(
    [index.as_retriever()],  # 可以传入多个检索器进行融合
    similarity_top_k=5,      # 每个查询返回 top 5 结果
    num_queries=3,           # 生成 3 个扩展查询
    use_async=False,         # 是否异步执行（True 可提升速度）
)

# ========== 第四步：构建查询引擎 ==========
# 11. 构建单轮查询引擎
# ResponseMode.REFINE: 先基于第一个 chunk 生成回答，再用其他 chunk 逐步优化
query_engine = RetrieverQueryEngine.from_args(
    fusion_retriever,
    node_postprocessors=[reranker],  # 应用重排序
    response_synthesizer=get_response_synthesizer(
        response_mode=ResponseMode.REFINE  # 其他模式：COMPACT, TREE_SUMMARIZE, SIMPLE_SUMMARIZE
    )
)

# ========== 第五步：构建对话引擎 ==========
# 12. 创建多轮对话引擎
# CondenseQuestionChatEngine: 将历史对话压缩为独立查询，适合长对话
chat_engine = CondenseQuestionChatEngine.from_defaults(
    query_engine=query_engine,
    # 可以自定义问题压缩的 prompt 模板
    # condense_question_prompt="..."
)

# 测试多轮对话
# User: deepseek v3有多少参数
# User: 每次激活多少

while True:
    question=input("User:")
    if question.strip() == "":
        break
    response = chat_engine.chat(question)
    print(f"AI: {response}")

9. 常见问题 FAQ

9.1 数据加载相关问题

Q: 如何处理大文件或大量文件？

A: 有几种策略：

• 使用recursive=True递归读取子目录
• 分批加载文件，避免一次性加载所有文件到内存
• 使用流式处理（Streaming），边读边处理
• 对于超大文件，考虑先预处理，提取关键部分

# 示例：分批加载
files = ["file1.pdf", "file2.pdf", "file3.pdf"]
for file in files:
    documents = SimpleDirectoryReader(input_files=[file]).load_data()
    # 处理 documents

Q: PDF 文件解析效果不好怎么办？

A: 可以尝试以下方法：

• 使用LlamaParse替代默认的 PDFReader（效果更好但需要 API key）
• 对于扫描版 PDF，先使用 OCR 工具提取文字
• 检查 PDF 是否包含可提取的文本层（非纯图片）

Q: 如何处理图像、视频、音频文件中的文字？

A: 需要使用专门的 Data Connectors：

• 图像 OCR：使用ImageReader或集成 OCR 服务
• 视频字幕：提取视频中的字幕文件
• 音频转文字：使用语音识别服务（如 Whisper）

️ 9.2 文本切分相关问题

Q: Chunk size 应该设置多大？

A: 需要根据以下因素综合考虑：

• LLM 上下文窗口：确保 chunk + 查询 + 回答不超过模型限制
• 文档类型：代码文档建议 512-1024，自然语言建议 256-512
• 检索精度：chunk 太小可能丢失上下文，太大可能包含无关信息
• 经验值：大多数场景下，512-1024 tokens 是比较好的选择

Q: Chunk overlap 设置多少合适？

A: 一般建议：

• 设置为 chunk_size 的 10-20%（如 chunk_size=512，overlap=50-100）
• 对于长文档或需要保持上下文连续性的场景，可以适当增大
• 注意：overlap 过大会增加存储和计算成本

Q: 为什么切分后的结果不理想？

A: 可能的原因和解决方案：

• 问题：在句子中间切断 →解决：使用SentenceSplitter而非TokenTextSplitter
• 问题：代码块被破坏 →解决：使用CodeSplitter
• 问题：语义不完整 →解决：使用SemanticSplitterNodeParser
• 问题：结构化文档解析错误 →解决：使用对应的NodeParser（如HTMLNodeParser、MarkdownNodeParser）

9.3 检索相关问题

Q: 检索效果不好，返回的结果不相关怎么办？

A: 可以尝试以下优化方法：

1. 调整 chunk size：太大或太小都可能影响效果
2. 尝试不同的 TextSplitter：SentenceSplitter通常比TokenTextSplitter效果更好
3. 使用 Rerank：使用LLMRerank对检索结果重新排序
4. 检查 Embedding 模型：确保使用的模型适合你的数据（如中文数据使用中文模型）
5. 使用混合检索：结合向量检索和关键字检索（如 RAG-Fusion）
6. 调整 similarity_top_k：适当增大返回结果数量，然后通过 Rerank 筛选

Q: 检索速度太慢怎么办？

A: 优化建议：

• 使用持久化向量数据库（如 Qdrant）而非内存存储
• 减少similarity_top_k的值
• 使用异步检索（use_async=True）
• 考虑使用更快的 Embedding 模型（如本地部署的轻量模型）
• 对于大规模数据，考虑使用专业的向量数据库服务（如 Pinecone）

Q: 向量检索和关键字检索应该选哪个？

A: 选择建议：

• 向量检索：适合语义搜索、理解同义词、多语言场景
• 关键字检索（BM25）：适合精确匹配、术语查询、代码搜索
• 混合检索：结合两者优势，通常效果最好（推荐）

9.4 中文文档处理问题

Q: 如何处理中文文档？

A: 关键点：

1. 使用支持中文的 Embedding 模型：
2. 使用适合中文的 TextSplitter：
3. 确保 LLM 支持中文：

# 中文场景推荐配置
from llama_index.embeddings.dashscope import DashScopeEmbedding
from llama_index.core.node_parser import SentenceSplitter

Settings.embed_model = DashScopeEmbedding(
    model_name=DashScopeTextEmbeddingModels.TEXT_EMBEDDING_V3
)
Settings.transformations = [SentenceSplitter(chunk_size=512, chunk_overlap=100)]

9.5 性能和成本问题

Q: 如何降低 API 调用成本？

A: 优化策略：

1. 使用开源模型：本地部署开源 LLM 和 Embedding 模型（如 Llama、Qwen、BGE）
2. 缓存机制：对相同查询结果进行缓存
3. 减少 Rerank 调用：只在必要时使用 LLMRerank（会增加成本）
4. 优化 chunk 数量：减少不必要的 chunk，降低 Embedding 调用次数
5. 选择合适的模型：简单任务使用轻量模型，复杂任务再用强模型

Q: 内存占用太大怎么办？

A: 解决方案：

• 使用持久化存储（Qdrant、Chroma 等）而非内存存储
• 分批处理文档，不要一次性加载所有数据
• 使用流式处理，边处理边释放内存
• 考虑使用更轻量的 Embedding 模型

Q: 索引构建速度慢怎么办？

A: 优化方法：

• 使用异步处理（use_async=True）
• 批量处理文档而非逐个处理
• 使用更快的 Embedding 模型
• 对于大规模数据，考虑分布式处理

9.6 部署和生产环境问题

Q: 如何持久化索引以便后续复用？

A: 两种方式：

1. 使用向量数据库（推荐）：

# 使用 Qdrant 等向量数据库，数据自动持久化
client = QdrantClient(path="./qdrant_db")

1. 使用本地文件存储：

# 保存索引到本地
index.storage_context.persist(persist_dir="./doc_emb")

# 后续加载
from llama_index.core import load_index_from_storage
storage_context = StorageContext.from_defaults(persist_dir="./doc_emb")
index = load_index_from_storage(storage_context)

Q: 如何更新已构建的索引？

A: 更新策略：

• 增量更新：使用index.insert()添加新文档
• 全量重建：删除旧索引，重新构建（适合文档经常变化的情况）
• 版本管理：为不同版本的索引创建不同的 collection

Q: 生产环境应该注意什么？

A: 关键点：

1. 使用持久化存储：避免数据丢失
2. 错误处理：添加异常捕获和重试机制
3. 监控和日志：记录 API 调用、检索性能等
4. 限流和缓存：避免 API 调用过频
5. 安全性：保护 API key，避免敏感数据泄露
6. 性能优化：使用异步、批量处理等技术

10. 总结

本文全面介绍了 LlamaIndex 框架的核心功能和使用方法，帮助读者快速上手构建 RAG 应用。

核心流程回顾

一个完整的 RAG 系统通常包含以下步骤：

1. 数据加载（Loading）
2. ️文本切分与解析（Chunking）
3. 构建索引（Indexing）
4. 检索（Retrieval）
5. 生成回答（QA & Chat）

关键要点

• ️Chunk 策略：选择合适的 chunk size 和 overlap 是 RAG 系统成功的关键
• 存储选择：根据数据规模和场景选择内存存储或持久化存储
• 检索策略：向量检索适合语义搜索，关键字检索适合精确匹配，混合检索通常效果最好
• 模型选择：根据任务需求和数据特点选择合适的 LLM 和 Embedding 模型
• 中文支持：处理中文文档时，务必使用支持中文的 Embedding 模型和合适的 TextSplitter

最佳实践建议

1. 开发阶段：使用内存存储和简单配置快速验证想法
2. 生产环境：使用持久化向量数据库，添加错误处理和监控
3. 性能优化：合理设置参数，使用异步处理，考虑缓存机制
4. 成本控制：根据任务复杂度选择模型，考虑使用开源模型降低成本

下一步学习

• 深入学习：LlamaIndex 官方文档
• 探索连接器：LlamaHub 上找到更多 Data Connectors
• 高级功能：了解 Agent 和 Workflow 的用法
• 实践项目：尝试构建自己的 RAG 应用，解决实际问题
• 社区支持：加入 LlamaIndex 社区，获取帮助和分享经验

希望本文能帮助你快速掌握 LlamaIndex，构建出强大的知识增强应用！如有问题，欢迎参考上面的常见问题部分，或查阅官方文档。

END

如果你觉得本文有帮助，欢迎点赞、在看、转发，也欢迎留言分享你的经验！