简介这份资源面向希望快速搭建企业级智能客服与私有化问答系统的开发者、运维及技术团队核心是基于企业私有知识库与大语言模型构建专属 AI 问答机器人。包内共 1302 个文件以 278 个 js、194 个 vue、116 个 ts 等前端源码106 个 go 后端代码以及 63 个 sql、70 个 json、57 个 css 和若干 Dockerfile、conf 配置为主压缩包约 34.01MB覆盖前后端、数据库与容器化部署的完整工程结构。系统支持导入企业已有知识构建知识库提供自动分段、QA 分段、手动输入与 CSV 等多种数据预处理方式并自动完成向量化或 QA 分割同时可一键接入全球 20 多种主流模型仅需配置 API key 即可使用。问答机器人支持 H5 链接、嵌入网站、桌面客户端等多渠道接入适配不同业务场景。已有 596 人学习适合研究私有化 LLM 问答系统落地与二次开发的读者参考。1. 企业私有知识库接入 LLM一套能私有化部署的智能客服问答系统很多团队在 2024 年之后都动过同一个念头把公司内部散落在 Confluence、飞书文档、PDF 手册、工单记录里的知识变成一个能对话的客服机器人。但真动手时才发现直接调云端大模型 API 有两个绕不过去的坎——数据出域和幻觉。尤其是金融、医疗、制造业的客户内部文档里全是产品参数、故障处理 SOP、合同条款这些东西一旦上传到外部接口合规部门第一个不答应。这套「基于企业私有知识库的 LLM 智能客服问答系统」解决的正是这个问题它把大语言模型、向量检索、私有化部署三件事串成一条完整链路让模型只基于你喂进去的文档回答答不出来就说不知道而不是编。适合谁适合手里有一堆内部文档、想搭一个能落地的问答系统、又必须把数据留在自己服务器上的工程师和团队。下面我按「是什么 → 怎么搭 → 坑在哪 → 怎么调优」的顺序把这份资源拆开讲透。2. RAG 架构拆解为什么私有知识库问答不能只靠微调2.1 检索增强生成到底解决了什么先说清楚一个常见误区很多人以为「让模型懂我们公司的知识」就得微调Fine-tuning。微调确实能让模型学会某种说话风格或领域术语但它有个致命问题——知识更新成本极高。你今天改了一份产品手册微调模型不会自动知道得重新跑一遍训练。而 RAGRetrieval-Augmented Generation检索增强生成的思路完全不同模型本身不动知识放在外部向量库里每次提问时先去库里检索相关片段再把片段塞进提示词让模型基于这些内容回答。这套系统的核心链路是这样的用户提问 → 问题向量化 → 在向量库中做相似度检索 → 取回 Top-K 相关文档片段 → 拼接成提示词 → 交给 LLM 生成回答 → 返回带出处的答案。整条链路里LLM 只负责「理解和组织语言」知识的事实性由检索结果保证。这就是为什么私有知识库问答几乎都选 RAG 而不是纯微调——知识可热更新、可溯源、可控制。常见做法是文档解析 → 文本分块Chunking→ 向量化Embedding→ 存入向量数据库 → 检索 → 重排Rerank→ 生成。这套资源把这几个环节都做成了可配置的模块下面逐个拆。2.2 文档解析与分块决定检索质量的第一道关文档解析看着简单实际上是最容易翻车的地方。PDF 里的表格、扫描件、双栏排版解析出来经常是乱的。我一般会按文件类型分流处理# 文档解析分流逻辑常见做法 import os from pathlib import Path def parse_document(file_path: str) - str: 根据文件类型选择解析器返回纯文本 suffix Path(file_path).suffix.lower() if suffix .pdf: # PDF 优先用 pdfplumber 保留表格结构 import pdfplumber text with pdfplumber.open(file_path) as pdf: for page in pdf.pages: # extract_tables 先抽表格再抽正文避免表格被拆散 tables page.extract_tables() for table in tables: for row in table: text | .join([cell or for cell in row]) \n text page.extract_text() or return text elif suffix in (.docx, .doc): from docx import Document doc Document(file_path) return \n.join([p.text for p in doc.paragraphs]) elif suffix in (.md, .txt): return Path(file_path).read_text(encodingutf-8) else: raise ValueError(f不支持的文件类型: {suffix})这段代码的关键点在 PDF 处理先抽表格再抽正文因为 pdfplumber 的extract_text()会把表格内容打散成一行行文字丢失行列对应关系。表格类文档比如产品参数表如果解析错了后面检索再准也没用。分块策略同样重要。固定 512 字符切一刀是最省事的做法但对中文文档不友好——容易把一句话从中间切断。我一般用「按段落切 超长段落再按句号切」的组合策略块大小控制在 300500 字块之间留 50 字左右重叠Overlap避免答案刚好落在两块交界处被漏掉。提示分块大小没有万能值。FAQ 类短文档可以切小一点200300 字技术手册类长文档切大一点500800 字。这套系统把 chunk_size 和 chunk_overlap 做成了配置项建议先用默认值跑通再根据召回效果调。2.3 向量化与向量库选型Embedding 模型怎么挑向量化就是把文本块变成一串浮点数向量语义相近的文本在向量空间里距离更近。这里有两个选型决策Embedding 模型选哪个、向量库选哪个。Embedding 模型方面中文场景我一般推荐 BGE 系列如 bge-large-zh或 M3E这两个在中文语义相似度任务上表现稳定而且可以本地部署不依赖外部接口。如果硬件资源紧张可以用 bge-small-zh维度从 1024 降到 512检索速度提升明显精度损失在可接受范围内。向量库选型看数据量向量库适用数据量特点FAISS10 万条以内轻量、无需额外服务、内存索引Milvus百万级以上分布式、支持持久化、运维成本高Chroma10 万条以内上手快、API 简洁、适合原型Qdrant十万到千万过滤检索强、Rust 实现性能好这套资源默认用的是 FAISS 本地持久化适合中小规模知识库几万条 chunk。如果文档量超过 50 万条建议换 Milvus 或 QdrantFAISS 的内存占用会成为瓶颈。# 向量化与入库以 FAISS BGE 为例 from sentence_transformers import SentenceTransformer import faiss import numpy as np # 加载本地 Embedding 模型首次运行会下载权重 model SentenceTransformer(BAAI/bge-large-zh-v1.5) def build_index(chunks: list[str], save_path: str faiss.index): 将文本块向量化并构建 FAISS 索引 # normalize_embeddingsTrue 让向量归一化内积等价于余弦相似度 embeddings model.encode( chunks, normalize_embeddingsTrue, batch_size32, show_progress_barTrue ) dim embeddings.shape[1] # bge-large-zh 是 1024 维 # IndexFlatIP 做内积检索配合归一化向量即余弦相似度 index faiss.IndexFlatIP(dim) index.add(np.array(embeddings).astype(float32)) faiss.write_index(index, save_path) return index参数说明normalize_embeddingsTrue是关键不做归一化的话内积检索结果会偏向长向量batch_size32在 8GB 显存的机器上比较稳显存大可调到 64 或 128IndexFlatIP是精确检索数据量超过 10 万条可以换成IndexIVFFlat做近似检索用少量精度换速度。3. 私有化部署实操从环境准备到服务启动3.1 硬件与依赖环境清单私有化部署的第一步是把硬件算清楚。这套系统的资源消耗分两块LLM 推理和 Embedding 推理。如果 LLM 用 7B 级别的模型如 Qwen2-7B、ChatGLM3-6BFP16 精度下需要约 14GB 显存4-bit 量化后降到 56GB。Embedding 模型 bge-large-zh 需要约 1.5GB 显存。所以一张 16GB 显存的卡如 4080、A4000可以同时跑 7B 量化和 Embedding24GB 卡3090、4090可以跑 7B FP16。纯 CPU 部署也能跑但 7B 模型在 CPU 上生成速度大约 25 token/s体验较差。如果只是内部低频使用可以接受高频客服场景建议至少上一张 GPU。依赖环境我一般这样配# 基础环境Python 3.10 CUDA 12.1 conda create -n rag-qa python3.10 -y conda activate rag-qa # 核心依赖 pip install torch2.1.0 --index-url https://download.pytorch.org/whl/cu121 pip install transformers4.36.0 accelerate0.25.0 pip install sentence-transformers2.2.2 pip install faiss-gpu1.7.4 # 有 GPU 用这个纯 CPU 换 faiss-cpu pip install pdfplumber python-docx # 文档解析 pip install fastapi uvicorn # API 服务 pip install gradio # 快速前端可选版本锁定很重要。transformers 和 sentence-transformers 的版本不匹配是高频翻车点上面这组版本组合我实测跑通过。如果要用 vLLM 加速推理torch 版本需要跟着 vLLM 的要求走不能照搬。3.2 模型加载与推理服务封装LLM 加载这块常见做法是用 transformers 的AutoModelForCausalLM直接加载或者用 vLLM 做推理加速。前者简单、兼容性好后者吞吐量高但配置复杂。这套资源默认走 transformers 路线适合中小规模部署。# LLM 加载与推理封装 from transformers import AutoTokenizer, AutoModelForCausalLM import torch MODEL_PATH /models/Qwen2-7B-Instruct # 本地模型路径 tokenizer AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( MODEL_PATH, torch_dtypetorch.float16, # FP16 精度显存不够改 load_in_4bitTrue device_mapauto, # 自动分配到可用 GPU trust_remote_codeTrue ) model.eval() def generate_answer(prompt: str, max_new_tokens: int 512) - str: 基于拼接好的提示词生成回答 inputs tokenizer(prompt, return_tensorspt).to(model.device) with torch.no_grad(): outputs model.generate( **inputs, max_new_tokensmax_new_tokens, temperature0.1, # 低温度减少发挥 top_p0.8, do_sampleTrue, repetition_penalty1.1 # 抑制重复输出 ) # 只取新生成的部分去掉输入 prompt answer tokenizer.decode( outputs[0][inputs[input_ids].shape[1]:], skip_special_tokensTrue ) return answer参数说明temperature0.1是知识库问答的关键设置温度越低模型越倾向于「照抄」检索到的内容而不是自由发挥max_new_tokens512控制回答长度客服场景一般够用repetition_penalty1.1防止模型陷入重复循环。如果显存不够把torch_dtype改成torch.float16并加load_in_4bitTrue需要额外装 bitsandbytes。3.3 提示词模板与检索结果拼接提示词是 RAG 系统里最容易被忽视、但对效果影响最大的部分。一个好的提示词要明确三件事角色定位、知识边界、输出格式。PROMPT_TEMPLATE 你是一个企业客服助手只能根据下面提供的知识片段回答问题。 规则 1. 如果知识片段中有明确答案直接回答不要添加片段之外的信息。 2. 如果知识片段中没有相关内容回答抱歉我暂时没有找到相关信息建议联系人工客服。 3. 回答时保持简洁不要重复问题。 知识片段 {context} 用户问题{question} 回答 def build_prompt(question: str, retrieved_chunks: list[str]) - str: 将检索结果拼接到提示词模板 # 多个片段用分隔符隔开避免模型混淆边界 context \n---\n.join(retrieved_chunks) return PROMPT_TEMPLATE.format(contextcontext, questionquestion)这段模板的核心是第 2 条规则——明确告诉模型「不知道就说不知道」。没有这条约束模型在检索结果不相关时会用自己的预训练知识编答案这是 RAG 系统最常见的幻觉来源。\n---\n分隔符的作用是让模型能区分不同片段避免把两个文档的内容混在一起理解。检索环节的 Top-K 一般设 35。K 太小可能漏掉答案K 太大则提示词变长、推理变慢而且无关片段会干扰模型判断。我一般先用 K5 跑看召回效果再调。4. 避坑与排查私有化问答系统上线前必须过的五道坎4.1 检索到了但模型不按检索内容回答现象明明向量库里有一条完全匹配的文档模型却给出了一个似是而非的答案甚至和文档内容矛盾。原因提示词约束不够强或者检索片段被放在了提示词的中间位置。LLM 对提示词开头和结尾的内容注意力更高中间部分容易被忽略这就是所谓的「Lost in the Middle」现象。解决把最相关的片段放在 context 的最前面在提示词里加一句「必须严格依据上述知识片段回答不得使用你自己的知识」如果还是不行把 temperature 降到 0.05 以下。4.2 中文文档分块后语义断裂现象用户问「XX 产品的保修期是多久」检索返回的片段只有「保修期为」几个字后面的「两年」被切到了下一块。原因固定长度分块没有考虑句子边界刚好在关键信息处切断。解决改用按标点分句后再合并的分块策略确保每个 chunk 以完整句子结尾。具体做法是用正则按。切分再贪心合并到目标长度。同时把 chunk_overlap 调大到 80100 字给边界情况留冗余。4.3 Embedding 模型和 LLM 抢显存导致 OOM现象单独加载 LLM 正常单独加载 Embedding 也正常两个一起跑就报 CUDA out of memory。原因两个模型默认都往 GPU 0 上放显存叠加超限。解决把 Embedding 模型放到 CPU 上跑model.encode(..., devicecpu)或者用CUDA_VISIBLE_DEVICES把两个模型分到不同卡上。Embedding 推理对延迟不敏感一次编码几十毫秒放 CPU 完全可接受。4.4 PDF 扫描件解析出来是空白现象解析某些 PDF 后 text 为空字符串向量库里什么都没有。原因这些 PDF 是扫描件内容是图片而非文字层pdfplumber 提取不到文本。解决先用page.extract_text()判断是否为空为空则走 OCR 流程如 PaddleOCR 或 Tesseract。OCR 后的文本质量参差不齐建议在入库前加一步人工抽检至少随机看 10 个 chunk 的内容是否通顺。4.5 相似问题召回不稳定现象同一个问题换个说法有时候能召回正确文档有时候召回的是无关内容。原因单一向量检索对措辞敏感尤其是短问题少于 10 个字向量信息量不足。解决加一层关键词检索做混合召回Hybrid Search向量检索和 BM25 各取 Top-10合并去重后再用 Rerank 模型如 bge-reranker精排。这套资源里预留了 Rerank 接口默认关闭数据量大或召回不稳定时建议打开。5. 效果调优与验证把召回率从 60% 拉到 90% 的几个手段系统跑通只是起点真正决定能不能上线的是召回率和回答准确率。我一般用一个笨办法先建立基线从真实客服对话里抽 50100 个问题人工标注每个问题的正确答案在哪个文档里然后跑一遍系统看 Top-5 召回率。低于 80% 就别急着上线先调检索。调优优先级我按这个顺序走分块策略 Embedding 模型 Rerank 提示词。分块是地基地基没打好后面怎么调都白搭。具体做法是把 chunk_size 从 300 到 800 按 100 步进各跑一遍看哪个值召回率最高。Embedding 模型方面bge-large-zh 换成 bge-m3 在多语言和长文本上更强但显存占用翻倍量力而行。Rerank 是性价比最高的一步。向量检索召回 Top-20再用 Rerank 模型精排出 Top-5 送给 LLM召回率通常能提升 1015 个百分点。代价是每次查询多几十毫秒延迟客服场景完全能接受。# 混合检索 Rerank 的简化实现 from rank_bm25 import BM25Okapi from sentence_transformers import CrossEncoder # 初始化 Rerank 模型首次运行下载权重 reranker CrossEncoder(BAAI/bge-reranker-large, max_length512) def hybrid_retrieve(question: str, chunks: list[str], top_k: int 5): 向量召回 BM25 召回 Rerank 精排 # 1. 向量召回 Top-20 q_vec model.encode(question, normalize_embeddingsTrue) _, vec_indices index.search(np.array([q_vec]).astype(float32), 20) vec_results [chunks[i] for i in vec_indices[0]] # 2. BM25 召回 Top-20中文需先分词这里用字符级简化 tokenized [list(c) for c in chunks] bm25 BM25Okapi(tokenized) bm25_scores bm25.get_scores(list(question)) bm25_indices np.argsort(bm25_scores)[::-1][:20] bm25_results [chunks[i] for i in bm25_indices] # 3. 合并去重 candidates list(dict.fromkeys(vec_results bm25_results)) # 4. Rerank 精排 pairs [[question, c] for c in candidates] scores reranker.predict(pairs) ranked sorted(zip(candidates, scores), keylambda x: x[1], reverseTrue) return [c for c, _ in ranked[:top_k]]这段代码里 BM25 的中文分词用了字符级简化生产环境建议换 jieba 分词。Rerank 模型bge-reranker-large约 1.3GB可以和 Embedding 模型共享 CPU 推理。整个混合检索链路比纯向量检索多约 100200ms 延迟但召回率提升明显这笔账划算。验证环节我有个习惯每次调完参数不光看召回率数字还要把 Top-5 的片段和用户问题一起打印出来人工过一遍。数字好看但片段不相关的 case 经常有只有人眼看了才知道问题出在分块、Embedding 还是 Rerank。从那以后我每次上线新知识库都强制走一遍「50 问题人工抽检」再也不敢只看指标就发布。希望这套拆解能帮你少走点弯路把私有知识库问答真正跑起来。本文还有配套的精品资源点击获取