LlamaIndex(一)：LlamaIndex核心组件

什么是LamaIndex

LlamaIndex是一个可以用于快速构建workflow，RAG，Agent的开源框架

• 官网：docs.llamaindex.ai/en/stable/
• github：github.com/run-llama

LlmamIndex有Typescript和python两个版本，两个版本都有对应的文档，但python版本相对更完善

• Python 文档地址：docs.llamaindex.ai/en/stable/
• Python API 接口文档：docs.llamaindex.ai/en/stable/a…
• TS 文档地址：ts.llamaindex.ai/

安装

# 通过pip安装
pip install llama-index

# 通过 npm 安装
npm install llamaindex

# 通过 yarn 安装
yarn add llamaindex

# 通过 pnpm 安装
pnpm add llamaindex

LlamaIndex的核心组件

数据加载

不管是什么程序，很重要的一部分就是获取需要的数据，LlamaIndex提供了一系列的工具

SimpleDirectoryReader

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 上代码：

文档是从deepseek论文中截取的一部分： pan.baidu.com/s/1jE5GfTZY…

import json
from pydantic.v1 import BaseModel
from llama_index.core import SimpleDirectoryReader

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

输出：

我们可以看到，文件是加载出来了，但是文件里的表格都是散的。

这里可以更换LlamaCloud提供的文件加载器，这个加载器收费，但是一开始注册会赠送免费额度

from llama_cloud_services import LlamaParse
from llama_index.core import SimpleDirectoryReader
import nest_asyncio
nest_asyncio.apply() # 只在Jupyter笔记环境中需要此操作，否则会报错

# set up parser
parser = LlamaParse(
    result_type="markdown"  # "markdown" and "text" are available
)
file_extractor = {".pdf": parser}

documents = SimpleDirectoryReader(input_dir="./data", required_exts=[".pdf"], file_extractor=file_extractor).load_data()
print(documents[0].text)

可以看到效果好了很多

Data Connectors

SimpleDirectoryReader只能加载文件，音频，视频，图片默认是不会加载的，这个时候我们就需要Data Connectors

例：读取网页

pip install llama-index-readers-web

from llama_index.readers.web import SimpleWebPageReader

documents = SimpleWebPageReader(html_to_text=True).load_data(
    ["https://juejin.cn/"]
)

print(documents[0].text)

更多DataConnectors可以在 LlamaHub上找到 也可以使用第三方数据加载器

文本切分与解析(Chunking)

为了检索方便，一般我们会把文档进行切分为Node，在LlamaIndex中，Node被定义为一个文本的chunck

使用TextSplitters对文本做切分

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

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

node_parser = TokenTextSplitter(
    chunk_size=1000,  # 每个 chunk 的最大长度
    chunk_overlap=500  # 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：根据语义相关性对将文本切分为片段。

使用 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://juejin.cn/post/7474803002438057994"]
)

# 默认解析 ["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等等

索引（Indexing）与检索（Retrieval）

现在数据已经获取到了，也进行了切分，那么接下来就是进行灌库，专业点说，叫进行索引，然后就是等待检索

在检索的过程中，索引是为了实现快速检索而设计的特定数据结构，关于索引的具体原理，可参考传统索引、向量索引

向量检索

VectorStoreIndex

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

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

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

# 定义 Node Parser
node_parser = TokenTextSplitter(chunk_size=1000, chunk_overlap=500)

# 切分文档
nodes = node_parser.get_nodes_from_documents(documents)

# 构建 index
index = VectorStoreIndex(nodes)

# 获取 retriever
vector_retriever = index.as_retriever(
    similarity_top_k=2 # 返回2个结果
)

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

print(results[0].text)

LlamaIndex默认embedding模型是text-embedding-ada-002，后续文章会写到如何进行更换

自定义VectorStore

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

client = QdrantClient(location=":memory:")
collection_name = "demo"
collection = client.create_collection(
    collection_name=collection_name,
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE)
)

vector_store = QdrantVectorStore(client=client, collection_name=collection_name)
# storage: 指定存储空间
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 创建 index：通过 Storage Context 关联到自定义的 Vector Store
index = VectorStoreIndex(nodes, storage_context=storage_context)

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

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

print(results[0])

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

• 关键字检索

  • BM25Retriever：基于 tokenizer 实现的 BM25 经典检索算法
  • KeywordTableGPTRetriever：使用 GPT 提取检索关键字
  • KeywordTableSimpleRetriever：使用正则表达式提取检索关键字
  • KeywordTableRAKERetriever：使用RAKE算法提取检索关键字（有语言限制）

• RAG-Fusion QueryFusionRetriever

• 还支持 KnowledgeGraph、SQL、Text-to-SQL 等等

检索后处理

有的时候检索结果不是很符合我们的需求，所以LlamaIndex也提供了一系列的后处理模块，比如，我们可以使用不同的模型对检索后的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")

使用postprocessor

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

经过了文档的加载，切分，索引，检索及后处理，没有以外我们就可以得到合适的查询内容了，下面就是生成回复

生成回复

单轮问答

qa_engine = index.as_query_engine()
response = qa_engine.query("deepseek v3数学能力怎么样?")

print(response)

输出:

DeepSeek-V3在数学相关的基准测试中取得了最先进的表现，超过了所有非长CoT开源和闭源模型。特别是在特定基准测试如MATH-500上甚至胜过了o1-preview，展示了其强大的数学推理能力。

多轮对话

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

输出:

DeepSeek v3 has state-of-the-art performance on math-related benchmarks and demonstrates robust mathematical reasoning capabilities. It even outperforms o1-preview on specific benchmarks like MATH-500.

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

输出：

DeepSeek v3 emerges as the top-performing model for coding competition benchmarks, such as LiveCodeBench, solidifying its position as the leading model in the coding domain.

流式输出

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)

输出：

DeepSeek v3 has state-of-the-art performance on math-related benchmarks among all non-long-CoT open-source and closed-source models. It demonstrates robust mathematical reasoning capabilities and even outperforms o1-preview on specific benchmarks, such as MATH-500.

好了，数据加载，切分，索引，检索，后处理都有了，好像还少一些东西，对了，prompt的处理，embedding，和LLM还没有搞定

LlamaIndex也提供了对应的接口

Prompt、LLM 与 Embedding

Prompt

prompt模板和其他框架类似，没有什么太特殊的点

from llama_index.core import PromptTemplate

prompt = PromptTemplate("写一个关于{topic}的笑话")

prompt.format(topic="小明")

多轮消息模板

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}\n\n" \
            "问题：{question}"
        )
    ),
]
text_qa_template = ChatPromptTemplate(chat_text_qa_msgs)

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

输出

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

问题：这是什么

LLM

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-reasoner", api_key=os.environ["DEEPSEEK_API_KEY"])

llm.complete("写个笑话")

输出

设置全局语言模型

from llama_index.core import Settings

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

除了openai的模型，LlamaIndex还继承了很多其他的大语言模型，包括云服务和本地部署api，官方文档：Available LLM integrations

Embedding模型

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

# 全局设定
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small", dimensions=512)

和大语言模型一样，LlamaIndex也集成了很多Embedding模型，官方文档。

现在一个RAG系统关键部分都有了，下面我们来实现一个完整的RAG系统

完整版RAG

功能要求：

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

import time

from llama_index.core import VectorStoreIndex, KeywordTableIndex, SimpleDirectoryReader
from llama_index.vector_stores.qdrant import QdrantVectorStore
from llama_index.core.node_parser import SentenceSplitter
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
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.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance

EMBEDDING_DIM = 512
COLLECTION_NAME = "full_demo"
PATH = "./qdrant_db"
# 连接向量数据库
client = QdrantClient(path=PATH)

# 指定全局llm与embedding模型
Settings.llm = OpenAI(temperature=0, model="gpt-4o")
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small", dimensions=EMBEDDING_DIM)

# 指定全局文档处理的 Ingestion Pipeline
Settings.transformations = [SentenceSplitter(chunk_size=500, chunk_overlap=250)]

# 加载本地文档
documents = SimpleDirectoryReader("./data").load_data()

if client.collection_exists(collection_name=COLLECTION_NAME):
    client.delete_collection(collection_name=COLLECTION_NAME)

# 创建 collection
client.create_collection(
    collection_name=COLLECTION_NAME,
    vectors_config=VectorParams(size=EMBEDDING_DIM, distance=Distance.COSINE)
)

# 创建 Vector Store
vector_store = QdrantVectorStore(client=client, collection_name=COLLECTION_NAME)

# 指定 Vector Store 的 Storage 用于 index
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(
    documents, storage_context=storage_context
)

# 定义检索后排序模型
reranker = LLMRerank(top_n=2)

# 定义 RAG Fusion 检索器
fusion_retriever = QueryFusionRetriever(
    [index.as_retriever()],
    similarity_top_k=5, # 检索召回 top k 结果
    num_queries=3,  # 生成 query 数
    use_async=False,
    # query_gen_prompt="...",  # 可以自定义 query 生成的 prompt 模板
)

# 构建单轮 query engine
query_engine = RetrieverQueryEngine.from_args(
    fusion_retriever,
    node_postprocessors=[reranker]
)

# 对话引擎
chat_engine = CondenseQuestionChatEngine.from_defaults(
    query_engine=query_engine, 
    # condense_question_prompt=... # 可以自定义 chat message prompt 模板
)

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

输出：

User: deepseek v3有多少参数
AI: DeepSeek-V3有6710亿个总参数。
User: 每次激活多少
AI: DeepSeek-V3每次激活37B参数。

以上就是LlamaIndex的部分核心组件及使用，为什么是部分？开头提到LlamaIndex不止可以做RAG，还可以做workflow和agent，后面的文章会进行介绍