ChatGLM+FAISS本地私有化RAG智能问答助理落地

简介面向希望在本机搭建私有化知识库问答系统的开发者与机器学习初学者这份示例项目围绕 Gradio 界面、FAISS 向量检索与 Sentence-Transformers 文本嵌入展开演示文件上传、文档处理、相似度召回和对话式回答的完整链路并兼顾 ChatGLM 等模型的本地接入与数据隐私需求。压缩包共 18 个文件约 336KB以 Python 源码和 txt 说明为主辅以 yaml 配置、whl 依赖包、sh 脚本以及 docx、xlsx、pdf 等示例文档和 pem 证书便于查看运行逻辑、依赖安装与配置项。已有 140 人学习下载。读者可从中获得可参考的私有化问答助理工程骨架、检索增强问答的关键实现、依赖与启动脚本以及用于验证上传和检索流程的样例资料适合按模块阅读并改造成自己的知识库应用。1. 从一台不通外网的机器说起本地部署的私有化智能问答助理到底解决什么上个月帮一个团队收拾内网机房一台装在角落的 GPU 工作站不给外网机器上放了几百份产品手册、接口文档和运维记录。新同事查一个字段含义得开 PDF 搜索、翻三四个文件、再去问老人一圈下来半小时没了。他们想要的东西很朴素一个能本地部署、数据不出机器的私有化智能问答入口背后接自己那堆文档。最后落地的方案就是这套基于 ChatGLM 系开源对话模型搭起来的智能问答助理——模型在本机跑、文档在本机切片入向量库、前端在浏览器里流式吐字。它适合三类人要在隔离环境里落地问答能力的小团队、想把 RAG 链路从零吃透的后端开发、以及拿它当私有化大模型起手项目的工程师。下面按能跑、能改的顺序把这个项目的骨架一层层拆开。2. 技术选型与整体架构模型、检索、服务三层怎么分工整套系统拆成三层职责边界很清楚模型层只负责「给定上下文和问题生成回答」检索层只负责「从文档库里捞出最相关的几段」服务层负责把两者串起来、管会话、管流式输出。三层之间用普通 Python 函数和 HTTP 接口通信没有引入消息队列也没上微服务单机 docker-compose 就能起来。这种朴素结构是刻意的私有化场景里运维成本比架构先进更重要一个能在内网机器上docker compose up就跑起来的系统比需要五个人维护的链路有价值得多。2.1 底座模型为什么是 ChatGLM 系 6B 量级而不是更大的选型的第一个约束是显存不是效果。6B 量级的对话模型在 FP16 下权重大约 1213GB加上 KV Cache 和推理时的中间激活单张 24GB 卡跑起来很宽松16GB 卡勉强INT8 量化后 8GB 上下INT4 量化后 5GB 左右就能起。这个显存区间正好覆盖了内网里最常见的几张卡也覆盖了「用一张消费级卡先验证效果」的场景。再往上换 13B、32B效果确实更好但很多内网机器根本装不下项目就跑不起来了。第二个约束是中文。ChatGLM 系本身就是中英双语对话模型中文问、中文答、中文文档里的术语识别都不需要额外做适配省掉了大量 prompt 调优的工作。它支持trust_remote_codeTrue方式加载模型结构和 tokenizer 逻辑都随模型仓库一起下发升级版本不用改调用代码这对长期维护的项目很关键。第三个约束是上下文长度。这一代的对话模型上下文普遍在 8k 量级单靠「把整篇文档塞进去」是行不通的所以检索层不是可选项而是必需品。8k 的窗口用来装「系统提示词 35 段检索结果 若干轮历史对话」刚刚好再多就会开始稀释注意力模型容易答非所问。加载方式权重显存6B 量级建议显卡体感FP16 全精度约 1213GB24GB 及以上质量最好速度中等INT8 量化约 78GB16GB质量接近 FP16略慢INT4 量化约 45GB812GB质量有损但问答场景够用CPU 推理内存 16GB无能跑但首字延迟几十秒只适合演示提示量化是在模型载入之后在线做的不是离线转换所以启动时间会比全精度多几十秒这是正常的不要误判成卡死。2.2 检索层RAG 链路为什么绕不开很多人第一反应是「模型上下文不是有 8k 吗把文档拼进去不就行了」。真跑一遍就知道不行几百份文档加起来上百万字8k 窗口连十分之一都装不下就算只装最相关的十页token 成本和时间成本也会让每次问答变得难以接受更麻烦的是文档会更新每次更新都要重新拼上下文模型本身却不知道新内容。检索增强这条链路解决的就是这三件事——只取相关的、每次只取几段、文档更新只重建索引不动模型。向量库的选择上这个项目用的是 FAISS理由是零依赖、纯本地文件、不需要额外起服务。内网环境里少一个进程就少一个故障点。如果后续文档量涨到几十万条、需要多进程并发写再换 Milvus 或 Chroma 也不迟接口层抽象好了替换成本不高。向量库部署形态适合规模取舍FAISS进程内库索引存本地文件十万级以内最简单无服务依赖但不支持并发写Chroma嵌入式或独立服务十万到百万级带元数据过滤API 友好依赖稍重Milvus独立集群百万级以上能力强运维成本也高Embedding 模型这块中文场景常见做法是用 text2vec 系列或 bge 系列的中文小模型几百 MB 大小CPU 上跑一条文本几十毫秒配合批量入库完全够用。要注意的是入库和查询必须用同一个 embedding 模型换模型等于索引作废这一点后面避坑章节还会提。2.3 服务层FastAPI SSE 前端的分工服务层用 FastAPI主要图三件事原生 async 支持、Pydantic 做请求体校验、以及StreamingResponse直接就能吐 SSE 流。对话类应用的体验核心是「首字快」用户按下回车之后一两秒内看到第一个字往外蹦和等十秒一次性刷出一整段感受完全是两回事。SSE 相比 WebSocket 的优势在于它就是普通 HTTP 响应代理、网关、负载均衡都不需要额外配置内网里那些老旧的反向代理也不会卡它。前端分两套一套 Gradio 页面用来做内部演示和调试改几行就能跑不用管前端工程化一套独立的前端页面走/api/chat接口用于正式交付。会话历史存在 SQLite 里按session_id分组简单场景够用如果要多实例部署换成 Redis 就行接口层封装一个SessionStore抽象换实现不动业务代码。整体链路是这样用户提问 → 服务层拿问题去向量库检索 top-k 片段 → 拼成 prompt → 调模型的stream_chat→ 逐块 yield 回前端 → 前端边收边渲染 → 回答结束后把这一轮问答写进会话历史。整条链路上没有异步任务、没有队列请求进来就处理处理完就返回逻辑直白到任何一个后端接手都能在半天内看懂。3. 目录结构与启动链路从入口脚本到第一个流式 token项目结构按「模型 / 检索 / 服务 / 前端」四块分目录每个目录只干一件事。这么分不是为了好看是为了让「换模型」「换向量库」「换前端」这三个高频改造动作各自只需要动一个目录。目录树长这样private-qa/ ├── app/ │ ├── main.py # FastAPI 入口注册路由、启动时加载模型 │ ├── api/ │ │ ├── chat.py # /api/chat 流式问答接口 │ │ └── admin.py # /api/admin/reindex 重建索引接口 │ ├── core/ │ │ ├── config.py # 读取 config.yaml 环境变量覆盖 │ │ └── logger.py # 统一日志格式带 request_id │ ├── llm/ │ │ ├── loader.py # 模型与 tokenizer 加载、量化 │ │ └── chat.py # stream_chat 封装、历史裁剪 │ ├── rag/ │ │ ├── splitter.py # 文档解析与分块 │ │ ├── embedder.py # embedding 模型封装 │ │ ├── index.py # FAISS 建索引、加载、检索 │ │ └── prompt.py # 系统提示词与上下文拼装 │ └── store/ │ └── session.py # SQLite 会话存储 ├── data/ │ ├── docs/ # 原始文档pdf/docx/md/txt │ └── index/ # faiss.index meta.jsonl ├── web/ # 独立前端页面 ├── config.yaml ├── requirements.txt ├── Dockerfile └── docker-compose.yml3.1 配置项与启动顺序配置用一份config.yaml打底环境变量做覆盖容器里改环境变量、本机开发改 yaml两边互不干扰。关键配置项如下每一项都对应一个实际会调的场景model: path: /models/chatglm-6b # 模型目录本地路径不走网络下载 quantize: 4 # 4 / 8 / 0(不量化) device: cuda # cuda / cpu max_length: 2048 # 单次生成的最大 token 数 rag: doc_dir: ./data/docs index_dir: ./data/index embed_model: ./models/text2vec-base-chinese chunk_size: 500 # 每块字符数 chunk_overlap: 50 # 相邻块重叠字符数 top_k: 4 # 检索返回条数 score_threshold: 0.35 # 低于该相似度的片段直接丢弃 server: host: 0.0.0.0 port: 8000 session_db: ./data/session.db启动顺序是有讲究的不能乱先加载 embedding 模型几百 MB快再加载对话模型几 GB慢然后检查索引文件是否存在不存在就触发一次全量入库最后才把 FastAPI 的端口亮出来。这么排的原因是模型加载动辄一两分钟如果先把端口开了健康检查探针会立刻打进来此时模型还没就绪请求会全部超时运维那边看到的就是「服务起来了但全 500」。# 本地起服务模型提前放到 /models 下 pip install -r requirements.txt python -m app.main --config config.yaml # 容器方式模型目录挂载进去避免打进镜像 docker compose up -d docker compose logs -f app | grep model ready--config指定配置文件路径不传则读当前目录的config.yaml。容器方式里模型目录通过 volume 挂载不要把几 GB 的权重打进镜像镜像会膨胀到无法分发每次换模型还得重新构建纯属给自己找麻烦。3.2 一次问答请求的完整链路把一次请求拆开看能看清每一层各自花了多少时间出问题的时候也知道该看哪段日志前端 POST/api/chatbody 里带session_id和query服务层用 Pydantic 校验字段缺字段直接 422 返回。服务层拿query调 embedding 模型编码成一个向量维度通常是 768耗时几十毫秒。用这个向量去 FAISS 里做内积检索取 top-k默认 4再按score_threshold过滤掉不相关的。从meta.jsonl里按 id 取回原始文本片段和来源文件名拼成引用块。取出该会话最近若干轮历史按 token 预算裁剪避免超长。用系统提示词 检索片段 历史 当前问题拼成最终 prompt交给模型stream_chat。模型逐 token 生成服务层包成 SSE 事件往前端推每块形如data: {delta: ...}\n\n。生成结束后发一个data: [DONE]前端收到后关闭连接同时把本轮问答落库。链路上有两个容易被忽略的点一是第 5 步的历史裁剪不做的话第 10 轮对话必然超长模型会开始胡言乱语二是第 7 步的 SSE 心跳长时间没有 token 输出时比如模型在做长思考中间的网络设备可能把空闲连接掐掉常见做法是每 15 秒发一个注释行: ping前端不渲染但连接保住了。4. 核心模块拆解入库、检索、拼 Prompt、流式返回这一章是全篇最该抄作业的部分。四个模块串起来就是一条完整的 RAG 链路每个模块我都把关键代码和参数含义写清楚照着改就能接到自己的文档上。4.1 文档解析与切分切多粗才不丢语义入库第一步是把 pdf、docx、md、txt 统一抽成纯文本再切成固定大小的块。切分策略直接决定检索质量切得太碎一句话被劈成两半检索到了也读不懂切得太粗一块里混了三四个主题向量被平均掉相似度反而不准。这个项目用的策略是按段落累积到 500 字切一刀相邻块保留 50 字重叠重叠的作用是防止关键句正好落在切口上被腰斩。# app/rag/splitter.py import re from pathlib import Path def clean_text(text: str) - str: # 去掉多余空行和连续空格PDF 抽出来的文本经常有大量断行 text re.sub(r[ \t], , text) text re.sub(r\n{3,}, \n\n, text) return text.strip() def split_text(text: str, chunk_size: int 500, overlap: int 50): 按段落聚合切块块间保留 overlap 个字符的重叠 text clean_text(text) paragraphs [p.strip() for p in text.split(\n\n) if p.strip()] chunks, buf [], for para in paragraphs: # 单段超长时先硬切避免一块顶到几万字 if len(para) chunk_size: if buf: chunks.append(buf) buf for i in range(0, len(para), chunk_size - overlap): chunks.append(para[i:i chunk_size]) continue if len(buf) len(para) 1 chunk_size: buf f{buf}\n{para} if buf else para else: chunks.append(buf) # 用上一块的尾部做重叠保证切口两侧语义连续 buf buf[-overlap:] \n para if overlap else para if buf: chunks.append(buf) return [c.strip() for c in chunks if len(c.strip()) 20] def load_documents(doc_dir: str): 遍历目录按后缀分发解析器返回 (文本, 来源文件名) 列表 docs [] for path in Path(doc_dir).rglob(*): if path.suffix.lower() .pdf: import fitz # PyMuPDF with fitz.open(path) as pdf: text \n\n.join(page.get_text() for page in pdf) elif path.suffix.lower() in (.md, .txt): text path.read_text(encodingutf-8, errorsignore) else: continue docs.append((text, path.name)) return docschunk_size和overlap是最需要按自己语料调的参数。技术手册这类信息密度高的文档500 字一块比较合适会议纪要、聊天记录这种口语化文本可以降到 300法规条文这种一句都不能断的建议按条款结构切别用定长。len(c.strip()) 20这个过滤是去掉页眉页脚、目录行这类噪声块不加的话索引里会混进一堆「第 3 页」之类的垃圾检索时经常被误召回。4.2 向量化与索引FAISS 的 index 和 metadata 怎么对齐FAISS 只存向量不存原文所以必须自己维护一份 id 到文本的映射。这里的做法是向量按入库顺序 appendmeta.jsonl里按同样顺序逐行写{id, text, source}检索拿到的下标直接当 id 用。顺序必须严格一致中途插入或删除会导致错位一旦错位检索出来的「原文」和向量就对不上了回答会出现驴唇不对马嘴的情况而且极难排查。# app/rag/index.py import json import faiss import numpy as np def build_index(vectors: np.ndarray, metas: list, index_dir: str): # 归一化后内积等价于余弦相似度FAISS 的 IndexFlatIP 才可用 faiss.normalize_L2(vectors) index faiss.IndexFlatIP(vectors.shape[1]) index.add(vectors) faiss.write_index(index, f{index_dir}/faiss.index) with open(f{index_dir}/meta.jsonl, w, encodingutf-8) as f: for i, m in enumerate(metas): f.write(json.dumps({id: i, **m}, ensure_asciiFalse) \n) def search(query_vec: np.ndarray, index_dir: str, top_k: int 4, threshold: float 0.35): index faiss.read_index(f{index_dir}/faiss.index) q query_vec.reshape(1, -1).astype(float32) faiss.normalize_L2(q) # 查询向量必须用同样的方式归一化 scores, ids index.search(q, top_k) metas [json.loads(line) for line in open(f{index_dir}/meta.jsonl, encodingutf-8)] hits [] for score, idx in zip(scores[0], ids[0]): if idx -1 or score threshold: continue # -1 表示不足 top_k低分片段直接丢 hits.append({**metas[idx], score: float(score)}) return hitsIndexFlatIP是暴力检索文档量小于十万条时完全够用一次查询几毫秒不需要折腾 IVF、HNSW 这些近似索引近似索引有召回损失在问答场景里丢一条关键文档的代价比省几毫秒大得多。threshold这个阈值不能省用户问一个文档里压根没提的问题时纯 top-k 一定会硬凑几条不相关的片段塞给模型模型拿到垃圾上下文就会一本正经地编这是幻觉的主要来源之一。4.3 Prompt 拼装系统提示词和历史轮次的处理Prompt 是这套系统里唯一能「编程」模型行为的地方写得好不好直接决定回答风格。核心原则有三条明确告诉模型只依据给定资料回答、明确要求它不知道就说不知道、明确引用格式。历史对话要按 token 预算裁不能无限往上传。# app/rag/prompt.py SYSTEM_PROMPT 你是一个企业内部的文档问答助手。请严格依据下面提供的参考资料回答问题。 要求 1. 只使用参考资料中的信息不要引入外部知识 2. 如果参考资料中没有答案直接回答「根据现有资料无法确定」不要猜测 3. 回答末尾用 [来源: 文件名] 的格式标注引用的资料。 def build_prompt(query: str, hits: list, history: list, max_history_turns: int 3): ctx \n\n.join( f[资料{i1} | {h[source]}]\n{h[text]} for i, h in enumerate(hits) ) or 未检索到相关资料 # 只保留最近几轮历史越长越容易超出上下文窗口 recent history[-max_history_turns * 2:] messages [{role: system, content: SYSTEM_PROMPT}] for turn in recent: messages.append(turn) messages.append({ role: user, content: f参考资料\n{ctx}\n\n问题{query} }) return messagesmax_history_turns控制带几轮历史默认 3 轮。带太多会挤占检索片段的位置而且早期轮次的话题可能已经切换留着反而干扰。ctx为空时显式塞一句「未检索到相关资料」比留空好——留空的时候模型容易把系统提示词里的「参考资料」四个字当成有内容开始脑补。4.4 流式接口与前端对接流式输出的关键是把模型的生成器直接接到 HTTP 响应上中间不做全量缓冲。模型每吐一段就包成一个 SSE 事件推出去。这里用同步生成器套在 FastAPI 的StreamingResponse里模型推理本身是同步阻塞的所以放在线程池里跑别把事件循环堵死。# app/api/chat.py import json from fastapi import APIRouter from fastapi.responses import StreamingResponse from pydantic import BaseModel router APIRouter() class ChatRequest(BaseModel): session_id: str query: str router.post(/api/chat) async def chat(req: ChatRequest): def event_stream(): try: hits retrieve(req.query) # 检索 messages build_prompt(req.query, hits, load_history(req.session_id)) for delta in stream_chat(messages): # 模型逐块产出 yield fdata: {json.dumps({delta: delta}, ensure_asciiFalse)}\n\n yield data: [DONE]\n\n save_history(req.session_id, req.query, full_text) except Exception as e: yield fdata: {json.dumps({error: str(e)}, ensure_asciiFalse)}\n\n return StreamingResponse(event_stream(), media_typetext/event-stream, headers{Cache-Control: no-cache, X-Accel-Buffering: no})media_type必须是text/event-stream前端才能用EventSource或 fetch 的 reader 正确解析。X-Accel-Buffering: no这个响应头是给 Nginx 看的不加的话 Nginx 会默认缓冲响应前端看到的就不是逐字蹦出而是等全部生成完一次性刷出来流式白做。这个坑我在两个项目里各踩过一次第二次还是忘了血泪经验。5. 避坑与排查显存、编码、端口这些踩过的坑这套系统的坑集中在三个地方模型加载、检索链路、服务部署。下面每条都按「现象 → 原因 → 解决」写遇到时对照着看能省不少时间。5.1 模型加载阶段现象启动时显存瞬间打满然后进程被杀日志里只有一行 Killed。原因通常是先按 FP16 把全量权重读进显存再做量化这个瞬间的峰值显存比量化后高得多小卡直接扛不住。解决方式是加载时就用low_cpu_mem_usageTrue和torch_dtypetorch.float16并把量化参数在加载阶段传进去避免「先全量后压缩」的峰值实在不行先在一张 24GB 卡上把量化后的权重转换好存盘再拿到小卡上加载。现象模型能加载但第一次问答要等一两分钟才出第一个字。这是首次推理的 CUDA kernel 编译和显存分配开销不是卡死。做法是在服务启动完成后主动跑一次极短的预热请求比如 query 传「你好」max_length 设 8把这条路径先走一遍之后用户请求就是正常速度。线上服务不做预热第一个用户必然是倒霉蛋。5.2 检索链路现象回答内容明显是编的但检索日志显示确实返回了片段。多半是相似度阈值没设或者设得太低top-k 硬凑了几条不相关片段模型拿到之后开始顺着编。解决是给score_threshold设一个合理值这个项目里是 0.35并把命中片段的分数打进日志低于阈值的直接不进 prompt宁可不答也别乱答。现象换了 embedding 模型之后检索结果全乱分数普遍偏低。向量维度和语义空间都变了但 FAISS 索引文件还是旧的等于拿新模型的向量去和旧模型的向量比相似度纯属玄学。解决是换 embedding 模型必须重建索引在admin.py里加一个版本号字段索引文件里记录 embedding 模型名启动时比对不一致就直接报错退出别让它带着错索引跑。现象PDF 抽出来的文本里混进了大量乱码和页眉检索老召回垃圾。编码和版式问题。PDF 解析器对扫描件、双栏排版、带页眉页脚的文档经常抽不干净。做法是入库前过一遍清洗去连续空格、去纯数字行、去重复出现的短行扫描件先走 OCR 再入库双栏文档用带版面分析的解析库。5.3 服务与部署现象本地跑得好好的部署到内网之后前端一个字都不往外蹦等半天一次性刷出全文。反向代理缓冲。Nginx 默认开启proxy_bufferingSSE 流会被攒着。解决是响应头加X-Accel-Buffering: no同时在 Nginx 配置里对该路径关掉缓冲、把proxy_read_timeout调大。现象并发两个人同时提问第二个人的回答串到了第一个人的会话里。模型实例是全局单例stream_chat内部维护了状态多线程并发调用时历史被串了。解决是为每个请求传入独立的 history 副本不共享可变状态如果并发量再大就得考虑用多进程各持一份模型或者换成支持批处理的推理服务。现象容器里跑 CPU 推理内存一路涨到被 OOM Killer 干掉。长时间运行 每次请求都新建 tokenizer 或缓存历史不清理。做法是把模型和 tokenizer 在启动时加载一次常驻历史会话设上限并按 LRU 淘汰容器加mem_limit兜底。6. 二次开发换模型、换向量库、加权限怎么改不返工拿到这套代码之后最常见的三个改造方向是换模型、换向量库、加权限。这三个动作能不能做干净取决于当初有没有把边界留出来。换模型要改的只有app/llm/一个目录。loader.py里暴露load_chat_model(path, quantize)chat.py里暴露stream_chat(messages, max_length)上层只认这两个函数签名。换别的开源对话模型时只要在新实现里把「messages 列表 → 逐块文本」这个转换写对服务层一行不用动。要留意的是不同模型的对话模板不一样有的要求 system 单独拼有的要求特殊 token 包裹这块写错的表现是模型回答质量断崖式下跌但不会报错属于隐形 bug改完一定要拿同一批问题对比一下回答。改造点需要动的文件验证方式换对话模型llm/loader.py、llm/chat.py同 20 条问题对比首字延迟和回答完整度换向量库rag/index.py拿固定 query 比对 top-4 命中是否一致加用户权限api/chat.py、store/session.py用两个账号交叉访问对方 session_id 应被拒加文档增量更新api/admin.py、rag/index.py传一份新文档后原问题能召回新内容加权限这块最小改动是在session_id之外再带一个user_id会话表里加一列查询时强制带user_id过滤。别指望前端不传就越权接口层必须自己校验我见过太多项目把权限判断写在前端路由里改个请求就绕过去了。文档级权限更麻烦一些需要在meta.jsonl的每条记录上加acl字段检索时把无权限的片段过滤掉再拼 prompt——注意是过滤片段不是过滤回答模型看不到的内容它才不会说出去。还有一个值得提前做的东西评测集。从真实文档里挑 30 条有标准答案的问题做成一个 jsonl每次改完模型或检索参数就跑一遍人工看命中率和回答质量。没有这个所有改造都是拍脑袋改完感觉「好像好了一点」实际可能退步了。从那以后我每次动检索参数或者换模型都强制把这个小评测集跑一遍再合代码跑一次十分钟比上线后被业务方追着问强太多。希望帮到你。本文还有配套的精品资源点击获取