使用LlamaIndex为API构建RAG文档助手
使用LlamaIndex构建API文档助手:加载Markdown文档,通过SentenceSplitter进行分块,进行嵌入处理,存储在Chroma中,并通过RAG QueryEngine进行查询。
来源: Building a RAG-Powered API Documentation Assistant with LlamaIndex (Part 1: Components)
你正在搭建一个新的支付 API。打开文档后,按下 Ctrl+F,输入“refund”,结果在四页中找到了十二个相关条目,其中一半因为仅提到该词而无关紧要。十五分钟后你终于找到了对应的接口端点,却已经忘了自己原本要做什么。
现在想象一下,输入“如何办理退款?”就能直接从文档中获得清晰答案的情景。这正是我们的目标:为名为 ShopSphere 的虚拟电商 API 创建一个小型助手。它不会依赖语言模型的一般知识来编造答案,而是直接搜索真实的 ShopSphere 文档并从中提取答案。LlamaIndex 负责处理繁重的工作,同时会逐条解释相关内容,包括那些让框架显得仿佛有魔力的部分。
要解决的问题
语言模型对世界了解很多,但对您公司的API参考文档却一无所知。在每个提示中粘贴数百页内容既缓慢又昂贵,还会产生大量冗余信息。更好的方法是先找到相关段落,再让模型基于这些段落回答问题。例如有人询问如何创建订单,系统就会定位到关于创建订单的章节,然后将该文本与问题一起传递给模型。
这种技术被称为检索增强生成(RAG):先检索,再生成。以下内容均围绕构建检索部分展开,最终让智能体自行选择使用哪些信息或工具。
LlamaIndex中的四个核心理念
该框架以四个概念为核心组织所有内容,一旦理解了这些概念,它就不再像一堆复杂的类名迷宫。用小型餐厅的厨房作个生动的类比:
- 组件指的是各种原料和设备:烤箱、冰箱、面粉。它们是最基础的要素。
- 工具则是贴在设备上的食谱,其编写方式便于新厨师无需询问就能照做。
- 执行者就是厨师,他根据顾客的需求决定按何种顺序、使用哪份食谱。
- 工作流程则是打印好的食谱卡,适用于不想即兴发挥、需要每次都遵循固定步骤的情况。
助手正是通过按此顺序组合这四者而构建起来的。
组件:将 Markdown 文档转化为可搜索的知识库
这是准备阶段。在开始任何推理之前,需要将五个文档文件(认证、产品、订单、错误信息以及Webhook)整理成计算机能够通过含义而非仅关键词进行检索的形式。这一过程需要五个步骤。
步骤1:加载
from llama_index.core import SimpleDirectoryReader
def load_documents():
reader = SimpleDirectoryReader(input_dir="data", required_exts=[".md"])
documents = reader.load_data()
return documents
读取器会打开data/文件夹中的每个Markdown文件,并将它们封装在Document对象中,这是LlamaIndex对文本及其来源信息的表示方式。来源信息的作用比看上去要重要得多——原始文件名会被作为元数据保留,这样后续当助手回答问题时,就可以直接指出信息来自如03-cart-orders.md这样的文件,而无需手动记录。
步骤2:分块
存在一个问题:03-cart-orders.md文件将购物车、结账、订单、退款和取消等所有内容都放在同一个文件中。如果将其视为一个独立的可搜索单元,就可能会用与退款无关的取消信息来回答相关问题。因此,每个文档会被分割成更小的部分,LlamaIndex将这些小部分称为节点,这就好比把一本书拆成一堆索引卡,每张卡片都记住对应的那本书的内容。
from llama_index.core.node_parser import SentenceSplitter
splitter = SentenceSplitter(chunk_size=400, chunk_overlap=40)
如果每400个字符就盲目切割,可能会将一个句子一分为二,更糟糕的是还会截断某个curl命令。SentenceSplitter则会寻找自然的句子分隔点。40个字符的少量重叠还能让一个片段末尾的内容出现在下一个片段的开头,从而将相关内容保持在一起,比如代码示例及其说明文字。
第3步:嵌入
基于语义的搜索依赖于这一步。每个文本片段都会经过嵌入模型处理,该模型会将文本映射为一系列数字,即向量。即使使用的词汇完全不同,含义相近的段落也会落在相似的向量上。
用户可能会问“我该如何拿回我的钱?”,而文档中却有一个名为“申请退款”的章节。这两个句子没有共同的关键词,但表达的是同一个意思。嵌入模型能够捕捉到这种关联,因此语义搜索就能找到相关的退款说明文档。
from llama_index.embeddings.huggingface import HuggingFaceInferenceAPIEmbedding
embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-small-en-v1.5",
)
第4步:存储嵌入向量
为每个数据块生成嵌入向量需要时间,且通过API调用可能会产生费用,没人希望每次启动程序时都重复这一过程。因此,这些向量会被存储到可重复使用的向量数据库中。此处使用的就是Chroma,这是一个免费的本地数据库,能够简化嵌入向量的持久化存储与检索操作。
import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore
db = chromadb.PersistentClient(path="./chroma_db")
chroma_collection = db.get_or_create_collection("shopsphere_api_docs")
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
LlamaIndex 可以将第 2 到第 4 步合并为单一流程 IngestionPipeline。只需定义一次各处理阶段,所有文档都会自动依次经过这些阶段:被分割、嵌入,最后写入 Chroma。
from llama_index.core.ingestion import IngestionPipeline
pipeline = IngestionPipeline(
transformations=[
SentenceSplitter(chunk_size=400, chunk_overlap=20),
embed_model
],
vector_store=vector_store,
)
运行一次后,一个持久且可搜索的索引就会生成在 chroma_db 文件夹中。只有当文档内容发生变化时才需要重新生成。
第5步:查询
现在到了收获成果的时刻。存储的向量被封装在 VectorStoreIndex 中,而该对象又会变成 QueryEngine,也就是你实际用来提出查询的对象。
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_vector_store(vector_store, embed_model=embed_model)
query_engine = index.as_query_engine(llm=llm, similarity_top_k=3)
query_engine.query("How do I create a new order?")
当有问题出现时,会发生三件事:
- 该问题会被转换为一个向量,使用与数据输入时相同的嵌入模型。这一点很重要,因为问题和各个片段必须处于同一个向量空间中。这就好比用统一的单位来衡量所有事物,因为混用英寸和厘米会让比较失去意义。
- 从向量存储中检索出最相似的片段。在这里,指的是那些含义与问题最为接近的三个片段。
- 这些片段会作为上下文传递给大语言模型,模型便能基于它们来生成答案,而无需仅依赖训练数据。
这就是一个完整的RAG流程,单凭它就已经相当实用了。不过它只能做一件事:先检索信息,再给出答案。它无法判断某个特定问题需要不同的查询方式,这需要借助专门的工具和智能体。
自行运行
可以将完成后的项目克隆并在本地运行。先创建一个虚拟环境,安装所需依赖,然后将Hugging Face令牌粘贴到.env文件中:
git clone https://github.com/H11199/API-Documentation-Agent.git
cd API-Documentation-Agent
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env # then paste your HF token in as HF_TOKEN=hf_...
python ingestion_pipeline.py # builds the index from the sample docs in data/
python app.py # chat with the assistant
下一步是什么
目前虽然已有可用的文档搜索引擎,但它仅能检索并回答问题。下一阶段将为助手提供工具,由智能体决定使用哪些工具。同时还会揭示LlamaIndex工作流中最初看似神奇的部分:即工作流如何知道下一步应执行哪个操作。