简介RAG检索增强生成技术能有效提升知识库问答的准确性与可解释性其核心原理在于将文档切块、向量化存储并在回答前检索最相关的片段作为上下文。对于内部资料、离线场景或轻量化应用一个极简的本地知识库系统往往比引入重型框架更务实。这种方案利用Python生态中的轻量组件即可实现完整闭环并通过FastAPI快速封装成可调用的服务接口。然而将系统打包分发给同事时常见问题如“file is not a zip file”或“could not find eocd”往往源于文件传输损坏或非标准压缩包而非代码本身。这篇文章从零拆解极简RAG的构建思路包括依赖选型、文档切块、向量检索与调优记录并重点总结zip分发时的踩坑经验帮助开发者在十分钟内搭建并分发一套可用的本地知识库问答系统。 先说个结论如果你只是想给一堆本地 PDF、Word、Markdown 搭一个问答机器人真没必要一上来就是 LangChain Chroma OpenSearch 全家桶。上个月我给自己的项目笔记做了个“Python 极简 RAG 知识库系统”压缩成 zip 后发给同事同事解压、装依赖、跑起来整个过程没超过十分钟。这个项目没有复杂的框架核心代码量很小但检索、问答、知识库更新这几个环节全都有。这篇文章就把这个 zip 里面的思路完整拆开讲极简 RAG 怎么搭、哪些依赖必须装、FastAPI 怎么包一层接口、最后打包成 zip 分发时踩过的那些坑特别是“file is not a zip file”这类经典报错。1. 极简RAG到底“简”在哪四件套和它们的边界先看一遍这个项目最终长什么样。解压 zip 之后目录结构是这样的rag_system/ ├── requirements.txt ├── README.md ├── app.py # FastAPI 服务入口 ├── rag/ │ ├── __init__.py │ ├── loader.py # 文档读取 │ ├── chunker.py # 文本切块 │ ├── embedder.py # 向量化与索引 │ ├── searcher.py # 检索 │ └── generator.py # 调用 LLM 生成回答 ├── models/ # 模型文件目录GGUF 等 └── data/ # 知识库原始文档我不放任何数据库配置没有 Redis、没有消息队列连向量数据库都是用一个本地 Faiss 索引文件替代的。为什么敢这么干因为 RAG 的本质其实就四步加载文档、把文本切块、把每一块转成向量存起来、用户提问时检索相关块喂给大模型。知道了这一步你就明白哪些组件是省不掉的哪些可以砍。文档加载pypdf 读 PDF内置的 open() 读 txt 和 markdown够用。文本切块自己写一个 splitter几十行代码不需要 LangChain 的 TextSplitter。向量化sentence-transformers 加载一个中文 embedding 模型。向量存储与检索faiss-cpu保存在内存里就行不需要单独部署服务。大模型生成llama.cpp 的 Python 绑定加载 Qwen2-7B 的 GGUF 模型纯本地推理。有人可能会问为什么不直接用 ChatGPT API因为知识库属于内部资料而且很多场景要求本地离线运行。用本地模型是“极简”的另一个含义不依赖外网、不额外花钱、数据不出内网。这个系统能在只有 CPU 的机器上跑虽然慢一点但能完整跑通链路。这套东西看起来很“简陋”但它恰恰覆盖了一个知识库问答系统的最小闭环。后续你想加权限、加增量更新、加多用户隔离都是在这个闭环上做扩展。先把最小闭环跑通比一开始就设计十来个微服务要靠谱得多。2. 依赖选型不用 LangChain 也能跑但 embedding 和 LLM 不能省我在一开始写的时候其实纠结过要不要用 LangChain。最后放弃了。不是 LangChain 不好而是它对你理解 RAG 原理没什么帮助反而把链路包了一层又一层。出了问题你要在抽象层之间跳来跳去排查起来很痛苦。极简项目的原则是每个组件都应该是你能看懂且能单独替换的。依赖我用的是这几样组件选型备注文档解析pypdf纯 Python适合 PDFtxt/md 直接读文本切块自写 chunker避免引入重依赖Embeddingsentence-transformers BAAI/bge-small-zh-v1.5中文效果不错维度 512向量索引faiss-cpuIndexFlatIP内存索引简单直接LLMllama-cpp-python Qwen2-7B-Instruct GGUF本地推理CPU/GPU 均可API 层FastAPI uvicorn轻量带 Swagger 文档先说 embedding 模型。中文场景我直接选了 BGE 系列中的 small 版本512 维。相比更大的 bge-large它的好处是内存占用低、速度快而且对 CPU 机器友好。如果知识库文档超过十万块再考虑用更大模型提升精度。实际测试下来对中文技术文档BGE-small 的 top-5 召回率已经很能打了。再说 LLM 部分。llama-cpp-python 有一个特点安装方式会因为硬件条件不同而不同。比如 CPU 版直接pip install llama-cpp-python就行如果有 Nvidia 显卡建议先用CMAKE_ARGS-DGGML_CUDAon pip install llama-cpp-python装带 CUDA 的版本。我当时图省事装了 CPU 版Qwen2-7B 用 Q4_K_M 量化16G 内存的机器也能跑一个 200 字的问题大概要等十几秒。如果换成 1.5B 或 3B 的模型延迟能降到 2 秒以内极简场景下其实更合适。还有个容易被忽略的坑requirements.txt里最好把版本锁死。因为llama-cpp-python、sentence-transformers、faiss-cpu这几个库更新很快不锁版本可能出现“今天能装下周装不上”的情况。我的 requirements 大致是fastapi0.109.0 uvicorn0.23.2 pypdf3.17.4 sentence-transformers2.2.2 faiss-cpu1.7.4 llama-cpp-python0.2.26 numpy1.24.4注意numpy版本不要太高因为 faiss-cpu 1.7.x 对 numpy 2.x 的兼容性有点问题。这个不是我瞎说我第一次在全新环境安装时就因为 numpy 自动升到 2.0 导致 faiss 导入报编译错误。3. 主流程代码从 PDF 切块到向量检索再到 Qwen 回答这块是项目的核心也是我建议你照着敲一遍的部分。我把它拆成几个小模块来写。3.1 文档加载不要只看扩展名loader.py 里面我处理了 pdf、txt、md 三种格式。为什么不处理 docx因为极简项目里我一般会建议把 Word 转成 PDF 或 txt 再导入。加了 python-docx 又多一个依赖收益不大。代码很简单from pypdf import PdfReader from pathlib import Path def load_document(path): path Path(path) suffix path.suffix.lower() if suffix .pdf: reader PdfReader(str(path)) text \n.join(page.extract_text() for page in reader.pages) elif suffix in (.txt, .md): text path.read_text(encodingutf-8) else: raise ValueError(f不支持的文档格式: {suffix}) return text这里请留个心extract_text()对扫描版 PDF 几乎是废的因为里面是图片不是文字。如果你要处理扫描件得先用 OCR但这会破坏“极简”的定位所以我没加。3.2 切块策略最简单的重叠窗口切块是整个 RAG 链路里最容易被低估的环节。切太碎语义不完整切太大检索出来上下文太长喂给大模型又浪费 token。我用的是固定长度加重叠窗口def chunk_text(text, chunk_size500, overlap50): if len(text) chunk_size: return [text] chunks [] start 0 while start len(text): end start chunk_size chunks.append(text[start:end]) if end len(text): break start max(end - overlap, start 1) return chunks这段逻辑很直白每次前进chunk_size - overlap个字符保证两个相邻切块中间有 50 个字符是重叠的。为什么需要重叠因为如果某个知识点刚好被拦腰切断重叠窗口能大概率让这个知识点出现在至少一个完整切块里。我在自己的技术笔记上试过chunk_size 在 300-500 之间overlap 在 50-100 之间效果比较稳定。3.3 向量化与 Faiss 索引embedder 模块里我保存了一个全局的 Faiss 索引和对应的原文列表。注意 Faiss 存的是向量不存原文所以必须有一个chunk_store列表把向量的顺序和切块原文对应起来。import faiss import numpy as np from sentence_transformers import SentenceTransformer _model SentenceTransformer(BAAI/bge-small-zh-v1.5) _dim 512 _index faiss.IndexFlatIP(_dim) _chunk_store [] def add_document(text): chunks chunk_text(text) vectors _model.encode(chunks, normalize_embeddingsTrue) _index.add(np.array(vectors, dtypenp.float32)) _chunk_store.extend(chunks) return len(chunks) def save_index(path): faiss.write_index(_index, path) def load_index(path): global _index if Path(path).exists(): _index faiss.read_index(path)这里有几个细节需要注意。第一normalize_embeddingsTrue很重要它把向量归一化到单位长度配合IndexFlatIP内积索引算出来的分数其实就是余弦相似度值域大概在 -1 到 1 之间。第二如果重启服务想保留之前的索引可以save_index到本地启动时再load_index。这也是极简方案里“持久化”的讨巧写法。3.4 检索不要只看相似度排序searcher 模块负责把 query 转成向量然后在 Faiss 里搜 top-k 并返回原文片段def search(query, top_k5): vec _model.encode([query], normalize_embeddingsTrue) scores, indices _index.search(np.array(vec, dtypenp.float32), top_k) results [] for score, idx in zip(scores[0], indices[0]): if idx 0 or idx len(_chunk_store): continue results.append((_chunk_store[idx], float(score))) return results索引里没有足够数据时Faiss 可能返回 -1所以要做一次范围判断。另外我会在实际使用中过滤掉分数很低的结果比如相似度低于 0.45 的切块基本可以认为和问题无关。宁可回答“知识库中找不到相关内容”也不要硬凑一段垃圾上下文给大模型。3.5 生成把检索结果塞进 Promptgenerator 里加载 Qwen2-7B 的 GGUF 文件然后构造一个简单的中文提示词模板。这里不需要任何复杂框架就是把检索到的文本拼接起来from llama_cpp import Llama _llm Llama( model_pathmodels/qwen2-7b-instruct-q4_k_m.gguf, n_ctx4096, n_threads8, verboseFalse, ) def generate(query, context_text): system_prompt 你是一个严谨的知识库问答助手。请仅根据提供的资料内容回答问题如果资料中找不到答案请明确说明。 prompt f{system_prompt}\n\n参考资料\n{context_text}\n\n问题{query}\n回答 output _llm(prompt, max_tokens512, temperature0.2, stop[|im_end|]) return output[choices][0][text]Qwen2 的 chat 格式一般带|im_start|和|im_end|如果你用的是官方 instruct 版本建议用它的 chat template而不要像我上面这样直接拼接。上面这段代码只是一个简化的可运行版本实际发布时我按 Qwen 的模板封装了一层format_chat在完整源码里能看到。temperature0.2是我在问答场景下的经验值。低于 0.2 会显得机械高于 0.5 容易跑题。知识库问答要的是稳定不是创造性。4. FastAPI 外壳几分钟把知识库变成可调用的问答服务光有推理逻辑还不够要让同事快速用起来我得给这个系统加一个 HTTP 接口。FastAPI 在这里很合适它自带 Swagger 文档浏览器打开/docs就能测试接口不需要额外写前端。4.1 先写两个接口接口设计得尽量简单一个用于上传文档一个用于提问。from fastapi import FastAPI, UploadFile, File from pydantic import BaseModel import io app FastAPI(title极简RAG知识库) class Question(BaseModel): q: str app.post(/upload) async def upload(file: UploadFile File(...)): content await file.read() # 兼容 PDF 和 txt if file.filename.endswith(.pdf): from pypdf import PdfReader reader PdfReader(io.BytesIO(content)) text \n.join(page.extract_text() for page in reader.pages) else: text content.decode(utf-8) n add_document(text) return {message: f成功添加 {n} 个切块} app.post(/query) async def query(question: Question): results search(question.q) context_text \n\n.join([r[0] for r in results]) answer generate(question.q, context_text) return {answer: answer, evidence: [{text: r[0], score: r[1]} for r in results]}这里我故意把/query的返回里带上 evidence 字段。为什么因为在知识库问答里用户需要知道答案是哪些资料支撑的。验证 RAG 效果最直接的方法就是看返回的 evidence 是不是真的和问题相关。你去调 ChatGPT 只会拿到一个答案但在这里你还能看到模型是从哪一段文本里找到的。这也是自建知识库系统比直接用通用大模型强的地方。4.2 前端演示页为了给同事做演示我还在static/里放了一个极简单的 HTML 页面就是两个 textarea 加一个按钮上传文档和提问都在同一个页面。不要把前端做复杂这个系统的重点是后端链路。启动方式很简单在项目根目录执行uvicorn app:app --host 0.0.0.0 --port 8000然后浏览器访问http://127.0.0.1:8000就能看到上传和问答的页面。如果你不想在服务器上暴露端口可以只监听127.0.0.1这样只有本机能访问。4.3 内存索引的边界这个设计有个明显边界Faiss 索引是存在内存里的一旦服务重启没保存过的索引就丢了。所以我在实际使用中给系统加了个“先建索引再启动”的脚本首次启动时扫描data/目录下所有文档全部向量化后把索引写到index.faiss后面再启动就直接加载。整个过程大概是这样if Path(index.faiss).exists(): load_index(index.faiss) else: for doc in Path(data).glob(*.pdf): text load_document(doc) add_document(text) save_index(index.faiss)这样做的好处就是知识库的内容在第一次建立索引后固化下来之后新增文档就通过/upload接口动态加入不会把内存撑爆。5. 分发 zip 才是难点解压报错、conda 安装和文件损坏排查我打包成 zip 的原因是同事机器性能一般不期望他装 Git、拉仓库、配环境只想让他解压后直接pip install -r requirements.txt。但正是这个“zip 分发”过程让我撞见了一连串问题每一个都值得单独拿出来说。5.1 打包命令和注意点在 Linux 或 macOS 下我一般这样打包zip -r rag_system.zip rag_system -x rag_system/models/*.gguf -x rag_system/__pycache__/*为什么排除 GGUF 模型文件因为模型文件动辄 4-5 GB走邮件或聊天软件根本发不出去。我会把模型单独放到网盘或内网共享目录给同事一个下载链接。所以 zip 里只包含代码、requirements.txt和 README模型让使用者自己放到models/目录。如果是在 Windows 上用 PowerShell 的Compress-Archive -Path rag_system -DestinationPath rag_system.zip也能生成 zip但压缩出来的文件结构会多一层目录README 里要写清楚解压路径。5.2 经典报错file is not a zip file这是同事们遇到最多的一个问题分为两种形态。第一种是在解压工具里直接弹“file is not a zip file”第二种是在 Java/Python 等代码里看到类似的 “invalid zip archive: could not find eocd”。我排查完后发现原因几乎都相同这个文件根本不是标准的 zip 文件。最常见的场景是我用网盘分享链接同事在浏览器里点击下载结果网络不稳定文件下载到一半中断或者下载出来的是一个 HTML 错误提示页但文件名后缀仍然是.zip。zip 格式的文件头固定是PK十六进制50 4B如果文件头不是PK那它大概率不是 zip。Linux 下直接看file rag_system.zip如果输出是HTML document那就说明你下载到了一个网页而不是压缩包。Windows 下可以看文件大小一个代码项目的 zip 通常至少几十 KB如果下载下来只有几 KB那基本就是错误页面。Python 也可以做一个快速检查import zipfile def check_zip(path): try: with zipfile.ZipFile(path) as zf: print(fzip 有效包含 {len(zf.namelist())} 个文件) except zipfile.BadZipFile as e: print(fBad zip: {e})could not find eocd里的 EOCD 是 zip 文件末尾的中央目录结束标记。一个完整的 zip 在最末尾必须有这段记录如果下载不完整或者有人强行给一个损坏文件改了后缀就会出现这个报错。处理方式很简单重新下载换个下载工具或用浏览器自带的下载功能尽量不要用不稳定的下载器。另外我建议我这边再发一次 zip 的 MD5 校验值同事下载完可以自己校验避免文件传输过程中被拦截或截断。5.3 在 conda base 环境里安装失败怎么办“github 下载的 zip 如何安装在 conda base 环境中”这类问题也常有人问。我的态度是不要直接装进 conda base。conda base 是你 Python 环境的本底里面可能有各种项目依赖直接pip install -r requirements.txt很容易把 base 搞得一团糟。正确做法是给这个 RAG 项目单独建一个环境conda create -n rag python3.10 conda activate rag pip install -r requirements.txt python -c from rag.embedder import _index; print(index ok)如果确实想装进 conda base倒也不是不行但你要做好心理准备。因为sentence-transformers依赖的torch版本可能和你 base 里已有的torch冲突轻则版本被覆盖重则其他项目跑不了。另外要注意conda 安装包时如果不指定 pip 的--no-cache-dir可能因为缓存原因安装某些库后出现“导入失败 caused by invalid zip archive: could not find eocd”这种诡异问题。解决办法是清掉 pip 缓存重新装pip install --no-cache-dir -r requirements.txt5.4 密码保护和解压路径我不建议在打包 zip 时加密码。因为 zip 的加密本质上只是对文件名和内容做简单 AES/ZipCrypto 加密密码一复杂接收方容易忘密码一简单等于没加密而且很多 Linux 默认解压工具并不支持带密码的 zip。如果项目里有敏感数据我建议把敏感数据单独拿出去不要和代码一起打包。如果别人给你发了一个带密码的 zip最靠谱的办法还是找分发人要密码或者用支持 AES 解密的软件如 7-Zip 来解。6. 你以为跑通就结束了吗切块、检索和模型参数的调优记录第一次跑通的时候我认为只要“能回答问题”就万事大吉了实际一测才发现回答质量离“能用”还有不少距离。这个章节记录了我调优的一些经验按重要性排序。6.1 切块长度和重叠比例怎么定我一开始用chunk_size1000, overlap100测试结果很一般。问题出在1000 个中文字符对很多技术文档来说太长了一个问题背景往往只涉及其中一两百字检索时相似度会被无关字符稀释。后来我改成chunk_size400, overlap80召回内容明显更聚焦。另一个细节是不要对所有文本用同一个切块函数。如果你的文档有明确的一二三级标题优先按标题切分把每一个标题下的内容作为一个候选块再对特别长的段落做二次切分。这比纯字符窗口更“懂”文档结构。我的 chunker 里加了一个笨办法如果文本中出现连续两个换行就在那个位置尝试断开优先保证每个切块能落在自然段边界上。6.2 检索 top-k 和分数阈值top_k 选多少我试过 3、5、8。选 3 时上下文太短模型经常答不全选 8 时无关内容太多模型容易被带偏。最后停在 5。另外一个更好用的是“截断策略”先取 top-10然后只看相似度在最高分 0.85 以上的那些这样做比固定 top_k 更鲁棒。在我写的 searcher 里实际逻辑和你看到的简化版有一点点不同def search(query, top_k10, min_ratio0.85): vec _model.encode([query], normalize_embeddingsTrue) scores, indices _index.search(np.array(vec, dtypenp.float32), top_k) results [] valid_scores [] for score, idx in zip(scores[0], indices[0]): if idx 0: continue results.append((_chunk_store[idx], float(score))) valid_scores.append(float(score)) if not valid_scores: return [] max_score max(valid_scores) results [r for r in results if r[1] max_score * min_ratio] return results这个min_ratio0.85是我调出来的经验值并不绝对。如果知识库内容覆盖比较密可以调到 0.9如果文档量少、问题跨度大0.75 更合适。6.3 模型量化和线程数Qwen2-7B 的 GGUF 量化版本很多我实测过几个Q8_0 回答质量最好但内存占用逼近 8GBCPU 机器慢得让人焦虑Q4_K_M 是质量和性能的折中Q2_K 不太推荐中文理解能力下降太明显。如果你只想验证流程可以先用 1.5B 的模型几分钟就能跑通整个链路之后再决定要不要换 7B。还有n_threads并不是越大越好。在我的 8 核 CPU 上n_threads4反而比n_threads8更快因为内存带宽会成为瓶颈。这个参数最好在你自己机器上对比几次再定。6.4 embedding 模型的知识库适配用 BGE-small 的时候要注意它的输入长度限制是 512 token。如果你的 chunk_size 是 400 个字符那没问题如果调到 800 个中文字符embedding 模型会自动截断被截掉的语义就丢了。这也是我最后选择chunk_size400的原因之一必须让切块长度和 embedding 模型的 max_seq_length 匹配。如果你想增大单块信息量可以考虑换用 bge-base 或 bge-large它们的最大长度可能更高但依赖库的安装和显存需求也会跟着上去。6.5 一个反直觉的问题检索不到就硬答很多人以为 RAG 的难点在生成其实大部分失败案例死在检索。我遇到一次很离谱的情况问“项目什么时候上线”模型答了一个看似合理的日期但我翻 evidence 发现根本没有相关文档。原因是 LLM 自己“脑补”了答案。后来我在 prompt 里加了严格约束“如果资料中没有明确信息请回答‘知识库中未找到相关信息’”并且把temperature降到 0.2这种情况才消失。所以prompt 不是随便写的它直接决定了 RAG 系统的鲁棒性。7. 写在最后这个 zip 留给我的几个经验打包这个“极简 RAG 知识库系统” zip 的过程比写 RAG 核心代码本身更让我有收获。第一点体会是把项目发给别人用之后我才真正理解“可分发性”是什么意思代码能跑只是第一步依赖锁版本、模型单独分发、README 里写清目录结构这些才是别人愿意用你项目的关键。第二点体会是遇到file is not a zip file、could not find eocd这类报错时不要先怀疑解压工具先检查文件本身是不是完整的 zip用file命令或者 Python 检查一下头部字节五分钟就能定位问题。我在这个项目后续的版本里还做了一些顺手的扩展支持批量上传多个 PDF、给每个文档设定独立的命名空间、用增量索引的方式避免全量重建。如果你想把 Zip 里的这个极简系统再往外推一步我建议先加一个“原文溯源”功能就是让回答返回时带上对应的文档名和页码。这是最直接能提升知识库系统可信度的功能比盲目上各种 RAG 框架都更有用。本文还有配套的精品资源点击获取