用户在商城里问“推荐一款手机”,普通聊天模型可以给出建议,但它不知道店里实际有哪些商品,也不知道用户是否已经下单。把模型接到 Spring Boot,只是建立了对话通道;接入业务查询、规则检索和受控操作,才逐步形成商城 Agent。
这篇先解释模型如何进入现有商城:模块放在哪里,配置怎样加载,请求经过哪些对象,以及怎样判断第一条链路已经接通。
项目:AgentShop,基于 macrozheng/mall 二次开发。本文按 2026-09-28 本地源码核对,区分“用于理解的最小片段”和“仓库当前完整实现”,不要求把后续功能删掉后再逐篇重建。
1. 从一个问题看完整分工
先用三种用户提问区分能力:
| 用户问题 | 答案从哪里来 |
|---|---|
| 手机参数怎么选? | 模型组织通用解释 |
| 这款手机还有货吗? | 商品 Service 查询 |
| 签收后怎么退货? | 商城规则与售后流程 |
第一种问题可以先用基础聊天验证接入。后两种必须依赖商城自己的数据,不能把模型训练时见过的内容当作本店事实。
七篇文章分别讨论以下主题,可按正在解决的问题阅读:
- 模型接入:Spring Boot 怎样调用模型。
- 商品 Tool:怎样查询真实商品。
- 订单查询:怎样限定当前会员的数据。
- 持久化 RAG:怎样检索商城规则。
- Redis Memory:怎样理解连续追问。
- 售后工作流:怎样确认并执行写操作。
- 观测、评测与工单:怎样发现和处理失败。
这些能力可以组合,但职责不同。例如 Memory 帮助理解“刚才那款”,不能证明“刚才查到的库存现在仍然有效”。
2. 模型连接放在 mall-ai,业务入口留在应用中
AgentShop 沿用 Maven 多模块结构。与本文相关的模块是:
mall-ai 模型配置、共享 AI 基础能力mall-portal 会员聊天入口、商品/订单/售后 Toolmall-admin 知识同步、评测、客服管理入口mall-common CommonResult 与通用异常mall-mbg 商城数据模型与 Mappermall-security 认证与权限基础设施共享的是模型连接方式,不应因为前后台都能调用模型,就共享同一个业务能力集合。
当前前台使用 PortalAiAssistantController 和 PortalAssistant。公共模块中的基础 MallAssistant 类仍可用来理解最初接入,但早期的公共 MallAssistantController 与 /ai/chat 路由已经移除。阅读当前仓库时,应从 POST /ai/portal/chat 进入。
把 Controller 放进两个应用都扫描的公共模块,会让两个应用同时暴露它。以后增加后台工具时,很容易把权限含义混在一起,因此业务入口应有明确归属。
3. 先对齐版本,再排查模型调用
本次核对的根 pom.xml 使用:
| 组件 | 仓库配置 |
|---|---|
| Java | 17 |
| Spring Boot | 3.5.14 |
| LangChain4j 核心 | 1.18.1 |
| Spring Boot Starter | 1.18.1-beta28 |
这是项目的依赖基线,不是所有读者都应立即升级到的版本。核心库与 Starter 的版本后缀可能不同,应以项目已经对齐的依赖组合为准。
根项目声明 mall-ai 模块并管理依赖版本;mall-portal、mall-admin 再依赖 mall-ai。用于模型连接的主要依赖是:
<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai-spring-boot-starter</artifactId></dependency>这里使用 OpenAI-compatible 客户端连接 DeepSeek,open-ai 是库与配置前缀,并不表示请求一定发给 OpenAI。请求目标由 base-url 决定。
从 AgentShop 根目录先编译相关模块:
mvn -pl mall-ai,mall-portal -am -DskipTests compile这一步验证 Java 与 Maven 依赖能否编译;它不会证明密钥有效、模型可用或数据库已经连接。
4. 配置只负责连接,不赋予商城能力
共享模型配置位于 mall-ai/src/main/resources/mall-ai-langchain4j.yml。以下是适合放进文章和环境模板的写法:
langchain4j: open-ai: chat-model: base-url: ${DEEPSEEK_BASE_URL:https://api.deepseek.com} api-key: ${DEEPSEEK_API_KEY} model-name: ${DEEPSEEK_MODEL_NAME} temperature: 0.2 timeout: 60s max-retries: 2 log-requests: false log-responses: false密钥与模型名由部署环境明确提供。文章不沿用本地开发配置中的密钥默认值,也不把某个模型别名写成永远有效的常量。
截至 2026-09-28,DeepSeek 官方更新日志推荐使用 deepseek-flash;旧 deepseek-v4-flash 名称暂时映射到新模型。复现项目时应记录实际模型标识,并重新验证工具调用行为,不能仅凭旧别名推断模型版本没有变化。DeepSeek 更新日志
应用通过配置导入加载共享资源:
spring: config: import: optional:classpath:mall-ai-langchain4j.ymloptional: 只表示导入资源可以缺失,不表示依赖 ChatModel 的 Bean 也可以缺失。排查“找不到 ChatModel”时,需要一起看资源是否打包、配置前缀、环境变量和自动配置条件。
单次模型超时与重试也不等于整次 Agent 请求的总预算。后续工具循环可能产生多次模型调用;请求层还需要自己的截止时间和容量控制。
5. 把模型调用收在一个清晰的服务边界
最小调用链只有四步:
HTTP 请求 → Java 服务 → ChatModel → 文本回答早期 MallAssistant 使用 chatModel.chat(SYSTEM_PROMPT + message)。这能发送文本,但拼接后的内容仍是一条用户消息,不是真正的 system/user 角色分离。
如果重新实现这个最小服务,可以明确构造消息。以下为教学改写片段,省略 Spring 注解与 import:
String chat(String message) { ChatResponse response = chatModel.chat( ChatRequest.builder() .messages(List.of( SystemMessage.from(""" 你是商城咨询助手,请用中文回答。 当前没有接入商品、库存和订单查询。 涉及实时数据时,请明确说明无法查询。 """), UserMessage.from(message))) .build());
return response.aiMessage().text();}ChatRequest、消息类型和 ChatResponse 均来自 LangChain4j。角色分离使消息结构更清晰,但系统提示仍不能代替工具权限和业务校验。
当前完整商城使用另一层抽象:定义 PortalAssistant 接口,由 AiServices.builder(...) 创建代理,把模型、Tool、RAG 和 Memory 组合起来。Controller 调用接口,代理负责与模型交互。它与 Spring 的业务 Service 是不同层次的对象。LangChain4j AI Services
6. 当前 HTTP 接口是什么样
聊天请求由 AiChatRequest 接收,消息要求非空且限制长度。长度限制保护入口资源,不保证模型输出正确,也不代替下游 Token 预算。
当前前台接口接收:
{ "conversationId": "shopping-demo", "message": "你好,你能帮我做什么?"}使用会员登录态调用 POST /ai/portal/chat,成功结果中的 data 已经是对象:
{ "code": 200, "message": "操作成功", "data": { "conversationId": "shopping-demo", "answer": "这里是助手回答。" }}answer 是示意文本,不能作为真实模型固定输出。前端需要读取 data.answer,不能继续按最早版本的 CommonResult<String> 解析。
在 PowerShell 中可以调用已启动的本地 Portal:
$chatBody = @{ conversationId = "shopping-demo" message = "你好,你能帮我做什么?"} | ConvertTo-Json
$chatArgs = @{ Method = "Post" Uri = "http://localhost:8085/ai/portal/chat" Headers = @{ Authorization = "Bearer $env:PORTAL_TOKEN" } ContentType = "application/json; charset=utf-8" Body = [Text.Encoding]::UTF8.GetBytes($chatBody)}Invoke-RestMethod @chatArgsPORTAL_TOKEN 是会员登录后取得的 Token,不能用管理员 Token 代替。当前 Controller 还会访问 Redis 会话服务,完整应用也依赖现有商城设施;这个接口不是只填模型密钥就能独立启动的 Demo。
启动多模块工程时,可以先安装依赖,再只对可执行模块启动:
mvn -pl mall-portal -am -DskipTests installmvn -f mall-portal/pom.xml spring-boot:run避免把 spring-boot:run 对整个依赖 Reactor 执行,导致它先尝试启动没有主类的公共模块。运行前按项目说明准备商城数据库、Redis 及启用的其他依赖。
7. 用分层验证定位失败
第一层验证 HTTP 协议:空消息是否被拦截,返回结构是否正确,未登录请求是否进入业务调用。这里可以 Mock Assistant,无需消耗模型额度。
第二层验证消息构造:用可控 ChatModel 检查系统消息、用户消息和模型返回值如何转换。这能验证程序协议,不能证明真实模型一定遵循所有要求。
第三层才是少量真实模型验证:使用测试账号和测试数据,确认模型可访问、响应能解析,并记录实际模型名。
遇到失败时,沿调用链定位:
| 现象 | 先看哪一层 |
|---|---|
| 找不到 ChatModel | 依赖、配置导入与 Bean |
| 商城接口拒绝登录 | Portal 的认证链 |
| 供应商返回鉴权错误 | 模型密钥与供应商响应 |
| 回答没有真实商品 | 商品 Tool 是否执行 |
| 前端展示为空 | 是否仍读取旧 data 格式 |
一段流畅回答只能证明模型返回了文本。要证明它查过商城,应继续观察商品 Tool 的执行轨迹,而不是只问模型“你是否查询了数据库”。
本文完成的是内容与源码核对,没有重新执行 AgentShop 的真实 DeepSeek 调用。文中的命令是复现步骤,不能当作本次联调成功记录。
If this article helped you, please share it with others!
Some information may be outdated






