第 39 篇我们讨论了 Spring AI 在 Agent 系统中的工程落地骨架。本篇继续往下走，聚焦三件在生产环境里绕不开的事：配置怎么写才稳、出错怎么查得快、多模型怎么选和怎么迁。需要先说明：以下关于 Spring AI 能力边界的描述，基于公开资料中对其“跨 AI 提供商可移植 API、支持多模型提供商、与 Spring Boot 集成”的定位；具体的配置键名、错误码和迁移成本属于工程分析，落地时请以所用版本官方文档为准。
一、配置分层：把“可移植”落到工程结构上
Spring AI 的核心设计目标之一是提供跨 AI 提供商的可移植 API。工程上建议把配置拆成三层：
1）依赖层：按提供商引入对应 starter，避免把所有厂商 SDK 都打进同一个制品。多模型场景下，用 Maven/Gradle 的 profile 或独立模块隔离，防止依赖冲突。
2）连接层：API Key、base URL、超时、重试、代理等放在环境变量或配置中心，不写进代码仓库。Spring Boot 的 @ConfigurationProperties 绑定是自然选择，但要注意密钥字段加 @ToString.Exclude 之类保护，避免日志泄露。
3）模型层：模型名、温度、最大 token、是否启用工具调用等按“用途”而非“厂商”命名，例如 agent.planner.model、agent.chat.model。这样迁移提供商时只改绑定值，不改业务代码。
一个常见的坑是把模型参数硬编码在 Prompt 调用处。Spring AI 的抽象本意是让调用侧面向统一接口，一旦参数散落各处，可移植性就名存实亡。建议在配置层定义好默认值，业务代码只做覆盖。
二、排错：先分清“框架层”还是“提供商层”
Spring AI 报错大致分三类，排查顺序建议从外到内：
第一类，启动期装配失败。典型表现是应用起不来，提示缺少某个 Bean 或属性绑定失败。优先检查：starter 是否引入、API Key 是否为空、@ConfigurationProperties 前缀是否拼错。这类问题在启动日志里通常有明确指向，不要一上来就怀疑网络。
第二类，调用期鉴权与配额错误。表现为 401/403 或限流。先确认密钥所属账号与模型权限是否匹配，再确认 base URL 是否指向了正确区域。多提供商接入时，最容易出现“密钥是 A 厂商的，URL 配成了 B 厂商”的低级错误，建议在配置类里做启动自检，打印脱敏后的提供商标识和 URL 前缀。
第三类，响应解析与超时。流式与非流式、工具调用返回结构差异，都可能导致反序列化失败。排查时先降级到最小请求：单轮、无工具、短 prompt，确认链路通后再逐步加回工具和流式。超时问题要区分连接超时和读超时，Agent 场景下 Planner 调用往往比普通对话长，读超时不宜照搬对话场景的默认值。
工程建议：为每次模型调用记录提供商、模型名、耗时、token 用量和错误类型，但不要记录完整 prompt 和密钥。这套埋点既是排错依据，也是后续选型的数据来源。
三、多模型选型：按“任务角色”而不是“厂商排名”
公开资料显示 Spring AI 支持多种模型提供商和矢量数据库提供商。选型时建议按 Agent 内部角色拆分：
- Planner/推理角色：看重指令遵循和结构化输出稳定性，优先选支持工具调用且返回格式可控的模型。
- 对话角色：看重延迟和成本，可选用更轻的模型。
- 嵌入角色：看重维度、成本和批量吞吐，且要与向量库维度对齐。
不要用一个模型打满所有角色。多模型的价值在于按角色匹配能力与成本，而不是堆厂商。选型对比至少覆盖：是否支持工具调用、是否支持流式、上下文窗口、结构化输出可靠性、限流策略、计费方式、区域可用性。这些维度中，前四项可从官方文档确认，后三项需结合自身账号实测。
四、迁移注意事项
得益于可移植 API，迁移的主要工作量不在业务代码，而在配置和验证。迁移清单建议：
1）参数映射：不同提供商的温度范围、最大 token 语义可能不同，迁移后要重新校准，不能直接照搬数值。
2）工具调用格式：统一抽象之下，各厂商对工具描述和返回的约束仍有差异，迁移后必须回归工具调用用例。
3）嵌入维度：换嵌入模型意味着向量库要重建或做双写过渡，这是迁移中成本最高的一环，务必提前规划。
4）灰度：用配置开关按流量比例切换提供商，保留回滚路径，不要一次性全量切换。
五、小结
Spring AI 的工程价值在于用统一抽象降低多提供商接入成本，但“可移植”不等于“零配置”。把配置分层、把排错顺序固定下来、按角色选型并准备好迁移清单，才能让 Agent 系统在生产环境里稳定演进。下一篇将继续沿系列定位推进，讨论 Agent 运行时的可观测与治理话题。