mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
2564 words
7 minutes
商城 Agent 实战(四):用 LangChain4j、Ollama 和 Qdrant 接入持久化 RAG
2026-08-11
2026-09-28

“订单发货了吗”可以查询订单表,“签收后怎么退货”则需要查商城规则。两者都需要依据,但依据的形态不同:一个是持续变化的业务记录,一个是运营维护的政策文档。

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 接线测试。阅读和执行测试时,应区分它们证明的内容:

  1. 同步测试:重复同步是否跳过,文档更新如何清理,失败状态是否记录。
  2. 检索测试:用测试问题检查召回来源、排序、例外条件是否完整。
  3. 生成评测:真实模型是否遵守来源,是否添加检索结果里没有的规则。
  4. 恢复测试:重启 Qdrant、清空测试索引或中断同步后,是否能发现并修复缺口。

假模型按测试设定返回拒答,只能验证上下文拼接与预期路径,不能证明真实模型能抵抗任意不可信文档。

建议至少准备政策正例、相似但不同政策、资料不存在、文档过期和依赖故障五类问题,再调 maxResults、阈值和切分参数。记录模型标识、文档版本和配置,结果才可比较。

知识同步管理入口是 POST /admin/ai/knowledge/sync,属于后台管理能力,不应注册成前台自由调用的 Tool。本次文章重构未重新运行 Ollama、Qdrant 或真实模型;完整运行与发布验收需在测试环境执行。

Share

If this article helped you, please share it with others!

商城 Agent 实战(四):用 LangChain4j、Ollama 和 Qdrant 接入持久化 RAG
https://github.com/huanchenfeng/agentShop
Author
梦幻晨风
Published at
2026-08-11
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents