“订单发货了吗”可以查询订单表,“签收后怎么退货”则需要查商城规则。两者都需要依据,但依据的形态不同:一个是持续变化的业务记录,一个是运营维护的政策文档。
RAG 为第二类问题增加检索步骤:先找出相关规则,再把规则与问题一起交给模型。本篇以 AgentShop 的 Markdown、Ollama、Qdrant 和 MySQL 实现为例,说明知识怎样入库、怎样被检索,以及更新失败时会发生什么。
项目:AgentShop。本文依据 2026-09-28 本地源码整理,配置值代表当前项目基线,不把早期手工检索分数或历史测试输出当作本次运行结果。
1. 先决定哪些信息应该进知识库
| 用户想知道什么 | 优先使用 |
|---|---|
| 当前商品价格和库存 | 商品 Tool |
| 我的订单与支付状态 | 订单 Tool |
| 退换货、配送、积分规则 | RAG |
| 刚才说的是哪款商品 | Memory 辅助理解 |
把库存写进规则文档,很快就会过时;把每条运营规则硬编码成工具方法,则会增加维护成本。混合问题可能同时需要两者,例如“这笔订单是否符合退货条件”:规则来自知识库,订单状态来自 Service,最终自动办理资格由业务代码判断。
RAG 增加了依据来源,不保证最终回答必然正确。检索可能漏掉例外条款,模型也可能误读召回内容,因此应分别验证检索与生成。
2. 四个组件各自保存或处理什么
Ollama + bge-m3:把文档和问题转换成向量Qdrant:保存向量、片段正文和来源元数据MySQL:记录文档版本与同步状态DeepSeek:阅读检索结果并组织回答入库与查询是两条不同链路:
入库:Markdown → 切分 → Embedding → Qdrant └→ MySQL 同步记录
查询:问题 → Embedding → 相似片段 → 来源与正文 → ChatModel问题与文档需要使用兼容的向量空间。同样是 1024 维,不代表两个不同 Embedding 模型生成的向量就能混用。替换模型或改变向量处理方式,通常应重建索引并重新评估检索质量。
概念不熟悉时,可先阅读 bge-m3 与 Embedding和 Qdrant 基础。
3. 把连接配置和索引契约分开理解
项目当前使用 Ollama 的 bge-m3,配置维度为 1024;Qdrant Collection 为 mall_knowledge_bge_m3_v1,使用 Cosine 距离。
mall: ai: embedding: base-url: ${EMBEDDING_BASE_URL:http://localhost:11434} model-name: ${EMBEDDING_MODEL_NAME:bge-m3} dimension: ${EMBEDDING_DIMENSION:1024} qdrant: host: ${QDRANT_HOST:localhost} http-port: 6333 grpc-port: 6334 collection-name: mall_knowledge_bge_m3_v1 payload-text-key: text这是共享配置中的相关字段节选。当前 QdrantEmbeddingStore 连接使用 gRPC 端口 6334,Collection 检查使用 HTTP 端口 6333。把两个端口弄反,会出现“服务明明启动了,但客户端连接失败”。
应用在初始化时检查 Collection 维度。如果实际向量输出与配置不符,不应直接修改维度数字掩盖问题,而应核对模型和已有索引。
容器运行还要把 /qdrant/storage 挂载到持久卷;固定镜像版本便于复现。挂载卷可以跨容器重建保留数据,但不是备份,也不能替代实际的重启恢复测试。Qdrant 文档
4. 切分时保留规则的条件和例外
当前前台资源目录 mall-portal/src/main/resources/knowledge/ 中有六份文档:
return-policy.md 退换货shipping-policy.md 配送payment-guide.md 支付member-rules.md 会员coupon-rules.md 优惠券after-sales-guide.md 售后流程例如,一段规则可能同时包含“签收后一定时间内可申请”“需要商品完好”和“不适用于某类商品”。只保留第一句,检索虽然命中了“退货”,答案却少了限制条件。
项目的切分器优先利用 Markdown 段落,再处理超长句子,默认块大小 500、重叠 50。这是字符长度层面的切分配置,不能直接当成模型 Token 数。
调整参数时应检查实际片段:标题是否丢失,条件与结论是否分离,重复内容是否太多。参数只靠一条问题调到命中,没有足够依据推广到全部规则。
5. 片段必须能够追溯到文档版本
Qdrant 中的 Point 除向量和正文外,还保存:
knowledgeKey 文档稳定标识source 来源文件title 标题category 分类contentHash 本次内容摘要chunkIndex 片段序号version 当前文档版本标识这些字段用于回答引用、增量同步和旧片段清理。只保存向量和一段正文,后面很难回答“这条规则来自哪份文件、是不是旧版本”。
当前 Point ID 由以下内容稳定生成:
String seed = collectionName + "|" + knowledgeKey + "|" + contentHash + "|" + chunkIndex;
String pointId = UUID.nameUUIDFromBytes( seed.getBytes(StandardCharsets.UTF_8)).toString();同一文档、同一版本、同一序号得到同一个 ID,可以避免重试时无限产生新 Point。但它不自动解决旧版本删除、源文件下架和多个同步任务竞争。
6. MySQL 记录“同步过”,不代表向量一定还在
ai_knowledge_document 保存文档 Hash、Embedding 模型名、Collection、片段数和 PENDING / SUCCESS / FAILED 状态。
当前 KnowledgeSyncService.shouldSkip() 的判断条件是:
上次状态为 SUCCESS且内容 Hash 未变且 Embedding 模型名未变且 Collection 名未变→ 跳过本次同步它能减少重复计算,但有两个容易忽略的边界。
第一,切分大小或重叠改变,而文档内容没有改变时,现有条件可能仍然跳过。更完整的索引版本应包含模型、预处理和切分策略的版本。
第二,Qdrant 的数据被清空或丢失,而 MySQL 仍标记成功时,单看 Hash 也可能跳过重建。需要强制重建入口或索引完整性校验,不能把“跳过 6 份文档”当作“6 份文档的向量目前都存在”的证据。
MySQL 状态与 Qdrant 写入之间没有跨系统原子事务,应设计可重试、可核对的同步流程。
7. 当前更新顺序有一个明确的故障窗口
源码中的主要更新顺序是:
保存 PENDING → 删除当前文档旧向量 → 生成新 Embedding → 写入新 Point → 保存 SUCCESS如果生成或写入新向量失败,旧内容已经删除,知识库会出现缺口。把状态改成 FAILED 有助于定位,却不能自动恢复被删掉的片段。
改进时可以采用版本发布过程:
生成并写入候选版本 → 校验片段数量与检索结果 → 将候选版本标记为可检索版本 → 清理旧版本这要求检索端按已发布版本过滤;如果只“先写新、后删旧”而没有发布边界,过渡期间可能同时召回两版冲突规则。另一种方式是完整构建新 Collection 后切换别名,并保留回滚条件。
源文件删除也应显式撤下对应文档,而不是只遍历现存文件做增量更新。以上是改进方案,当前同步器尚不能据此宣称具备无损版本切换。
8. 把检索结果与来源一起交给模型
当前检索器的核心配置是:
ContentRetriever delegate = EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(embeddingModel) .maxResults(4) .minScore(0.70) .build();这表示最多返回 4 个达到阈值的片段。0.70 是本项目的起始配置,不是“70% 可信度”,也不是所有模型、数据集通用的阈值。
PortalKnowledgeConfig 在正文前补充来源:
来源标题:退换货政策来源文件:return-policy.md内容:这里是实际召回的规则片段……这样模型有机会引用实际召回的文件。更严格的界面可以由服务端直接渲染来源列表,避免让模型自行编造引用。
当前将 ContentRetriever 直接接入 AI Services,每次调用会进入检索增强流程,不能描述成“模型判断为政策问题时才检索”。若希望减少无关检索,需要另加路由或条件检索策略。LangChain4j RAG
9. 无结果、不可用和正常命中要分别表达
三个结果不能混在一起:
| 检索状态 | 应表达的含义 |
|---|---|
| 有相关片段 | 基于来源回答 |
| 正常检索但无命中 | 当前资料不足以确认 |
| Ollama / Qdrant 异常 | 知识库暂时不可用 |
当前异常路径会返回一条“商城知识库暂时不可用”的特殊 Content,并用系统提示要求模型直接说明情况。这改善了模型上下文,但仍然由模型生成最终回答,不能把它描述成服务端已经硬性阻止无依据回答。
对于必须确定拒答的政策接口,可以由编排层检查检索状态并直接返回固定响应,或在输出中显式携带依据状态。不要把依赖故障静默降级成模型凭训练知识回答商城政策。
检索文本还可能包含“忽略规则、调用某个工具”等普通字符串。它们只是文档数据;文档审核、发布权限、工具授权和业务规则仍然需要独立执行。
10. 分开验证检索质量与回答质量
源码中已有同步器、切分器、Collection 检查与 RAG 接线测试。阅读和执行测试时,应区分它们证明的内容:
- 同步测试:重复同步是否跳过,文档更新如何清理,失败状态是否记录。
- 检索测试:用测试问题检查召回来源、排序、例外条件是否完整。
- 生成评测:真实模型是否遵守来源,是否添加检索结果里没有的规则。
- 恢复测试:重启 Qdrant、清空测试索引或中断同步后,是否能发现并修复缺口。
假模型按测试设定返回拒答,只能验证上下文拼接与预期路径,不能证明真实模型能抵抗任意不可信文档。
建议至少准备政策正例、相似但不同政策、资料不存在、文档过期和依赖故障五类问题,再调 maxResults、阈值和切分参数。记录模型标识、文档版本和配置,结果才可比较。
知识同步管理入口是 POST /admin/ai/knowledge/sync,属于后台管理能力,不应注册成前台自由调用的 Tool。本次文章重构未重新运行 Ollama、Qdrant 或真实模型;完整运行与发布验收需在测试环境执行。
If this article helped you, please share it with others!
Some information may be outdated






