手写一个 RAG:从零搭建可溯源的检索增强问答系统

发布时间:2026/11/16 8:16:38

手写一个 RAG:从零搭建可溯源的检索增强问答系统 1. 引言为什么需要手写 RAG大语言模型虽然强大但存在知识截止、幻觉和无法引用来源等问题。检索增强生成Retrieval-Augmented GenerationRAG通过先检索再生成的方式把外部知识注入模型从而提升回答的准确性和可溯源性。本文不依赖 LangChain 等框架从零手写一个可运行的 RAG 系统覆盖文档加载、切分、向量化、检索、生成和溯源全流程。手写 RAG 的好处在于你能清楚看到每个环节的输入输出便于调试、定制和教学。下面我们逐步搭建。2. 系统架构与整体流程一个最小可用的 RAG 系统包含以下模块文档加载器读取本地文本或 Markdown 文件。文本切分器把长文档切成适合检索的块Chunk。向量化器把文本块编码为向量。向量存储与检索保存向量并支持相似度检索。提示词组装把检索结果和用户问题拼成 Prompt。生成器调用大模型生成回答。溯源模块把回答关联到原始文档块。整体流程如下flowchart TD A[加载文档] -- B[文本切分] B -- C[向量化] C -- D[向量存储] E[用户提问] -- F[问题向量化] F -- G[相似度检索] D -- G G -- H[组装 Prompt] H -- I[大模型生成] I -- J[返回回答与溯源]3. 环境准备与依赖安装本文使用 Python 3.10核心依赖如下pip install openai numpy说明openai用于调用 Embedding 模型和对话模型兼容 OpenAI 接口的服务均可。numpy用于向量相似度计算。如果你希望完全本地运行可以把 Embedding 和生成模型替换为本地模型如 BGE、Qwen本文以 OpenAI 兼容接口为例便于快速跑通。4. 文档加载与文本切分首先实现文档加载器支持读取纯文本和 Markdown 文件from pathlib import Path def load_document(file_path: str) - str: 读取本地文本或 Markdown 文件内容。 path Path(file_path) if not path.exists(): raise FileNotFoundError(f文件不存在: {file_path}) return path.read_text(encodingutf-8)接下来实现文本切分器。切分策略直接影响检索质量这里采用「按段落优先、按长度兜底」的策略import re def split_text(text: str, chunk_size: int 500, overlap: int 50) - list[str]: 把长文本切成多个块。 - chunk_size: 每个块的最大字符数 - overlap: 相邻块之间的重叠字符数用于保持上下文连贯 # 先按空行切分为段落 paragraphs [p.strip() for p in re.split(r\n\s*\n, text) if p.strip()] chunks [] current for para in paragraphs: # 如果当前块加上新段落会超长先保存当前块 if len(current) len(para) 1 gt; chunk_size and current: chunks.append(current) # 保留尾部 overlap 字符作为下一块的开头保持上下文 current current[-overlap:] if overlap gt; 0 else current (current \n para).strip() if current: chunks.append(current) return chunks切分时保留重叠区域可以避免关键信息恰好落在块边界而被截断。5. 向量化与向量存储向量化负责把文本块转换为向量。这里封装一个 Embedding 客户端from openai import OpenAI class EmbeddingClient: def init(self, api_key: str, base_url: str, model: str text-embedding-3-small): self.client OpenAI(api_keyapi_key, base_urlbase_url) self.model model def embed(self, texts: list[str]) -gt; list[list[float]]: 批量把文本编码为向量。 resp self.client.embeddings.create(modelself.model, inputtexts) return [item.embedding for item in resp.data]向量存储使用简单的内存实现支持添加和检索import numpy as np class VectorStore: def init(self): self.vectors [] # 向量列表 self.metadata [] # 每个向量对应的文本块和来源信息 def add(self, vectors: list[list[float]], metadatas: list[dict]): 批量添加向量及其元数据。 self.vectors.extend(vectors) self.metadata.extend(metadatas) def search(self, query_vector: list[float], top_k: int 3) -gt; list[dict]: 余弦相似度检索返回最相似的 top_k 个结果。 每个结果包含 text、score 和 source 字段。 if not self.vectors: return [] q np.array(query_vector) mat np.array(self.vectors) # 余弦相似度 点积 / (模长乘积) scores (mat q) / (np.linalg.norm(mat, axis1) * np.linalg.norm(q) 1e-9) top_indices np.argsort(scores)[::-1][:top_k] results [] for idx in top_indices: results.append({ text: self.metadata[idx][text], score: float(scores[idx]), source: self.metadata[idx].get(source, ), chunk_index: self.metadata[idx].get(chunk_index, 0), }) return results这里使用余弦相似度衡量相关性分数越高表示越相关。6. 索引构建把文档写入向量库把加载、切分、向量化、存储串起来构建索引def build_index(file_path: str, embed_client: EmbeddingClient, store: VectorStore): 读取文档、切分、向量化并写入向量存储。 text load_document(file_path) chunks split_text(text) vectors embed_client.embed(chunks) metadatas [ { text: chunk, source: file_path, chunk_index: i, } for i, chunk in enumerate(chunks) ] store.add(vectors, metadatas) print(f已索引 {len(chunks)} 个文本块)这一步完成后向量库就具备了检索能力。7. 检索与提示词组装用户提问时先把问题向量化再从向量库检索相关块def retrieve(query: str, embed_client: EmbeddingClient, store: VectorStore, top_k: int 3) - list[dict]: 检索与问题最相关的文本块。 query_vector embed_client.embed([query])[0] return store.search(query_vector, top_ktop_k)把检索结果组装成带上下文的 Promptdef build_prompt(query: str, retrieved: list[dict]) - str: 把检索结果和用户问题组装成 Prompt。 context \n\n.join( f[来源 {i1}] {item[text]} for i, item in enumerate(retrieved) ) prompt f请根据以下参考资料回答用户问题。如果资料中没有相关信息请明确说明“资料中未找到相关内容”不要编造。 参考资料 {context} 用户问题{query} 请给出准确、简洁的回答并在回答末尾列出引用的来源编号。 return prompt提示词中明确要求模型引用来源编号这是实现可溯源回答的关键。8. 生成回答与溯源输出调用对话模型生成回答并把来源信息一并返回class ChatClient: def __init__(self, api_key: str, base_url: str, model: str gpt-4o-mini): self.client OpenAI(api_keyapi_key, base_urlbase_url) self.model model def generate(self, prompt: str) -gt; str: resp self.client.chat.completions.create( modelself.model, messages[{role: user, content: prompt}], temperature0.2, ) return resp.choices[0].message.content def ask(query: str, embed_client: EmbeddingClient, store: VectorStore, chat_client: ChatClient, top_k: int 3) - dict: 完整的 RAG 问答入口返回回答和溯源信息。 retrieved retrieve(query, embed_client, store, top_k) prompt build_prompt(query, retrieved) answer chat_client.generate(prompt) return { answer: answer, sources: [ { text: item[text], score: item[score], source: item[source], chunk_index: item[chunk_index], } for item in retrieved ], }返回结果中同时包含回答和来源块前端可以据此展示引用来源实现可溯源。9. 完整实战跑通一个问答示例下面把以上模块串起来用一个示例文档跑通全流程。假设有一份产品说明文档product.md# 智能音箱 X1 使用说明 基本功能 智能音箱 X1 支持语音播放音乐、设置闹钟、查询天气和控制智能家居设备。 连接方式 首次使用请下载 App并按照提示连接 Wi-Fi。设备支持 2.4G 和 5G 双频段。 常见问题 如果音箱无法唤醒请检查电源和网络连接并确认麦克风未被静音。主程序如下def main(): api_key your-api-key base_url https://api.openai.com/v1 embed_client EmbeddingClient(api_key, base_url) chat_client ChatClient(api_key, base_url) store VectorStore() 1. 构建索引 build_index(product.md, embed_client, store) 2. 提问 query 音箱无法唤醒怎么办 result ask(query, embed_client, store, chat_client, top_k2) 3. 输出回答 print(回答, result[answer]) print(\n溯源信息) for i, src in enumerate(result[sources], 1): print(f [{i}] 来源: {src[source]} 第{src[chunk_index]}块 相似度: {src[score]:.4f}) print(f 内容: {src[text][:80]}...) if name main: main()运行后系统会先索引文档再根据问题检索相关块最终生成带来源编号的回答。10. 可溯源机制的设计要点可溯源是本文 RAG 的核心目标设计上包含三个层面块级溯源每个文本块都记录来源文件和块序号检索结果天然携带来源。提示词约束在 Prompt 中要求模型引用来源编号从生成侧约束回答可追溯。结果透出问答接口同时返回回答和来源块前端可展示引用卡片。此外相似度分数可以作为溯源可信度的参考分数越高说明该块与问题越相关回答依据越可靠。11. 优化方向与进阶建议手写版本跑通后可以从以下方向继续优化切分策略引入语义切分或按标题结构切分提升块质量。混合检索结合关键词检索BM25和向量检索兼顾精确匹配和语义匹配。重排序在检索后增加重排序模型进一步提升 top_k 结果的相关性。持久化存储把向量库落盘如使用 SQLite 或 FAISS避免每次重启重建索引。多文档支持扩展加载器支持 PDF、Word、网页等格式。这些优化都可以在本文的模块化结构上逐步叠加而无需推翻重写。12. 总结本文从零手写了一个可运行的 RAG 系统覆盖文档加载、文本切分、向量化、向量存储、检索、提示词组装、生成和溯源全流程。核心收获有三点理解 RAG 的完整数据流文档到块、块到向量、向量到检索、检索到生成。掌握可溯源的实现方法块级元数据 提示词约束 结果透出。获得一个可扩展的模块化代码骨架便于后续接入更复杂的优化策略。你可以把这份代码作为基础结合自己的业务文档和模型服务快速搭建一套属于自己的检索增强问答系统。
延伸阅读

更多相关文章

2026/11/15 9:07:32

3分钟掌握无损歌词下载:163MusicLyrics歌词获取终极指南

3分钟掌握无损歌词下载:163MusicLyrics歌词获取终极指南 【免费下载链接】163MusicLyrics 云音乐歌词获取处理工具【网易云、QQ音乐】 项目地址: https://gitcode.com/GitHub_Trending/16/163MusicLyrics 还在为喜欢的歌曲找不到高质量歌词而烦恼吗&#xff…

2026/11/10 7:44:50

SPI接口原理以及读写接口用例的详细介绍

一,spi接口原理 SPI接口,即串行外设接口(Serial Peripheral Interface),是一种同步串行数据传输协议。它主要用于连接微处理器和各种外设,如存储器、传感器、ADC(模数转换器)和DAC&a…

2026/11/13 7:05:03

终极指南:BilibiliDown - 免费跨平台B站音频提取工具

终极指南:BilibiliDown - 免费跨平台B站音频提取工具 【免费下载链接】BilibiliDown (GUI-多平台支持) B站 哔哩哔哩 视频下载器。支持稍后再看、收藏夹、UP主视频批量下载|Bilibili Video Downloader 😳 项目地址: https://gitcode.com/gh_mirrors/bi…

2026/11/16 8:12:02

西安临时电工证怎么考?电子证书怎么查?实操考试心理没底别慌

西安临时电工证怎么考?电子证书怎么查?实操考试心理没底别慌 实操考试心里没底怕挂科,这是很多准备考西安临时电工证的朋友最真实的感受。尤其是像你这样刚毕业的焦作工程类学生,对考试流程和要求不太熟悉,再加上担心操作不规范导致考试失败,压力真的不…

2026/11/16 8:12:02

广东省电工证怎么换证良心建议:外省电工证怎么转过来

广东省电工证怎么换证良心建议:外省电工证怎么转过来 之前考的证在外省能不能转过来?这几乎是每个想在广东从事电工工作的人都会问的问题。特别是那些已经在其他省份考取了电工证,现在准备在广东发展的朋友,更是关心如何换证或补办。今天就来聊一聊【广东…

2026/11/16 8:12:02

电工证考不过白交培训费?看懂电工作业安全鞋+电子证书全攻略

电工证考不过白交培训费?看懂电工作业安全鞋+电子证书全攻略 怕考不过白交培训费?这事儿真不是危言耸听,尤其你要是像我一样,是鹤壁房建工程一线电工,天天在工地和高压电打交道,要是连电工证都拿不下,别说干活了,连上岗都成问题。别急,这篇文章讲的…

2026/11/16 8:12:02

家庭电工证考题千万别踩坑:证书过期了不知道怎么复审延期怎么办?

家庭电工证考题千万别踩坑:证书过期了不知道怎么复审延期怎么办? 你是不是也遇到过这种情况?手里拿着的电工证眼看就要到期了,却不知道去哪儿复审、怎么延期,一不小心就“失效”了,工作都受影响。这种事真的不能大意,特别是现在国家对特种作业人员的管…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/16 0:00:11

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱 你是不是也和我一样,想考电工证,但不知道去哪报名,怕被中介坑?最近网上有不少人问“黎城电工证查询报名费多少钱”,结果一查,信息五花八门,真假难辨。别担心,今天我就从一线从业者的角度…

2026/11/16 0:00:11

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来?

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来? 之前考的证在外省能不能转过来?这个问题困扰着很多在外地打工的电工,尤其是像南阳卧龙区的建筑工人,他们常年在工地作业,手上持有电工证是基本要求,但很多人因为工作流动性大,担心证书不能转到本…

2026/11/15 4:46:37

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑