简介检索增强生成RAG是当前构建企业知识库问答系统的核心技术范式。其原理是将文档切块、向量化并存入向量数据库在用户提问时通过语义检索召回相关片段再由大模型组织生成回答。这项技术能有效缓解大模型幻觉问题并让模型基于私有知识库提供精准答复广泛应用于内部FAQ、产品手册、制度查询等场景。本文从零开始拆解一套Python极简RAG系统的完整落地过程涵盖项目结构、环境配置、文本切块、Embedding模型选型、向量库使用、检索与生成链路调试并给出常见的工程问题排查方法和低成本优化方向帮助开发者快速搭建可用的本地文档问答系统。 网上讲 RAG 的资料一抓一大把但真能“解压就能跑、改改就能用”的极简版本其实不多。前两天我拿到一份《Python极简RAG知识库系统.zip》解压完大概一百多兆核心代码不算多一条链路却很完整文档导入、文本切块、向量化、检索、大模型生成全齐了。这套东西适合谁适合刚接触 RAG、想快速在本地搭一个文档问答系统的人也适合那些已经看过理论、但一直没动手把流程跑通的朋友。我花了一个晚上把它跑起来又用一个周末改成了可以回答部门内部 FAQ 的小工具这篇文章就是完整的拆解和实操记录。1. 拿到压缩包先做什么项目结构与环境准备很多人解压完 zip 的第一反应是直接找 main.py 然后 python main.py这个习惯在 OpenAI 接口时代勉强能跑但 RAG 项目不行。因为它涉及文本处理、向量库、模型下载、依赖版本任何一个环节缺了都会半路报错。所以拿到压缩包后我建议你先别急着跑把目录结构翻一遍弄清楚它是由哪些模块组成的。1.1 解压之后先翻一翻目录结构一份典型的极简 RAG 项目不管作者把代码写成什么风格最后都会落到这几个模块上文档加载、切块、向量化、检索、问答接口。我拿到这个 zip 后看到的目录大概是这样的Python极简RAG知识库系统/ ├── data/ # 放你的原始文档txt/md/pdf 都行 ├── vectorstore/ # 向量数据库持久化目录 ├── src/ │ ├── ingest.py # 文档导入 切块 写向量库 │ ├── retriever.py # 检索模块 │ ├── generator.py # 大模型生成回答 │ └── config.py # 全局配置模型名、切块参数、API Key ├── app.py # FastAPI 服务入口 ├── requirements.txt └── README.md先说结论这份代码的模块划分是清晰的把“索引”和“问答”分开了这是个好习惯。ingest.py 负责把 data 里的文档变成向量库里的数据retriever.py 负责根据用户问题召回相关片段generator.py 负责把检索结果交给大模型组织成答案。不要小看这种拆分后面你要改切块策略、换向量库、换模型都是只动其中一个文件不用把整条链路掀翻。我建议你复制一份压缩包里的 vectorstore 目录出来做备份。因为向量库构建很费时间万一后面因为版本升级或者参数调整把库搞坏了重建一遍要重新 embedding 所有文档相当痛苦。这种经验都是踩过坑才有的。1.2 Python 环境与依赖安装依赖安装是第一个坑。极简 RAG 系统一般会用到这些库用于文档加载的 pypdf、python-docx用于切块的 langchain-text-splitters用于向量化的 sentence-transformers用于向量存储的 chromadb 或 faiss-cpu用于接口的 fastapi 和 uvicorn。requirements.txt 大概长这样fastapi0.115.6 uvicorn0.34.0 pypdf5.1.0 python-docx1.1.2 langchain-text-splitters0.3.5 sentence-transformers3.4.1 chromadb0.5.23这里我强烈建议用 venv 创建独立环境而不是直接装到系统 Python 里。原因很现实RAG 项目依赖非常敏感chromadb 和 langchain 的兼容性经常出问题你装了别的项目可能把版本冲掉。创建方式cd Python极简RAG知识库系统 python -m venv venv source venv/bin/activate # Windows 是 venv\Scripts\activate pip install -r requirements.txt如果你是国内网络环境pip 默认源下载会很慢尤其 sentence-transformers 还会牵扯 torch 这种几百兆的包。我的习惯是先配好镜像源再安装能省下一大半等待时间pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple另外注意 Python 版本建议 3.10 或 3.11。3.8 太老很多新版本库已经不支持3.12 和 chromadb 的一些旧版本有兼容问题。如果你的系统里同时装了多个 Python 版本用 python3.10 来创建 venv 是最稳妥的别直接用 python 命令赌默认版本。2. RAG 链路到底在做什么三个核心环节拆解RAG 全称是 Retrieval-Augmented Generation检索增强生成。极简版的核心就三件事把文档切成适合检索的片段把片段编码成向量存进向量库检索时把最相关的片段拼进 prompt 让大模型回答。理解这三件事是后面所有调优的前提。2.1 文档加载与文本切块为什么不能整篇扔给模型切块是 RAG 系统里最容易敷衍、也最影响检索质量的一步。很多人图省事直接把整个 PDF 塞进向量库结果检索出来的“相关片段”要么太长、要么半句话都说不完大模型根本没法用。切块的目的不是简单地控制长度而是让每个块成为一个语义相对独立、信息密度适中的检索单元。为什么不能整篇丢给模型首先是 embedding 模型有最大输入长度限制像 bge-small-zh-v1.5 支持 512 token超了会被截断截断后向量表达的就是“文档开头”后面的关键内容根本进不了向量。其次是检索粒度问题如果一块是几千字用户问一个小点召回的块里真正相关的可能只有一小段剩下全是噪音大模型容易被带偏。最后是成本问题每个块都会作为 prompt 的一部分发给大模型块越多越长调用成本越高。极简版里最常用的切块方式是“递归字符分隔切块”。它的思路很朴素先按段落分隔符如换行切如果切出来的块还是太长再按句号、逗号、空格逐级往下切。LangChain 里的 RecursiveCharacterTextSplitter 就是这个逻辑参数一般这样设from langchain_text_splitters import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap80, separators[\n\n, \n, 。, , , , ], )chunk_size 为什么取 500这是根据你的 embedding 模型和文档语言定的。中文字符和 token 的换算大概 1 个汉字约等于 0.6 到 1 个 token如果模型上限是 512 token那 500 字符比较安全如果用的是 8192 上下文的模型可以放大到 800 到 1000。chunk_overlap 的作用是让相邻块之间保留一部分重叠内容避免一句话恰好被从中间切开、语义断裂。经验上 overlap 取 chunk_size 的 10% 到 20% 比较合理80 在 500 的块下就是 16%。切完块之后要做两个事一是保留每个块的来源信息比如文件名、页码、标题二是打印几条切分结果看看有没有出现“一句话被拦腰截断”或者“一个块里塞了两三个无关主题”的情况。这个检查和调参过程值得你花 10 分钟认真做一遍因为后面所有检索质量都依赖这一步。2.2 Embedding 与向量检索把文本变成坐标再找邻居切好的文本片段要变成向量才能检索。Embedding 这个词听着玄乎你可以理解成给每段文本计算一组坐标把语义相近的文本映射到坐标空间中相近的位置。用户提问时也把问题变成向量然后去向量库里找“坐标最近”的几个片段。这个环节第一个坑是 embedding 模型选择。如果文档全是中文强烈建议用中文语料训练过的模型。英文模型不是不能用而是对中文语义的表达能力明显弱检索出来的结果经常“看起来相关、实际不对”。极简系统里用 bge-small-zh-v1.5 是个比较稳的选择体积小、中文效果好、CPU 也能跑。加载方式from sentence_transformers import SentenceTransformer model SentenceTransformer(BAAI/bge-small-zh-v1.5)如果你的机器有 NVIDIA 显卡可以换 bge-large-zh-v1.5效果更好但显存占用也更高。如果完全不打算本地跑 embedding也可以调用现成的 Embedding API代码里把 SentenceTransformer 换成对应的 API 客户端就行。极简版用本地模型的好处是离线可用、无额外成本坏处是首次运行要下载模型网络不好时容易卡住。我一般会提前把模型下载到本地再加载避免程序每次启动都要检查网络。向量库的选择上极简项目用 Chroma 或 FAISS 都行。Chroma 的优点是自带管理界面、持久化简单适合做知识库这种需要多次增删的场景FAISS 更轻量、检索更快但需要自己管理索引的保存和加载。这份 zip 里默认用的是 Chroma因为它对新手最友好pip 安装后直接能用本地路径就是持久化存储。检索的核心是相似度计算极简版用的通常是余弦相似度。Chroma 里默认的检索距离是 L2有时也会配成余弦。概念上不用太纠结你只需要知道检索结果里会返回一个 distance 分数分数越低代表越相似L2 距离如果配了余弦距离则相反。后面调阈值时要先搞清楚这个距离类型否则会把阈值设反。检索参数里最常用的两个要召回多少个候选块。这个值太小比如 2可能漏掉关键信息太大比如 20又会让 prompt 变得冗长、大模型抓不住重点。极简版先设 4 到 6 跑起来后面再根据效果调。2.3 生成环节本地模型与 API 两种路线检索只负责召回最终回答要靠大模型。极简 RAG 系统里生成环节有两条路线代码里通常都留了接口。第一条是调用云端大模型 API比如 OpenAI 兼容接口。这样配置最简单效果也最稳定适合快速验证。但要注意 Base URL 和 API Key 的配置很多国内服务商都提供 OpenAI 兼容的接口你只要在 config.py 里改两个配置就行。第二条是在本地跑开源模型比如通过 Ollama 加载 qwen2.5:7b或者用 llama.cpp 跑 GGUF 格式的量化模型。这条路的好处是数据不出本机、无按量付费适合做私有知识库。代码里一般只需要把模型名配成你本地 Ollama 的模型标签# config.py LLM_PROVIDER ollama # 可选 api 或 ollama OLLAMA_MODEL qwen2.5:7b OLLAMA_BASE_URL http://localhost:11434生成环节背后是一个 prompt 拼接的过程。检索出来的相关片段会塞进一个系统提示词模板里让大模型“只根据给定资料回答不要臆测”。这个模板对回答质量影响非常大。极简版里通常是这样prompt f你是知识库问答助手。请仅根据下面的参考资料回答问题。 如果资料中没有相关信息请直接说“根据现有资料无法回答”不要编造。 参考资料 {context} 用户问题{query} 回答注意这里的措辞。如果不加“仅根据资料回答”的约束大模型会自由发挥看起来答得挺顺溜其实可能是在胡编。知识库问答最怕的就是一本正经地胡说八道所以 prompt 里的约束不能省。这也是极简 RAG 系统里为数不多“不需要增加代码量只需改几句话”就能显著提升质量的地方。3. 从零跑通一遍最简配置实操记录理论部分讲完该上手了。我实际跑这套系统时是按照“准备测试资料 → 构建索引 → 启动问答 → 提问验证”的顺序来的。下面每一步都记录了我当时的操作和结果你可以照着走一遍。3.1 准备一份最小可用的测试资料第一份测试资料不用多我建议准备 3 到 5 篇文档就够了内容要有点区分度。比如你可以放到 data 目录下三份文件一份公司制度说明、一份产品 FAQ、一份技术方案。格式用 txt 或 md 最省事PDF 还要处理解析依赖。需要注意编码问题。txt 文件必须保存为 UTF-8Windows 记事本默认的 ANSI 编码在读取时容易乱码。我踩过这个坑后来统一在 VS Code 里把文件编码改成 UTF-8 再放入 data 目录。还有一个容易忽略的点文档的标题和目录信息最好保留。很多极简系统切块时没有把标题作为元数据写入每个块导致检索时只知道“某个片段来自某份文档”不知道它属于哪个章节。这样回答里的引用溯源就不够精确。如果你打算做知识库问答建议在文档里用清晰的标题层级至少让切块后的每个块能对应到一个小节。后面你可以在元数据里加上 heading 字段引用时直接显示“来源《产品FAQ》/ 3.1 权限问题”观感会好很多。不过极简版先不折腾这些把三份测试文档放好就行。3.2 构建索引embedding 全部文档并写入向量库构建索引是整个流程中耗时最久的一步。运行方式通常是这样python src/ingest.py --data ./data --vectorstore ./vectorstoreingest.py 的逻辑是遍历 data 目录下的所有文件按扩展名选择合适的加载器接着逐个切块、逐块计算 embedding最后写入 Chroma 持久化目录。日志里会打印每一份文档处理了多少个块、耗时多少秒。我当时三份文档一共不到两万字切出来大概五十多个块CPU 环境下 embedding 用了几十秒速度还可以接受。如果你换成一千页的 PDF这个过程可能持续十几分钟甚至更久。这里我要特别强调embedding 完成后你要去检查一下向量库里的块数量是否跟预期一致。一个常见的 bug 是文档加载器解析失败导致某个文件静默跳过你还没发现最后检索时就是查不到那份文档里的内容。验证方法很简单Chroma 里查一下 collection 的 countimport chromadb client chromadb.PersistentClient(path./vectorstore) collection client.get_or_create_collection(knowledge) print(collection.count())如果数量明显偏少就去查 ingest 日志里有没有解析失败的文件。对于 PDF尤其要小心扫描件那种纯图片型的 PDF 必须先 OCR否则解析出来是一堆空行。另外要说一下增量更新的问题。极简版最常见的做法是全量重建索引也就是每次新增文档把 vectorstore 目录删掉重跑 ingest。文档少的时候这么做没问题但文档多了以后每次全量重建都是在浪费时间。更合理的做法是让系统支持增量导入每次只 embedding 新文件。这个改造不难核心就是先按文件路径查一下是否已经在向量库里如果存在就跳过或删除旧块再写入。如果你的系统里有这个需求可以优先考虑改造这一点。3.3 启动问答服务命令行与 Web 接口索引构建好之后就可以启动问答服务了。极简版一般有两种交互方式命令行问答和 FastAPI 接口。命令行方式适合自测python src/chat.py --query 员工请假需要提前几天申请它会打印出召回的前几个片段以及最终回答。这种方式调试最方便你能直接看到 prompt 里到底拼了哪些内容。第一次提问前建议先看一下打印出来的召回片段确认它们跟问题确实相关。如果相关片段本身就答非所问那后面大模型生成得再好也白搭。FastAPI 方式适合接前端或做服务化。启动命令uvicorn app:app --host 0.0.0.0 --port 8000然后就可以用 curl 测接口了curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {query: 员工请假需要提前几天申请}返回的 JSON 通常长这样{ answer: 根据资料员工请假需要至少提前 3 天申请特殊情况需提前 1 天说明。, sources: [ { content: 请假制度员工请假需提前三天提交申请……, source: data/公司制度.txt, score: 0.82 } ] }我实际跑通时最深的感受是RAG 系统“跑通”只是第一步远没到“好用”的层面。第一次问答往往有两种极端结果要么检索到的片段偏离主题要么大模型回答得太发散。这两种问题分别在检索链路和生成链路排查方式完全不同。下面的章节我会详细说。4. 常见问题与排查技巧实录极简 RAG 系统能跑通不难难的是出问题时能快速定位在哪一环。我在部署和改造过程中遇到过的典型问题基本可以分为四类依赖安装问题、Embedding 问题、检索质量问题和生成质量问题。下面整理成速查表后面再展开讲几个印象深刻的。问题现象可能原因处理方式启动时报 No module named langchain_communitylangchain 新版拆分了子包按 requirements 安装对应依赖或降级到 langchain 0.1.x中文检索结果明显不相关embedding 模型是英文模型换成 bge-small-zh-v1.5 或 bge-large-zh-v1.5向量库报 Collection 不存在目录路径不对或首次 ingest 失败检查 vectorstore 路径、重新 ingestChroma 打开旧库失败chromadb 版本升级不兼容用与构建库时相同的 chromadb 版本或重建索引回答里包含“根据提供的信息”这类空话prompt 约束不足强化 prompt“直接给出答案不要复述资料”答案是对的但来源对应不上切块时没保留标题元数据切块时把文档标题、章节写入 metadataPDF 导入后没有内容PDF 是扫描件或解析库兼容问题先用 pdfplumber 测试抽取扫描件需 OCR大模型回答过长/过短prompt 没有限制回答格式在 prompt 中约束回答长度和风格4.1 Embedding 模型选错中文检索效果惨不忍睹这个是新手最容易踩的坑。我最初那份 zip 里默认配的是 all-MiniLM-L6-v2一个经典的英文通用 embedding 模型。我用中文文档跑了一遍问“请假需要提前几天”召回的片段全是“薪资发放日期”“办公用品申领”之类完全不在点上。原因不复杂英文模型训练时中文语料占比太少对中文字词的语义映射很差导致中文句子在向量空间里的区分度很低。解决办法就是换中文模型。bge-small-zh-v1.5 是我用过性价比比较高的它还会做 query 指令优化检索时给 query 加一个“为这个句子生成表示以用于检索相关文章”的前缀效果更好不过极简代码里一般没有这个操作不加也能用。值得注意的是embedding 模型一旦换掉之前构建的向量库必须重建。因为不同模型的向量维度、语义空间都不一样旧向量和新向量混在一起检索结果一定会乱套。所以换 embedding 模型之前一定要先确认你愿意重新跑一遍 ingest。4.2 Chroma 版本升级导致向量库打不开这个坑很典型。极简系统的 requirements 通常只锁定大版本不锁具体版本号。过了一段时间你重新安装依赖很可能装到一个比原来新的 chromadb而 chromadb 升级到 0.4 以后对持久化格式有变更旧库可能直接报错或者读取异常。遇到这种情况最稳妥的办法是不要纠结于“修好旧库”直接把 vectorstore 目录删掉用当前版本的依赖重新 ingest。代价只是重新跑一遍 embedding但能避免因为版本兼容问题浪费数小时。我的建议是在你第一次成功跑通后立刻执行 pip freeze 把当前版本固定下来生成一份 requirements-lock.txt。以后无论换机器还是给别人复现都用这份锁文件安装能把很多兼容性问题扼杀在摇篮里。4.3 检索到的片段“看起来相关实际不对”这是最让人头疼的情况。系统不报错回答也通顺但内容就是不对。排查时要先看召回片段再决定是调检索还是调生成。具体步骤我一般这样走第一步直接打印检索结果。看召回的前几个片段里标题、关键词跟问题的匹配程度。如果召回的内容确实跟问题相关那就是生成环节的问题比如 prompt 里没有强调“严格基于资料”。如果召回的内容本身就跑偏了那就是检索环节的问题需要调 embedding 模型、切块参数或检索阈值。第二步检查切块粒度。我遇到过一个问题“产品的续费价格是多少”结果召回的都是包含“价格”两个字的块但那些块是在讲“价格调整通知”里的无实质内容。因为我的 chunk_size 设得太大一个块里包含了多个主题embedding 的结果被其他主题稀释了。把切块调小一点或者按标题切块问题就消失了。第三步看阈值。Chromager 返回的相似度分数能反映召回质量。如果你把阈值设得很低很多不相关的块也会混进来大模型被噪音干扰设得太高该召回的被过滤掉了。先用默认参数跑一遍统计几次问答的分数分布再去定阈值而不是凭空猜。5. 把系统改成适合自己的业务形态低成本优化方向跑通极简版之后下一步往往是按自己的业务场景做改造。RAG 的优化点非常多但我不建议一上来就上 Agent、GraphRAG 那些复杂架构。先把基础链路打磨好性价比更高。下面几个是我实际用过的低成本优化方向。5.1 切块策略按文档结构做调整通用切块器适合快速启动但如果你有结构明显的文档比如规章制度、手册、培训资料按标题切块往往效果更好。思路是先解析文档的标题层级把每个标题下的内容作为一个候选块如果内容太长再递归切分同时把标题作为 metadata 写入每个块。这样做有两个好处一是块的语义完整性更好因为一个标题下的内容通常围绕同一主题二是引用溯源更精确回答里可以直接显示“来源《XX手册》/ 2.3 申请流程”读者一看就知道出处。实现上可以基于 MarkdownHeaderTextSplitter或者自己写一个简单的按 Markdown 标题拆分的函数。极简版系统不需要引入额外框架写几十行代码就能搞定。5.2 检索增强混合检索与重排纯向量检索有个通病对专有名词、精确编号、型号这类信息不敏感。比如你问“备案号是 2024-001 的文件在哪个目录下”embedding 匹配可能找不准。这时候混合检索就很有用在向量检索之外再加一路关键词检索通常是 BM25。两条路各召回一批结果取并集再排序。排序环节可以引入 cross-encoder 重排模型比如 bge-reranker-base。它的思路是把问题和候选片段成对输入模型让模型直接打分比向量相似度更准。极简做法是先召回 20 个候选块重排后只取前 5 个进 prompt。这一步对检索精度的提升非常明显代价只是多花几十毫秒。不过要注意cross-encoder 重排模型也需要加载到内存里如果你的机器资源紧张可以先不加。先把基础链路用顺再逐步叠加这些能力。5.3 引用溯源与防幻觉让模型学会说“不知道”知识库问答最要紧的是可信度。我的经验是光靠 prompt 里一句“不要编造”远远不够还要把引用信息带进回答。具体做法召回时把每个片段的内容、来源、页码都存下来生成时在 prompt 里给每个片段编号要求模型在回答末尾标注引用了哪几个编号。然后我们把这些编号映射回片段元数据展示给用户。这个改造在代码层面不难但要提前在切块阶段就把 source 信息写好否则后面补很麻烦。防幻觉的另一个有效手段是在 prompt 里给模型“拒绝回答”的权限。我用的模板是如果参考资料中找不到与问题直接相关的信息请回答“根据现有资料无法回答该问题”不要尝试推测。你能访问的资料范围是固定的超出范围的内容一律不回答。加上这句话之后系统面对超出知识库范围的问题时会老实很多。你可以自己测试一下问几个库里显然没有的问题对比加这句前后的回答。很多时候回答说“不知道”不是服务的失败而是可靠性的表现。5.4 后续方向从 RAG 到 Agentic RAG如果基础链路已经稳定想再往前走一步可以考虑 Agentic RAG 的方向。它不是另起炉灶而是在现有检索问答之上让模型具备“判断和行动”的能力比如先判断问题是否需要检索、用改写后的关键词重新检索、检索结果不足时主动追问用户、把多轮对话中的上下文纳入检索条件。这个方向很好但实现复杂度明显上升而且调试成本高。以我的经验如果你手上的场景就是“一堆文档做一个问答助手”当前这套极简 RAG 已经能覆盖大部分需求。Agentic 的改造更适合那些问题形态非常多、检索条件经常需要动态调整的场景。不要为了一时的技术潮流把系统做得过于复杂。先把检索质量、引用溯源、切块策略这三件事做到位你得到的收益会比上个框架多得多。我实际把这套极简系统部署到部门内部之后最深的体会是RAG 项目真正花时间的不是把链路跑通而是把“文档切得好不好、检索准不准、回答稳不稳”这三件事反复打磨。这份 zip 是一个很好的起点但想要用在真实业务里至少要经历一次“测试文档 → 真实文档 → 调参 → 再测”的循环。如果你也正在折腾类似的项目建议先从三份文档开始跑通后把切块参数和 embedding 模型各换几种对比效果。这个过程中的手感比看任何教程都管用。本文还有配套的精品资源点击获取