下面是spring ai alibaba简单学习的源码介绍，包括依赖、配置文件、数据源配置类、模型配置类、向量数据库配置类、Agent配置类和各种案例的Contoller.

源码结构

本次项目用的是jdk17

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.5</version>
        <relativePath/>
    </parent>
    <groupId>com.study</groupId>
    <artifactId>spring-ai-alibaba-study</artifactId>
    <version>1.0.0</version>
    <name>spring-ai-alibaba-study</name>
    <description>Spring AI Alibaba 学习项目：ChatClient/ChatModel/Embedding/Tool/Memory/Prompt/结构化输出/向量存储/RAG/Graph Agent</description>
    <properties>
        <java.version>17</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <!-- Spring AI Alibaba 版本（官网 https://java2ai.com） -->
        <spring-ai-alibaba.version>1.0.0.2</spring-ai-alibaba.version>
        <!-- Spring AI 版本，与 Spring AI Alibaba 1.0.0.2 配套 -->
        <spring-ai.version>1.0.0</spring-ai.version>
    </properties>
    <dependencyManagement>
        <dependencies>
            <!-- Spring AI Alibaba BOM：统一管理 dashscope starter / graph-core 等版本 -->
            <dependency>
                <groupId>com.alibaba.cloud.ai</groupId>
                <artifactId>spring-ai-alibaba-bom</artifactId>
                <version>${spring-ai-alibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <!-- Spring AI BOM：统一管理 spring-ai 官方组件版本 -->
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>${spring-ai.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <!-- Web MVC -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- FreeMarker 页面模板 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-freemarker</artifactId>
        </dependency>
        <!-- JDBC（DataSource、JdbcTemplate、对话记忆持久化都用它） -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>
        <!-- Spring AI Alibaba：DashScope(阿里云百炼/通义) 模型适配 Starter
             自动装配 ChatModel / EmbeddingModel / ChatClient.Builder 等 Bean -->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        </dependency>
        <!-- Spring AI Alibaba Graph：工作流 / 多智能体框架（Agent 示例使用） -->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-graph-core</artifactId>
        </dependency>
        <!-- Gson：Graph 框架默认状态序列化器所需 -->
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
        </dependency>
        <!-- Spring AI OpenAI 模块（非 starter，手动构建 Bean）：
             DeepSeek / 腾讯混元 / 字节豆包 / Kimi / GLM 等厂商都提供 OpenAI 兼容接口，
             通过 study.model.provider=openai 切换，见 ModelProviderConfig -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai</artifactId>
        </dependency>
        <!-- Spring AI 向量存储抽象 + 内存实现 SimpleVectorStore -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-vector-store</artifactId>
        </dependency>
        <!-- ============ 可选向量数据库实现（study.vectorstore.type 切换，默认 simple 内存版） ============ -->
        <!-- Redis Stack（本地最轻量的持久化向量库；协议与阿里云 Tair 兼容） -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-vector-store-redis</artifactId>
        </dependency>
        <!-- Milvus（开源向量数据库，本地 Docker 一行命令即可跑） -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-vector-store-milvus</artifactId>
        </dependency>
        <!-- Chroma（轻量本地向量数据库，适合个人项目） -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-vector-store-chroma</artifactId>
        </dependency>
        <!-- 阿里云 Tair（阿里云自研 Redis 兼容数据库，支持向量检索；用云上实例时选它） -->
        <dependency>
            <groupId>com.alibaba.cloud.ai</groupId>
            <artifactId>spring-ai-alibaba-starter-store-tair</artifactId>
        </dependency>
        <!-- H2 内存数据库（study.db-type=h2 时使用，零配置直接跑） -->
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <!-- MySQL 驱动（study.db-type=mysql 时使用） -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

application.yml

server:
  port: 8080
spring:
  application:
    name: spring-ai-alibaba-study
  freemarker:
    charset: UTF-8
    content-type: text/html;charset=UTF-8
    enabled: true
    suffix: .ftl
  web:
    resources:
      add-mappings: true
  ai:
    dashscope:
      # 大模型密钥：优先读环境变量 AI_DASHSCOPE_API_KEY，也可以直接把 key 写在下面
      # 获取地址：https://bailian.console.aliyun.com/（阿里云百炼平台）
      # 说明：默认给了一个占位值，保证未配置 Key 时项目也能正常启动（此时调用模型接口会返回友好报错）
      api-key: ${AI_DASHSCOPE_API_KEY:xxxxxxx}
      chat:
        options:
          # 对话模型：必须是阿里云百炼(DashScope)上真实存在的模型名，
          # 常用：qwen-plus(推荐,性价比高) / qwen-max(最强) / qwen-turbo(便宜快速) / qwen-flash(超快)
          # 注意：glm、deepseek 官方版等非阿里模型不能填在这里，会报 "url error, please check url"
          model: qwen-plus
          temperature: 0.7
      embedding:
        options:
          # 嵌入(向量化)模型
          model: text-embedding-v3
    # 重试策略：失败快速返回（默认重试 10 次等待太久，不适合学习项目）
    retry:
      max-attempts: 3
      backoff:
        initial-interval: 2000
        multiplier: 2
        max-interval: 10000
    vectorstore:
      # 关键开关：chroma/milvus/redis 的官方自动装配在该属性"缺失"时会默认激活
      # 并互相冲突（Bean 名都叫 vectorStore）。这里显式指定一个不匹配任何
      # starter 的值，让它们全部让位 —— 向量库统一由下面的 study.vectorstore.type 控制。
      # （这也是 Spring AI 1.0 官方的多向量库切换属性，若想用官方自动装配可改回
      #   redis / milvus / chroma，但本项目为了学习价值选择手动装配）
      type: simple
# ================= 自定义学习项目配置 =================
study:
  # ---------- 模型来源切换 ----------
  model:
    # 对话模型来源：
    #   dashscope - 阿里云百炼（qwen 系列，走 spring-ai-alibaba starter）
    #   openai    - 任意 OpenAI 兼容接口：DeepSeek / 腾讯混元 / 字节豆包 / Kimi / GLM ...
    provider: openai
    # 嵌入模型来源：auto(跟随 provider) / dashscope / openai
    # 注意：DeepSeek 不提供 embedding 接口 —— 对话选 DeepSeek 时保持 auto 即可，
    #       嵌入会自动回退到 DashScope（需保留有效的百炼 Key）
    embedding-provider: auto
    # provider=openai 时生效（各厂商速查，任选其一改这三项即可）：
    #   DeepSeek  base-url: https://api.deepseek.com                     chat-model: deepseek-chat
    #   腾讯混元  base-url: https://api.hunyuan.cloud.tencent.com/v1    chat-model: hunyuan-turbos-latest
    #   字节豆包  base-url: https://ark.cn-beijing.volces.com/api/v3    chat-model: doubao-seed-1-6-250615
    #   Kimi     base-url: https://api.moonshot.cn/v1                  chat-model: moonshot-v1-8k
    #   智谱GLM  base-url: https://open.bigmodel.cn/api/paas/v4        chat-model: glm-4-flash
    openai:
      base-url: https://api.deepseek.com
      # 对应厂商的 API Key（也可用环境变量 OPENAI_COMPATIBLE_API_KEY 覆盖）
      api-key: ${OPENAI_COMPATIBLE_API_KEY:xxxxx}
      chat-model: deepseek-v4-flash
      # 嵌入模型名：混元/豆包/Kimi 等有 embedding 的厂商填对应模型（如 doubao-embedding-large）；
      # DeepSeek 留空即可（自动回退 DashScope 嵌入）
      embedding-model: ""
      temperature: 0.7
  # ---------- 数据库切换 ----------
  # 数据库类型开关：h2(默认，内存库模拟) / mysql(真实博客库)
  # 注意：仅 h2 模式会自动建 content 表并插入示例数据；mysql 模式只读真实库，不做任何建表/写入
  db-type: h2
  mysql:
    # study.db-type=mysql 时生效，改成你真实的博客数据库连接
    url: jdbc:mysql://192.168.192.19:3306/xxx?useUnicode=true&serverTimezone=Asia/Shanghai&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull&autoReconnect=true&allowMultiQueries=true&useSSL=false&allowPublicKeyRetrieval=true
    username: xxxxxx
    password: xxxxxx
    # study.db-type=mysql 时生效：自定义查询 SQL（从真实博客库读取要向量化的内容）
    # 要求返回三列且列名/别名为 id、title、content；改成你需要的表和过滤条件即可
    content-sql: "SELECT id,content_title as title,content_details as content   FROM content  where id='2062803744227950592'"
  # ---------- 向量数据库切换 ----------
  vectorstore:
    # 向量数据库类型：
    #   simple - 内存版（默认，零部署直接跑，重启后需重新初始化 RAG）
    #   tair   - 阿里云 Tair（Redis 协议兼容 + 向量检索，Spring AI Alibaba 官方适配）
    #   redis  - Redis Stack（本地最轻量持久化方案，docker run -p 6379:6379 redis/redis-stack-server）
    #   milvus - Milvus（开源向量数据库，本地 docker 部署，默认端口 19530）
    #   chroma - Chroma（轻量本地向量数据库，docker run -p 8000:8000 chromadb/chroma）
    type: simple
    # 嵌入向量维度：必须与嵌入模型一致！阿里 text-embedding-v3 = 1024
    embedding-dimensions: 1024
    # type=tair 时生效（阿里云 Tair 实例连接信息，控制台获取）
    tair:
      host: r-bp1xxxxxx.redis.rds.aliyuncs.com
      port: 6379
      username: ""
      password: ""
      index-name: study-rag-index
    # type=redis 时生效
    redis:
      host: localhost
      port: 6379
      username: ""
      password: ""
      index-name: study-rag-index
    # type=milvus 时生效
    milvus:
      host: localhost
      port: 19530
      database-name: default
      collection-name: study_rag
    # type=chroma 时生效
    chroma:
      base-url: http://localhost:8000
      collection-name: study_rag
  rag:
    # 启动时是否自动执行 RAG 初始化（向量化 content 表内容，需要有效的 API Key）
    auto-init: false
    # 检索时返回最相似的前 K 段
    top-k: 4
    # content 表为空时是否插入示例博文（方便开箱即用；自己的库有数据则不会插入）
    sample-data-on-empty: true
logging:
  level:
    com.study.saa: info
    org.springframework.ai: info

StudyApplication.java

package com.study.saa;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
/**
 * Spring AI Alibaba 学习项目启动类。
 *
 * <p>启动前请配置通义大模型 API Key（二选一）：
 * <ul>
 *   <li>环境变量 AI_DASHSCOPE_API_KEY=sk-xxx</li>
 *   <li>或直接写入 application.yml: spring.ai.dashscope.api-key</li>
 * </ul>
 *
 * <p>启动后访问首页：http://localhost:8080/
 */
@SpringBootApplication
@ConfigurationPropertiesScan
public class StudyApplication {
    public static void main(String[] args) {
        SpringApplication.run(StudyApplication.class, args);
    }
}

StudyTools.java

package com.study.saa.tools;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
import java.util.Map;
import java.util.concurrent.ThreadLocalRandom;
/**
 * 工具调用（Function Calling）示例：普通 Spring Bean 中的方法加上 @Tool 注解，
 * 即可被大模型在对话过程中自动选择并调用。
 *
 * <p>这里提供两个模拟工具：天气查询、四则运算计算器。
 */
@Component
public class StudyTools {
    /**
     * 模拟天气查询工具（真实项目可对接天气 API）。
     */
    @Tool(description = "查询指定城市的实时天气情况，返回天气现象和温度")
    public String getWeather(
            @ToolParam(description = "城市名称，例如：北京、上海、杭州") String city) {
        // 模拟数据：真实场景替换为天气 API 调用
        Map<String, String> weather = Map.of(
                "北京", "晴, 12°C, 北风3级",
                "上海", "多云, 18°C, 东风2级",
                "杭州", "小雨, 16°C, 东南风3级",
                "深圳", "阴, 26°C, 微风");
        String result = weather.get(city);
        if (result == null) {
            result = "晴转多云, " + (15 + ThreadLocalRandom.current().nextInt(10)) + "°C, 微风";
        }
        return city + "当前天气：" + result;
    }
    /**
     * 四则运算计算器工具。
     */
    @Tool(description = "计算两个整数的四则运算结果，operation 取值：add(加)/subtract(减)/multiply(乘)/divide(除)")
    public double calculate(
            @ToolParam(description = "第一个整数") int a,
            @ToolParam(description = "运算类型：add/subtract/multiply/divide") String operation,
            @ToolParam(description = "第二个整数") int b) {
        return switch (operation) {
            case "add" -> (double) a + b;
            case "subtract" -> (double) a - b;
            case "multiply" -> (double) a * b;
            case "divide" -> b == 0 ? Double.NaN : (double) a / b;
            default -> throw new IllegalArgumentException("不支持的运算类型: " + operation);
        };
    }
}

StudyAgentConfig.java

package com.study.saa.agent;
import com.alibaba.cloud.ai.graph.CompiledGraph;
import com.alibaba.cloud.ai.graph.KeyStrategy;
import com.alibaba.cloud.ai.graph.OverAllState;
import com.alibaba.cloud.ai.graph.OverAllStateFactory;
import com.alibaba.cloud.ai.graph.StateGraph;
import com.alibaba.cloud.ai.graph.action.AsyncEdgeAction;
import com.alibaba.cloud.ai.graph.action.AsyncNodeAction;
import com.alibaba.cloud.ai.graph.state.strategy.ReplaceStrategy;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.Map;
import static com.alibaba.cloud.ai.graph.StateGraph.END;
import static com.alibaba.cloud.ai.graph.StateGraph.START;
/**
 * 示例十：Agent 的创建与使用 —— 基于 Spring AI Alibaba Graph 的工作流智能体。
 *
 * <p>本示例实现一个「学习助手 Agent」，流程：
 * <pre>
 *            ┌────────────┐
 *   START ──▶│ 分类节点    │  LLM 判断问题类型：concept(概念) / code(代码) / chat(闲聊)
 *            └─────┬──────┘
 *      ┌───────────┼─────────────┐
 *      ▼           ▼             ▼        （条件边按分类结果路由）
 * ┌─────────┐ ┌─────────┐  ┌─────────┐
 * │概念讲解  │ │代码助手  │  │闲聊陪伴  │   三个不同的专家节点，各自使用不同的系统提示词
 * └────┬────┘ └────┬────┘  └────┬────┘
 *      └───────────┼─────────────┘
 *                  ▼
 *                 END
 * </pre>
 *
 * <p>核心概念：
 * <ul>
 *   <li>StateGraph：状态图，声明节点(Node)与边(Edge)</li>
 *   <li>NodeAction：节点动作，读取 OverAllState、返回要写入的状态更新</li>
 *   <li>条件边(Conditional Edge) + EdgeAction：根据状态动态决定下一个节点</li>
 *   <li>OverAllState：全局状态，在节点间传递共享数据（input/category/answer）</li>
 * </ul>
 */
@Configuration
public class StudyAgentConfig {
    @Bean
    public CompiledGraph studyAgentGraph(ChatModel chatModel) throws Exception {
        ChatClient chatClient = ChatClient.builder(chatModel).build();
        // 全局状态工厂：注册状态 Key 及其更新策略（ReplaceStrategy 每次写入覆盖旧值）
        OverAllStateFactory stateFactory = () -> {
            OverAllState state = new OverAllState();
            state.registerKeyAndStrategy("input", new ReplaceStrategy());
            state.registerKeyAndStrategy("category", new ReplaceStrategy());
            state.registerKeyAndStrategy("answer", new ReplaceStrategy());
            return state;
        };
        // ---------- 节点 1：意图分类（调用 LLM 判断问题类别） ----------
        var classifyNode = AsyncNodeAction.node_async(state -> {
            String input = readString(state, "input");
            String category = chatClient.prompt()
                    .system("""
                            你是一个问题分类器。判断用户输入属于以下哪一类，只输出类别名，不要任何其他内容：
                            - concept：概念、原理、理论知识类问题
                            - code：代码编写、调试、报错类问题
                            - chat：闲聊、打招呼、与学习无关的内容
                            """)
                    .user(input)
                    .call()
                    .content();
            String result = category == null ? "chat" : category.trim().toLowerCase();
            if (!result.contains("concept") && !result.contains("code")) {
                result = "chat";
            } else if (result.contains("concept")) {
                result = "concept";
            } else {
                result = "code";
            }
            return Map.of("category", result);
        });
        // ---------- 节点 2a：概念讲解专家 ----------
        var conceptNode = AsyncNodeAction.node_async(state -> {
            String input = readString(state, "input");
            String answer = chatClient.prompt()
                    .system("""
                            你是一位耐心的技术导师，擅长把复杂概念讲得通俗易懂。
                            回答结构：一句话定义 -> 生活化类比 -> 展开要点（3 条以内）。
                            """)
                    .user(input)
                    .call()
                    .content();
            return Map.of("answer", "[概念讲解专家] " + (answer == null ? "" : answer));
        });
        // ---------- 节点 2b：代码助手专家 ----------
        var codeNode = AsyncNodeAction.node_async(state -> {
            String input = readString(state, "input");
            String answer = chatClient.prompt()
                    .system("""
                            你是一位资深 Java 工程师。回答代码类问题时：
                            先给出可直接运行的示例代码，再逐段解释关键点，最后提醒常见坑。
                            """)
                    .user(input)
                    .call()
                    .content();
            return Map.of("answer", "[代码助手专家] " + (answer == null ? "" : answer));
        });
        // ---------- 节点 2c：闲聊陪伴 ----------
        var chatNode = AsyncNodeAction.node_async(state -> {
            String input = readString(state, "input");
            String answer = chatClient.prompt()
                    .system("你是一个友好的学习伙伴，轻松简短地回应闲聊，并顺势引导对方聊点技术学习话题。")
                    .user(input)
                    .call()
                    .content();
            return Map.of("answer", "[闲聊伙伴] " + (answer == null ? "" : answer));
        });
        // ---------- 条件边：根据分类结果路由到不同专家节点 ----------
        var dispatcher = AsyncEdgeAction.edge_async(state -> readString(state, "category"));
        // ---------- 组装状态图 ----------
        StateGraph graph = new StateGraph("study-agent", stateFactory)
                .addNode("classify", classifyNode)
                .addNode("concept_expert", conceptNode)
                .addNode("code_expert", codeNode)
                .addNode("chat_expert", chatNode)
                .addEdge(START, "classify")
                .addConditionalEdges("classify", dispatcher, Map.of(
                        "concept", "concept_expert",
                        "code", "code_expert",
                        "chat", "chat_expert"))
                .addEdge("concept_expert", END)
                .addEdge("code_expert", END)
                .addEdge("chat_expert", END);
        return graph.compile();
    }
    private static String readString(OverAllState state, String key) {
        return state.value(key).map(Object::toString).orElse("");
    }
}

AiConfig.java

package com.study.saa.config;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.memory.ChatMemory;
import org.springframework.ai.chat.memory.InMemoryChatMemoryRepository;
import org.springframework.ai.chat.memory.MessageWindowChatMemory;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
 * AI 核心组件配置：
 *
 * <ul>
 *   <li>ChatClient —— Spring AI 提供的高层对话 API（推荐日常使用）</li>
 *   <li>ChatMemory —— 对话记忆：内存实现（每个会话保留最近 20 条消息）。
 *       如需持久化，可引入 spring-ai-starter-model-chat-memory-repository-jdbc
 *       并把 ChatMemoryRepository 换成 JdbcChatMemoryRepository（MySQL 模式）</li>
 *   <li>VectorStore —— 向量存储：已迁移到 {@link VectorStoreConfig}，
 *       支持 simple/tair/redis/milvus/chroma 配置化切换</li>
 * </ul>
 */
@Configuration
public class AiConfig {
    /**
     * 通用 ChatClient：不带记忆，供基础示例使用。
     *
     * <p>注意：这里基于 ModelProviderConfig 中 @Primary 的 ChatModel 构建，
     * 而不是 starter 自动装配的 ChatClient.Builder —— 这样切换模型来源
     * （DashScope / DeepSeek / 混元 / 豆包...）后所有示例自动生效。
     */
    @Bean
    public ChatClient chatClient(ChatModel chatModel) {
        return ChatClient.builder(chatModel).build();
    }
    /**
     * 对话记忆：MessageWindowChatMemory 基于 InMemoryChatMemoryRepository，
     * 按会话 ID 隔离，每个会话保留最近 20 条消息（重启后清空，学习演示够用）。
     */
    @Bean
    public ChatMemory chatMemory() {
        return MessageWindowChatMemory.builder()
                .chatMemoryRepository(new InMemoryChatMemoryRepository())
                .maxMessages(20)
                .build();
    }
}

DataSourceConfig.java

package com.study.saa.config;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.datasource.DriverManagerDataSource;
import javax.sql.DataSource;
/**
 * 数据库配置：通过 study.db-type 开关切换数据源。
 *
 * <p>study.db-type=h2    -> 使用 H2 内存数据库（MySQL 兼容模式），零配置，适合本地学习演示。
 * <p>study.db-type=mysql -> 使用 application.yml 中 study.mysql.* 配置的真实 MySQL 连接。
 *
 * <p>说明：学习项目为了结构清晰直接使用 DriverManagerDataSource（无连接池）；
 * 生产项目请换成 HikariCP 等连接池。
 */
@Configuration
@EnableConfigurationProperties(StudyProperties.class)
public class DataSourceConfig {
    /**
     * H2 内存库（默认）。DB_CLOSE_DELAY=-1 保证应用运行期间库不销毁；MODE=MySQL 兼容 MySQL 语法。
     */
    @Bean
    @ConditionalOnProperty(name = "study.db-type", havingValue = "h2", matchIfMissing = true)
    public DataSource h2DataSource() {
        DriverManagerDataSource ds = new DriverManagerDataSource();
        ds.setDriverClassName("org.h2.Driver");
        ds.setUrl("jdbc:h2:mem:studydb;DB_CLOSE_DELAY=-1;MODE=MySQL;DATABASE_TO_LOWER=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE");
        ds.setUsername("sa");
        ds.setPassword("");
        return ds;
    }
    /**
     * 真实 MySQL（study.db-type=mysql 时生效），连接博客数据库中的 content 表。
     */
    @Bean
    @ConditionalOnProperty(name = "study.db-type", havingValue = "mysql")
    public DataSource mysqlDataSource(StudyProperties properties) {
        DriverManagerDataSource ds = new DriverManagerDataSource();
        ds.setDriverClassName("com.mysql.cj.jdbc.Driver");
        ds.setUrl(properties.getMysql().getUrl());
        ds.setUsername(properties.getMysql().getUsername());
        ds.setPassword(properties.getMysql().getPassword());
        return ds;
    }
}

ModelProviderConfig.java

package com.study.saa.config;
import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatModel;
import com.alibaba.cloud.ai.dashscope.embedding.DashScopeEmbeddingModel;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.document.MetadataMode;
import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.ai.openai.OpenAiEmbeddingModel;
import org.springframework.ai.openai.OpenAiChatOptions;
import org.springframework.ai.openai.OpenAiEmbeddingOptions;
import org.springframework.ai.openai.api.OpenAiApi;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.beans.factory.config.BeanDefinition;
import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Conditional;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.core.type.AnnotatedTypeMetadata;
/**
 * 模型来源（Provider）切换配置 —— 学习重点：多模型厂商接入。
 *
 * <p>Spring AI 中不同厂商的模型都以 ChatModel / EmbeddingModel 接口暴露，
 * 业务代码（ChatClient、RAG、Agent...）只面向接口，切换厂商零改动。
 *
 * <p>本项目支持两条通道（由 study.model.provider 决定）：
 * <ul>
 *   <li><b>dashscope</b>：阿里云百炼（通义千问 qwen 系列），
 *       直接使用 spring-ai-alibaba-starter-dashscope 自动装配的 Bean；</li>
 *   <li><b>openai</b>：任意 OpenAI 兼容接口 —— DeepSeek、腾讯混元、字节豆包(火山方舟)、
 *       Kimi、智谱 GLM 等厂商都提供该协议，只需改 base-url / api-key / model 三个配置。</li>
 * </ul>
 *
 * <p>常见厂商 OpenAI 兼容接口速查（填到 study.model.openai.base-url）：
 * <pre>
 *   DeepSeek   https://api.deepseek.com                    模型: deepseek-chat / deepseek-reasoner（无 embedding 接口）
 *   腾讯混元   https://api.hunyuan.cloud.tencent.com/v1    模型: hunyuan-turbos-latest 等
 *   字节豆包   https://ark.cn-beijing.volces.com/api/v3    模型: doubao-seed-1-6-250615 / doubao-embedding-large 等
 *   Kimi       https://api.moonshot.cn/v1                  模型: moonshot-v1-8k 等
 *   智谱 GLM   https://open.bigmodel.cn/api/paas/v4        模型: glm-4-flash 等
 * </pre>
 *
 * <p>实现要点（值得学习的 Spring 技巧）：
 * DashScope starter 自动装配出来的 Bean 自带 @Primary；当切换到 openai 通道时，
 * 通过 {@link #dashScopePrimaryDemoter()}（BeanFactoryPostProcessor）把 starter Bean
 * 的 primary 标记降级，再装配自己的 @Primary Bean，从而避免「两个 primary」注入歧义。
 */
@Configuration
public class ModelProviderConfig {
    private static final Logger log = LoggerFactory.getLogger(ModelProviderConfig.class);
    /**
     * 切换通道时降级 DashScope starter 的 primary Bean（只改标记，不删除 Bean ——
     * 嵌入模型回退等场景仍可能用到它）。
     */
    @Bean
    public static BeanFactoryPostProcessor dashScopePrimaryDemoter() {
        return beanFactory -> {
            // Environment 是容器启动时手动注册的单例，此处可安全获取
            org.springframework.core.env.Environment env =
                    beanFactory.getBean(org.springframework.core.env.Environment.class);
            String provider = env.getProperty("study.model.provider", "dashscope");
            String embeddingProvider = env.getProperty("study.model.embedding-provider", "auto");
            boolean chatUseOpenai = "openai".equalsIgnoreCase(provider);
            boolean embeddingUseOpenai = "openai".equalsIgnoreCase(embeddingProvider)
                    || ("auto".equalsIgnoreCase(embeddingProvider) && chatUseOpenai);
            if (chatUseOpenai) {
                demotePrimary(beanFactory, DashScopeChatModel.class, "对话");
            }
            if (embeddingUseOpenai) {
                demotePrimary(beanFactory, DashScopeEmbeddingModel.class, "嵌入");
            }
        };
    }
    private static void demotePrimary(ConfigurableListableBeanFactory beanFactory,
                                      Class<?> beanClass, String label) {
        for (String name : beanFactory.getBeanDefinitionNames()) {
            // 自动配置的 Bean 通常由 @Bean 工厂方法创建（getBeanClassName 为 null），
            // 因此用 getType(name) 解析实际类型再比较
            Class<?> type = beanFactory.getType(name);
            if (type != null && beanClass.isAssignableFrom(type)) {
                BeanDefinition bd = beanFactory.getBeanDefinition(name);
                if (bd.isPrimary()) {
                    bd.setPrimary(false);
                    log.info("{}通道切换为 OpenAI 兼容接口，已降级 DashScope Bean [{}] 的 primary 标记", label, name);
                }
            }
        }
    }
    /**
     * 对话模型（openai 通道）：study.model.provider=openai 时生效。
     * 所有注入 ChatModel 的地方（ChatClient、RAG、Agent...）自动拿到它。
     */
    @Bean
    @Primary
    @ConditionalOnProperty(name = "study.model.provider", havingValue = "openai")
    public ChatModel chatModel(StudyProperties properties,
                               ObjectProvider<DashScopeChatModel> dashscopeChatModel) {
        StudyProperties.Model.OpenAi o = properties.getModel().getOpenai();
        log.info("对话模型走 OpenAI 兼容通道：{}，模型：{}", o.getBaseUrl(), o.getChatModel());
        OpenAiApi api = OpenAiApi.builder()
                .baseUrl(o.getBaseUrl())
                .apiKey(o.getApiKey())
                .build();
        return OpenAiChatModel.builder()
                .openAiApi(api)
                .defaultOptions(OpenAiChatOptions.builder()
                        .model(o.getChatModel())
                        .temperature(o.getTemperature())
                        .build())
                .build();
    }
    /**
     * 嵌入模型（openai 通道）：study.model.embedding-provider=openai，
     * 或 =auto 且 provider=openai 时生效。
     *
     * <p>典型组合：
     * <ul>
     *   <li>对话 DeepSeek + 嵌入 DashScope（DeepSeek 无 embedding 接口，
     *       此时保持 embedding-provider=auto 且不填 embedding-model，自动回退）</li>
     *   <li>对话与嵌入都走混元/豆包/Kimi（填上对应的 embedding-model 即可）</li>
     * </ul>
     */
    @Bean
    @Primary
    @Conditional(ModelProviderConfig.EmbeddingUseOpenAiCondition.class)
    public EmbeddingModel embeddingModel(StudyProperties properties,
                                         ObjectProvider<DashScopeEmbeddingModel> dashscopeEmbeddingModel) {
        StudyProperties.Model.OpenAi o = properties.getModel().getOpenai();
        if (o.getEmbeddingModel() == null || o.getEmbeddingModel().isBlank()) {
            // 未配置 OpenAI 兼容嵌入模型（例如只配了 DeepSeek）→ 回退 DashScope 嵌入模型
            log.info("未配置 OpenAI 兼容嵌入模型，嵌入模型回退 DashScope(text-embedding-v3)");
            return dashscopeEmbeddingModel.getIfAvailable(() -> {
                throw new IllegalStateException(
                        "嵌入模型不可用：请在 study.model.openai.embedding-model 配置嵌入模型，或提供 DashScope API Key 作为回退");
            });
        }
        log.info("嵌入模型走 OpenAI 兼容通道：{}，模型：{}", o.getBaseUrl(), o.getEmbeddingModel());
        OpenAiApi api = OpenAiApi.builder()
                .baseUrl(o.getBaseUrl())
                .apiKey(o.getApiKey())
                .build();
        return new OpenAiEmbeddingModel(api, MetadataMode.EMBED,
                OpenAiEmbeddingOptions.builder()
                        .model(o.getEmbeddingModel())
                        .build());
    }
    /** 条件：嵌入模型走 OpenAI 兼容通道（embedding-provider=openai，或 auto 且 provider=openai） */
    static class EmbeddingUseOpenAiCondition implements org.springframework.context.annotation.Condition {
        @Override
        public boolean matches(org.springframework.context.annotation.ConditionContext context,
                               AnnotatedTypeMetadata metadata) {
            String provider = context.getEnvironment().getProperty("study.model.provider", "dashscope");
            String embeddingProvider = context.getEnvironment()
                    .getProperty("study.model.embedding-provider", "auto");
            return "openai".equalsIgnoreCase(embeddingProvider)
                    || ("auto".equalsIgnoreCase(embeddingProvider) && "openai".equalsIgnoreCase(provider));
        }
    }
}

StudyProperties.java

package com.study.saa.config;
import org.springframework.boot.context.properties.ConfigurationProperties;
/**
 * 学习项目自定义配置（对应 application.yml 中 study.* 前缀）。
 */
@ConfigurationProperties(prefix = "study")
public class StudyProperties {
    /** 数据库类型开关：h2 / mysql */
    private String dbType = "h2";
    private Mysql mysql = new Mysql();
    private Rag rag = new Rag();
    private Model model = new Model();
    private VectorStoreGroup vectorStore = new VectorStoreGroup();
    /**
     * 向量数据库配置：支持内存 / 阿里云 Tair / Redis / Milvus / Chroma 五种，
     * 由 study.vectorstore.type 一键切换，业务代码零改动（统一面向 VectorStore 接口）。
     */
    public static class VectorStoreGroup {
        /**
         * 向量数据库类型：
         * - simple：内存版（默认，零部署直接跑）
         * - tair  ：阿里云 Tair（Redis 协议兼容 + 向量检索增强）
         * - redis ：Redis Stack（本地 docker run redis-stack 即可）
         * - milvus：Milvus（开源向量数据库，本地 docker 部署）
         * - chroma：Chroma（轻量本地向量数据库）
         */
        private String type = "simple";
        /**
         * 嵌入向量维度：必须与所用嵌入模型输出维度一致！
         * 阿里 text-embedding-v3 = 1024；切换嵌入模型时记得同步修改。
         */
        private int embeddingDimensions = 1024;
        private Tair tair = new Tair();
        private Redis redis = new Redis();
        private Milvus milvus = new Milvus();
        private Chroma chroma = new Chroma();
        /** 阿里云 Tair 连接配置（type=tair 时生效） */
        public static class Tair {
            private String host = "r-xxx.redis.rds.aliyuncs.com";
            private int port = 6379;
            /** ACL 用户名，经典部署（仅密码）可留空 */
            private String username = "";
            private String password = "";
            /** 向量索引名 */
            private String indexName = "study-rag-index";
            public String getHost() { return host; }
            public void setHost(String host) { this.host = host; }
            public int getPort() { return port; }
            public void setPort(int port) { this.port = port; }
            public String getUsername() { return username; }
            public void setUsername(String username) { this.username = username; }
            public String getPassword() { return password; }
            public void setPassword(String password) { this.password = password; }
            public String getIndexName() { return indexName; }
            public void setIndexName(String indexName) { this.indexName = indexName; }
        }
        /** Redis Stack 连接配置（type=redis 时生效） */
        public static class Redis {
            private String host = "localhost";
            private int port = 6379;
            private String username = "";
            private String password = "";
            private String indexName = "study-rag-index";
            public String getHost() { return host; }
            public void setHost(String host) { this.host = host; }
            public int getPort() { return port; }
            public void setPort(int port) { this.port = port; }
            public String getUsername() { return username; }
            public void setUsername(String username) { this.username = username; }
            public String getPassword() { return password; }
            public void setPassword(String password) { this.password = password; }
            public String getIndexName() { return indexName; }
            public void setIndexName(String indexName) { this.indexName = indexName; }
        }
        /** Milvus 连接配置（type=milvus 时生效） */
        public static class Milvus {
            private String host = "localhost";
            private int port = 19530;
            private String databaseName = "default";
            private String collectionName = "study_rag";
            public String getHost() { return host; }
            public void setHost(String host) { this.host = host; }
            public int getPort() { return port; }
            public void setPort(int port) { this.port = port; }
            public String getDatabaseName() { return databaseName; }
            public void setDatabaseName(String databaseName) { this.databaseName = databaseName; }
            public String getCollectionName() { return collectionName; }
            public void setCollectionName(String collectionName) { this.collectionName = collectionName; }
        }
        /** Chroma 连接配置（type=chroma 时生效） */
        public static class Chroma {
            private String baseUrl = "http://localhost:8000";
            private String collectionName = "study_rag";
            public String getBaseUrl() { return baseUrl; }
            public void setBaseUrl(String baseUrl) { this.baseUrl = baseUrl; }
            public String getCollectionName() { return collectionName; }
            public void setCollectionName(String collectionName) { this.collectionName = collectionName; }
        }
        public String getType() { return type; }
        public void setType(String type) { this.type = type; }
        public int getEmbeddingDimensions() { return embeddingDimensions; }
        public void setEmbeddingDimensions(int embeddingDimensions) { this.embeddingDimensions = embeddingDimensions; }
        public Tair getTair() { return tair; }
        public void setTair(Tair tair) { this.tair = tair; }
        public Redis getRedis() { return redis; }
        public void setRedis(Redis redis) { this.redis = redis; }
        public Milvus getMilvus() { return milvus; }
        public void setMilvus(Milvus milvus) { this.milvus = milvus; }
        public Chroma getChroma() { return chroma; }
        public void setChroma(Chroma chroma) { this.chroma = chroma; }
    }
    public VectorStoreGroup getVectorStore() { return vectorStore; }
    public void setVectorStore(VectorStoreGroup vectorStore) { this.vectorStore = vectorStore; }
    /**
     * 模型来源配置：支持阿里云百炼(DashScope) 与 任意 OpenAI 兼容接口 两种通道。
     */
    public static class Model {
        /**
         * 对话模型来源：
         * - dashscope：阿里云百炼（qwen 系列，走 spring-ai-alibaba-starter-dashscope）
         * - openai：任意 OpenAI 兼容接口（DeepSeek / 腾讯混元 / 字节豆包 / Kimi / GLM ...）
         */
        private String provider = "dashscope";
        /**
         * 嵌入模型来源：auto(跟随 provider) / dashscope / openai。
         * 注意：DeepSeek 不提供 embedding 接口 —— 对话选 DeepSeek 时，
         * 建议这里配 dashscope（混元/豆包/Kimi/GLM 则可配 openai）。
         */
        private String embeddingProvider = "auto";
        private OpenAi openai = new OpenAi();
        public static class OpenAi {
            /** OpenAI 兼容接口地址，例如 https://api.deepseek.com */
            private String baseUrl = "https://api.deepseek.com";
            /** 对应厂商的 API Key（也可用环境变量 OPENAI_COMPATIBLE_API_KEY） */
            private String apiKey = "";
            /** 对话模型名，例如 deepseek-chat / deepseek-reasoner */
            private String chatModel = "deepseek-chat";
            /** 嵌入模型名，留空则回退 DashScope 嵌入模型 */
            private String embeddingModel = "";
            /** 对话温度 */
            private Double temperature = 0.7;
            public String getBaseUrl() { return baseUrl; }
            public void setBaseUrl(String baseUrl) { this.baseUrl = baseUrl; }
            public String getApiKey() { return apiKey; }
            public void setApiKey(String apiKey) { this.apiKey = apiKey; }
            public String getChatModel() { return chatModel; }
            public void setChatModel(String chatModel) { this.chatModel = chatModel; }
            public String getEmbeddingModel() { return embeddingModel; }
            public void setEmbeddingModel(String embeddingModel) { this.embeddingModel = embeddingModel; }
            public Double getTemperature() { return temperature; }
            public void setTemperature(Double temperature) { this.temperature = temperature; }
        }
        public String getProvider() { return provider; }
        public void setProvider(String provider) { this.provider = provider; }
        public String getEmbeddingProvider() { return embeddingProvider; }
        public void setEmbeddingProvider(String embeddingProvider) { this.embeddingProvider = embeddingProvider; }
        public OpenAi getOpenai() { return openai; }
        public void setOpenai(OpenAi openai) { this.openai = openai; }
        /** 解析后的对话通道：true 表示走 OpenAI 兼容接口 */
        public boolean isOpenAiCompatible() { return "openai".equalsIgnoreCase(provider); }
        /** 解析后的嵌入通道：true 表示走 OpenAI 兼容接口 */
        public boolean embeddingUseOpenAi() {
            if ("auto".equalsIgnoreCase(embeddingProvider)) return isOpenAiCompatible();
            return "openai".equalsIgnoreCase(embeddingProvider);
        }
    }
    public Model getModel() { return model; }
    public void setModel(Model model) { this.model = model; }
    public static class Mysql {
        private String url;
        private String username;
        private String password;
        /**
         * 自定义查询 SQL（study.db-type=mysql 时生效）：
         * 从你的真实博客库读取用于 RAG 向量化的内容。
         * 要求返回三列且列名/别名为 id、title、content。
         */
        private String contentSql = "SELECT id, title, content FROM content ORDER BY id";
        public String getUrl() {
            return url;
        }
        public void setUrl(String url) {
            this.url = url;
        }
        public String getUsername() {
            return username;
        }
        public void setUsername(String username) {
            this.username = username;
        }
        public String getPassword() {
            return password;
        }
        public void setPassword(String password) {
            this.password = password;
        }
        public String getContentSql() {
            return contentSql;
        }
        public void setContentSql(String contentSql) {
            this.contentSql = contentSql;
        }
    }
    public static class Rag {
        /** 启动时是否自动执行 RAG 初始化 */
        private boolean autoInit = true;
        /** 检索返回 Top-K */
        private int topK = 4;
        /** content 表为空时是否插入示例博文 */
        private boolean sampleDataOnEmpty = true;
        public boolean isAutoInit() {
            return autoInit;
        }
        public void setAutoInit(boolean autoInit) {
            this.autoInit = autoInit;
        }
        public int getTopK() {
            return topK;
        }
        public void setTopK(int topK) {
            this.topK = topK;
        }
        public boolean isSampleDataOnEmpty() {
            return sampleDataOnEmpty;
        }
        public void setSampleDataOnEmpty(boolean sampleDataOnEmpty) {
            this.sampleDataOnEmpty = sampleDataOnEmpty;
        }
    }
    public String getDbType() {
        return dbType;
    }
    public void setDbType(String dbType) {
        this.dbType = dbType;
    }
    public Mysql getMysql() {
        return mysql;
    }
    public void setMysql(Mysql mysql) {
        this.mysql = mysql;
    }
    public Rag getRag() {
        return rag;
    }
    public void setRag(Rag rag) {
        this.rag = rag;
    }
}