简介这是一套面向有私有化需求的企业技术团队的智能客服问答系统源码基于企业私有知识库与大语言模型解决通用LLM无法直接回答内部数据、数据安全与合规等核心问题。压缩包共1302个文件大小约34.01MB包含Vue、JS、TS前端代码Go后端服务SQL初始化脚本JSON配置以及Dockerfile等部署文件覆盖管理后台、移动端与接入SDK结构清晰便于本地部署和二次开发。目前已有596人浏览/学习。系统基于ChatWiki框架内置20多种主流模型的一键接入能力支持自动分段、QA分段、手动输入和CSV导入等知识构建方式并自动完成文本预处理与向量化发布端可选用H5链接、嵌入网站或桌面客户端能较快落地为企业专属问答应用。1. 企业私有知识库LLM智能客服为什么是“反直觉”的AI落地做企业智能客服最怕的不是用户问倒你而是模型一本正经地编制度。你问它“报销上限是多少”它给你一个流畅的数字结果公司制度里根本没这条——这是大模型落地的一个典型翻车现场。标题里的“企业私有知识库”就是冲着这个问题去的把员工手册、产品文档、历史工单预先切好、向量化、存进内网再让LLM只从这些资料里找答案。整条链路从模型推理到知识库存储都在企业内网完成数据不出域这就是“支持私有化部署”的核心价值。适合正在做企业AI客服、内部办公助手或知识库平台的工程师也适合给业务部门做选型评估的技术负责人。2. 把大模型从“懂王”变成“话务员”RAG架构与知识库服务的基本盘2.1 为什么智能客服优先选“检索增强”而不是“微调”智能客服这个场景有一个明显特征知识是快速变化的而回答必须忠于给定事实。今天产品手册改一版明天报销制度调一次要是靠微调给模型灌知识就得每改一版训一次成本高还容易把旧知识和新知识混在一起。所以业界的主流做法是RAGRetrieval-Augmented Generation检索增强生成它的思路很简单模型不负责记忆知识只负责“照着资料讲话”。每次收到问题先到向量库里检索最相关的几个文本片段再把这些片段拼进提示词交给大模型生成回答。RAG和微调不是二选一的关系但客服场景里RAG通常赢在四个维度。数据更新上RAG换一批文档重建索引就能生效微调要重新训练事实准确性上RAG可以追溯答案来自哪一段原文微调则是把知识揉进参数里出了问题很难定位部署成本上RAG只需要一个推理服务和向量库微调需要准备训练集、GPU资源和调参时间隐私边界上RAG可以把全部数据留在内网微调的数据处理环节更多。下面这张表是我在方案评审时常用来跟业务方对齐的对比维度RAG 检索增强微调 Fine-tuning知识更新更新索引即可分钟级生效重新训练小时到天级事实准确性答案可溯源到原文片段依赖模型参数记忆易幻觉数据合规文档、索引、推理均可内网闭环训练数据需离开业务系统硬件要求一个GPU推理服务即可起步训练需要更多显存和算力适用场景知识库问答、客服、制度查询风格迁移、意图分类、格式控制还要说清楚一个常被混淆的点知识库不只是“文本段落”。企业里其实同时存在三类知识结构知识库FAQ条目、SQL表、Excel参数表适合用精确匹配或数据库查询语义知识库产品手册、技术文档这种非结构化文本适合用向量检索图谱知识库KG适合做多跳关系查询比如“这个配件的上游供应商是谁”。智能客服系统里最常见的形态是“结构知识库做兜底、RAG做扩展”用户问“退货政策”先查FAQ表命中就直接返回标准答案没命中再去向量库捞文档。别指望一个方案吃掉所有知识形态这个认知能帮你少踩很多坑。2.2 一条问答流拆成五段解析、切片、向量化、召回、生成把RAG客服拆开看一条完整问答流水线是五个环节文档解析、切片、向量化、召回、生成。文档解析负责把PDF、Word、网页、公众号文章这类非结构化内容抽成纯文本或Markdown。很多团队在这里栽跟头因为PDF解析出来的文字经常乱序、丢表格直接拿去切片会带出一堆噪声。我一般会把文档先统一转成Markdown格式表格尽量转成Markdown表格而不是图片这样后续无论用正则还是语义切分都更可控。图片和扫描件必须走OCR否则图里的信息在向量检索阶段相当于不存在——向量库里可以存图片关联的文本描述但检索依旧是“文字进、文字出”。切片是决定检索质量的一个关键步骤。切片太粗一个chunk里混了好几个主题检索回来一堆无关内容切片太细同一段操作说明被切成碎片语义不完整。中文文档我建议按段落标题和句号、问号、分号这些语义边界来切而不是无脑按字符数硬切。切完之后做向量化用同一个embedding模型把每个chunk转成向量存进向量数据库用户提问时用同一个模型转成向量去搜这是很多人忽略的铁律——任何一边换了模型检索效果立刻崩。召回阶段用向量做近似最近邻搜索取回top_k个候选片段。生成阶段才是大模型登场把“系统指令 检索到的片段 用户问题”拼成一个提示词让模型生成回答。这一步里有个很关键的设计模型不是“被问了一个问题然后凭记忆回答”而是“被给了一叠资料然后做阅读理解”。提示词里必须明确告诉模型“只能根据给定资料回答资料里没有就直接说不知道”。否则模型还是会忍不住动用自己预训练里的知识来补全幻觉就从这里冒出来。很多团队把注意力全放在调模型上却忽略了第五步的提示词约束这是导致客服答案“流畅但不可信”的主要原因。2.3 私有化部署的三个组件选型模型推理、向量库、知识库流水线“支持私有化部署”这句话写起来容易落到架构上是四个组件全部内网化LLM推理服务、embedding模型、向量数据库、知识库管理后台。LLM推理服务常见做法是选一个中文能力强的开源基座模型用Ollama或vLLM这类推理框架跑在内网GPU服务器上对外暴露一个兼容HTTP的调用接口。选模型时不要只盯着参数规模和榜单分数要拿你自己知识库里的真实问题去试同一个问题问十个模型看哪个“照章办事”的能力最强。embedding模型我会优先选中文语料训练过的开源模型这类模型的语义相似度判断更贴合中文企业文档的表达习惯。向量数据库选型主要看数据规模和并发量。小团队几十万条文本以内Chroma这类轻量级方案最省心一个目录就能持久化部署简单排查也方便规模上千万条、并发要求高Milvus这类分布式向量库更合适但要接受更高的运维成本如果公司已经有Elasticsearch也可以直接用ES的向量检索能力让文本搜索和向量搜索共用一个集群。下面这张表是我给团队做技术选型时常用的参考组件常见方案适合场景注意点LLM推理Ollama、vLLM、Xinference内网GPU服务器部署开源模型显存决定并发7B量化模型适合起步Embedding模型开源中文向量模型中文文档向量化查询和文档必须用同一模型向量库Chroma、Milvus、ES按规模和运维能力选小规模用轻量库大规模用分布式知识库流水线Dify、RagFlow或自建Python服务非技术运营维护 vs 研发可控性低代码平台快自建更灵活知识库流水线是很多人忽略的一个组件。Dify、RagFlow这类开源低代码平台把文档解析、切片、索引、API发布做成了可视化界面运营同学自己就能更新知识库不需要每次都找研发。如果团队有开发能力或者业务对回答格式有很强的定制要求自建Python服务也完全可以只要把文档上传、切片入库、索引重建这几个能力做成后台任务就行。我的建议是团队小于五个人直接上开源流水线平台团队有维护能力再考虑自建否则知识库维护会成为整个系统里最脆弱的一环。3. 从零跑通最小闭环知识库问答链路搭建与接口封装3.1 装依赖、起服务、拉一个适合中文的开源模型先搭一个能跑通的最小环境。到这一步不需要想太复杂目标只有一个让一条问题从API进去经过检索和生成再带着答案和引用来源出来。我习惯先用Python虚拟环境把依赖隔离好避免把系统环境搞乱。下面这套组合是本地私有化部署里最常见的一套FastAPI做接口服务Chroma做向量库sentence-transformers做向量化本机用Ollama起一个开源模型当LLM推理服务。# 创建独立环境避免污染系统Python python3 -m venv .venv source .venv/bin/activate # 基础依赖接口服务、向量库、向量化模型 pip install fastapi uvicorn chromadb sentence-transformers # 用Ollama拉取一个中文能力稳定的开源基座模型 ollama pull qwen2.5:7b-instruct这里每个依赖都有明确分工FastAPI负责把问答能力封装成HTTP接口Chroma负责把文本向量持久化到本地目录sentence-transformers负责把中文文本转成向量Ollama负责在本地跑大模型推理、对外暴露HTTP调用。拉模型这一步需要一点耐心模型文件不小但它是“私有化部署”的关键一步——拉下来之后所有推理都在本机发生不再依赖任何外部API。拉起之后先在终端里确认模型服务可用再写业务代码不然排错时你会分不清是模型问题还是代码问题。# 验证本机推理服务是否正常 curl http://localhost:11434/api/generate \ -H Content-Type: application/json \ -d {model:qwen2.5:7b-instruct,prompt:你好请简短回复,stream:false}这条curl能返回内容说明LLM推理服务已经就绪。注意这个服务默认监听11434端口后面我们的问答API会直接复用它。这里有个参数容易踩坑stream要设为false让接口一次性返回完整结果方便调试实际生产环境如果要做打字机效果再改成true走流式。3.2 文档切片与向量化chunk_size、overlap 和“图片怎么处理”接下来把知识库文档变成可检索的向量。核心操作是三步读入文档、切分成chunk、向量化后写入向量库。我选Markdown格式作为中间格式因为企业内部文档无论是PDF还是公众号网页最终都能转成Markdown或纯文本接下来处理逻辑就完全统一了。切分这一步用递归字符切分器它比固定长度切分更聪明会优先按段落、句号这些自然边界断句。from langchain_text_splitters import RecursiveCharacterTextSplitter from sentence_transformers import SentenceTransformer # 1. 加载文档为纯文本示例运营提供的产品手册 with open(product_manual.md, r, encodingutf-8) as f: raw_text f.read() # 2. 按语义边界切片中文场景推荐 300~500 字符 splitter RecursiveCharacterTextSplitter( chunk_size400, chunk_overlap80, separators[\n\n, \n, 。, , , , , , ], ) chunks splitter.split_text(raw_text) # 3. 用同一个embedding模型做向量化保证查询和文档在同一向量空间 model SentenceTransformer(BAAI/bge-large-zh-v1.5, devicecuda) vectors model.encode(chunks, normalize_embeddingsTrue, batch_size32)两个参数值得单独解释。chunk_size400表示每个切片段落最多约400个字符中文场景下这个值既能保留一个完整语义单元又不至于让无关内容混进来chunk_overlap80表示相邻两个切片有80个字符的重叠目的是避免句子刚好被切断在边界处。如果文档里大量是短句的操作步骤chunk_size可以降到300如果是政策制度这类长段落可以调到600。向量化时normalize_embeddingsTrue会把向量归一化这样后面算余弦相似度就等价于点积分数更容易解释。这一步完成后向量还只存在内存里需要入库才能实现持久化和检索。import chromadb # 持久化到本地目录这就是最简的私有化知识库存储 client chromadb.PersistentClient(path./kb_store) collection client.get_or_create_collection( nameproduct_manual, metadata{hnsw:space: cosine} ) collection.add( ids[fchunk_{i} for i in range(len(chunks))], embeddingsvectors.tolist(), documentschunks, )这段代码把向量和原始文本一起存进了本地目录kb_store。为什么要把原始文本也存进去因为检索返回的是向量对应的文本片段后续要拼进提示词、要展示给用户做引用溯源都离不开原文。metadata里指定hnsw:space为cosine意味着建索引时用余弦相似度作为距离度量这和我们对向量做了归一化是对应的。到这里一个完全不出内网的知识库就算建立完成了。3.3 封装问答API召回 prompt拼接 流式返回引用知识库建好了下一步是把问答逻辑封装成一个HTTP接口。这个接口内部做三件事用用户问题去向量库召回最相关的chunk把chunk拼成一段带约束的提示词交给本地大模型生成答案。注意这里不能直接把整个知识库塞给模型每次只取top 5左右的chunk这是控制成本和准确率的关键。from fastapi import FastAPI import requests app FastAPI() def retrieve(query: str, top_k: int 5): 召回问题向量化后在向量库中找最相似的文本片段 qv model.encode([query], normalize_embeddingsTrue) return collection.query(query_embeddingsqv.tolist(), n_resultstop_k) def build_prompt(query: str, docs: list[str]) - str: 拼提示词把资料和问题组合成一段带约束的指令 context \n\n.join(docs) return ( 你是一位企业智能客服。请只根据下面提供的资料回答问题 如果资料中没有答案请直接说“资料中未找到相关内容”不要编造。\n\n f【资料】\n{context}\n\n【问题】\n{query} ) app.post(/chat) def chat(body: dict): query body[question] hits retrieve(query) prompt build_prompt(query, hits[documents][0]) answer requests.post( http://localhost:11434/api/generate, json{ model: qwen2.5:7b-instruct, prompt: prompt, stream: False, temperature: 0.2, } ).json()[response] return {answer: answer, sources: hits[documents][0]}这段代码是最小的可运行闭环。retrieve函数里用同一个embedding模型处理用户问题保证问题向量和文档向量在同一空间可比collection.query返回的documents里是命中的原始文本直接作为答案的依据。build_prompt里那句“只根据资料回答不要编造”不是可有可无的客套话它是抑制幻觉最有效的一道闸门。temperature设成0.2是让模型输出更保守、更贴近原文而不是自由发挥。# 用curl直接测一下这个问答接口 curl -X POST http://127.0.0.1:8000/chat \ -H Content-Type: application/json \ -d {question:差旅报销上限是多少}返回结果里的sources字段值得好好利用。把它原样传给前端用户就能看到“答案来自哪份文档的哪一段”这就是引用溯源是知识库客服和企业内部可信赖程度的分水岭。接入微信、千牛这类渠道时原理也是一样的渠道方把用户消息通过Webhook转发到这个/chat接口再把返回的answer按渠道格式回传核心机制没有变化。4. 把答准率从“听天由命”调到“可控”必调参数与两种实用策略4.1 四个必调参数top_k、score阈值、chunk_size与temperature跑通最小闭环之后真正的调优工作才开始。这个阶段你会明显感受到RAG系统是个“黑匣子”里的复杂联动系统改一个检索参数可能影响生成质量改一个模型参数又会暴露检索的短板。我调过上百个问答case之后得出的结论是优先调四个参数top_k、score阈值、chunk_size和temperature。参数建议范围对结果的影响调参方向top_k310默认5太漏答案太多混入噪声FAQ短条目设3长文档设5~8score阈值0.30.7低于阈值应拒答防止模型硬编按真实问题分数分布设定chunk_size300~800字符决定一个切片里语义是否完整操作步骤设300制度文档设600temperature00.5控制模型创造性客服一律0.1~0.3闲聊可0.5四个参数里最容易忽略的是score阈值。向量检索的相似度分数不是一个绝对数值不同embedding模型打分的分布差异很大所以我一般会先用二三十个真实用户问题跑一遍把“命中的相似度”和“没命中的相似度”打印出来看分布。正常情况两者之间会有一个明显的分界带取中间值作为阈值。低于阈值的检索结果应该宁可答“未找到”也不要硬答这是把幻觉率压到最低的一个关键手段。top_k和score阈值通常是配合使用的top_k取5但第五个分数掉得厉害实际只取前3个如果全部低于阈值直接走“资料未找到”的兜底话术。chunk_size的调整有一个容易被忽视的联动chunk切得越大每个chunk包含的语义越杂单个chunk的向量就越“中庸”召回回来的片段相关性自然下降chunk切得越小召回越精准但容易把一条完整操作说明切成两半生成阶段会丢信息。我的经验是以400字符为中心向300或600两个方向试哪个方案在你自己的测试集上分数高就用哪个不要照搬别人的默认值。temperature的影响最直观但要注意它不能弥补检索的缺失——检索回来的段落压根不含答案temperature设多低模型都会胡说所以调参顺序永远应该是先调检索再调生成。4.2 混合检索与查询改写FAQ精确匹配和关键词漏召回怎么补纯向量检索有一个经典短板用户在问题里用了一个词文档里用的是它的同义词或缩写向量模型可能召不回来。比如用户问“报销上限”文档里一直写“费用报销标准上限”有时候向量模型能兜住有时候就漏。业内通用做法是混合检索一路走向量召回另一路走BM25这类关键词召回最后用RRF把两路结果融合。RRF算法的好处是不需要把两路分数归一化只看排名实现起来很干净。def rrf_merge(vec_rank: dict, bm25_rank: dict, k60): RRF融合把向量召回和关键词召回的排名合并成最终排序 scores {} for doc_id in set(vec_rank) | set(bm25_rank): scores[doc_id] 0 if doc_id in vec_rank: scores[doc_id] 1 / (k vec_rank[doc_id]) if doc_id in bm25_rank: scores[doc_id] 1 / (k bm25_rank[doc_id]) return sorted(scores.items(), keylambda x: x[1], reverseTrue)这段代码里vec_rank和bm25_rank分别是两路检索对每个doc_id的排名doc_id可以就是chunk的id。RRF给每路结果算一个基于排名的分数排名越靠前贡献越大然后把两路加和。k60是经验值控制排名权重下降的速率一般60左右效果稳定。混合检索适合“文档里有大量专业名词、缩写、编号”的场景能明显减少召回漏掉的情况。还有一个在真实客服系统里更有性价比的补法结构知识库精确匹配兜底。把高频FAQ整理成一张表问题、标准答案、关键词三列用数据库查询或Elasticsearch做精确匹配命中就直接返回标准答案不再走向量检索。这套“先精确匹配后向量召回”的两级路由能解决80%“用户想问的就是那条FAQ”的场景而且响应速度极快。知识库分类上这就是结构化知识库和RAG知识库的典型协同方式FAQ和参数表走结构化查询产品文档和操作手册走向量库KG图谱只有在需要多跳关联查询时才引入。4.3 多轮会话与引用溯源让客服“记得上文”和“拿证据说话”单轮问答跑通后真实客服会话几乎都是多轮的。用户先问“退货怎么处理”再问“那运费呢”这里的“那运费呢”单独拎出来去检索结果一定很散。多轮会话的常见做法是接口层接收一个history参数把最近几轮对话的问答内容拼进提示词让模型理解“那运费呢”指的是“退货那件事的运费”。但检索时有一个容易踩的坑不要用整段历史去做向量检索而是应该用“当前问题 最近一轮用户问题改写后的query”去检索否则历史里的噪声会把向量检索带偏。app.post(/chat) def chat(body: dict): history body.get(history, []) # 格式[{role: user/assistant, content: ...}] query body[question] # 检索只用当前问题历史对话只用来帮助模型理解上下文 hits retrieve(query) prompt build_prompt(query, hits[documents][0], historyhistory[-4:]) ...history[-4:]表示只保留最近4条消息避免提示词被历史撑爆也防止太早的对话干扰当前意图。注意检索函数里用的还是query本身这是有意为之的权衡query改写做得好能提升召回做不好反而引入歧义对于第一版系统先把历史交给生成阶段处理检索阶段保持简单后续再迭代查询改写模块。引用溯源方面可以在build_prompt里加一句“回答每个要点后标注来源编号如[1]”然后让生成结果里的编号与返回的sources列表一一对应。前端拿到sources后点击编号就能查看原文段落这在企业内部推广时说服力非常强。5. 私有知识库客服落地避坑五条一线踩坑记录5.1 答案很流畅但全是从模型“脑子”里编的现象用户问“年假能攒到第二年吗”客服答了一大段逻辑严密的政策说明细看发现知识库文档里根本没有这一条。原因模型在生成阶段没有受到足够强的约束或者检索阶段分数虽然低但阈值没挡住模型就开始动用预训练知识补全。解决双层防线。第一层在build_prompt里把约束话术写死“如果资料中没有答案请回答‘资料中未找到相关内容’。”第二层加score阈值门槛所有召回片段分数低于阈值的直接拒答。我见过太多团队只加第一层不加第二层因为模型“忍不住”想回答所以两层都上才稳。5.2 私有化换了模型后效果断崖式下降现象本机用云端API测试时效果很好换成私有化部署的开源模型后答非所问、格式全乱。原因不同基座模型的指令遵循能力和中文理解能力差异很大云端API背后是很强的商用模型本地开源模型如果选小了或者prompt写法不兼容效果立刻现原形。解决换模型后不要只做“能通”验证要拿同一套测试集跑一遍再上。优先选中文语料强的7B级以上模型prompt写法也要为本地模型适配有些模型对“请只根据资料回答”这种指令理解不到位需要改成更直白的“你没有其他知识来源”这类表达。这一步没有捷径只能用一个标准评估集反复验。5.3 文档明明更新了机器人还在答旧内容现象运营把新产品手册传上去了客服系统回答的还是老产品的参数。原因知识库后台有“上传文件”和“重建索引”两个动作运营通常只完成了第一个。很多低代码平台里上传新文件并不自动触发旧文件的向量删除和索引重建。解决在知识库管理后台明确区分“全量重建”和“增量更新”。每次更新文档后对已变更文件做内容hash比对hash变了就重新切片入库、删除旧chunk如果系统支持定时每晚执行一次全量重建兜底确保新文档一定生效。5.4 下班高峰一并发服务卡到被客服投诉现象白天几个人试用没问题晚上业务高峰期涌入几十个并发接口响应从2秒变成30秒有的直接超时。原因embedding模型和LLM推理都是计算密集操作直接部署在API服务进程里时每个请求都占CPU和GPU又没有队列和并发控制资源一挤就崩。解决把LLM推理单独拆成服务用vLLM或Xinference这类带连续批处理的推理引擎跑吞吐量远高于每次请求单独加载模型的做法API层加线程池和超时控制向量库连接用连接池复用embedding模型如果用的是sentence-transformers要预加载到显存并加锁避免重复加载模型。5.5 办公网上“答非所问”本机演示却全对现象同一份代码开发者的笔记本上跑得好好的部署到办公网服务器后各种奇葩回答甚至直接报错。原因办公网环境通常有访问控制、DNS重定向和网关鉴权模型服务的内部调用地址一旦被改写或者Python依赖版本和服务端不一致就会出这种“环境性翻车”。解决部署时不要手工装依赖直接用Docker镜像固定Python版本和依赖版本把模型服务、embedding服务、向量库、API服务拆成四个独立探活点启动后用curl逐一验证连通性所有关键链路打日志把检索到的chunk和最终prompt打印出来出问题一眼就能看到是哪一段断了。6. 用一套验证集给机器人打分答准率、命中率与AB实验给自己搭一个“考卷”是RAG客服从demo走向生产最值得做的一件事。我现在的习惯是从真实客服会话里抽出一百条问题每条标注三个字段——标准答案、答案所依据的知识库文档片段、以及这条问题是否该拒答。这套数据就是黄金评估集以后每次改prompt、换模型、调参数先在这套集上跑一遍再决定要不要上生产。评估时看三个核心指标答准率人工判断回答内容与标准答案是否一致召回命中率返回的sources里是否包含了标注的依据片段拒答准确率对该拒答的问题是否真的拒答了没有胡编。三条指标合格线我一般定在答准率90%以上、命中率85%以上、拒答准确率95%以上否则不进生产。# 批量评估脚本的最小形态 for case in test_set: result requests.post( http://127.0.0.1:8000/chat, json{question: case[question]} ).json() hit any(case[reference] in src for src in result[sources]) answer_ok judge(case[answer], result[answer]) # 人工或LLM打分 reject_ok result[answer].startswith(资料中未找到) print(case[question], hit, answer_ok, reject_ok)这套东西最有价值的地方是它能把很多“玄学”争论变成数据对比。我上过一回当凭感觉换了一个排行榜更高的embedding模型自认为效果更好结果黄金集上答准率掉了六个点从此所有改动都先过考卷再上线。这种评估机制也天然支持AB实验——把旧参数和新参数各跑一遍测试集对比同一套指标谁上去用谁的。如果你也打算把这类智能客服系统接进生产环境我建议在建完知识库之后立刻做这套考卷它会成为你整个系统里最大的一颗后悔药。希望帮到你。本文还有配套的精品资源点击获取