企业官网建设流程全解析

1. 电商导购为什么要用 Multi-Agent 而不是单模型硬扛

电商导购这个场景，单模型硬扛的问题在真实项目里暴露得特别快。用户一句“想给上大学的妹妹挑台轻薄本，预算五千左右，最好能带去图书馆”，背后其实混了三个意图：品类识别（笔记本）、参数约束（轻薄、续航、预算）、场景偏好（学生、便携）。你把这些全塞进一个 Prompt，模型要么顾此失彼，要么在追问环节反复问已经说过的信息，体验直接崩。

Multi-Agent 的思路是把这团乱麻拆开。Router Agent 只干一件事：判断用户这句话该交给哪个专项 Agent。手机 Agent、笔记本 Agent、家电 Agent 各自维护自己的追问逻辑和商品知识库。知识库 Agent 负责 RAG 检索，把实时库存和参数拉进上下文。这样每个 Agent 的 Prompt 都能写得很窄，窄就意味着稳定。

但拆开之后立刻冒出一个工程问题：多个 Agent 各自调用大模型，API 通道怎么统一？如果每个 Agent 各配一套 Key、各写一个 Base URL，配置散落在四五个地方，改一次环境要翻遍整个工程。更麻烦的是，百炼工作流本身也要调模型，Spring AI Alibaba 的 ChatClient 也要调模型，两边如果走不同通道，日志对不上，排查问题像盲人摸象。

我试过的做法是：把所有模型的出口收敛到一个统一的 Base URL 上，Spring AI Alibaba 这边通过application.yml配置，百炼工作流那边通过环境变量注入，两边指向同一个网关。这样 Multi-Agent 编排里不管多少个 Agent 在跑，底层通道只有一条，出问题只看一个地方。

这篇就按这个思路走：先讲清楚 Spring AI Alibaba 接入百炼工作流的配置怎么落，再给出 Base URL 改到 TaoToken 的完整可复制片段，最后用一个导购对话请求验证多 Agent 路由是否正常返回商品推荐。适合正在做电商导购、智能客服，或者任何需要 Multi-Agent 编排的 Java 后端同学。

核心检索词先摆出来：Spring AI Alibaba 接入百炼工作流、Multi-Agent 电商智能导购、Base URL 统一配置。这三个词贯穿全文，你照着配就能跑。

2. TaoToken 前置：把模型通道统一到 Base URL

在动手改配置之前，得先想明白一件事：为什么要在 Spring AI Alibaba 和百炼工作流之间加一层统一通道。百炼工作流是阿里云侧的编排引擎，它自己会调通义千问系列模型；Spring AI Alibaba 是应用侧的框架，它通过 ChatClient 调模型。如果两边都直连各自的默认端点，你会遇到两个问题。

第一，Key 管理分散。百炼工作流用一套凭证，Spring AI Alibaba 用另一套，Multi-Agent 里每个 Agent 如果还各自 new 一个 ChatClient，Key 就散得更开。第二，切换模型或做灰度时，你得同时改多个地方，漏一个就出现“部分 Agent 走新通道、部分走旧通道”的诡异现象，日志里表现为同一轮对话里模型返回风格不一致。

统一到 TaoToken 的 Base URL 之后，Spring AI Alibaba 侧只需要在application.yml里写一个base-url，百炼工作流侧通过环境变量把模型端点指过来。所有 Agent 共享同一个出口，Key 也只用管一份。这不是为了省事，是为了让 Multi-Agent 的调用链可观测——你打开日志，所有模型请求都带着同一个来源标识，路由到哪个 Agent、用了哪个模型、耗时多少，一目了然。

具体要准备的东西不多：一个 TaoToken 的 API Key，一个 Base URL。Base URL 用https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 Spring AI Alibaba 的base-url值。API Key 去控制台生成，地址是 https://taotoken.net/console/api-keys ，生成后复制保存，后面配置里要用。

模型 ID 这块要留意。Spring AI Alibaba 的model字段填的是模型标识，比如qwen-plus、qwen-max这类。你在 TaoToken 的模型对话页面可以确认当前可用的模型 ID，地址是 https://taotoken.net/models ，页面上会列出模型名称和对应的调用标识。Multi-Agent 场景下，Router Agent 可以用轻量模型做意图分类，专项导购 Agent 用能力更强的模型生成推荐话术，这样成本和效果能平衡。

有一点必须说清楚：TaoToken 在这里的角色是统一的模型调用通道，不是替代百炼工作流。百炼工作流该编排还是编排，该做 RAG 还是做 RAG，只是它调模型的那一段走统一出口。Spring AI Alibaba 该写 Agent 逻辑还是写，只是 ChatClient 的 Base URL 指向统一通道。两者是配合关系，不是替代关系。

配置前建议先确认网络能正常访问https://taotoken.net/api，用 curl 测一下连通性。如果公司内网有出口限制，提前找运维开白名单，别等到跑起来才发现连不上。这一步花五分钟，能省后面半小时的排查。

3. 可复制配置：application.yml 与百炼工作流对接

这一节是全文最干的部分，直接给可复制的配置片段。先看 Spring AI Alibaba 侧的application.yml，这是 Multi-Agent 所有 Agent 共享的基础配置。

spring: ai: alibaba: ai: # 统一模型通道 Base URL，所有 Agent 共用 base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: qwen-plus temperature: 0.7 max-tokens: 2048 # 百炼工作流对接配置 workflow: enabled: true endpoint: ${BAILIAN_WORKFLOW_ENDPOINT} app-id: ${BAILIAN_APP_ID}

这里有几个点要展开。base-url写死为https://taotoken.net/api，不要在后面加/v1或其他路径，Spring AI Alibaba 内部会拼接具体端点。api-key用环境变量注入，别硬编码在 yml 里，尤其是要提交到 Git 的工程。model字段填qwen-plus作为默认模型，Router Agent 如果要用更轻的模型，可以在代码里单独覆盖。

百炼工作流侧的对接，通过workflow.endpoint和app-id指定。工作流本身在百炼控制台编排，Spring AI Alibaba 这边只负责触发和接收结果。工作流内部调模型的那一段，需要在百炼控制台的环境变量里把模型端点指向同一个 Base URL，这样两边通道才真正统一。

接下来是 Multi-Agent 的 Java 配置。Router Agent 负责意图路由，专项 Agent 按品类划分。下面是一个可运行的配置骨架：

@Configuration public class AgentConfig { @Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder .defaultSystem("你是电商导购助手，根据用户意图路由到对应品类。") .build(); } @Bean public RouterAgent routerAgent(ChatClient chatClient, MobileAgent mobileAgent, LaptopAgent laptopAgent) { return new RouterAgent(chatClient) .addRule("手机", mobileAgent) .addRule("笔记本", laptopAgent) .addRule("电脑", laptopAgent); } @Bean public LaptopAgent laptopAgent(ChatClient chatClient) { return new LaptopAgent(chatClient, "你是笔记本导购专家，主动追问屏幕尺寸、预算、续航需求。"); } }

这段代码的关键在于所有 Agent 共享同一个ChatClient，而ChatClient的 Base URL 来自application.yml里的统一配置。这样 Router Agent 做意图分类、Laptop Agent 生成推荐话术，底层走的是同一条通道。如果你要给某个 Agent 单独指定模型，可以在该 Agent 内部用chatClient.mutate().defaultOptions(...)覆盖，但 Base URL 不变。

百炼工作流的编排配置，在控制台里用 YAML 描述步骤依赖。下面是一个导购场景的工作流片段：

steps: - name: demand_analysis agent: router_agent inputs: - user_query - name: product_recommend agent: ${output.demand_analysis.agent} depends_on: - demand_analysis inputs: - user_query - demand_analysis.result

这个工作流先跑demand_analysis做意图识别，拿到路由结果后，动态选择对应的专项 Agent 执行product_recommend。${output.demand_analysis.agent}是百炼工作流的变量引用语法，表示用上一步的输出决定下一步用哪个 Agent。这样 Multi-Agent 的编排逻辑就落在工作流层，Spring AI Alibaba 侧只提供 Agent 实现。

配置写完，启动应用前记得设置环境变量：

export TAOTOKEN_API_KEY="你的Key" export BAILIAN_WORKFLOW_ENDPOINT="你的工作流端点" export BAILIAN_APP_ID="你的应用ID"

环境变量设好再启动 Spring Boot 应用，否则api-key注入为空，第一次请求就会报 401。这个坑很常见，尤其是本地开发时忘了 export。

4. 验证请求：一次导购对话确认多 Agent 路由

配置写完不能只看启动日志，得发一个真实请求，确认 Multi-Agent 路由确实按预期工作。下面用一个 curl 请求模拟用户咨询，观察返回结果里是否包含商品推荐，以及路由是否命中笔记本 Agent。

curl -X POST http://localhost:8080/api/guide/chat \ -H "Content-Type: application/json" \ -d '{ "userId": "u10086", "message": "想给上大学的妹妹挑台轻薄本，预算五千左右，最好能带去图书馆" }'

这个请求打到你的 Spring Boot 应用，应用内部会先触发百炼工作流的demand_analysis步骤，Router Agent 分析出意图是“笔记本”，然后路由到LaptopAgent。LaptopAgent结合知识库检索，生成追问或推荐。

预期返回结构大概是这样：

{ "code": 0, "data": { "agent": "laptop_agent", "reply": "给妹妹选轻薄本，五千预算可以重点看这几款。先确认一下：她平时用电脑主要写论文还是也要跑设计软件？如果只是文档和网课，14寸、1.3kg以内的机型就很合适。", "recommendations": [ { "sku": "NB-2024-014", "title": "14英寸轻薄本 16G+512G", "price": 4799, "reason": "重量1.28kg，续航实测9小时，适合图书馆场景" } ], "routeTrace": ["router_agent", "laptop_agent", "knowledge_agent"] } }

重点看三个字段。agent字段确认路由到了laptop_agent，不是手机或家电。routeTrace展示完整调用链，能看到 Router Agent 先跑，然后 Laptop Agent，最后 Knowledge Agent 做 RAG 检索。recommendations里有具体商品和推荐理由，说明知识库检索和模型生成都正常。

如果返回里agent是router_agent而不是laptop_agent，说明路由规则没命中，检查addRule里的关键词是否覆盖了“笔记本”“轻薄本”这些说法。如果recommendations为空，说明知识库检索没返回结果，去百炼控制台确认商品数据是否已生成向量索引。

再测一个手机场景，确认路由能正确切换：

curl -X POST http://localhost:8080/api/guide/chat \ -H "Content-Type: application/json" \ -d '{"userId": "u10086", "message": "有没有拍照好的手机，预算三千"}'

这次预期agent字段变成mobile_agent，routeTrace里出现mobile_agent。两个请求对比，就能确认 Multi-Agent 路由是按意图动态切换的，不是写死一个 Agent。

验证通过后，建议把这两个 curl 请求存成脚本，每次改完配置跑一遍，作为回归测试。Multi-Agent 系统最怕的就是改了一个 Agent 的 Prompt，影响了路由判断，回归脚本能快速发现这类问题。

5. 常见报错排查：401、local proxy failed 与 choices 解析

配置和验证过程中，有几个报错出现频率特别高，这里逐个对照排查。

401 Unauthorized。这个最直接，Key 没配对或者没注入。先检查环境变量TAOTOKEN_API_KEY是否真的 export 了，在启动应用的终端里执行echo $TAOTOKEN_API_KEY确认有值。如果用的是 IDE 启动，检查 Run Configuration 里的 Environment variables 有没有设。还有一种情况是 Key 复制时带了空格或换行，去 https://taotoken.net/console/api-keys 重新复制一次，粘贴时注意首尾不要有多余字符。

local proxy failed / connection refused。这个报错说明应用连不上https://taotoken.net/api。先在本机用 curl 测连通性：

curl -I https://taotoken.net/api

如果 curl 也失败，检查网络出口、DNS 解析、公司防火墙。如果 curl 成功但应用失败，检查application.yml里base-url是否写成了https://taotoken.net/api/带了尾部斜杠，或者误加了/v1。Spring AI Alibaba 对 Base URL 的拼接比较敏感，多一个斜杠就可能导致路径错误。

reading choices 解析失败。这个报错通常出现在模型返回结构不符合预期时。比如你用的模型 ID 在 TaoToken 侧不支持，返回了错误结构，Spring AI Alibaba 尝试解析choices字段就失败了。去 https://taotoken.net/models 确认model字段填的 ID 在可用列表里。另外检查max-tokens是否设得太小，导致返回被截断，JSON 不完整也会解析失败。

OAuth / token 过期。如果你在百炼工作流侧也配了模型端点，工作流调模型时可能报 OAuth 相关错误。检查百炼控制台里工作流的模型配置，确认端点指向https://taotoken.net/api，并且凭证用的是同一份 API Key。百炼工作流和 Spring AI Alibaba 两边如果用了不同的 Key，会出现一边正常一边 401 的情况。

路由不生效，所有请求都走同一个 Agent。这个不是报错，但比报错更难查。先看routeTrace，确认 Router Agent 是否执行了。如果 Router Agent 没执行，检查百炼工作流的depends_on配置，product_recommend是否真的依赖demand_analysis。如果 Router Agent 执行了但路由结果不对，检查addRule的关键词列表，用户说的“轻薄本”是否被“笔记本”规则覆盖，必要时加同义词。

排查时有个通用技巧：把日志级别调到 DEBUG，Spring AI Alibaba 会打印每次模型请求的 URL、请求体和响应体。这样你能直接看到 Base URL 拼接后的完整地址，以及模型返回的原始 JSON。很多问题看一眼原始请求就清楚了。

logging: level: com.alibaba.cloud.ai: DEBUG org.springframework.web.client: DEBUG

加上这段配置，重启应用，再发一次请求，控制台会输出完整的调用链日志。对照日志里的 URL 和响应，基本能定位到是配置问题还是代码问题。

6. 把通道统一这件事做扎实

Multi-Agent 电商导购的复杂度不在单个 Agent 写得多聪明，而在多个 Agent 之间的协作和通道一致性。Router Agent 路由错了，后面全错；通道不统一，排查问题时日志对不上，一个小问题能耗掉半天。

把 Base URL 统一到 TaoToken 之后，Spring AI Alibaba 侧和百炼工作流侧共享同一个模型出口，Key 只用管一份，日志来源一致。这不是架构上的花活，是实打实降低维护成本。你后面要加新的品类 Agent，只需要在AgentConfig里加一个 Bean，在 Router Agent 里加一条规则，通道配置完全不用动。

配置片段和验证请求都在上面了，照着跑一遍，确认routeTrace里能看到完整的 Agent 调用链。跑通之后，建议把application.yml里的模型 ID、温度、max-tokens 这些参数做成可外部覆盖的，方便不同环境用不同配置。长期做编码和 Agent 编排的话，可以关注一下 Coding Plan 相关的资源，地址是 https://taotoken.net/coding-plan ，里面有面向持续开发场景的配置建议。

最后留一个实用技巧：在 Router Agent 的 Prompt 里加一句“如果无法确定品类，返回 unknown 并追问”，这样遇到模糊需求时不会硬路由到错误 Agent，而是让 Router 主动澄清。这个改动很小，但能明显减少误路由带来的体验问题。