简介面向企业私有化部署需求该资源为一套将大语言模型与企业知识库结合的智能客服问答系统完整源码适合需要自建AI问答机器人的开发者、运维和技术负责人。系统包含专属知识库构建、20多种主流模型一键接入、数据自动分段与QA处理、多渠道发布H5、网页嵌入、桌面端等核心能力能直接支撑业务场景落地。压缩包约34MB共1302个文件以vue/js/ts/go等前后端代码为主配合sql数据库脚本、json配置和dockerfile方便本地运行、容器化部署和二次开发。已有596人学习下载。通过复用源码中的模型对接、知识库检索和接口设计可显著降低从零搭建问答系统的时间成本尤其适合拿来即用的中小团队。1. 企业智能客服为什么必须走私有知识库这条路我见过不少团队把大模型接到客服系统上结果机器人依旧答非所问最气人的是它能把官网明确写着的退换货政策说反。问题不在模型参数不够大而在知识没有真正喂进去。基于企业私有知识库的LLM智能客服问答系统核心是把散落在PDF、Word、Wiki、工单系统里的标准答案切分、向量化后存进一个内网知识库问答时先检索再生成。支持私有化部署意味着数据不出内网、模型和向量库全在自有机器上跑这对金融、政务、制造这类有合规要求的行业几乎是唯一选择。这篇笔记我会按架构、索引、编排、避坑一路拆到可复现适合正在选型或已经踩坑的从业者。2. 私有化知识库问答系统的整体架构从文档入库到 LLM 回答要过哪几道关动手之前先想清楚一个问题你要的“知识库”到底长什么样。很多人直接把知识库等同于向量数据库其实企业落地时经常要同时用三种形态。选错后面全得返工。2.1 三种知识库范式KG、RAG、结构化知识库的区别与选型最近经常被问到“kg知识库、rag知识库和结构知识库怎么区分”这也是知识库负责人最该想明白的事。三者的存储逻辑和适用场景完全不同范式存储单位检索方式最擅长的场景典型代价KG 知识图谱实体、关系、属性图遍历/规则查询多跳关系比如“这个零件被哪些供应商供过质量如何”构建和运维成本高需要大量人工标注RAG 知识库文本切片及向量向量相似度召回非结构化文档问答比如制度文件、产品手册、售后问答对分块、召回质量敏感结构化知识库数据库表、ExcelSQL、筛选聚合精确查询如订单状态、库存数量、价格梯度需要预先建表和清洗数据我在实际项目里的选型原则是凡是能精确落库的工单编号、库存、售后期限先放结构化表凡是高度关联、需要推理关系的设备故障链路、客诉归因才做知识图谱而剩下大量 PDF、网页、对话记录统一进 RAG。智能客服 80% 的问题是“某文档里怎么写的”所以 RAG 是主链路KG 和结构化库作为辅助插件按需挂进来。很多团队一上来就搭知识图谱结果光建本体和抽取关系就耗费三个月客诉问题还是没有改善。反过来纯 RAG 也有硬伤——它不知道“A customer asked to return a defective battery”和“退换货政策第3条”之间的业务关联这正是 KG 能补的位置。但你要知道对大多数做私有化客服的团队第一版根本不需要图谱把 RAG 跑通就比现状强一个数量级。2.2 最小可用架构接入层、检索层、生成层的组件清单私有化部署的智能客服无论用什么框架包装最后都要拆成三个层。我习惯这样划分接入层负责把客服渠道网页、企微、钉钉的消息转成统一的用户问询对象并做意图分流简单规则命中直接返回复杂语义才走大模型。检索层负责把用户问题转成向量或查询条件从向量库、数据库、图谱里捞出候选答案并做重排。生成层负责把候选片段和系统提示词交给 LLM要求它只基于给定内容作答并附上引用来源。三层的组件选择直接决定你能否私有化、好不好维护。我倾向用以下组合层级可选组件私有化友好度备注接入层FastAPI 渠道 SDK高自己写适配器别绑死平台检索层Milvus / Chroma / Qdrant高选支持中文和按条件过滤的向量模型BGE / 通义Text-Embedding / M3E高决不可用在线 API否则没法内网生成层Qwen / ChatGLM / DeepSeek 开源版本高7B14B 即可支撑客服场景编排Dify / LangChain / 自写中Dify 最省事LangChain 更灵活我曾经在只有一台 8 卡 A10 的机房跑 14B 模型加 80 万文档的向量库最后也稳定扛住了日均两万次客服调用。关键不是堆算力而是把链路压短、把超时兜住。三层各自都要有降级方案——比如 LLM 挂了直接走检索层的 top1 片段返回这样客服不会直面“模型不可用”的白屏。2.3 从零搭一套离线环境依赖安装与模型下载先从最基础的离线环境说起。常见的做法是用 Docker 在自有服务器上把 Ollama 和向量库拉起来模型通过内网代理下载或从已联网机器拷贝。下面这组命令我每次搭新环境都会用到# 1. 安装 DockerUbuntu 22.04 示例 curl -fsSL https://get.docker.com | sudo sh sudo systemctl enable --now docker # 2. 启动 Ollama用于本地跑 LLM docker run -d --gpus all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama # 3. 拉取并运行 7B 对话模型这里用 qwen2.5:7b 举例 docker exec ollama ollama pull qwen2.5:7b docker exec ollama ollama run qwen2.5:7b 你是客服机器人的底层模型 # 4. 使用向量库 Chroma轻量够用 docker run -d --name chroma -p 8000:8000 -v chroma_data:/data chromadb/chroma逻辑说明第一步把容器运行时装好Ollama 以守护进程方式常驻-v做持久化避免模型重启丢失。第二步指定--gpus all把 GPU 直通给容器如果服务器没有 NVIDIA 驱动这一步会失败后续改跑 CPU 版本也能起但慢很多。第三步拉取模型后先跑一句测试确认模型能正常输出再进入下一步。第四步启动独立向量库为什么不用 FAISS因为客服场景需要持久化、并发读写和按租户过滤FAISS 是内存索引进程退出就没了生产环境不推荐。参数说明端口11434是 Ollama 默认 API 端口供 Dify 或自研代码调用8000是 Chroma 的 REST 端口。如果你内网已有镜像仓库可以把ollama/ollama和chromadb/chroma换成私有镜像地址符合离线部署要求。这里要特别提醒私有化部署不只是把服务跑起来还要规划模型文件的离线分发。我碰到过服务器完全没有外网权限的客户最后是用移动硬盘把 Ollama 模型文件大概 46GB拷进去再用ollama create注册到本地。所以拉模型时要保留好 model 文件路径别等断网才想起来。3. 让 LLM 能查企业资料基于 RAG 的入库与检索实现架构通了接下来是最容易出效果也最容易翻车的部分把企业文档变成可检索的片段并在用户提问时召回正确内容。RAG 知识库能不能真正解决问题七成功夫在索引阶段。3.1 文档解析与分块参数chunk_size 和 overlap 怎么定很多团队直接把 PDF 扔给向量库然后抱怨效果差——向量库不认识 PDF它只认识文本片段。所以第一步是解析文档把表格、页眉页脚、图片说明都抽出来。常见做法是用PyMuPDF加上rapidocr做 OCR处理扫描件和图片型 PDF。如果你的知识库里混着图片问答别指望直接把图片存成向量正确做法是 OCR 提取文字后把文字切片入库原图作为引用链接附在结果里。下面是一段我常用的解析与分块代码import fitz # PyMuPDF from langchain.text_splitter import RecursiveCharacterTextSplitter def load_pdf_chunks(path, chunk_size300, chunk_overlap40): doc fitz.open(path) text for page in doc: # 抓取正文跳过页眉页脚页号 blocks page.get_text(blocks) for b in blocks: text b[4] \n # 再按段落粒度切分保留自然边界 splitter RecursiveCharacterTextSplitter( chunk_sizechunk_size, chunk_overlapchunk_overlap, separators[\n\n, \n, 。, , , ], keep_separatorFalse, ) return splitter.split_text(text)逻辑说明get_text(blocks)返回的是带坐标的文字块筛选时我一般会过滤掉b[0]和b[1]接近页面顶底的小块这些是页眉页脚。分块器使用了递归分隔符优先按段落切段落太长再按句子切避免把一个完整制度条款硬切两半。参数说明chunk_size300指的是字符数不是 token。中文场景一个 token 大约 1.5 个字300 字对应约 200 token正好在 7B/14B 模型的上下文窗里留出余量。chunk_overlap40是相邻块之间重叠的前后文长度用来防止跨越切分边界的答案被截断。这里我刻意选了 40 而不是更大的数字因为客服问答大多是“找一段话里的结论”重叠太多会让向量索引更模糊。如果你做的是制度全文、需要跨段落综合的问答可以把 overlap 提到 80但检索耗时和噪音也会上升。记住切分参数要跟你手里的真实文档走最好的办法是抽 10 段典型文档肉眼检查切分结果。3.2 用开源 Embedding 模型做向量化代码与参数分块完成后要把每块文本转成向量。绝不能用在线 Embedding API否则私有化就是空谈。我生产环境常驻的是BAAI/bge-large-zh-v1.5它在中英文混合场景下召回稳定而且允许输入 512 token正好匹配我们的切分。也可以用M3E或text2vec-large-chinese但 bge 系列对后续 rerank 的兼容性更顺手。from sentence_transformers import SentenceTransformer import chromadb from chromadb.config import Settings # 离线加载 Embedding 模型 model SentenceTransformer(/data/models/bge-large-zh-v1.5, devicecuda) # 初始化持久化客户端 client chromadb.PersistentClient(path/data/chroma_data, settingsSettings(anonymized_telemetryFalse)) # 建 collection指定余弦距离 collection client.get_or_create_collection( nameenterprise_kb, metadata{hnsw:space: cosine} ) # 批量入库id 用文档名块号保证唯一 for idx, chunk in enumerate(chunks): emb model.encode(chunk, normalize_embeddingsTrue) collection.add( ids[fdoc1_chunk_{idx}], embeddings[emb.tolist()], documents[chunk], metadatas[{source: return_policy.docx, chunk_index: idx}] )逻辑说明PersistentClient会把向量持久化到磁盘服务重启不丢。hnsw:space用 cosine 是因为 bge 官方建议对向量做归一化后用内积或余弦余弦在语义相似度上更符合我们的直觉。normalize_embeddingsTrue会把向量长度归一为 1这样后续用点积当余弦算检索速度更快。参数说明模型路径/data/models/bge-large-zh-v1.5是离线拷贝后的目录在线环境可以直接传模型名让库自动下载但生产我从不这么做。chunk_index元数据很重要后续可以从向量库反查原文片段给客服回答附带“出处”。这里ids必须是唯一字符串建议格式是文档ID_块号不然重跑会覆盖。另外一个容易踩的坑是当知识库规模超过几十万块时model.encode逐条调用会非常慢做成批量model.encode(chunks, batch_size64)更合适也可以在入库时给集合配置hnsw:ef_construction等参数但默认值通常足够。3.3 召回与重排top_k、score 阈值和 rerank 的必要性入库只是开始。用户提问时检索层要先向量化问题再从库里找相似块。这块我见过太多系统直接query_embeddings然后取 top5结果召回一堆意义不明的片段。检索需要带条件过滤和重排。def retrieve(question, top_k8, threshold0.6): q_emb model.encode(question, normalize_embeddingsTrue) # 限定返回指定客户的资料范围防止串库 result collection.query( query_embeddings[q_emb.tolist()], n_resultstop_k, where{source: {$in: permitted_docs}}, include[documents, metadatas, distances] ) # 过滤低相似度结果 picks [] for doc, meta, dist in zip(result[documents][0], result[metadatas][0], result[distances][0]): if 1 - dist threshold: picks.append((round(1 - dist, 4), meta[source], doc)) # 按相似度降序 picks.sort(reverseTrue) return picks逻辑说明where{source: {$in: permitted_docs}}是按来源过滤这一步在生产系统中几乎必做——不同渠道的客服只能看到对应权限范围内的知识防止 A 部门的知识被 B 部门误召回也是私有化数据隔离的基本功。1 - dist是因为集合用的 cosine 距离距离越小相似度越高。参数说明top_k先取 8是为了给重排留出候选余量不要一上来就取 5。threshold0.6是一个起步值实际要根据你文档的相似度分布调整。如果很多问题明明该有答案却召回很少阈值要往下放如果召回一堆不相关内容就往上收。我见过最极端的场景同一批文档用不同的 Embedding 模型相似度分数差出 0.2——所以阈值必须绑定模型调换模型必须重新跑评估。关于重排当知识库文档量大、相似片段多时光靠向量相似度不够。我会再挂一个bge-reranker-large对 top_k 候选做精排把真正相关的那一两条提到最前。理由是向量检索擅长“找出语义相近”但相近不等于能回答问题。重排器会按“这段文字能否回答这个问题”再打一遍分。生产经验是不加重排答非所问率大概 8%加了 rerank能降到 2% 以内。代价是每次问答多 100300ms客服场景完全可接受。4. 用 Dify 搭智能客服问答流水线私有化部署的关键配置如果你不想从零写一套编排框架Dify 是目前私有化场景里最省力的选择。它把 RAG 知识库、Agent 流程、模型管理、日志审计集成在一个 web 应用里Docker Compose 一拉就能起天然支持 Ollama 这类本地模型。不少团队直接拿它做内外网隔离的智能客服后台。4.1 为什么选 Dify 而不是从零写编排自研编排意味着你要自己处理对话记忆、知识库片段注入、工具调用、多轮上下文截断这些工作量远超想象。Dify 的价值在于把这些能力预置好并且提供了可视化的工作流和“知识库流水线”你可以在界面上把“检索知识库”和“LLM”两个节点串起来。对内网部署来说它不强制依赖外部服务所有组件都能跑在自己的 Docker 网络里。我从三个角度选型维护性Dify 有 web 控制台非研发同事也能改 Prompt 和知识库客服主管自己就能调话术不必每次都找算法工程师。可控性它允许你指定“仅从知识库回答”限制模型胡编也能在回答末尾带上引用片段这个能力对客服质检太重要。兼容性Dify 支持自定义模型接入Ollama、vLLM 都可以通过 OpenAI 兼容接口挂进来不需要绑定某个云厂商。当然Dify 也不是银弹。如果你的流程非常特殊比如要实时查库存表并计算运费还是得在 Dify 外面套一层自己的服务把 Dify 当作“问答中间件”来用。4.2 在本地启动 Dify 并接入 Ollama 模型启动 Dify 的常见做法是从 GitHub 拉官方 compose 文件然后docker compose up -d。我不能替每个版本背参数细节但核心配置如下# 假设你已经把 dify 项目源码放在 /opt/dify cd /opt/dify/docker cp .env.example .env # 编辑 .env关键项如下 # EXPOSE_NGINX_PORT80 # OLLAMA_API_BASE_URLhttp://host.docker.internal:11434/v1 docker compose up -d逻辑说明.env里前面几项是端口和存储路径OLLAMA_API_BASE_URL让 Dify 容器能访问宿主机上的 Ollama 服务。因为 Dify 容器和 Ollama 容器是分开启动的不能直接用localhost要用host.docker.internal解析到宿主机。如果你把 Ollama 也放进同一个 compose 网络里直接把地址改成服务名http://ollama:11434也行。配置完成后进 Dify 后台的模型供应商页面选 OpenAI-API-compatible填模型名称qwen2.5:7b和 API Base URLhttp://host.docker.internal:11434/v1。注意 Ollama 的接口路径是/v1不要漏。这一步经常会遇到容器内外网络不通我的排查顺序是先docker exec dify-docker curl http://host.docker.internal:11434/api/tags看通不通不通就检查 Docker Desktop 或 Linux 的extra_hosts配置。这里有个很容易被忽略的点如果你在局域网多台机器上部署建议把 Ollama 监听地址改为0.0.0.0并在 Ollama 镜像启动时加--network host或映射端口。否则 Dify 只能在宿主机上访问 Ollama换台机器就废了。4.3 知识库与 Prompt 配置系统提示词和引用格式Dify 的知识库建好后重点是编排里的 Prompt。客服场景的 Prompt 核心约束是只依据给定上下文回答禁止杜撰不知道就说不知道。下面是我在 Dify 的 LLM 节点的系统提示词你是一个企业智能客服助手。你的回答必须严格基于context中给出的企业知识库片段。 规则 1. 如果context中有明确答案直接回答并引用来源名称。 2. 如果context中只有部分相关先说明你掌握的信息再引导用户联系人工。 3. 如果context中没有答案只能回答“我暂时没有找到相关内容已转接人工”禁止猜测。 4. 不要回答与客服无关的人身、政治、法律问题。 5. 如果用户问题涉及价格、库存、售后期限等精确字段且上下文中没有不得自行推算。 context {{context}} /context参数说明{{context}}是 Dify 知识检索节点传入的召回片段我一般让它传 6 条左右。Prompt 里第 1 条要求附来源这个来源对应我们在 Chroma 里存的source元数据第 3 条是防幻觉的核心能显著降低客服乱答的概率。注意不要在大模型 Prompt 里堆太长的“回答要求清单”规则超过 6 条模型就会开始漂。还有Dify 的上下文注入会把片段拼接得比较乱建议在知识检索节点后加一个代码节点做格式化把来源和正文按 markdown 引用的形式拼好再交给 LLM。另外一个参数是温度temperature客服问答我固定设 0.2最高不超过 0.3。温度太低会回答僵硬太高会自己发挥。这个参数值得你在测试集上对比 0.1、0.2、0.5 三档很多所谓的“乱答”问题温度从 0.8 降到 0.2 就能消掉一半。5. 私有化部署避坑指南数据安全、并发与模型幻觉的排查实录这部分是我最想写的。下面四个问题是我在多个客服项目中反复遇到的每个都对应具体的坑和解决路径。5.1 问题一知识库更新后回答还是旧内容现象管理员把最新的售后政策 PDF 上传到知识库并完成了索引但用户在客服窗口提问回复仍然是旧政策里的内容甚至引用出错的条款。原因常见的有三种。第一Dify 或自研代码在构建检索语句时没有过滤知识库版本新旧两份文档同时被召回模型选了旧片段。第二向量数据库更新后切分块的 ID 没有变化导致“更新”操作变成了追加旧块依然存在。第三缓存——很多会话框架会把上一轮回答缓存用户问相同问题时直接命中缓存。解决针对第一种我在入库时给元数据加version字段检索过滤条件固定取versionlatest。针对第二种重跑入库前先按source删除旧块再插入新块。针对第三种会话缓存键里加入知识库版本号版本更新后自动失效。另外建议在上传文档后跑一条特定问题做回归验证比如“最新保修期是多少”看回答里引用的源文件名称是否对得上。5.2 问题二召回结果全是无关片段相关文档排不到前面现象用户问“发票抬头怎么改”检索出来的 top 5 里头 4 条是“发票类型说明”“发票邮寄地址”真正讲“抬头修改”的那条排到了第 8模型没采到。原因问题里的“发票”和“抬头”两个实体在库中被拆到了不同切片又或者分块时把“抬头修改步骤”和前面的“发票类型定义”塞在了同一个块里导致向量被前文稀释。还有一种可能是 Embedding 模型对业务术语理解不足比如“抬票”这种内部行话。解决第一步加大top_k到 1012再靠 rerank 把正确答案顶上来。第二步调整分块策略把“步骤类”内容单独成一个块不要混在介绍里。第三步收集这类失败 case用它们微调 Embedding 模型成本太高更实际的做法是给知识库补充同义词条目比如把常见口语问题映射到标准文档段。我在项目里会维护一个“问题-标准片段ID”的映射表命中时直接绕过向量检索。这个表和 RAG 共存效果立竿见影。5.3 问题三内网部署后模型加载慢、GPU 显存不足现象私有化机房用的是两张 16G 的 T4部署 14B 模型后每次回答要等 58 秒显存占用经常打到临界值一到并发高峰期直接 OOM 重启。原因14B 模型在 fp16 下权重就要约 28G单张 16G 放不下需要多卡切分或量化。很多团队直接拉原版 fp16没有开 KV cache 量化也没限制最大并发导致显存吃紧。解决我一般先把模型量化到 int8 或 int4用Ollama里的q4_K_M量化版本显存占用降到 810G单卡即可跑 7B14B 用 int4 大概 9G勉强能上单卡 16G。然后在 Dify 或自研服务层面限制最大并发为 4超出排队避免显存尖峰。最后开 KV cache 量化Ollama 环境变量OLLAMA_KV_CACHE_TYPEq8_0能把长对话的显存再省一半。对话轮次也要限制最多保留最近 8 轮否则 KV cache 会无脑膨胀。5.4 问题四客服回复包含敏感信息或杜撰内容现象用户问“你们公司有多少员工”模型回答“有 5000 人”但公司从未公开过这个数字甚至在某些 prompt 注入攻击下让客服输出内部系统结构。原因这属于两个问题。杜撰是因为训练参数或 Prompt 没有严格限定“只来自知识库”敏感泄漏是因为知识库切分时把内部机密文档也索引了又没有在检索阶段做权限过滤。解决杜撰的解法是双保险——Prompt 里强制“无依据不许答”同时在生成后加一个校验节点用正则匹配“我暂时没有找到”等兜底话术如果模型输出了知识库片段里不存在的具体数字就用规则拦截重写。敏感泄漏的解法是文档分级入职手册、产品手册可以全量索引薪酬、财务明细必须在入库前剔除或者给 collection 加security_level元数据在检索条件里强制限定security_level 当前用户级别。如果你的客服系统有多个部门隔离这一步绝对不能省。另外时常有人问要不要给客服加“不要讨论政治”的拦截我的回答是在接入层加独立的关键词过滤服务别把这种逻辑交给大模型既不稳定也无法审计。6. 验证与复盘用 30 条客诉语料给问答系统打分系统上线前必须做一次可量化的验收不然你根本不知道是模型的问题、检索的问题还是知识库缺文档。我会用一个固定测试集加一个快速脚本半天就能出结论。测试集不是随便从网上找的而是从近三个月的真实客服会话里抽 30 条高频问题人工配好参考答案和对应文档来源。然后写脚本批量跑问答系统用两个指标评估答案是否包含正确答案要点人工看以及引用的来源是否正确。下边是我常用的评估逻辑import json from openai import OpenAI client OpenAI(base_urlhttp://localhost:11434/v1, api_keyollama) with open(test_cases.json, encodingutf-8) as f: cases json.load(f) for case in cases: resp client.chat.completions.create( modelqwen2.5:7b, messages[ {role: system, content: 你是一个评测员判断候选回答是否覆盖标准答案的要点只输出 PASS 或 FAIL。}, {role: user, content: f标准答案{case[gold]}\n候选回答{case[answer]}} ], temperature0 ) case[verdict] resp.choices[0].message.content说明这里用 LLM 当评测员省去人工逐条打分的体力活。temperature0保证评测稳定。我第一次跑这种脚本系统只及格了 16/30其中 9 条是“来源引用错误”导致的 fail说明问题出在召回排序不在文本理解。后来把 rerank 打开把top_k从 5 提到 10正确率升到 26/30。剩下 4 条是知识库本身没有答案只能走人工转接。这种评估每两周跑一次每次增加新客诉 case。长期下来你会得到一个非常清晰的基线哪些问题涨了哪些又跌了。我在新员工入职的客服团队里实践这套流程后才发现很多“幻觉”其实源于知识库陈旧。所以我的最后一个习惯是每次更新知识库必须重跑这 30 条基线不允许在没验证的情况下发版。希望帮到你哪怕只帮你避开一个显存坑这通折腾也算值了。本文还有配套的精品资源点击获取