尧图网页设计 
简介一份基于检索增强生成技术构建的智能文档检索系统完整项目主要面向需要实现文档问答落地的Python开发者、算法工程师和毕业设计学生解决从文档上传解析、文本向量化、向量存储到流式智能问答的全流程实现问题。系统以Streamlit构建前端Python作为后端核心覆盖用户认证、角色权限控制、文件类型限制、文档解析与向量化、MySQL存储、模型接口调用、流式响应及管理员面板模块划分清晰便于二次开发。压缩包共62个文件包括24个Python源码文件、18个编译后的pyc文件、5个CSS和3个JS前端资源以及XML配置、项目架构图和说明文档总大小约175KB轻量且结构完整。目前已有73人学习下载特别适合想掌握检索增强生成工程化、网页端权限设计、向量检索问答等实战能力的读者。随包附有架构图和示例文档可作为本地部署、功能演示或毕设项目基础。1. 为什么我把这套 RAG 文档检索系统拆了三遍它解决的不只是问答做企业知识库最头疼的不是“模型不够聪明”而是“文档根本喂不进去”。这套基于 RAG 检索增强生成技术的智能文档检索系统把用户认证、文档解析、向量化、MySQL 存储、Streamlit 前端、Python 后端串成了一条完整链路。它不是给你一个孤立的 QA 脚本而是一个可以直接部署的本地化知识库登录后上传 PDF、Word、TXT系统自动切片、向量化问答时先检索再生成并以流式响应吐出答案还带角色权限和文件类型白名单。对正在搭企业知识库、或者想从零理解 RAG 落地流程的工程师来说这份资源能省掉你从散落碎片里拼架构的几周时间。我把这套系统反复拆了三遍下面把我的配置习惯和踩过的坑一次说清。2. 系统架构与数据流从登录到流式回答请求在系统里走了一条什么路2.1 前后端与数据库的角色划分Streamlit、Python 后端、MySQL 各自管什么首先要把三个角色分清。Streamlit 只负责界面和交互它本身不做重活Python 后端比如 FastAPI 或 Flask是核心逻辑所在负责文档解析、向量化、检索、权限判断、调用大模型MySQL 承担的是三份职责用户与角色表、文档原始内容与元数据表、向量数据存储。我刚拿到这套资源时先看了一眼目录结构发现它把 Streamlit 前端代码、后端 API、数据库初始化脚本分开放。这种分层值得保留前端和后端通过 HTTP 接口通信而不是在 Streamlit 里直接写 SQL。很多初学者喜欢在 Streamlit 回调里直接操作数据库一时方便但角色权限、文件类型限制、向量检索这些逻辑很快会搅成一团。拆开后前端只负责收集问题和展示答案后端统一处理鉴权和检索MySQL 只作为存储层职责单一出问题时日志一查就知道是哪一环。2.2 文档入库的完整链路解析、切片、向量化、存储这套系统的核心链路是文档入库。用户上传文件后后端先做文件类型校验允许的扩展名之外直接拒绝这是第一道闸。通过后按类型走不同解析器PDF 用文本提取Word 用 docx 解析TXT 直接读。解析出纯文本后按照设定的分块大小比如 300 到 500 字把长文档切成多个片段每一段都要保留文档 ID、页码、章节标题等元数据方便检索后回看原文。然后进入向量化环节把每个文本片段通过嵌入模型转成一个向量。向量维数取决于模型常见的有 384 维、768 维、1024 维。向量本身和对应的文本片段一起存入 MySQL。你可能会有疑问MySQL 存向量不专业吧但实际项目里数据量在百万片段以内时MySQL 配合向量字段或单独表完全够用还能直接复用事务、备份和权限体系。热搜里“mysql安装教程”“mysql 5.7.44”之所以高频就是因为很多人在部署这一步卡住——后面我会专门讲数据库的坑。# 文档入库流程的简化伪码实际项目中我按这个结构写 def ingest_document(file_path, allowed_exts, chunk_size400, overlap50): if file_path.suffix not in allowed_exts: raise PermissionError(文件类型不在允许列表中) text parse_document(file_path) # 按类型调用PDF/DOCX/TXT解析器 chunks split_text(text, chunk_size, overlap) # 分块带重叠 for i, chunk in enumerate(chunks): vector embedding_model.encode(chunk) # 向量化 save_to_mysql( doc_idfile_path.stem, chunk_indexi, textchunk, vectorvector.tolist(), # 转list方便存入JSON或BLOB字段 page_numberextract_page_number(chunk) )这里chunk_size和overlap是影响检索质量最直接的两个参数。常见做法是分块 400 字、重叠 50 字。重叠的意义是避免一个重要句子被拦腰截断落到两个块里。嵌入模型我用的是本地模型而不是在线 API原因很现实企业文档往往涉及内部数据走外部 API 有隐私风险而且离线部署不用等网络。如果检索效果不理想优先调这两个参数而不是换模型。2.3 问答阶段的检索增强生成向量检索怎么和 LLM 配合问答阶段不是把整个知识库喂给模型而是先“缩小范围”。用户提问后同一个嵌入模型把问题转成向量然后到 MySQL 里做相似度检索找出最相关的几个片段TopK再把这些片段和用户问题拼成一条 prompt 交给大模型生成答案。这套流程的优势在于模型不需要记住全部文档内容只需要基于检索到的片段做推理所以回答有出处幻觉明显减少。系统里还实现了流式响应——后端把大模型的输出token边生成边发给前端Streamlit 逐字显示。做前端的同事跟我提过如果不用流式一个长答案要等十几秒才一次性出现体验像卡死流式响应后第一句话在一两秒内就能出现这直接影响用户会不会把系统当废物。def answer_question(question, top_k5, threshold0.5): q_vec embedding_model.encode(question) candidates search_similar(q_vec, top_ktop_k, thresholdthreshold) context build_context(candidates) # 拼检索片段带文档名和页码 prompt f基于以下资料回答问题\n{context}\n问题{question} for token in llm_stream(prompt): # 生成器每次yield一个token yield token这里threshold0.5是相似度下限低于阈值的一律不采用。我一般调通后看几条检索结果再定如果阈值设太低会把无关段落拼进上下文模型容易被带偏设太高则经常“查不到”。另外注意top_k和threshold是配合关系文档片段本身越碎top_k反而要越大否则上下文信息不够。角色权限控制穿插在整条链路上。用户登录后后端给每个请求带上角色标识admin 可以上传和管理全部文档editor 只能上传但看不到其他部门的私有文档viewer 只能问答不能上传。前端只是把不可用按钮置灰真正的校验在后端每个入口处——这一点很重要我在避坑章会再强调。3. 搭建与配置从零跑通这套系统的操作步骤3.1 环境准备Python 版本、MySQL 安装与依赖资源里一般会附requirements.txt你要做的第一件事是建一个干净的 Python 虚拟环境。社区里同样热门问题“python安装教程”“python官网下载”之所以被反复问背后其实是环境冲突系统自带的 Python 3.8 和项目要求的 3.10 混在一起依赖装错位置。我的习惯是每个项目单独建 venv哪怕这台机器上只跑这一套系统。MySQL 部分建议直接装 8.0 及以上版本因为向量存储用 JSON 或 BLOB 字段8.0 的 JSON 功能更完善。Windows 上安装时注意“选择 Server Only”避免装一堆用不到的东西macOS 上用 Homebrew 也行。安装教程网上多这里重点说数据库初始化完成后Python 连接时常见的报错是 authentication plugin 不兼容解决办法是在 MySQL 里把默认认证方式改成mysql_native_password。# 创建虚拟环境并安装依赖 python -m venv venv source venv/bin/activate # Windows下用 venv\Scripts\activate pip install -r requirements.txtrequirements.txt里至少要包含streamlit、fastapi、uvicorn、pymysql、sentence-transformers、pdfplumber、python-docx。如果你用在线大模型接口还要加上对应的 SDK。装依赖时最容易翻车的是sentence-transformers它会拉取 torch 这个几个 GB 的大家伙。建议先单独安装 CPU 版 torch再装 sentence-transformers能避免把 CUDA 版 torch 也拉下来。装完后用python -c import sentence_transformers验证别急着启动。3.2 数据库与表结构初始化用户表、文档表、向量索引数据库初始化脚本一般叫schema.sql。核心是三张表users存用户和角色documents存文档元数据chunks存文本片段和向量。向量字段我习惯用BLOB存原始二进制或者用JSON存浮点数组。BLOB 性能更好但排障时看不了内容JSON 可读性强、调试方便数据量不大时差别可以忽略。CREATE DATABASE IF NOT EXISTS rag_system DEFAULT CHARSET utf8mb4; USE rag_system; CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(64) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, role ENUM(admin,editor,viewer) DEFAULT viewer, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE documents ( id INT PRIMARY KEY AUTO_INCREMENT, filename VARCHAR(255) NOT NULL, file_type VARCHAR(20) NOT NULL, uploader_id INT NOT NULL, department VARCHAR(100), created_at DATETIME DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (uploader_id) REFERENCES users(id) ); CREATE TABLE chunks ( id INT PRIMARY KEY AUTO_INCREMENT, doc_id INT NOT NULL, chunk_index INT NOT NULL, text TEXT NOT NULL, vector JSON NULL, page_number INT, FOREIGN KEY (doc_id) REFERENCES documents(id) ON DELETE CASCADE ); CREATE INDEX idx_chunks_doc ON chunks(doc_id);执行前确认数据库字符集是utf8mb4否则中文乱码会从入库一路带到问答。注意chunks表没有为vector建索引因为 MySQL 原生不支持向量索引除非你用专门的向量插件。在百万级以下规模时全表扫描加 numpy 计算余弦相似度完全能接受等到需要上千万级再迁移到 Milvus 或 FAISS。这就是“先用 MySQL 跑通再考虑专用向量库”的务实路线。3.3 启动后端与前端命令与参数后端我推荐用 FastAPI 启动因为流式响应用 ASGI 支持得比较自然。当然资源里也可能用 Flask核心不冲突。启动后端时指定端口比如 8000Streamlit 前端默认 8501。前后端地址通过环境变量配置不要写死。# 先启动后端 export MYSQL_HOST127.0.0.1 export MYSQL_USERroot export MYSQL_PASSWORDyourpassword export EMBEDDING_MODELshibing624/text2vec-base-chinese uvicorn backend.main:app --host 0.0.0.0 --port 8000 # 再启动前端另开一个终端 export API_BASE_URLhttp://127.0.0.1:8000 streamlit run frontend/app.py --server.port 8501EMBEDDING_MODEL换成本地模型路径或模型名都可以。text2vec-base-chinese是我常用的中文嵌入模型384 维体积小CPU 也能跑。如果你的文档是英文为主换成all-MiniLM-L6-v2效果更稳。这里要注意环境变量里的密码不要写进代码仓库即使是一个本地项目养成习惯也好。启动后先访问http://127.0.0.1:8501用种子账号登录。如果没有种子账号用schema.sql里预置的 admin 账号密码通常是哈希值建议先跑一个一次性脚本来生成密码哈希。# 生成密码哈希并写入用户表使用passlib的bcrypt from passlib.hash import bcrypt hash_value bcrypt.hash(admin123) print(hash_value)把打印出来的哈希值更新到users表对应行即可。这一步很多人直接跳过结果登录一直报错其实只是忘了初始化账号密码。另外首次启动后端时sentence-transformers会自动下载模型文件慢的话几十分钟。建议预先用脚本把模型下载好放到本地目录再通过EMBEDDING_MODEL指向该目录避免启动时长时间卡住。3.4 配置角色权限与文件类型限制参数怎么改角色权限不是固定写死的而是在后端配置里声明哪些接口需要什么角色。文件类型限制一般是一个列表你随时可以增删。这部分的代码是这套系统的“安全闸门”不值得省。# 配置文件 config.py 中的权限与文件类型设置 ALLOWED_EXTENSIONS {.pdf, .docx, .txt} # 按需加 .pptx 或 .md ROLE_PERMISSIONS { admin: {upload: True, delete: True, view_all: True}, editor: {upload: True, delete: False, view_all: False}, viewer: {upload: False, delete: False, view_all: False} } def check_permission(user_role, action): return ROLE_PERMISSIONS.get(user_role, {}).get(action, False)后端接口在处理上传请求时第一步必须是check_permission(user_role, upload)不通过直接返回 403前端看不到任何提示。文件类型校验要同时做两次后端收到文件名后先查扩展名再检查文件头的 magic bytes防止别人把 exe 改名成 pdf 上传。常见的“重命名绕过”用file命令就能识破。校验失败时记录日志原因写清是“权限不足”还是“类型不符”排障时一眼能看出来。角色和文件类型这两个配置放在同一个 config 文件里是有意的——它们都属于“接口入口策略”。改动后无需重启服务代码里直接引用这个模块即可如果你改了ROLE_PERMISSIONS记得清一下登录 token 缓存否则旧权限还会留在会话里。4. 向量存储与检索的参数调优嵌入模型、分块大小、TopK 和相似度阈值4.1 向量化的关键参数分块大小与重叠分块大小对检索质量的影响比模型选择更大。设太小比如 100 字一个完整知识点被拆到三四个块里检索时只能捞到其中一块上下文不完整设太大比如 1000 字一个块里塞了多个主题向量平均化后哪个都不像相似度会被稀释。文本切分还要考虑句子边界不要硬按字符数切先按段落再在段落内补齐到接近目标长度。def split_text(text, chunk_size400, overlap50): paragraphs text.split(\n\n) chunks [] buffer for para in paragraphs: if len(buffer) len(para) chunk_size: buffer para \n else: if buffer: chunks.append(buffer.strip()) buffer para \n # 最后补上尾部 if buffer: chunks.append(buffer.strip()) # 重叠处理保留上一块末尾overlap字到下一块开头 merged [] for i, c in enumerate(chunks): if i 0: merged.append(c) else: prev_tail chunks[i-1][-overlap:] if overlap else merged.append(prev_tail c) return merged这个实现兼顾了段落完整性和重叠。参数含义chunk_size是目标块长overlap是块间重叠字符数。中文环境下 400 字较稳如果文档是技术手册术语密度高我会降到 300如果是政策制度类长文本500 也行。判断依据很简单入库后随机挑几个问题看看检索出来的片段是否完整覆盖答案。别迷信某个固定值。4.2 检索参数TopK、相似度阈值、重排序检索阶段有三个参数联动top_k决定从库里捞多少个候选片段threshold决定最低相似度重排序是在top_k结果里用更精细的模型或规则再排一次。系统里通常先取top_k10并加阈值过滤再对过滤后的结果按“命中关键词数量 原文位置”做加权重排最后取前 3 个拼进上下文。def search_similar(query_vec, top_k10, threshold0.5): rows select_all_vectors() # 从MySQL读出所有向量 scored [] for row in rows: score cosine_similarity(query_vec, row[vector]) if score threshold: scored.append((score, row)) scored.sort(keylambda x: -x[0]) return [row for score, row in scored[:top_k]]注意select_all_vectors在数据量大时就是性能瓶颈MySQL 里跑全表扫描加 Python 算相似度一万条片段大概几十毫秒百万条就到秒级。我一般把向量用.npy缓存一份在内存入库时增量更新检索时直接从内存算MySQL 只做持久化。这样既享受 MySQL 的备份和事务又避开数据库算向量的低效。如果资源里没有这个优化你可以自己加一个vector_cache模块。threshold的取值需要观察实际分布。我通常先不设阈值跑一遍把每个问题的相似度分数打出来看相关与不相关的分数分界在哪。比如很多不相关片段也有 0.4 的余弦相似度那阈值至少要 0.45。这个值不是算出来的是标出来的——建立一个几十条问题的测试集反复看检索日志调出来的。4.3 与 MySQL 协同向量存储和元数据管理怎么分工MySQL 在这套系统里不只是向量仓库更是元数据中枢。documents表记录上传者、部门、时间chunks表记录文本和向量。做权限过滤时先通过用户角色拿到他有权限的documents.id集合再检索时只在这些文档的 chunks 里找向量。这个“过滤再搜索”的顺序非常重要否则向量检索会返回用户无权访问的内容等于权限白设。def search_with_permission(query_vec, allowed_doc_ids, top_k10): rows select_vectors_by_docs(allowed_doc_ids) # 先按文档ID过滤 scored [] for row in rows: score cosine_similarity(query_vec, row[vector]) if score threshold: scored.append((score, row)) scored.sort(keylambda x: -x[0]) return scored[:top_k]在 MySQL 层面为chunks.doc_id建索引是必须的。如果你发现检索变慢先看EXPLAIN SELECT ... WHERE doc_id IN (...)确认走索引。另外删除文档时让chunks表ON DELETE CASCADE自动删向量避免手工清垃圾数据。我见过有人把向量存成 JSON 后忘建全文索引导致文档删除后碎片仍被检索出来答案里出现已删除的内容——这是很危险的事故。5. 避坑指南我在这套系统上踩过的六个典型问题5.1 中文文档向量化后检索效果差切分把句子切碎了现象上传一篇中文说明书问“设备功率是多少”返回的片段里全是零散词组答案完全不对。原因默认按英文空格切分的中文分词器把“额定制冷功率 500W”切成了“额定制冷”“功率”“500W”三个块向量化后各自偏离原意。解决改用中文分句逻辑先按句号、问号、感叹号切句再按目标块长组块。另外嵌入模型换成中文专用模型比如text2vec-base-chinese。从那以后我规定所有入库前的文本先做一次段落归一化把多余空格、换行符清理掉再做分块。5.2 第一次问答特别慢嵌入模型加载和连接池现象启动后第一次提问等了三十秒才出答案之后恢复几秒。原因嵌入模型第一次调用时才真正加载到内存属于“冷启动”同时 MySQL 连接池未预热第一次查询要握手建连。解决在服务启动时预先加载模型并初始化 5~10 个数据库连接。后端日志里加一行“model loaded”确定加载完成后再接受问答请求。配置连接池参数pool_size10max_overflow5避免高并发时重复建连。5.3 文件名或路径带中文导致解析失败现象上传“技术方案最终版.pdf”失败改名为tech.pdf后成功。原因后端用pathlib处理路径时Windows 下编码不一致或者某些库内部按默认编码读取文件名遇到中文字符报错。解决统一在入口处把文件名规范化为 UTF-8 编码的纯字母数字另存一份original_filename到数据库。同时确保保存文件时使用Path(filename).resolve()并设置encodingutf-8。这一步花了我半天后来我直接把“上传文件重命名”写成了后端必做动作。5.4 角色权限绕过只在前端隐藏按钮不够现象viewer 角色虽然看不到上传按钮但用浏览器开发者工具调用后端接口照样能上传成功。原因前端只是界面隐藏后端上传接口没有做角色校验任何人都能直接 POST。解决每个写操作接口都做两层校验第一层是登录态解析第二层是check_permission。注意校验必须在函数最前面执行不要在“处理完文件后”再校验——否则攻击者已经上传了。这个问题是安全评审时被挑出来的属于最常见的低级漏洞。5.5 MySQL 连接失败认证插件和字符集双坑现象本地启动后端后日志报Authentication plugin caching_sha2_password cannot be loaded。原因MySQL 8.0 默认认证插件是caching_sha2_password而 Python 的pymysql默认不兼容。同时数据库建表没用utf8mb4中文全变问号。解决创建用户时指定IDENTIFIED WITH mysql_native_password BY password如果建库已经用utf8执行ALTER DATABASE rag_system DEFAULT CHARACTER SET utf8mb4。两个问题虽然不同但经常一起出现排查时先看连接错误再看字符集别来回改配置。5.6 流式响应不生效代理缓冲与浏览器拦截现象后端和前端代码都用了流式但 Streamlit 页面还是等全部输出完才显示。原因如果前端页面走了 Nginx 等反向代理代理默认缓冲响应流式 token 被攒住。另外 Streamlit 的st.write_stream需要后端正确设置text/event-stream或按行输出。解决在 Nginx 配置里关掉该路径的缓冲proxy_buffering off;。后端响应头加Cache-Control: no-cache。Streamlit 端用st.write_stream(generator)不要自己循环st.text。这个问题最容易误导新人——代码明明没问题但部署环境把流式吃掉了。6. 进阶用法与验证技巧把检索质量量化避免“自己觉得好用”当系统能跑通之后最大的问题变成我怎么知道这次调参是变好了还是变坏了我的答案是建立一个几十条问题的验证集每条问题配一个标准答案片段然后写脚本自动跑检索计算“问题相关片段是否出现在检索结果里”的命中率。validation_set [ {question: 设备的最大功耗是多少, expected_chunk: 最大功耗为 500W}, {question: 售后电话是什么, expected_chunk: 售后热线 400-xxx-xxxx}, ] def evaluate(retrieval_func): hit 0 for item in validation_set: results retrieval_func(item[question], top_k5) if any(item[expected_chunk] in r[text] for r in results): hit 1 return hit / len(validation_set) print(fRecall5: {evaluate(retrieve)})建议把召回率打印在每次调参后。我从实践里的经验是90% 以上的问题能在 TopK5 的范围内命中才算基本可用低于 80% 就先别调 prompt回头检查分块和阈值。这个验证集一旦建立后续换模型、改分块参数、调阈值都有了依据。另外我会在日志里把每次问答的检索片段 ID 也记录到一张query_log表字段包括问题、命中文档 ID、相关度分数、最终答案。第二天回看时能发现哪些文档经常被检索但用户实际没点开——那是分块或标题写得有歧义哪个老问题反复被问但检索不出说明知识库里缺内容或分块方式不对。这套验证方式花不了多少代码却能让项目从“demo 能跑”变成“真的敢让同事用”。最后只有一个忠告别一开始就花大精力调大模型 promptRAG 系统 70% 的效果由“检索到正确内容”决定。我每次部署新知识库都强制自己先跑完一遍验证集、盯完十条检索日志再动 prompt。这份资源已经把链路给你串好了希望你拿到后先把基础流程跑通再用验证集慢慢打磨。希望帮到你。本文还有配套的精品资源点击获取 基于RAG的企业知识库文档检索系统：架构、配置与避坑实战
简介一份基于检索增强生成技术构建的智能文档检索系统完整项目主要面向需要实现文档问答落地的Python开发者、算法工程师和毕业设计学生解决从文档上传解析、文本向量化、向量存储到流式智能问答的全流程实现问题。系统以Streamlit构建前端Python作为后端核心覆盖用户认证、角色权限控制、文件类型限制、文档解析与向量化、MySQL存储、模型接口调用、流式响应及管理员面板模块划分清晰便于二次开发。压缩包共62个文件包括24个Python源码文件、18个编译后的pyc文件、5个CSS和3个JS前端资源以及XML配置、项目架构图和说明文档总大小约175KB轻量且结构完整。目前已有73人学习下载特别适合想掌握检索增强生成工程化、网页端权限设计、向量检索问答等实战能力的读者。随包附有架构图和示例文档可作为本地部署、功能演示或毕设项目基础。1. 为什么我把这套 RAG 文档检索系统拆了三遍它解决的不只是问答做企业知识库最头疼的不是“模型不够聪明”而是“文档根本喂不进去”。这套基于 RAG 检索增强生成技术的智能文档检索系统把用户认证、文档解析、向量化、MySQL 存储、Streamlit 前端、Python 后端串成了一条完整链路。它不是给你一个孤立的 QA 脚本而是一个可以直接部署的本地化知识库登录后上传 PDF、Word、TXT系统自动切片、向量化问答时先检索再生成并以流式响应吐出答案还带角色权限和文件类型白名单。对正在搭企业知识库、或者想从零理解 RAG 落地流程的工程师来说这份资源能省掉你从散落碎片里拼架构的几周时间。我把这套系统反复拆了三遍下面把我的配置习惯和踩过的坑一次说清。2. 系统架构与数据流从登录到流式回答请求在系统里走了一条什么路2.1 前后端与数据库的角色划分Streamlit、Python 后端、MySQL 各自管什么首先要把三个角色分清。Streamlit 只负责界面和交互它本身不做重活Python 后端比如 FastAPI 或 Flask是核心逻辑所在负责文档解析、向量化、检索、权限判断、调用大模型MySQL 承担的是三份职责用户与角色表、文档原始内容与元数据表、向量数据存储。我刚拿到这套资源时先看了一眼目录结构发现它把 Streamlit 前端代码、后端 API、数据库初始化脚本分开放。这种分层值得保留前端和后端通过 HTTP 接口通信而不是在 Streamlit 里直接写 SQL。很多初学者喜欢在 Streamlit 回调里直接操作数据库一时方便但角色权限、文件类型限制、向量检索这些逻辑很快会搅成一团。拆开后前端只负责收集问题和展示答案后端统一处理鉴权和检索MySQL 只作为存储层职责单一出问题时日志一查就知道是哪一环。2.2 文档入库的完整链路解析、切片、向量化、存储这套系统的核心链路是文档入库。用户上传文件后后端先做文件类型校验允许的扩展名之外直接拒绝这是第一道闸。通过后按类型走不同解析器PDF 用文本提取Word 用 docx 解析TXT 直接读。解析出纯文本后按照设定的分块大小比如 300 到 500 字把长文档切成多个片段每一段都要保留文档 ID、页码、章节标题等元数据方便检索后回看原文。然后进入向量化环节把每个文本片段通过嵌入模型转成一个向量。向量维数取决于模型常见的有 384 维、768 维、1024 维。向量本身和对应的文本片段一起存入 MySQL。你可能会有疑问MySQL 存向量不专业吧但实际项目里数据量在百万片段以内时MySQL 配合向量字段或单独表完全够用还能直接复用事务、备份和权限体系。热搜里“mysql安装教程”“mysql 5.7.44”之所以高频就是因为很多人在部署这一步卡住——后面我会专门讲数据库的坑。# 文档入库流程的简化伪码实际项目中我按这个结构写 def ingest_document(file_path, allowed_exts, chunk_size400, overlap50): if file_path.suffix not in allowed_exts: raise PermissionError(文件类型不在允许列表中) text parse_document(file_path) # 按类型调用PDF/DOCX/TXT解析器 chunks split_text(text, chunk_size, overlap) # 分块带重叠 for i, chunk in enumerate(chunks): vector embedding_model.encode(chunk) # 向量化 save_to_mysql( doc_idfile_path.stem, chunk_indexi, textchunk, vectorvector.tolist(), # 转list方便存入JSON或BLOB字段 page_numberextract_page_number(chunk) )这里chunk_size和overlap是影响检索质量最直接的两个参数。常见做法是分块 400 字、重叠 50 字。重叠的意义是避免一个重要句子被拦腰截断落到两个块里。嵌入模型我用的是本地模型而不是在线 API原因很现实企业文档往往涉及内部数据走外部 API 有隐私风险而且离线部署不用等网络。如果检索效果不理想优先调这两个参数而不是换模型。2.3 问答阶段的检索增强生成向量检索怎么和 LLM 配合问答阶段不是把整个知识库喂给模型而是先“缩小范围”。用户提问后同一个嵌入模型把问题转成向量然后到 MySQL 里做相似度检索找出最相关的几个片段TopK再把这些片段和用户问题拼成一条 prompt 交给大模型生成答案。这套流程的优势在于模型不需要记住全部文档内容只需要基于检索到的片段做推理所以回答有出处幻觉明显减少。系统里还实现了流式响应——后端把大模型的输出token边生成边发给前端Streamlit 逐字显示。做前端的同事跟我提过如果不用流式一个长答案要等十几秒才一次性出现体验像卡死流式响应后第一句话在一两秒内就能出现这直接影响用户会不会把系统当废物。def answer_question(question, top_k5, threshold0.5): q_vec embedding_model.encode(question) candidates search_similar(q_vec, top_ktop_k, thresholdthreshold) context build_context(candidates) # 拼检索片段带文档名和页码 prompt f基于以下资料回答问题\n{context}\n问题{question} for token in llm_stream(prompt): # 生成器每次yield一个token yield token这里threshold0.5是相似度下限低于阈值的一律不采用。我一般调通后看几条检索结果再定如果阈值设太低会把无关段落拼进上下文模型容易被带偏设太高则经常“查不到”。另外注意top_k和threshold是配合关系文档片段本身越碎top_k反而要越大否则上下文信息不够。角色权限控制穿插在整条链路上。用户登录后后端给每个请求带上角色标识admin 可以上传和管理全部文档editor 只能上传但看不到其他部门的私有文档viewer 只能问答不能上传。前端只是把不可用按钮置灰真正的校验在后端每个入口处——这一点很重要我在避坑章会再强调。3. 搭建与配置从零跑通这套系统的操作步骤3.1 环境准备Python 版本、MySQL 安装与依赖资源里一般会附requirements.txt你要做的第一件事是建一个干净的 Python 虚拟环境。社区里同样热门问题“python安装教程”“python官网下载”之所以被反复问背后其实是环境冲突系统自带的 Python 3.8 和项目要求的 3.10 混在一起依赖装错位置。我的习惯是每个项目单独建 venv哪怕这台机器上只跑这一套系统。MySQL 部分建议直接装 8.0 及以上版本因为向量存储用 JSON 或 BLOB 字段8.0 的 JSON 功能更完善。Windows 上安装时注意“选择 Server Only”避免装一堆用不到的东西macOS 上用 Homebrew 也行。安装教程网上多这里重点说数据库初始化完成后Python 连接时常见的报错是 authentication plugin 不兼容解决办法是在 MySQL 里把默认认证方式改成mysql_native_password。# 创建虚拟环境并安装依赖 python -m venv venv source venv/bin/activate # Windows下用 venv\Scripts\activate pip install -r requirements.txtrequirements.txt里至少要包含streamlit、fastapi、uvicorn、pymysql、sentence-transformers、pdfplumber、python-docx。如果你用在线大模型接口还要加上对应的 SDK。装依赖时最容易翻车的是sentence-transformers它会拉取 torch 这个几个 GB 的大家伙。建议先单独安装 CPU 版 torch再装 sentence-transformers能避免把 CUDA 版 torch 也拉下来。装完后用python -c import sentence_transformers验证别急着启动。3.2 数据库与表结构初始化用户表、文档表、向量索引数据库初始化脚本一般叫schema.sql。核心是三张表users存用户和角色documents存文档元数据chunks存文本片段和向量。向量字段我习惯用BLOB存原始二进制或者用JSON存浮点数组。BLOB 性能更好但排障时看不了内容JSON 可读性强、调试方便数据量不大时差别可以忽略。CREATE DATABASE IF NOT EXISTS rag_system DEFAULT CHARSET utf8mb4; USE rag_system; CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(64) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, role ENUM(admin,editor,viewer) DEFAULT viewer, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE documents ( id INT PRIMARY KEY AUTO_INCREMENT, filename VARCHAR(255) NOT NULL, file_type VARCHAR(20) NOT NULL, uploader_id INT NOT NULL, department VARCHAR(100), created_at DATETIME DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (uploader_id) REFERENCES users(id) ); CREATE TABLE chunks ( id INT PRIMARY KEY AUTO_INCREMENT, doc_id INT NOT NULL, chunk_index INT NOT NULL, text TEXT NOT NULL, vector JSON NULL, page_number INT, FOREIGN KEY (doc_id) REFERENCES documents(id) ON DELETE CASCADE ); CREATE INDEX idx_chunks_doc ON chunks(doc_id);执行前确认数据库字符集是utf8mb4否则中文乱码会从入库一路带到问答。注意chunks表没有为vector建索引因为 MySQL 原生不支持向量索引除非你用专门的向量插件。在百万级以下规模时全表扫描加 numpy 计算余弦相似度完全能接受等到需要上千万级再迁移到 Milvus 或 FAISS。这就是“先用 MySQL 跑通再考虑专用向量库”的务实路线。3.3 启动后端与前端命令与参数后端我推荐用 FastAPI 启动因为流式响应用 ASGI 支持得比较自然。当然资源里也可能用 Flask核心不冲突。启动后端时指定端口比如 8000Streamlit 前端默认 8501。前后端地址通过环境变量配置不要写死。# 先启动后端 export MYSQL_HOST127.0.0.1 export MYSQL_USERroot export MYSQL_PASSWORDyourpassword export EMBEDDING_MODELshibing624/text2vec-base-chinese uvicorn backend.main:app --host 0.0.0.0 --port 8000 # 再启动前端另开一个终端 export API_BASE_URLhttp://127.0.0.1:8000 streamlit run frontend/app.py --server.port 8501EMBEDDING_MODEL换成本地模型路径或模型名都可以。text2vec-base-chinese是我常用的中文嵌入模型384 维体积小CPU 也能跑。如果你的文档是英文为主换成all-MiniLM-L6-v2效果更稳。这里要注意环境变量里的密码不要写进代码仓库即使是一个本地项目养成习惯也好。启动后先访问http://127.0.0.1:8501用种子账号登录。如果没有种子账号用schema.sql里预置的 admin 账号密码通常是哈希值建议先跑一个一次性脚本来生成密码哈希。# 生成密码哈希并写入用户表使用passlib的bcrypt from passlib.hash import bcrypt hash_value bcrypt.hash(admin123) print(hash_value)把打印出来的哈希值更新到users表对应行即可。这一步很多人直接跳过结果登录一直报错其实只是忘了初始化账号密码。另外首次启动后端时sentence-transformers会自动下载模型文件慢的话几十分钟。建议预先用脚本把模型下载好放到本地目录再通过EMBEDDING_MODEL指向该目录避免启动时长时间卡住。3.4 配置角色权限与文件类型限制参数怎么改角色权限不是固定写死的而是在后端配置里声明哪些接口需要什么角色。文件类型限制一般是一个列表你随时可以增删。这部分的代码是这套系统的“安全闸门”不值得省。# 配置文件 config.py 中的权限与文件类型设置 ALLOWED_EXTENSIONS {.pdf, .docx, .txt} # 按需加 .pptx 或 .md ROLE_PERMISSIONS { admin: {upload: True, delete: True, view_all: True}, editor: {upload: True, delete: False, view_all: False}, viewer: {upload: False, delete: False, view_all: False} } def check_permission(user_role, action): return ROLE_PERMISSIONS.get(user_role, {}).get(action, False)后端接口在处理上传请求时第一步必须是check_permission(user_role, upload)不通过直接返回 403前端看不到任何提示。文件类型校验要同时做两次后端收到文件名后先查扩展名再检查文件头的 magic bytes防止别人把 exe 改名成 pdf 上传。常见的“重命名绕过”用file命令就能识破。校验失败时记录日志原因写清是“权限不足”还是“类型不符”排障时一眼能看出来。角色和文件类型这两个配置放在同一个 config 文件里是有意的——它们都属于“接口入口策略”。改动后无需重启服务代码里直接引用这个模块即可如果你改了ROLE_PERMISSIONS记得清一下登录 token 缓存否则旧权限还会留在会话里。4. 向量存储与检索的参数调优嵌入模型、分块大小、TopK 和相似度阈值4.1 向量化的关键参数分块大小与重叠分块大小对检索质量的影响比模型选择更大。设太小比如 100 字一个完整知识点被拆到三四个块里检索时只能捞到其中一块上下文不完整设太大比如 1000 字一个块里塞了多个主题向量平均化后哪个都不像相似度会被稀释。文本切分还要考虑句子边界不要硬按字符数切先按段落再在段落内补齐到接近目标长度。def split_text(text, chunk_size400, overlap50): paragraphs text.split(\n\n) chunks [] buffer for para in paragraphs: if len(buffer) len(para) chunk_size: buffer para \n else: if buffer: chunks.append(buffer.strip()) buffer para \n # 最后补上尾部 if buffer: chunks.append(buffer.strip()) # 重叠处理保留上一块末尾overlap字到下一块开头 merged [] for i, c in enumerate(chunks): if i 0: merged.append(c) else: prev_tail chunks[i-1][-overlap:] if overlap else merged.append(prev_tail c) return merged这个实现兼顾了段落完整性和重叠。参数含义chunk_size是目标块长overlap是块间重叠字符数。中文环境下 400 字较稳如果文档是技术手册术语密度高我会降到 300如果是政策制度类长文本500 也行。判断依据很简单入库后随机挑几个问题看看检索出来的片段是否完整覆盖答案。别迷信某个固定值。4.2 检索参数TopK、相似度阈值、重排序检索阶段有三个参数联动top_k决定从库里捞多少个候选片段threshold决定最低相似度重排序是在top_k结果里用更精细的模型或规则再排一次。系统里通常先取top_k10并加阈值过滤再对过滤后的结果按“命中关键词数量 原文位置”做加权重排最后取前 3 个拼进上下文。def search_similar(query_vec, top_k10, threshold0.5): rows select_all_vectors() # 从MySQL读出所有向量 scored [] for row in rows: score cosine_similarity(query_vec, row[vector]) if score threshold: scored.append((score, row)) scored.sort(keylambda x: -x[0]) return [row for score, row in scored[:top_k]]注意select_all_vectors在数据量大时就是性能瓶颈MySQL 里跑全表扫描加 Python 算相似度一万条片段大概几十毫秒百万条就到秒级。我一般把向量用.npy缓存一份在内存入库时增量更新检索时直接从内存算MySQL 只做持久化。这样既享受 MySQL 的备份和事务又避开数据库算向量的低效。如果资源里没有这个优化你可以自己加一个vector_cache模块。threshold的取值需要观察实际分布。我通常先不设阈值跑一遍把每个问题的相似度分数打出来看相关与不相关的分数分界在哪。比如很多不相关片段也有 0.4 的余弦相似度那阈值至少要 0.45。这个值不是算出来的是标出来的——建立一个几十条问题的测试集反复看检索日志调出来的。4.3 与 MySQL 协同向量存储和元数据管理怎么分工MySQL 在这套系统里不只是向量仓库更是元数据中枢。documents表记录上传者、部门、时间chunks表记录文本和向量。做权限过滤时先通过用户角色拿到他有权限的documents.id集合再检索时只在这些文档的 chunks 里找向量。这个“过滤再搜索”的顺序非常重要否则向量检索会返回用户无权访问的内容等于权限白设。def search_with_permission(query_vec, allowed_doc_ids, top_k10): rows select_vectors_by_docs(allowed_doc_ids) # 先按文档ID过滤 scored [] for row in rows: score cosine_similarity(query_vec, row[vector]) if score threshold: scored.append((score, row)) scored.sort(keylambda x: -x[0]) return scored[:top_k]在 MySQL 层面为chunks.doc_id建索引是必须的。如果你发现检索变慢先看EXPLAIN SELECT ... WHERE doc_id IN (...)确认走索引。另外删除文档时让chunks表ON DELETE CASCADE自动删向量避免手工清垃圾数据。我见过有人把向量存成 JSON 后忘建全文索引导致文档删除后碎片仍被检索出来答案里出现已删除的内容——这是很危险的事故。5. 避坑指南我在这套系统上踩过的六个典型问题5.1 中文文档向量化后检索效果差切分把句子切碎了现象上传一篇中文说明书问“设备功率是多少”返回的片段里全是零散词组答案完全不对。原因默认按英文空格切分的中文分词器把“额定制冷功率 500W”切成了“额定制冷”“功率”“500W”三个块向量化后各自偏离原意。解决改用中文分句逻辑先按句号、问号、感叹号切句再按目标块长组块。另外嵌入模型换成中文专用模型比如text2vec-base-chinese。从那以后我规定所有入库前的文本先做一次段落归一化把多余空格、换行符清理掉再做分块。5.2 第一次问答特别慢嵌入模型加载和连接池现象启动后第一次提问等了三十秒才出答案之后恢复几秒。原因嵌入模型第一次调用时才真正加载到内存属于“冷启动”同时 MySQL 连接池未预热第一次查询要握手建连。解决在服务启动时预先加载模型并初始化 5~10 个数据库连接。后端日志里加一行“model loaded”确定加载完成后再接受问答请求。配置连接池参数pool_size10max_overflow5避免高并发时重复建连。5.3 文件名或路径带中文导致解析失败现象上传“技术方案最终版.pdf”失败改名为tech.pdf后成功。原因后端用pathlib处理路径时Windows 下编码不一致或者某些库内部按默认编码读取文件名遇到中文字符报错。解决统一在入口处把文件名规范化为 UTF-8 编码的纯字母数字另存一份original_filename到数据库。同时确保保存文件时使用Path(filename).resolve()并设置encodingutf-8。这一步花了我半天后来我直接把“上传文件重命名”写成了后端必做动作。5.4 角色权限绕过只在前端隐藏按钮不够现象viewer 角色虽然看不到上传按钮但用浏览器开发者工具调用后端接口照样能上传成功。原因前端只是界面隐藏后端上传接口没有做角色校验任何人都能直接 POST。解决每个写操作接口都做两层校验第一层是登录态解析第二层是check_permission。注意校验必须在函数最前面执行不要在“处理完文件后”再校验——否则攻击者已经上传了。这个问题是安全评审时被挑出来的属于最常见的低级漏洞。5.5 MySQL 连接失败认证插件和字符集双坑现象本地启动后端后日志报Authentication plugin caching_sha2_password cannot be loaded。原因MySQL 8.0 默认认证插件是caching_sha2_password而 Python 的pymysql默认不兼容。同时数据库建表没用utf8mb4中文全变问号。解决创建用户时指定IDENTIFIED WITH mysql_native_password BY password如果建库已经用utf8执行ALTER DATABASE rag_system DEFAULT CHARACTER SET utf8mb4。两个问题虽然不同但经常一起出现排查时先看连接错误再看字符集别来回改配置。5.6 流式响应不生效代理缓冲与浏览器拦截现象后端和前端代码都用了流式但 Streamlit 页面还是等全部输出完才显示。原因如果前端页面走了 Nginx 等反向代理代理默认缓冲响应流式 token 被攒住。另外 Streamlit 的st.write_stream需要后端正确设置text/event-stream或按行输出。解决在 Nginx 配置里关掉该路径的缓冲proxy_buffering off;。后端响应头加Cache-Control: no-cache。Streamlit 端用st.write_stream(generator)不要自己循环st.text。这个问题最容易误导新人——代码明明没问题但部署环境把流式吃掉了。6. 进阶用法与验证技巧把检索质量量化避免“自己觉得好用”当系统能跑通之后最大的问题变成我怎么知道这次调参是变好了还是变坏了我的答案是建立一个几十条问题的验证集每条问题配一个标准答案片段然后写脚本自动跑检索计算“问题相关片段是否出现在检索结果里”的命中率。validation_set [ {question: 设备的最大功耗是多少, expected_chunk: 最大功耗为 500W}, {question: 售后电话是什么, expected_chunk: 售后热线 400-xxx-xxxx}, ] def evaluate(retrieval_func): hit 0 for item in validation_set: results retrieval_func(item[question], top_k5) if any(item[expected_chunk] in r[text] for r in results): hit 1 return hit / len(validation_set) print(fRecall5: {evaluate(retrieve)})建议把召回率打印在每次调参后。我从实践里的经验是90% 以上的问题能在 TopK5 的范围内命中才算基本可用低于 80% 就先别调 prompt回头检查分块和阈值。这个验证集一旦建立后续换模型、改分块参数、调阈值都有了依据。另外我会在日志里把每次问答的检索片段 ID 也记录到一张query_log表字段包括问题、命中文档 ID、相关度分数、最终答案。第二天回看时能发现哪些文档经常被检索但用户实际没点开——那是分块或标题写得有歧义哪个老问题反复被问但检索不出说明知识库里缺内容或分块方式不对。这套验证方式花不了多少代码却能让项目从“demo 能跑”变成“真的敢让同事用”。最后只有一个忠告别一开始就花大精力调大模型 promptRAG 系统 70% 的效果由“检索到正确内容”决定。我每次部署新知识库都强制自己先跑完一遍验证集、盯完十条检索日志再动 prompt。这份资源已经把链路给你串好了希望你拿到后先把基础流程跑通再用验证集慢慢打磨。希望帮到你。本文还有配套的精品资源点击获取