基于 Python、Qdrant、fastembed 和 Gemini 的本地 RAG 流水线
一个用 Python 实现的小型 RAG 流程:将本地文档分割成块,使用 fastembed 在离线环境下嵌入这些文档,将向量存储在 Qdrant 中,最后通过命令行界面利用 Gemini 回答问题。
自定义的RAG(检索增强生成)架构听起来比实际要复杂得多。有种说法认为,要让大型语言模型读取本地文件就必须使用企业级技术栈,但事实并非如此。只需一台机器、Qdrant和Gemini,就能构建出功能完备的增量处理流程,无需复杂的框架或额外的服务器管理。下文将介绍其工作原理、代码功能以及运行方法。
RAG解决的问题
语言模型仅了解其训练数据,它们从未见过你的笔记、报告或今天早上保存的PDF文件。RAG填补了这一空白。系统不会指望模型依靠通用知识猜测答案,而是会在你的文档中搜索相关内容,将这些片段提供给模型,并要求模型仅基于这些上下文来作答。由于模型读取的是你的实际资料,因此不会再凭空编造内容。
普通的关键词搜索虽然可以找到相关段落,但效率很快就会下降,因此向量搜索才是通常的选择。
向量与向量搜索
向量是一组数字,用于表示一段文本的含义。将“你怎么样”和“你多大了”转化为向量后,就可以计算它们之间的相似度。向量搜索正是运用这一原理,在表述方式不同时也能找到答案。问题以及每段文档内容都会被嵌入到同一个数值空间中,含义最接近的内容就会胜出。这一点很重要,因为人们很少会用与文档完全相同的方式来表述问题。即使有人问“我该如何拿回我的钱”,他仍然需要“退款政策”这一章节。
RAG流程就是连接这一切的机制,通常包含六个步骤:
- 数据导入:文件被放入某个文件夹中,本例中为
documents/。 - 分块处理:脚本会将文件切割成多个较小的重叠片段。若将50页的文档视为一个整体进行搜索则效果不佳,因此需要先进行分割。
- 向量化:一个小型本地模型会将每个片段转换为向量,这样主题相似的片段就会彼此靠近。
- 存储:这些向量会被存储在Qdrant中,这是一种专为快速处理新向量并从中从数百万个向量中找出最相似的向量而设计的向量数据库。它速度快、开源,可在本地运行,无需搭建服务器或注册账号。
- 检索:问题也会被转换为向量,随后Qdrant会返回与之最相似的那些片段,这些片段最有可能包含答案。
通过 -i 标志或 -w 监视器,步骤 1 到 4 会自动执行,因此文档始终可被搜索。当使用 -q 时,步骤 5 和 6 才会根据需求执行。
Python 实现
该代码结构简洁,未使用大型框架,因此很容易了解数据的流向。
读取文件
首先,无论是对 Markdown 笔记还是格式混乱的 Word 文档,都需要找到文件并提取原始文本:
def read_document(path) -> str:
# dispatches on extension: .txt/.md read directly,
# .pdf via pypdf, .docx via docx2txt -> returns plain textdef file_status(path, state) -> str:
# "not_indexed" if never seen, "modified" if file_hash(path)
# differs from the hash stored in state, else "indexed"
分块处理
接下来,通过简单的滑动窗口将文本分割,这样跨越分割点的句子仍能保留其上下文:
def chunk_text(text, chunk_size=500, overlap=50) -> list:
words = text.split()
step = chunk_size - overlap
return [" ".join(words[i:i+chunk_size])
for i in range(0, len(words), step)]
嵌入向量与稳定标识
嵌入操作在本地完成,每句文本无需调用外部API。每个文本块还会根据其内容的哈希值获得一个可预测的标识,因此即使文本内容不变,不同运行次数的标识也保持一致:
def chunk_ids_for(chunks) -> dict:
# id = uuid5(namespace, chunk_text) for each chunk
# -> same text always gets the same id, across re-indexes
...
嵌入操作本身是在 Qdrant 调用过程中完成的:
# inside index_file():
client.add(collection_name=index_name, documents=new_chunks, ids=new_ids)
# Qdrant's fastembed integration embeds `documents` automatically
将文件与数据库同步
在此处,本地文件与数据库会被同步。修正拼写错误时无需清除索引并重新启动。该代码会比对编号,删除已消失的文件片段,并添加新的文件片段:
def index_file(path, state) -> bool:
chunks = chunk_text(read_document(path))
new_ids = chunk_ids_for(chunks)
old_ids = state[path.name].chunk_ids # from last time
client.delete(collection_name, ids=old_ids - new_ids) # removed chunks
client.add(collection_name, ids=new_ids - old_ids, ...) # new/changed chunks
state[path.name] = {...updated record...}
从文件夹中移除的文件也会被清理:
def prune_deleted(state) -> int:
# for each file in state no longer present in DOCUMENT_DIR:
# delete its Qdrant collection, drop its state entry
查询响应
当有查询到来时,系统会要求Qdrant在选定的文档中找出最匹配的结果。首先会有一个辅助模块来确定需要搜索哪些索引:
def resolve_index_names(spec, state) -> list:
# "all" -> every indexed collection; "a,b" -> ["a","b"], validated
然后该查询会对每一个进行查询,并合并结果:
def cmd_query(index_spec, question, top_k, show_sources):
for name in resolve_index_names(index_spec, state):
hits += client.query(collection_name=name, query_text=question, limit=top_k)
hits = sorted(hits, key=score, reverse=True)[:top_k]
生成
最后,检索到的片段会直接传送到 Gemini,由其对照提供的文本进行处理:
def generate_answer(question, context) -> str:
prompt = f"Answer using only this context:\n{context}\n\nQuestion: {question}"
return genai.Client(api_key=...).models.generate_content(
model=GEMINI_MODEL, contents=prompt
).text
其余部分为辅助代码。get_client()用于建立与 Qdrant 的连接,load_state()和save_state()负责读取和写入.rag_state.json文件,而sanitize_index_name()则将文件名转换为有效的集合名称。命令函数(cmd_list_files、cmd_index、cmd_watch)将所有功能与命令行参数关联起来。
在本地运行
克隆该仓库并进入项目文件夹:
git clone https://github.com/Shivvam/rag-pipeline-qdrant.git
cd rag-cli
接着创建一个环境,安装所需依赖,并配置文件:
python3 -m venv venv
source venv/bin/activate # on Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # then edit in your GEMINI_API_KEY
在运行 app.py 之前,请在任何新的终端中重新激活虚拟环境。-q 选项若要生成答案,则必须设置 GEMINI_API_KEY,而其他命令无需该参数即可正常运行。
命令行使用方式
所有数据导入与查询操作均通过终端完成。若要查看文档文件夹中有哪些文件需要处理,或存在哪些索引,可执行相应操作:
python app.py -lf # list files in ./documents + status
python app.py -li # list existing indexes
要处理新文档或更新已修改的文档:
python app.py -i myfile.md # index one file (or re-index if changed)
python app.py -i all # index every not_indexed/modified file
如需在编辑时实现自动索引,请在另一个终端中持续运行此命令:
python app.py -w # watch ./documents, auto-index on add/edit
要对单个文件、多个文件或全部内容提问:
python app.py -q report "What is X?" # query a single index
python app.py -q report,notes "What is X?" # query multiple indexes together
python app.py -q all "What is X?" --sources # query everything, show retrieved chunks
python app.py -q report "..." -k 8 # retrieve top 8 chunks instead of default 5
-lf显示的状态有三种取值。not_indexed表示该文件从未被处理过,indexed表示它已被当前处理,而modified则表示自上次运行后该文件已更改,此时需要再次执行-i命令。
设计选择
为追求快速与简洁,我们做出了一些设计决策。
- Qdrant:每个文件都会拥有一个独立的集合,集合名称取自处理后的文件名,若名称冲突则会添加数字后缀。默认情况下它采用磁盘本地模式(
./qdrant_storage),因此无需服务器。如需支持并发访问,可在.env文件中设置QDRANT_URL指向真实的Qdrant服务器。本地模式会将目录锁定给单个进程,因此-w和-q命令无法同时运行。
BAAI/bge-small-en-v1.5 模型通过 fastembed 运行。该模型只需下载一次并缓存,因此无需支付 API 费用,查询时也不依赖网络。gemini-3.5-flash 模型。.rag_state.json 文件记录了文件哈希值、状态、索引名称以及内容块数量,这使得使用 -lf 和 -li 命令时无需重新扫描,因为 Qdrant 不需要再次处理数据。内容块标识符直接来自文本本身,因此重新索引是增量式的,只有发生变化的内容块会被重新嵌入并更新。.txt和.md可直接使用。.pdf和.docx需要pypdf或docx2txt,这两者均已列在需求清单中。