企业官网建设流程全解析

"RAG知识库小程序"这个词条，你去搜索引擎里翻一翻，能找出几十篇教程，但真正跑通的人没想象中那么多，跑通了之后还觉得自己被坑了的，倒是占了相当比例。原因特别简单：市面上大量的"知识库小程序"，只是给大模型套了一层API壳，用户问什么就直接丢给ChatGPT或者DeepSeek，把返回结果原封不动地端回去。真正的检索增强生成（RAG），是用户提问之后，先从他自己上传的文档里把相关片段捞出来，再让大模型基于这些片段组织答案，这里面涉及切片、向量化、索引、相似度检索，一步都不能少。

这篇文章我会把两件事拆开讲透。第一，一个能用的RAG知识库小程序到底该怎么搭，从微信小程序前端到后端服务，到向量库选型，到嵌入模型、检索策略和引用标注，给出可以直接抄作业的方案；第二，怎么辨别你手里或者别人手里的"RAG"是真是假，包括从代码层面、行为层面和网络抓包层面去验证，避免花了时间还被套壳方案忽悠。另外，实操中高频踩坑的API 401、上下文超长、知识不更新、排队等问题，也会一并整理成排查记录。

1. 先搞清楚：什么才算"真RAG"，什么只是"API套壳"

1.1 真RAG的核心链路：索引-检索-生成

RAG全称Retrieval-Augmented Generation，翻译过来是检索增强生成。它之所以叫"增强"，是因为它改变了传统LLM回答问题的信息来源。传统LLM只能依靠训练时见过的参数，知识截止日期是固定的，你不能指望它知道昨天刚更新的产品手册写了什么；而RAG给模型提供了一份"我允许你临时查阅的资料"，让它先查资料再回答。

一条完整的RAG链路可以拆成两条流水线。离线部分叫索引管道：文档上传后要做格式解析、清洗、切片，然后把每个切片喂给嵌入模型转成向量，写入向量数据库。在线部分叫查询管道：用户提问后，先把问题也转成向量，从向量库里召回最相关的Top-K片段，拼进Prompt里，再交给大模型生成答案。最后这一步很重要，大模型看到的不是整个知识库，而是经过检索筛出来的几段高相关文本，这样既能控制token开销，也能让答案出处可追溯。

判断真假RAG的关键，就是看这两条流水线是否真的存在。索引管道有没有？检索动作有没有发生在生成之前？如果没有，那它就是套壳。

1.2 三类常见的"伪RAG"套路

先说说我实际见到的套壳方案，基本能归成三类。

第一类叫"全文塞入型"。这类方案不建索引，也不做检索，用户上传的文档被当成一个超长的system prompt塞进上下文。技术上最省事，但效果最差，文档一多就爆context长度上限，你会在日志里看到类似"this model's maximum context length is 1048576 tokens"的报错。本质上就是用LLM的上下文窗口硬扛，跟RAG没有半毛钱关系。

第二类叫"关键词过滤型"。这类方案用Elasticsearch或者数据库的LIKE查询，把用户问题里的关键词拿去文档里做字面匹配，匹配到的段落拼进Prompt。它的检索逻辑是词汇级别的，不是语义级别的，换个说法就查不到，准确率很感人。在演示环境里放两句简单问答还能糊弄过去，真正塞进去几十上百页文档就原形毕露。

第三类最隐蔽，叫"演示死数据型"。这类方案把某个固定领域的内容硬编码成知识卡片存在JSON或者配置文件里，用户提问时走一层if-else匹配或者模版匹配，看似有"命中"，实则没有任何动态摄取能力。你换一批文档进去，它马上就失效了。这三种套壳的共同点都是：没有向量化、没有语义检索、没有动态索引构建。

1.3 伪RAG为什么会翻车

有人可能觉得，"反正都是让大模型回答，为什么非要做检索呢？"我给你讲个实测场景。我在本地跑过一个由多种病案和检验指标组成的医疗知识库，测试问题里有一句"病人肌酐偏高到300，需要考虑什么方向"。套壳方案会把整份文档全文塞进去，大模型确实能回答，但回答会把文档里所有跟肌酐无关的内容也考虑进来，因为上下文里除了问题本身没有任何"定向信息"。而真RAG方案会优先召回包含"肌酐""肾功能""急性肾损伤"这几个语义中心的段落，Prompt里只包含这些相关片段，模型的注意力就不会被无关内容拉走，答案质量和稳定性明显不同。

翻车更明显的是知识更新场景。伪RAG要更新知识，得改代码、改配置、重新部署；真RAG只需要把新文档传到知识库管道里重新切片索引，产品层面一个按钮就能解决。这也是鉴别RAG真伪很重要的产品化指标。

2. 知识库小程序从0到1：架构选型与核心组件拆解

2.1 小程序前端：更克制的人机交互设计

微信小程序前端的核心不是炫酷的UI，而是"移动端场景下的人机交互要克制"。用户在小程序里提问，输入框、对话列表、上传入口、知识库文档管理这四个界面足够覆盖绝大多数需求。

这里有几个容易被忽略的细节。第一，小程序顶部导航栏高度不是固定值，在iPhone X以上机型、Android各种刘海屏之间差异很大，用wx.getMenuButtonBoundingClientRect()加wx.getSystemInfoSync()动态计算胶囊位置，比写死padding更稳妥。第二，聊天列表的"加载更多"不要每次拉全部历史消息，采用分页接口，配合onPullDownRefresh做下拉分页，体验会比一次性渲染好得多。第三，动态设置标题用wx.setNavigationBarTitle，这个API在知识库场景里挺常用，比如用户从"农业知识库"点进一个具体分类，标题就从总名称切换成具体分类名，让用户清楚自己所在的位置。

前端还有一个容易踩坑的点：不要在小程序里直接存API Key。很多人为了演示方便，把模型API Key写在前端代码里，这不只是安全问题，还直接暴露了你用的是哪家大模型的接口，别人抓包一眼就能看穿这就是套壳。正确的信息流应该是小程序只跟自己的后端服务通信，后端再去调用LLM和向量库。

2.2 后端服务与API网关：为什么不能直接暴露LLM Key

我会建议你用Python FastAPI或者Node.js写一个轻量后端，提供一个/api/chat接口，小程序端把用户问题POST上来，后端内部完成检索和生成，再把结果返回。这个中间层至少能帮你做三件事。

第一，隐藏所有鉴权信息。你调用的嵌入模型API Key、LLM API Key、向量库连接串，全部只存在于后端环境变量里，小程序端拿到的只有一个你自己的会话Token。第二，做流量控制和限流。不用后端直接暴露API，意味着你可以在入口层加一层简单限流，比如单用户每分钟最多请求10次，防止有人拿你的后端当免费代理刷量。第三，拦截和改写。你可以在后端对用户输入做简单的敏感词过滤、长度限制、降级策略，也可以把多条历史消息拼进Prompt，控制上下文结构。

后端不止是转发，它还是RAG管道的执行者。检索逻辑写在API接口的调用链里，这就是与伪RAG最本质的区别。

2.3 向量库选型：从小规模到生产级怎么选

向量数据库是RAG的底座，选型不能盲目追新。我按规模分三档。

最轻量的是Chromadb，pip装完就能跑，数据存在本地目录，开发调试最方便，单机几千条文档完全够用。小步快跑的验证项目可以直接用。假如你的知识库是面向几百人的内部工具，Qdrant或者Milvus的Docker单机模式是不错的选择，它们提供HTTP接口，跟FastAPI集成比较顺手，还支持过滤字段，可以在检索时按文档类型做前置过滤。再往上是生产级分布式方案，Milvus集群或者云上的向量服务，支持高并发和水平扩容，一般小程序日活几千以上才需要考虑。

在选数据库时有一个核心指标千万别忽略：检索延迟。用户在小程序里发一个问题，你总不希望转菊花转三秒吧。我在本地用chromadb做过测试，在1万条向量规模下，单次相似度检索大概在几十毫秒以内，完全够用；到了几十万条向量，内存占用和扫描耗时开始明显上升，这时候才需要考虑更专业的引擎。起步阶段用chromadb，别过度设计。

3. 实操过程：一个最小可用的RAG知识库小程序是怎么搭出来的

3.1 文档接入与切片：这些坑我全踩过

知识库第一步是文档接入。很多人以为上传PDF、Word、TXT就能自动建库，其实解析环节的坑挺多的。PDF如果是扫描件，没有OCR就什么都提不出来；Word里嵌的表格，纯文本抽取会打乱行列结构；Markdown文件的代码块会被错误地切成不完整片段。

我把切片逻辑拆成三步。第一步做格式解析，用pypdf抽取文本，用python-docx处理Word，遇到扫描版PDF就接入OCR服务，比如MinerU或者PaddleOCR。第二步做清洗，去掉页眉页脚、重复的换行符、多余的空格。第三步才是切片，切片策略按"先分段、再补重叠"来处理。比如RecursiveCharacterTextSplitter按段落切，chunk_size=500，chunk_overlap=100，这样能保证相邻切片在语义上保持衔接，不会在切点位置丢失上下文。

切片大小是个需要专门调的参数。我在农业知识库里测试过多个尺寸，大切片如800字能保留更多上下文，但检索精度会下降；小切片如200字检索更精确，但拼进Prompt后可能缺乏上下文连贯性。500字上下加100字重叠，是一开始比较稳妥的规模。

3.2 嵌入模型与检索策略：Top-K、相似度阈值、混合检索

切片之后要向量化，这里嵌入模型的选择直接影响检索质量。国内能用且效果不错的方案挺多，比如BGE系列、智谱的embedding-3、OpenAI的text-embedding-3-small。注意一个很容易踩的坑：嵌入模型必须和检索向量库的维度匹配，而且换嵌入模型一般意味着需要重新构建整个索引，所以上线之前一定要把嵌入模型定下来，别中途换。

检索策略不要只做"一次性Top-K"。我给你一个可落地的检索函数思路。第一步，对用户问题进行向量化。第二步，用相似度检索召回Top-20候选片段，这里chromadb的query接口可以直接返回距离。第三步，在代码里做二次过滤，保留相似度超过阈值比如0.7的结果，把低于阈值的直接丢掉，避免模型胡编。第四步，如果知识库里同一个文档有多个片段被召回，可以做去重和合并。这样最终进入Prompt的片段数量虽然少了，但质量明显更高，同时token消耗也被控制住了。

假如知识库内容有明确的分类字段，比如农业知识库里水稻、小麦、病害防治三个分类，可以先用元数据过滤缩小范围，再做向量检索，这种组合方式命中率会比纯向量检索高不少，我实测大概能提升8%到15%的Hit Rate。

3.3 生成与引用：怎么让回答可追溯

配置好检索之后，生成端也有讲究。大模型生成的Prompt，我建议采用固定模板加少量示例的结构。

system: 你是一个知识库问答助手。请基于以下检索得到的资料片段回答用户问题。 如果资料中没有相关信息，请直接说明"知识库中未找到相关内容"，不要编造。 引用格式：回答末尾标注资料编号，如[1]、[2]。 资料片段： [1] 来源：水稻常见病害防治手册.pdf（第32页） | 内容：稻瘟病在水稻分蘖期多发... [2] 来源：常见农药使用规范.docx（第5页） | 内容：三环唑可用于防治稻瘟病... 用户问题：水稻得了稻瘟病用什么药？

**这个模板的几个设计意图值得展开说说。**标注资料编号不是形式主义，它让大模型生成的答案天然带上出处，你在后端解析出[1]编号，就能在小程序前端把对应的引用变成可点击的角标。用户点一下就能看到原始片段，这恰恰是知识库类产品最让人信服的特性，也是识别真RAG的产品面表现。其次，"找不到就直说"这句话必须写进system prompt，否则大模型会强行编造，这是RAG应用最容易翻车的点之一。

生成端的另一个细节是上下文拼接策略。不要把知识库里所有召回的片段全部塞进去，实测最多拼4到6个切片就够了，超过之后答案质量不升反降。同时保留用户最近的几轮对话历史，这样处理连续追问时会顺畅很多。

3.4 部署与微信小程序联调：从本地到线上

后端写好后，本地Test没问题，就该考虑部署了。小项目我推荐直接上云服务器加Docker Compose，把FastAPI后端、向量库、嵌入模型服务三个容器编排起来。前端联调有三个地方需要检查。

第一是本地的HTTPS配置。微信开发者工具默认要求请求域名是HTTPS且已备案，本地调试时可以在工具详情里勾选"不校验合法域名"，但上线时必须在微信公众平台配置request合法域名。第二是POST请求的Content-Type，微信小程序的wx.request默认发送的是application/json，后端CORS中间件要放行对应来源。第三是响应体积，知识库流水线如果返回了很长一段文本，注意分包加载和数据截断，别让一个页面的数据量太大。

如果前端用了uniapp开发，打包微信小程序时还要注意一个坑：部分uniapp内置组件在微信端的样式表现不一致，比如scroll-view的滚动边界问题，实测下来建议在真机上专项测一遍再发布。

4. 一眼识破"API套壳伪RAG"：甄别清单与检验方法

4.1 代码层面：看有没有向量库、有没有索引

拿到一个号称是RAG知识库的项目，第一步打开它的代码目录，按这张清单逐一排查。

• 有没有独立的索引管道代码？比如ingest、index、build_vector_db这类目录或文件。
• 有没有引用向量数据库？看依赖清单里有没有chromadb、qdrant、milvus、faiss这样的库。
• 有没有嵌入模型的调用？比如embedding、encode、text-embedding字段。
• Prompt构建时有没有加入检索结果？还是只拼了对话历史。

如果上面四项里三项都没有，那基本可以断定是套壳。反过来，仅仅有向量库依赖也不等同于真RAG，因为存在一种更隐蔽的做法：代码里装了向量库，但实际请求链路完全没有走检索，只调用了LLM接口，向量库是个摆设。这时候就要看下一步的行为测试。

4.2 行为层面：问几个刁钻问题，马上现原形

行为测试是最直观的验证手段。我通常会用三个问题组合去测一个RAG系统。

第一个是"换词测试"。知识库文档里写的是"高血压患者应限制钠盐摄入"，你提问时换成"盐吃多了对血压高的人有什么影响"。真RAG依靠语义向量相似度，能检索到相关片段；伪RAG的关键词匹配在这一步很可能就抓瞎了。第二个是"跨文档测试"。知识库里有A文档介绍产品功能，B文档介绍价格，提问"这个产品的功能对得起它的价格吗"，真RAG会把两个文档里的片段都召回再让模型综合，伪RAG往往只能答出其中一面。第三个是"负样本测试"。问一个跟知识库完全无关的问题，比如知识库是农业的，你却问"怎么修汽车轮胎"。真RAG因为检索不到相关片段、相似度低于阈值，会诚实地说没找到；伪RAG为了让对话不冷场，通常会强行启动通用大模型能力扯一通。

用户看不到代码，但产品里可以用这三个问题自查。如果答案是"啥都能答、答得还很泛"，那大概率不是真RAG，而是套壳大模型。

4.3 网络层面：抓包看请求到底发给谁

到了网络层，就轮到抓包工具上场了。我平时用Charles比较多，它在Windows和macOS上都很顺手，下面是针对微信小程序抓包的操作思路。

先在电脑上安装Charles，开启SSL Proxying，然后在菜单里配置Proxy -> SSL Proxying Settings，把需要抓包的域名加进去。手机和电脑连同一个Wi-Fi，手机Wi-Fi代理设为电脑的IP加Charles默认端口8888。在微信开发者工具里预览小程序时，如果你勾选了"不校验合法域名"，请求能发出去，但Charles里照样能看到请求记录。

抓到请求之后重点看三处。第一，请求的URL是/api/chat这样的自有后端接口，还是直接指向了某个大模型服务商的域名。第二，POST请求体的结构，如果里面有messages数组但没有documents、没有retrieved_chunks这类字段，那就没走检索。第三，响应体是不是直接透传大模型的流式输出，中间有没有插入检索片段和引用标记。除了Charles，也可以用小程序的"真机调试"配合微信开发者工具的Network面板，真机面板在安卓上经常抽风，Charles反而是最稳妥的方案。

我还用抓包验证过一个号称"本地知识库"的产品：它的请求直接打到了某个商业API网关，文档上传后根本没有生成任何向量索引文件。网络层面这个证据链一旦锁定，套壳就实锤了，不需要再争什么。

5. 常见问题排查实录：API错误、上下文超限、知识更新踩坑

5.1 API Key 401报错：比我预想中多的翻车现场

运行RAG服务时，日志里高频出现unexpected status 401 unauthorized: incorrect api key provided，这个报错信息很明确：API Key不对。但"不对"背后的原因通常有三层。

第一层是环境变量没传对。后端进程启动时读取.env文件失败，或者Key里带了引号、空格，都会被当成无效Key。排查方式是在后端代码里打一行调试日志，把环境变量名的存在性打出来，但不要打全量Key，防泄露。第二层是Key本身失效。很多模型的Key是充值余额制，余额用完或过期后接口就会返回401，这时候去服务商控制台看余额和Key状态就能确认。第三层是Key和模型不匹配，比如某个Key只开通了Chat模型权限，你却拿它去调嵌入模型接口，也会报鉴权失败。

排查顺序我建议是：先确认环境变量是否加载成功，再去控制台测试Key在官方接口里直接调用是否正常，最后看代码路径里有没有误把其他服务的BaseUrl拼到请求上。一米一个环节，坏不了多长时间就能定位。

5.2 Context Length超限：为什么RAG反而能省token

我在排查日志时还经常看到这么一条：api error: 400 this model's maximum context length is 1048576 tokens。这个问题通常发生在伪RAG方案里，因为伪RAG会把整份知识库文档全部塞进Prompt。尤其是当你上传的文档很大，单次请求可能就超过模型的上下文上限，接口直接拒绝。

真RAG几乎不会遇到这个上限问题，这是它的设计优势：检索只取Top-K，上下文可控。如果你的真RAG也报超限，多半是切片大小设得太大，或者把多个切片合并成了一大段。解决办法就是把chunk_size调小，从500降到300，并减少同时拼接的切片数量。还有一个优化手段，是给每次对话算一算Prompt实际token数，对接OpenAI兼容接口时可以用tiktoken离线估算，超限前主动降级，避免用户看到报错。

5.3 知识库排队、检索不到：从Dify到自建的排错路径

如果你用Dify这类二次开发平台搭知识库，会遇到"知识库排队中"这样的任务状态卡死。常见原因有三个：一是嵌入模型服务把队列占满，Dify的并发设置默认并不高；二是向量库索引构建期间任务被重复提交；三是后台worker数量配置不足。你可以把Dify的Worker并发数调大，并检查向量库索引，必要时手动清掉为空的索引重建。

自建RAG遇到"搜不到答案"的问题，排查方向和Dify不太一样，建议按这个顺序来。先检查文档解析是否成功，打开切片预览确认没有乱码；再检查嵌入模型调用是否返回了正确的向量维度；然后查向量库检索日志，确认相似度得分有没有高于阈值；最后看Prompt拼装时检索片段有没有真的被塞进去。我碰到过一次"搜不到"的案例，最后发现是切片内容被清洗逻辑误删了，一行正则表达式把整篇内容过滤掉了，这种低级但隐蔽的错误，排查起来最磨人。

5.4 关于"知识库能存图片吗"这类延伸问题

很多人问RAG知识库能不能存图片，这是个很好的问题。标准做法是把图片存到对象存储里，元数据写入向量库，图片本身不进向量空间。用户上传一张含文字的产品说明书截图，你要么走OCR把文字抽出来再向量化，要么把图片的URL存进文档表的附字段，检索时把URL一并返回给前端展示。直接把图片二进制嵌入向量库是不现实的，那既浪费存储也检索不准。

这是我在实际建库中绕了很久才想明白的：RAG的检索对象是文本语义，图片应该作为"文档的补充元数据"存在，检索到了相关文本，再去取对应图片的URL给用户看。这样产品上表现为"知识库能展示图片"，但底层逻辑依然是文本驱动，检索效果也是稳定的。

写在最后：我的实际体会

如果你问我搭知识库小程序到底难不难，我的真实答案是：把链路跑通不难，难的是想清楚"你做的到底是不是RAG"。

我见过不少团队花了两星期把前端聊天界面做得花里胡哨，却在检索端草草了事，最后上线被用户骂"这不就是个聊天机器人嘛"。反过来，那些把切片、检索、引用做扎实的项目，即使UI粗糙一点，用户用起来也会觉得"这个机器人真的懂我的资料"。RAG的本质不在于你调了谁家的模型，而在于你构建了一条让模型只能在限定资料范围内作答的流水线。

如果你只是想快速做个Demo验证，那Dify、FastGPT这些平台确实能帮你省掉一半的工程时间；但如果你的目标是做一个真正可运营的知识库产品，我建议你还是自己搭一次RAG链路，哪怕是一次小规模的。只有亲手经历过切片、向量化、检索、引用、调Threshold这些步骤，你才能准确判断什么方案适合你的场景，也才不会被市面上那些伪RAG的演示糊弄住。这套经验，比任何现成框架都值钱。