SpringAI模型调用避坑手册：Prompt指定与ChatModel切换的5个常见错误
最近在几个SpringBoot项目中集成AI能力时，我发现团队在模型调用这个看似简单的环节上，踩坑的频率高得惊人。特别是当项目需要灵活切换不同模型，或者在运行时动态指定模型参数时，各种诡异的问题层出不穷。有些错误甚至会导致整个AI服务不可用，而调试起来又特别耗时。
这篇文章我想结合自己踩过的坑，聊聊SpringAI中模型调用的五个典型陷阱。我会用实际的代码对比来展示错误和正确的做法，重点聚焦在Prompt临时指定模型和ChatModel动态切换这两个高频场景。如果你正在实施AI集成的SpringBoot项目，这些经验应该能帮你省下不少调试时间。
1. 配置层面的依赖冲突与自动装配陷阱
很多团队刚开始接触SpringAI时，最容易犯的第一个错误就是依赖配置不当。SpringAI的自动装配机制虽然方便，但在多模型场景下，如果配置不当，很容易导致启动失败或者模型调用混乱。
1.1 多模型依赖的典型配置错误
先看一个常见的错误配置。假设项目需要同时使用OpenAI和Ollama两种模型，很多开发者会这样配置pom.xml：
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
</dependencies>
然后在application.yml中这样配置：
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
chat:
options:
model: gpt-4
ollama:
base-url: http://localhost:11434
chat:
options:
model: llama2
问题来了：当你启动应用时，Spring会尝试自动装配两个ChatModel的bean，但默认情况下它不知道应该用哪一个。更糟糕的是，如果你在代码中这样注入：
@Autowired
private ChatModel chatModel; // 这里会注入哪个？
Spring会抛出NoUniqueBeanDefinitionException，因为有两个候选bean都实现了ChatModel接口。
1.2 正确的多模型配置策略
正确的做法需要更精细的控制。首先，你需要明确每个模型的用途，并为它们创建独立的bean。这里有两种推荐的做法：
方案一：使用@Qualifier明确指定
@Configuration
public class ChatModelConfig {
@Bean
@Qualifier("openAiChatModel")
public ChatModel openAiChatModel(OpenAiChatModel chatModel) {
return chatModel;
}
@Bean
@Qualifier("ollamaChatModel")
public ChatModel ollamaChatModel(OllamaChatModel chatModel) {
return chatModel;
}
}
使用时通过@Qualifier明确指定：
@Autowired
@Qualifier("openAiChatModel")
private ChatModel openAiModel;
@Autowired
@Qualifier("ollamaChatModel")
private ChatModel ollamaModel;
方案二：禁用默认自动装配，完全手动控制
对于更复杂的场景，我建议完全禁用SpringAI的默认自动装配，自己掌控一切：
spring:
ai:
chat:
client:
enabled: false # 禁用默认的ChatClient自动装配
然后在配置类中手动排除不需要的自动配置：
@SpringBootApplication(exclude = {
OpenAiChatAutoConfiguration.class,
OllamaChatAutoConfiguration.class
// 排除其他不需要的自动配置
})
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
注意：排除自动配置时，需要根据实际报错信息逐步添加。SpringAI的自动配置类之间可能存在依赖关系，一次性排除太多可能会导致其他问题。
1.3 依赖版本冲突的排查技巧
多模型依赖还经常遇到版本冲突问题。SpringAI的不同模型starter可能依赖不同版本的底层SDK。我建议在pom.xml中使用dependencyManagement统一管理版本：
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>1.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
如果还是遇到冲突，可以使用Maven的依赖树分析工具：
mvn dependency:tree -Dincludes=com.fasterxml.jackson
重点关注Jackson、OkHttp、Reactor等公共库的版本冲突。
2. Prompt临时指定模型时的参数覆盖问题
通过Prompt临时指定模型是SpringAI提供的一个灵活特性，但这里有几个容易忽略的细节。
2.1 错误示例：Options参数未正确传递
看这个常见的错误代码：
public String generateWithModel(String promptText, String modelName) {
// 错误做法：直接创建Prompt，没有正确设置Options
Prompt prompt = new Prompt(promptText);
// 错误：试图通过message设置模型，但Options才是控制模型的地方
prompt.getInstructions().get(0).getMetadata().put("model", modelName);
return chatModel.call(prompt).getResult().getOutput().getContent();
}
这段代码的问题在于，它错误地认为可以通过message的metadata来指定模型。实际上，模型选择是通过ChatOptions来控制的。
2.2 正确使用OllamaOptions指定模型
对于Ollama模型，正确的做法是使用OllamaOptions：
public String generateWithOllamaModel(String promptText, String modelName) {
List<Message> messages = List.of(new UserMessage(promptText));
// 正确：通过OllamaOptions指定模型
OllamaOptions options = OllamaOptions.builder()
.model(modelName) // 这里指定具体模型
.temperature(0.7)
.topP(0.9)
.build();
Prompt prompt = new Prompt(messages, options);
return ollamaChatModel.call(prompt).getResult().getOutput().getContent();
}
但这里还有一个隐藏的坑：如果你的OllamaChatModel在创建时已经设置了默认的options，那么Prompt中传入的options会与默认options合并，而不是完全覆盖。
2.3 Options合并规则与优先级
理解SpringAI中options的合并规则至关重要。看这个例子：
@Bean
public OllamaChatModel ollamaChatModel() {
// 创建时设置默认options
OllamaOptions defaultOptions = OllamaOptions.builder()
.model("llama2") // 默认模型
.temperature(0.5) // 默认温度
.numPredict(100) // 默认预测token数
.build();
return OllamaChatModel.builder()
.ollamaApi(new OllamaApi("http://localhost:11434"))
.defaultOptions(defaultOptions)
.build();
}
// 使用时
public String generate(String promptText) {
// 只指定模型，不指定其他参数
OllamaOptions runtimeOptions = OllamaOptions.builder()
.model("qwen2.5") // 只覆盖模型
.build();
Prompt prompt = new Prompt(
List.of(new UserMessage(promptText)),
runtimeOptions
);
// 问题：temperature和numPredict会用什么值？
return ollamaChatModel.call(prompt).getResult().getOutput().getContent();
}
在这个例子中，最终的options会是：
model: "qwen2.5"（运行时指定，覆盖默认值）temperature: 0.5（使用默认值，因为运行时未指定）numPredict: 100（使用默认值，因为运行时未指定）
关键点：运行时options与默认options是合并关系，不是替换。运行时指定的参数会覆盖默认值，未指定的参数保持默认值。
2.4 跨供应商模型指定的注意事项
如果你需要支持多种模型供应商（如OpenAI、Anthropic、Ollama等），在Prompt中指定模型时需要特别注意：
public String generateWithAnyModel(String promptText, String modelName, String vendor) {
ChatOptions options;
switch (vendor.toLowerCase()) {
case "openai":
options = OpenAiChatOptions.builder()
.model(modelName)
.temperature(0.7)
.build();
break;
case "ollama":
options = OllamaOptions.builder()
.model(modelName)
.temperature(0.7)
.build();
break;
case "anthropic":
options = AnthropicChatOptions.builder()
.model(modelName)
.temperature(0.7)
.build();
break;
default:
throw new IllegalArgumentException("Unsupported vendor: " + vendor);
}
Prompt prompt = new Prompt(
List.of(new UserMessage(promptText)),
options
);
// 问题：这里应该用哪个ChatModel？
return chatModel.call(prompt).getResult().getOutput().getContent();
}
这里暴露了一个更根本的问题：不同的options类型需要匹配对应的ChatModel实现。你不能把OllamaOptions传给OpenAiChatModel，反之亦然。
3. ChatModel动态切换的实现陷阱
在实际项目中，我们经常需要根据业务逻辑动态切换不同的模型。这个需求看似简单，但实现时有很多细节需要注意。
3.1 简单的模型工厂模式
先看一个基础但不够完善的实现：
@Component
public class SimpleModelFactory {
@Autowired
@Qualifier("openAiChatModel")
private ChatModel openAiModel;
553
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
