深度聚焦：RAG 工程落地与 LlamaIndex 开发核心要点 - 文章 - 开发者社区

一、商业落地实施RAG工程的核心步骤

数据集的准备（语料）

将相关资料文档、数据源等收集整理；
非结构化文档（比如PDF）进行结构化处理（可程序处理）；

测试集的准备（QA对）

使用主流的 LLM 模型来根据文档来生成 QA 对

技术选型

NativeRAG（客服对话类，主要是文字）
GraphRAG（知识图谱）
AgenticRAG（智能体+RAG）

构建知识库

（自研）LlamaIndex+Vector
（自研）LangChain+Vector
（开源RAG方案）RAGFlow
（Agent智能体RAG）Dify/Coze

测试和优化

根据不同的阶段来进行优化处理
数据预处理，结构化处理
切片策略
召回策略
重排序
RAFT

最终效果评估

Ragas 来进行 RAG 性能的评估
LlamIndex框架自带评估功能

生产环境部署

大模型使用本地模型部署 vLLM或者调用第3方API
RAG应用程序使用Docker部署

picture.image

二、LlamaIndex实现RAG的核心步骤

大语言模型开发框架的价值是什么？

SDK：Software Development Kit，它是一组软件工具和资源的集合，旨在帮助开发者创建、测试、部署和维护应用程序或软件。

所有开发框架（SDK）的核心价值，都是降低开发、维护成本。

大语言模型开发框架的价值，是让开发者可以更方便地开发基于大语言模型的应用。主要提供三类帮助：

第三方能力抽象。比如 LLM、向量数据库、搜索接口等
常用工具、方案封装
底层实现封装。比如流式接口、超时重连、异步与并行等

好的开发框架，需要具备以下特点：

可靠性、鲁棒性高
可维护性高
可扩展性高
学习成本低

举些通俗的例子：

与外部功能解依赖

比如可以随意更换 LLM 而不用大量重构代码
更换三方工具也同理

经常变的部分要在外部维护而不是放在代码里

比如 Prompt 模板

各种环境下都适用

比如线程安全

方便调试和测试

至少要能感觉到用了比不用方便吧
合法的输入不会引发框架内部的报错



划重点：选对了框架，事半功倍；反之，事倍功半。

LlamaIndex 介绍

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

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

picture.image

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

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

Python 文档地址：

https://docs.llamaindex.ai/en/stable/

Python API 接口文档：

https://docs.llamaindex.ai/en/stable/api\_reference/

TS 文档地址：

https://ts.llamaindex.ai/

LlamaIndex 的核心模块

picture.image

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

  
pip install llama-index

  
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  
  
reader = SimpleDirectoryReader(  
        input_dir=r"D:\Test\LLMTrain\0602\data", # 目标目录  
        recursive=False, # 是否递归遍历子目录  
        required_exts=[".pdf"] # (可选)只读取指定后缀的文件  
    )  
documents = reader.load_data()  
print(documents[0].text)  
show_json(documents[0].json())

注意：对图像、视频、语音类文件，默认不会自动提取其中文字。如需提取，参考下面介绍的 Data Connectors。

默认的 PDFReader 效果并不理想，需要将PDF转MarkDown。一般我们采用pymupdf4llm 或docling，将PDFReader/Words等非结构化文件转MarkDown,并且对内部的图片上传图片服务器，然后再使用LlamaIndex对于MarkDown进行切分。

PDF是非结构化文档，需要转成结构化文档，LlamaIndex有专门的结构化文档解析器。

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://www.csdn.net/"]  
)  
  
print(documents[0].text)

更多 Data Connectors

内置的文件加载器
连接三方服务的数据加载器，例如数据库
更多加载器可以在 LlamaHub 上找到

文本切分与解析（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  
  
node_parser = TokenTextSplitter(  
    chunk_size=512,  # 每个 chunk 的最大长度  
    chunk_overlap=200  # chunk 之间重叠长度  
)  
  
nodes = node_parser.get_nodes_from_documents(  
    documents, show_progress=False  
)  
  
show_json(nodes[1].json())  
show_json(nodes[2].json())

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

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


对于非结构化的数据，比如一篇小说txt,word、pdf里的内容等，一般使用TextSplitters文本切分，转化为Nodes。对于结构化数据，比如MarkDown,Json等数据，可以根据不同级别的标题、json的子节点方式来切割。

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.cnblogs.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")

例如：MarkdownNodeParser解析 MarkDown文档

  
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex  
from llama_index.core.node_parser import MarkdownNodeParser  
  
# 加载 Markdown 文档  
documents = SimpleDirectoryReader(input_dir=r"D:\Test\LLMTrain\0602\data", required_exts=[".md"]).load_data()  
  
# 创建 Markdown 节点解析器  
node_parser = MarkdownNodeParser.from_defaults(  
    include_metadata=True,            # 包含元数据(默认True)  
    include_prev_next_rel=True,       # 包含前后节点关系(默认True)  
    header_path_separator="/"         #(默认/)  
)  
  
# 将文档解析为节点列表  
nodes = node_parser.get_nodes_from_documents(documents)  
  
  
# 查看解析结果（可选）  
for node in nodes:  
    print(f"节点 ID: {node.node_id}")  
    print("节点内容:")  
    print(node.text)  
    print("元数据:")  
    print(node.metadata)  
    print(f"文本长度: {len(node.get_content())}")  
    print("-" * 40)

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


总结：第3、4章节文本加载和数据切分的目标可以简单的理解为：源文件转成 List[BaseNode]：源文件 ---> List[BaseNode]

索引（Indexing）与检索（Retrieval）

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

5.1、向量检索

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

  
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader  
from llama_index.core.node_parser import TokenTextSplitter, SentenceSplitter  
  
# 加载 pdf 文档  
documents = SimpleDirectoryReader(  
    "./data",   
    required_exts=[".pdf"],  
).load_data()  
  
# 定义 Node Parser  
node_parser = TokenTextSplitter(chunk_size=512, chunk_overlap=200)  
  
# 切分文档  
nodes = node_parser.get_nodes_from_documents(documents)  
  
# 构建 index，默认是在内存中  
index = VectorStoreIndex(nodes)  
  
# 另外一种实现方式  
# index = VectorStoreIndex.from_documents(documents=documents, transformations=[SentenceSplitter(chunk_size=512)])  
  
# 写入本地文件  
# index.storage_context.persist(persist_dir="./doc_emb")  
  
# 获取 retriever  
vector_retriever = index.as_retriever(  
    similarity_top_k=2 # 返回2个结果  
)  
  
# 检索  
results = vector_retriever.retrieve("deepseek v3数学能力怎么样？")  
  
print(results[0].text)

2、使用自定义的 Vector Store，以 Chroma为例,Chroma数据库已有向量数据：

  
pip install llama-index-vector-stores-chroma

  
  
# 创建chroma数据库客户端，和传关键集合collection  
chroma_client = chromadb.PersistentClient(path=r"D:\Test\LLMTrain\day22_rag_data\chroma_db2")  
chroma_collection = chroma_client.get_or_create_collection("quickstart")  
  
  
# set up ChromaVectorStore  
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)  
  
# 从chromadb中创建索引  
index = VectorStoreIndex.from_vector_store(  
    vector_store  
)  
  
# 构建查询引擎  
query_engine = index.as_query_engine()  
  
# 查询，需要设置LLM大模型  
response = query_engine.query("陈平安是谁?")  
print(response)

5.2、更多索引与检索方式

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

关键字检索

BM25Retriever

：基于 tokenizer 实现的 BM25 经典检索算法

KeywordTableGPTRetriever

：使用 GPT 提取检索关键字

KeywordTableSimpleRetriever

：使用正则表达式提取检索关键字

KeywordTableRAKERetriever

：使用 RAKE 算法提取检索关键字（有语言限制）

RAG-Fusion QueryFusionRetriever
还支持 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")

将检索后的nodes进行重排序：

  
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}")

LLMRerank的大模型还可以手动指定。更多的 Rerank 及其它后处理方法，参考官方文档：

https://docs.llamaindex.ai/en/stable/module\_guides/querying/node\_postprocessors/node\_postprocessors/

生成回复（QA & Chat）

6.1 单轮问答（Query Engine）

  
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()

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()  
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)

底层接口：Prompt、LLM 与 Embedding

7.1 Prompt 模板

PromptTemplate 定义提示词模板

  
from llama_index.core import PromptTemplate  
  
template = (  
    "我们已经提供了以下上下文信息：\n"  
    "---------------------\n"  
    "{context_str}"  
    "\n---------------------\n"  
    "根据这些信息，请回答以下问题：{query_str}\n"  
)  
qa_template = PromptTemplate(template)  
  
# 创建文本提示（适用于 completion API）  
prompt = qa_template.format(context_str="上下文内容", query_str="你的问题")  
  
# 或者创建消息提示（适用于 chat API）  
messages = qa_template.format_messages(context_str="上下文内容", query_str="你的问题")

在上述示例中，{context_str} 和 {query_str} 是占位符，format() 方法会用实际的上下文和问题替换这些占位符。

ChatPromptTemplate 定义多轮消息模板

  
from llama_index.core import ChatPromptTemplate  
from llama_index.core.llms import ChatMessage, MessageRole  
  
message_templates = [  
    ChatMessage(role=MessageRole.SYSTEM, content="你是一个智能助手。"),  
    ChatMessage(role=MessageRole.USER, content="你是谁？"),  
    ChatMessage(role=MessageRole.ASSISTANT, content="我是..."),  
    ChatMessage(role=MessageRole.USER, content="{query_str}")  
]  
chat_template = ChatPromptTemplate(message_templates)  
  
# 创建聊天消息提示  
messages = chat_template.format_messages(query_str="你的问题")  
  
print(messages)

picture.image