Spring AI Alibaba 1.x 系列【11】Spring AI Models 扩展：DashScope

文章目录

[1. Spring AI Models](#1. Spring AI Models)
[2. Spring AI Alibaba Models](#2. Spring AI Alibaba Models)
- [2.1 dashscope-sdk-java](#2.1 dashscope-sdk-java)
- [2.2 spring-ai-alibaba-dashscope-sdk](#2.2 spring-ai-alibaba-dashscope-sdk)
- [2.3 spring-ai-alibaba-dashscope](#2.3 spring-ai-alibaba-dashscope)
[3. 演示案例](#3. 演示案例)
- [3.1 创建 API Key](#3.1 创建 API Key)
- [3.2 引入依赖](#3.2 引入依赖)
- [3.3 配置属性](#3.3 配置属性)
- - [3.3.1 重试配置](#3.3.1 重试配置)
  - [3.3.2 基础连接配置](#3.3.2 基础连接配置)
  - [3.3.3 聊天模型配置](#3.3.3 聊天模型配置)
- [3.4 基本使用](#3.4 基本使用)
- [3.5 手动配置](#3.5 手动配置)
- [3.6 底层 API 客户端](#3.6 底层 API 客户端)
- [3.7 API Key 管理](#3.7 API Key 管理)
- [3.8 模型推理内容获取](#3.8 模型推理内容获取)
- [3.9 ChatClient 集成](#3.9 ChatClient 集成)
- [3.10 ReactAgent 集成](#3.10 ReactAgent 集成)

1. Spring AI Models

Model API 统一了与 AI 模型的通信，它管理请求准备和响应解析的复杂性，提供直接且简化的 API 交互。

Generic Model API 包含：

Model
StreamingModel
ModelRequest
ModelOptions
ModelResponse
ModelResult

Chat Model API 包括：

ChatModel
StreamingChatModel
Prompt
Message
ChatOptions
ChatResponse
Generation

2. Spring AI Alibaba Models

Spring AI Alibaba Extensions 扩展了 Spring AI 的 Models 功能，提供了阿里云大模型服务百炼平台上的模型支持，包括通义千问系列、Deepseek 系列模型。

DashScope（阿里灵积）是阿里云推出的一站式大模型开发与服务平台（MaaS），后来升级为百炼平台，但是DashScope 相关的名称保留了下来，实际上已经是同一个东东。

Java 生态调用百炼平台上的模型服务，包含以下模块：

dashscope-sdk-java
spring-ai-alibaba-dashscope-sdk
spring-ai-alibaba-dashscope

2.1 dashscope-sdk-java

GitHub 仓库

官方 DashScope 模型的 Java SDK ，和 Spring AI 没有任何关联。

maven 依赖：

xml 复制代码

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>{dashscope-sdk-java-version}</version>
</dependency>

非流式简单案例：

java 复制代码

import com.alibaba.dashscope.aigc.conversation.Conversation;
import com.alibaba.dashscope.aigc.conversation.ConversationResult;
import com.alibaba.dashscope.aigc.conversation.qwen.QWenConversationParam;

public class Main {

  public static void main(String[] args) {
    Conversation conversation = new Conversation();

    //QWEN model, if using other model, you can replace the QWenConversationParam here.
    QWenConversationParam param =
            QWenConversationParam.builder()
                    .model(QWenConversationParam.QWEN_TURBO)
                    .prompt("hello")
                    .apiKey("testKey")
                    .build();

    ConversationResult result = conversation.call(param);
  }
}

2.2 spring-ai-alibaba-dashscope-sdk

GitHub 仓库

属于Spring AI Alibaba Extensions 项目下的子模块，是对阿里云官方 dashscope-sdk-java SDK 的 Spring AI 适配封装，将 SDK 原生能力映射到 Spring AI 标准接口。

目录结构：

java 复制代码

models/
└── dashscope-sdk/     # 官方 SDK 封装实现
    └── src/main/java/com/alibaba/cloud/ai/dashscope/sdk/
        ├── audio/
        │   ├── transcription/  # 语音转文字
        │   └── tts/            # 文字转语音
        ├── chat/                # 对话模型
        ├── common/              # 通用工具
        ├── embedding/           # 向量嵌入
        ├── image/               # 图像生成
        └── metadata/            # 元数据

提示：如果只需要使用 Spring AI ，仅需基础 Model 功能，不需要 RAG、Agent、Rerank 等高级特性时，可以考虑使用。

简单示例：

java 复制代码

@Autowired
private ChatModel chatModel;  // DashScopeSdkChatModel

public String chat(String userMessage) {
    ChatResponse response = chatModel.call(new Prompt(userMessage));
    return response.getResult().getOutput().getText();
}

2.3 spring-ai-alibaba-dashscope

属于Spring AI Alibaba Extensions 项目下的子模块，基于 Spring AI 、 HTTP/WebFlux 自定义实现，提供完整的 AI 能力支持。

项目结构：

java 复制代码

models/
├── dashscope/         # HTTP/WebFlux 自定义实现
│   └── src/main/java/com/alibaba/cloud/ai/
│       ├── advisor/          # ChatClient Advisor
│       ├── agent/            # Agent 抽象
│       ├── aot/              # AOT 编译提示
│       ├── dashscope/
│       │   ├── agent/        # DashScope Agent
│       │   ├── api/          # API 客户端
│       │   ├── audio/        # 音频模型（TTS/ASR）
│       │   ├── chat/         # 对话模型
│       │   ├── common/       # 通用工具
│       │   ├── embedding/    # 向量嵌入
│       │   ├── image/        # 图像生成
│       │   ├── metadata/     # 元数据
│       │   ├── observation/  # 可观测性
│       │   ├── protocol/     # WebSocket 协议
│       │   ├── rag/          # RAG 组件
│       │   ├── rerank/       # 重排序
│       │   ├── spec/         # API 规范定义
│       │   └── video/        # 视频生成
│       └── tool/             # 工具调用管理

实现的 Spring AI 接口：

接口	实现类	默认模型	功能特性
ChatModel	DashScopeChatModel	qwen-plus	对话、流式、工具、多模态、思维链
EmbeddingModel	DashScopeEmbeddingModel	text-embedding-v2	文本向量
ImageModel	DashScopeImageModel	wanx-v1	图像生成
TextToSpeechModel	DashScopeAudioSpeechModel	sambert-zhichu-v1	语音合成
AudioTranscriptionModel	DashScopeAudioTranscriptionModel	paraformer-v2	语音识别
RerankModel	DashScopeRerankModel	-	文档重排序
Agent	DashScopeAgent	-	百炼智能体

高级特性：

RAG (检索增强生成)
Rerank (文档重排序)
Agent (百炼智能体)
多模态与思维链配置

RAG 应用简单示例：

java 复制代码

// 1. 文档入库
DashScopeCloudStore cloudStore = new DashScopeCloudStore(dashScopeApi, 
    new DashScopeStoreOptions("my-index"));
cloudStore.add(List.of(
    new Document("doc1", "内容1", Map.of()),
    new Document("doc2", "内容2", Map.of())
));

// 2. 检索
DashScopeDocumentRetriever retriever = new DashScopeDocumentRetriever(dashScopeApi,
    DashScopeDocumentRetrieverOptions.builder()
        .indexName("my-index")
        .denseSimilarityTopK(10)
        .enableReranking(true)
        .rerankMinScore(0.5)
        .build());

List<Document> docs = retriever.retrieve(new Query("用户问题"));

// 3. 带 RAG 的对话
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(new DocumentRetrievalAdvisor(retriever))
    .build();

提示：本模块不依赖于dashscope-sdk-java、 spring-ai-alibaba-dashscope-sdk

3. 演示案例

在使用 Spring AI Alibaba 智能体开发框架，对接阿里云百炼平台模型时，肯定需要使用 spring-ai-alibaba-dashscope 。

3.1 创建 API Key

DashScope 模块用于接入阿里云百炼平台中的系列模型，所以需要在阿里云 DashScope 控制台创建账户，并在 API Keys 页面生成 API Key。

在 application.properties 文件中设置此配置属性：

yml 复制代码

spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}

3.2 引入依赖

引入依赖：

xml 复制代码

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.2</version>
</dependency>

3.3 配置属性

3.3.1 重试配置

前缀：spring.ai.retry

作用：配置 DashScope Chat Model 的请求重试机制

属性	描述	默认值
spring.ai.retry.max-attempts	最大重试次数	10
spring.ai.retry.backoff.initial-interval	指数退避策略初始等待时长	2 sec.
spring.ai.retry.backoff.multiplier	退避间隔乘数	5
spring.ai.retry.backoff.max-interval	最大退避等待时长	3 min.
spring.ai.retry.on-client-errors	是否对4xx客户端错误重试；false则直接抛出非瞬态异常	false
spring.ai.retry.exclude-on-http-codes	禁止重试的HTTP状态码列表	empty
spring.ai.retry.on-http-codes	强制重试的HTTP状态码列表	empty

3.3.2 基础连接配置

前缀：spring.ai.dashscope

作用：配置 DashScope 通用连接参数

属性	描述	默认值
spring.ai.dashscope.base-url	API 服务地址	https://dashscope.aliyuncs.com
spring.ai.dashscope.api-key	百炼 API 密钥	-
spring.ai.dashscope.work-space-id	可选，指定API请求的工作空间ID	-

提示：多工作空间用户可配置该参数，API 使用量将计入指定工作空间

3.3.3 聊天模型配置

通过顶级属性控制 Chat Model 自动装配（支持多模型切换）

启用：spring.ai.model.chat=dashscope（默认）
禁用：spring.ai.model.chat=none

前缀：spring.ai.dashscope.chat

优先级：专属配置 > 通用连接配置，支持为聊天模型单独配置密钥/地址

属性	描述	默认值
spring.ai.model.chat	启用 DashScope 聊天模型	dashscope
spring.ai.dashscope.chat.base-url	可选，聊天模型专属基础URL	-
spring.ai.dashscope.chat.completions-path	聊天接口请求路径	/api/v1/services/aigc/text-generation/generation
spring.ai.dashscope.chat.api-key	可选，聊天模型专属API密钥	-
spring.ai.dashscope.chat.work-space-id	可选，聊天模型专属工作空间ID	-
spring.ai.dashscope.chat.options.model	对话模型名称（qwen-plus/qwen-turbo等）	qwen-plus
spring.ai.dashscope.chat.options.temperature	采样温度 [0,2)，控制随机性	0.85
spring.ai.dashscope.chat.options.topP	核采样概率 (0,1]，控制随机性	0.8
spring.ai.dashscope.chat.options.topK	Top-K 采样候选池，>100则禁用	-
spring.ai.dashscope.chat.options.seed	随机种子，保证结果可复现	-
spring.ai.dashscope.chat.options.stop	生成停止符（最多4个）	-
spring.ai.dashscope.chat.options.maxTokens	生成内容最大Token数	-
spring.ai.dashscope.chat.options.maxInputTokens	输入内容最大Token数	-
spring.ai.dashscope.chat.options.repetitionPenalty	重复惩罚系数，1.0无惩罚	1.1
spring.ai.dashscope.chat.options.enableSearch	是否启用模型内置联网搜索	false
spring.ai.dashscope.chat.options.searchOptions	联网搜索策略（仅搜索开启时生效）	-
spring.ai.dashscope.chat.options.responseFormat	返回格式：text/json_object	-
spring.ai.dashscope.chat.options.incrementalOutput	流式输出是否启用增量模式	true
spring.ai.dashscope.chat.options.tools	模型可调用的工具列表（仅支持函数）	-
spring.ai.dashscope.chat.options.toolChoice	工具调用策略（none/auto/指定函数）	-
spring.ai.dashscope.chat.options.parallelToolCalls	是否启用并行函数调用	-
spring.ai.dashscope.chat.options.enableThinking	是否启用思考过程（Qwen3系列专用）	false
spring.ai.dashscope.chat.options.thinkingBudget	思考过程最大长度（思考开启时生效）	-
spring.ai.dashscope.chat.options.vlHighResolutionImages	视觉模型高清图像Token限制	-
spring.ai.dashscope.chat.options.vlEnableImageHwOutput	视觉模型图像硬件输出开关	false
spring.ai.dashscope.chat.options.multiModel	是否为多模型请求	false
spring.ai.dashscope.chat.options.modalities	输出类型（文本/音频）	-
spring.ai.dashscope.chat.options.audio	音频生成参数（音频输出必填）	-
spring.ai.dashscope.chat.options.asrOptions	语音识别(ASR)配置	-
spring.ai.dashscope.chat.options.ocrOptions	文字识别(OCR)配置	-
spring.ai.dashscope.chat.options.logprobs	是否返回Token对数概率	-
spring.ai.dashscope.chat.options.topLogProbs	Top-K 对数概率数量	-
spring.ai.dashscope.chat.options.translationOptions	翻译配置	-
spring.ai.dashscope.chat.options.outputFormat	输出格式	-
spring.ai.dashscope.chat.options.streamOptions	流式输出配置	-
spring.ai.dashscope.chat.options.httpHeaders	自定义请求头	-
spring.ai.dashscope.chat.options.toolNames	函数调用工具名称列表	-
spring.ai.dashscope.chat.options.toolCallbacks	工具回调处理器	-
spring.ai.dashscope.chat.options.internalToolExecutionEnabled	是否由Spring AI内部执行工具调用	true

核心补充说明：

配置优先级：聊天模型专属配置（spring.ai.dashscope.chat.xxx） > 通用连接配置（spring.ai.dashscope.xxx）
运行时覆盖：所有 spring.ai.dashscope.chat.options 前缀的参数，均可在 Prompt 调用时通过请求级配置覆盖

3.4 基本使用

创建 REST 接口，支持同步对话和流式对话：

java 复制代码

@RestController
public class ChatController {

    private final ChatModel chatModel;

    // 自动注入 Spring 自动配置的 ChatModel
    @Autowired
    public ChatController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    /**
     * 同步对话接口
     */
    @GetMapping("/ai/generate")
    public Map<String, String> generate(
            @RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    /**
     * 流式对话接口
     */
    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(
            @RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

3.5 手动配置

不依赖自动配置，手动创建 DashScopeChatModel 实例：

java 复制代码

// 1. 构建 DashScope 原生 API 客户端
DashScopeApi dashScopeApi = DashScopeApi.builder()
        .apiKey(System.getenv("AI_DASHSCOPE_API_KEY")) // 从环境变量读取密钥
        .build();

// 2. 构建对话参数配置
DashScopeChatOptions chatOptions = DashScopeChatOptions.builder()
        .model("qwen-plus")       // 模型名称
        .temperature(0.4)         // 随机性
        .maxTokens(200)           // 最大生成Token
        .build();

// 3. 手动创建 ChatModel（需注入工具管理器、重试模板、观测注册表）
DashScopeChatModel chatModel = new DashScopeChatModel(
        dashScopeApi,
        chatOptions,
        toolCallingManager,
        retryTemplate,
        observationRegistry
);

// 同步调用
ChatResponse response = chatModel.call(new Prompt("Generate the names of 5 famous pirates."));

// 流式调用
Flux<ChatResponse> streamResponse = chatModel.stream(new Prompt("Generate the names of 5 famous pirates."));

3.6 底层 API 客户端

直接使用原生 DashScopeApi 调用百炼接口，适用于自定义场景：

java 复制代码

// 初始化客户端
DashScopeApi dashScopeApi = DashScopeApi.builder()
        .apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
        .build();

// 构造用户消息
ChatCompletionMessage message = new ChatCompletionMessage("Hello world", ChatCompletionMessage.Role.USER);

// 1. 同步请求
ResponseEntity<DashScopeApi.ChatCompletion> syncResponse = dashScopeApi.chatCompletionEntity(
        new ChatCompletionRequest(
                "qwen-plus",
                new DashScopeApi.ChatCompletionRequestInput(List.of(message)),
                new DashScopeApi.ChatCompletionRequestParameter(),
                false,
                false
        )
);

// 2. 流式请求
Flux<DashScopeApi.ChatCompletionChunk> streamResponse = dashScopeApi.chatCompletionStream(
        new ChatCompletionRequest(
                "qwen-plus",
                new DashScopeApi.ChatCompletionRequestInput(List.of(message)),
                new DashScopeApi.ChatCompletionRequestParameter(),
                true,
                false
        )
);

3.7 API Key 管理

自定义密钥获取逻辑（如从密钥库读取、动态轮换）：

java 复制代码

// 自定义 ApiKey 实现
ApiKey customApiKey = new ApiKey() {
    @Override
    public String getValue() {
        // 自定义逻辑：从安全存储/配置中心获取密钥
        return "your-custom-api-key";
    }
};

// 构建自定义客户端
DashScopeApi dashScopeApi = DashScopeApi.builder()
        .apiKey(customApiKey)
        .build();

// 构建自定义 ChatModel
DashScopeChatModel chatModel = DashScopeChatModel.builder()
        .dashScopeApi(dashScopeApi)
        .build();

3.8 模型推理内容获取

适配 Qwen3 系列思维链模型，获取模型内部推理过程。

同步获取推理内容：

java 复制代码

// 启用思维链配置
DashScopeChatOptions options = DashScopeChatOptions.builder()
        .model("qwen3")
        .enableThinking(true)    // 开启推理过程
        .thinkingBudget(1000)    // 推理内容最大长度
        .build();

// 调用模型
ChatResponse response = chatModel.call(new Prompt("9.11和9.8哪个数字更大？", options));

// 获取助手消息
AssistantMessage message = response.getResult().getOutput();

// 1. 获取模型推理过程（思维链）
String reasoningContent = message.getMetadata().get("reasoningContent");
System.out.println("推理过程：" + reasoningContent);

// 2. 获取最终答案
String finalAnswer = message.getContent();
System.out.println("最终答案：" + finalAnswer);

流式获取推理内容：

java 复制代码

import reactor.core.publisher.Flux;

// 流式调用
Flux<ChatResponse> responseFlux = chatModel.stream(new Prompt("解一道逻辑题...", options));

StringBuilder reasoning = new StringBuilder();
StringBuilder answer = new StringBuilder();

// 订阅流式结果，累积推理内容和答案
responseFlux.subscribe(chunk -> {
    AssistantMessage message = chunk.getResult().getOutput();
    
    // 累积思维链
    String chunkReasoning = message.getMetadata().get("reasoningContent");
    if (chunkReasoning != null) reasoning.append(chunkReasoning);
    
    // 累积答案
    if (message.getContent() != null) answer.append(message.getContent());
});

3.9 ChatClient 集成

java 复制代码

import org.springframework.ai.chat.client.ChatClient;

// 创建 ChatClient
ChatClient chatClient = ChatClient.create(chatModel);

// 获取完整响应
ChatResponse response = chatClient.prompt()
        .user("9.11和9.8哪个数字更大？")
        .call()
        .chatResponse();

// 提取推理内容
String reasoning = response.getResult().getOutput().getMetadata().get("reasoningContent");

3.10 ReactAgent 集成

java 复制代码

@Configuration
class ChatClientConfig {

    @Bean("chatAgent")
    public ReactAgent chatAgent(DashScopeChatModel chatModel) {
        // 创建 agent
        return ReactAgent.builder()
                .name("chat_agent") // 指定名称
                .model(chatModel) // 指定 ChatModel
                .build();
    }

}