企业官网建设流程全解析

1. 多智能体工作流里，Key 分散到底有多痛

如果你已经用 Spring AI 搭过一两个 Agent，大概率经历过这个阶段：ChatClient 调通义千问一个 Key，EmbeddingClient 调另一个模型又一个 Key，工作流里某个节点想换成别的模型，又得翻配置文件改 base-url 和 api-key。等到多智能体协作跑起来，三个 Agent 用三个模型，配置文件里散落着四五组凭证，本地一套、测试环境一套，改一次要动好几个地方。

Spring AI Alibaba（下面简称 SAA）解决的正是「怎么把 Agent、Workflow、Multi-agent 用 Spring 的方式写出来」这件事。它基于 Spring AI 的抽象，深度集成了百炼平台，提供 Graph 多智能体框架、MCP 集成、可观测接入等能力。简单类比：Spring AI 像 JDBC，给你统一的调用接口；SAA 在此基础上补上了国产模型生态、工作流编排和企业级集成。

但框架再顺手，模型接入这一层如果还是每个模型一套 Key，多智能体工作流照样会卡在配置管理上。这篇就聚焦一个具体问题：用 TaoToken 的统一 Key 和 API 通道，把 SAA 里多模型、多智能体的凭证收敛成一份配置。适合已经用 Spring AI 写过 Agent、正准备上多智能体工作流的 Java 开发者。下面给出 settings.json 与 config.toml 骨架、接入步骤，以及一次多智能体工作流调用的验证动作，目标是一份能直接复制的配置清单。

2. TaoToken 作为统一模型入口的前置准备

在动手改 SAA 配置之前，先把「统一入口」这件事想清楚。SAA 里每个模型调用最终都会落到一个 base-url + api-key 的组合上。如果每个模型都指向不同的服务商，配置就会发散；如果所有模型都指向同一个兼容 OpenAI 协议的入口，只是 model 名不同，配置就能收敛成一份。

TaoToken 在这里扮演的就是这个统一入口：一个 API Key、一个 base-url，通过切换 model 参数来调用不同模型。对 SAA 来说，这意味着 ChatClient、EmbeddingClient、以及 Graph 里各个节点用的模型，都可以共用同一组凭证。

你需要先拿到两样东西：

• 一个 API Key：在控制台的 API Keys 页面创建，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite
• 确认 base-url：https://taotoken.net/api （这个地址不加 UTM 参数，直接用于配置）

注意：API Key 只创建一次就够，后面所有模型共用它。不要在每个 Agent 里重复填不同的 Key，那样就失去统一入口的意义了。

如果你还没决定用哪些模型，可以先到模型对话页面看看可用模型列表和实际效果，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。选好模型名之后，再回到配置里填。

前置准备就这些：一个 Key、一个 base-url、一份模型名清单。接下来进入配置环节。

3. settings.json 与 config.toml 骨架配置

SAA 项目里配置通常分两层：一层是 Spring Boot 的 application 配置（yaml 或 properties），另一层是某些工具链或 CLI 用的 settings.json / config.toml。这里我把两种骨架都给出来，你可以按项目实际情况取用。

3.1 settings.json 骨架

如果你的项目或工具链用 JSON 管理模型配置，可以按下面这个结构组织。核心思路是：把 base-url 和 api-key 提到顶层，模型只保留 model 名和少量参数。

{ "ai": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "models": { "chat": "qwen-plus", "reasoning": "qwen-max", "embedding": "text-embedding-v3" }, "defaultOptions": { "temperature": 0.7, "maxTokens": 2048 } }, "agents": { "planner": { "model": "reasoning" }, "executor": { "model": "chat" }, "retriever": { "model": "embedding" } } }

这里apiKey用环境变量占位，避免把 Key 写进版本库。agents段里每个 Agent 只引用模型别名，不重复写 base-url 和 Key。这样新增一个 Agent 时，只需要加一行模型引用。

3.2 config.toml 骨架

如果项目用 TOML 管理配置，等价的结构如下：

[ai] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}" [ai.models] chat = "qwen-plus" reasoning = "qwen-max" embedding = "text-embedding-v3" [ai.defaults] temperature = 0.7 max_tokens = 2048 [agents.planner] model = "reasoning" [agents.executor] model = "chat" [agents.retriever] model = "embedding"

两份骨架的语义完全一致，选你项目里已经在用的格式即可。关键点是：base-url 和 api-key 只出现一次，模型名集中管理，Agent 只做引用。

3.3 映射到 Spring Boot 配置

SAA 最终读的是 Spring 的配置。把上面的结构翻译成 application.yml，大致是这样：

spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: qwen-plus temperature: 0.7 embedding: options: model: text-embedding-v3

如果你在 Graph 里为不同节点指定不同模型，可以在节点构建时覆盖 model 参数，而 base-url 和 api-key 仍然继承全局配置。这样多智能体工作流里每个节点用不同模型，但凭证只有一份。

4. 接入步骤与多智能体工作流验证

配置写好后，按下面步骤接入并验证。

4.1 设置环境变量

先把 Key 放进环境变量，避免硬编码：

export TAOTOKEN_API_KEY="你的_API_Key"

Windows 下用set TAOTOKEN_API_KEY=你的_API_Key，或者在 IDE 的运行配置里加环境变量。

4.2 构建 ChatClient 与 EmbeddingClient

在 Spring 配置类里，让 SAA 用全局配置构建客户端：

@Configuration public class AiConfig { @Bean public ChatClient chatClient(ChatClient.Builder builder) { return builder .defaultSystem("你是一个多智能体工作流中的执行节点") .build(); } @Bean public EmbeddingClient embeddingClient(EmbeddingClient.Builder builder) { return builder.build(); } }

base-url 和 api-key 已经在 application.yml 里配好，这里不需要再传。

4.3 定义多智能体工作流节点

用 SAA 的 Graph 框架定义两个节点，一个负责规划、一个负责执行，分别用不同模型：

@Bean public StateGraph multiAgentGraph(ChatClient chatClient) { return new StateGraph() .addNode("planner", state -> { String plan = chatClient.prompt() .options(ChatOptions.builder().model("qwen-max").build()) .user("请为任务制定步骤：" + state.get("task")) .call() .content(); state.put("plan", plan); return state; }) .addNode("executor", state -> { String result = chatClient.prompt() .options(ChatOptions.builder().model("qwen-plus").build()) .user("按计划执行：" + state.get("plan")) .call() .content(); state.put("result", result); return state; }) .addEdge("planner", "executor") .setEntryPoint("planner"); }

注意两个节点用了不同 model，但都走同一个 chatClient，也就是同一组 base-url 和 api-key。这就是统一入口的价值。

4.4 验证请求

写一个测试入口触发工作流：

@RestController public class WorkflowController { private final StateGraph graph; public WorkflowController(StateGraph graph) { this.graph = graph; } @GetMapping("/run") public Map<String, Object> run(@RequestParam String task) { Map<String, Object> state = new HashMap<>(); state.put("task", task); return graph.invoke(state); } }

启动应用后访问：

curl "http://localhost:8080/run?task=整理一份Spring AI Alibaba的核心能力清单"

成功的话，返回的 JSON 里会包含plan和result两个字段，分别由两个不同模型生成。如果只看到其中一个字段，说明工作流在某个节点中断了，往下看排查部分。

5. 本篇常见错排查

5.1 401 或鉴权失败

最常见的原因是环境变量没生效。先确认：

echo $TAOTOKEN_API_KEY

如果输出为空，说明变量没设上。另一个原因是配置文件里 base-url 写成了带路径的形式，比如https://taotoken.net/api/v1，而客户端又自动拼了一次路径。base-url 保持https://taotoken.net/api即可，不要手动加/v1。

5.2 模型名不识别

如果报「model not found」，先到模型对话页面确认模型名拼写。不同模型的命名规则不一样，比如qwen-plus和qwen-max是两个不同的模型，不能混用。把模型名集中放在配置里，就是为了避免这种拼写错误散落在代码各处。

5.3 工作流节点模型不生效

如果你在节点里用ChatOptions.builder().model(...)覆盖了模型，但发现还是用了全局默认模型，检查一下覆盖的 options 有没有真正传进prompt()。SAA 里 options 的优先级是：节点级 > 全局级。如果节点级没生效，多半是 builder 链的顺序问题，把.options()放在.user()之前。

5.4 Embedding 调用超时

Embedding 模型和 Chat 模型走的是同一个 base-url，但请求体格式不同。如果 Chat 正常、Embedding 超时，先确认 embedding 的 model 名是否正确，再检查网络出口是否对taotoken.net放行。企业内网环境下，可能需要把域名加进白名单。

5.5 多智能体上下文丢失

Graph 里节点之间靠 state 传递数据。如果 executor 拿不到 planner 的输出，检查 planner 节点有没有把结果put进 state，以及 addEdge 的方向是否正确。SAA 的 StateGraph 是有向图，边决定了执行顺序，写反了就会跳过节点。

6. 把统一 Key 用进你的长期编码工作流

配置收敛成一份之后，日常开发里最明显的变化是：新增一个 Agent 或换一个模型，只需要改一行模型名，不用再翻找 Key。如果你打算把 SAA 的多智能体工作流长期跑下去，尤其是涉及多个 Agent 协作、频繁切换模型的场景，可以考虑用 Coding Plan 来管理调用额度，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。

接入过程中如果遇到鉴权或配置问题，接入文档里有更细的参数说明：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。需要重新生成或管理 Key 时，回到控制台即可：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。

我自己的做法是把 settings.json 里的模型别名和 Agent 角色对应起来，planner 用推理强的模型，executor 用响应快的模型，retriever 用 embedding 模型。这样每次调整工作流，改的都是别名映射，而不是散落各处的凭证。你可以先按上面的骨架跑通一次双节点工作流，确认 plan 和 result 都正常返回，再往里面加更多 Agent。