Spring AI Alibaba + Ollama 实战教程(基于本地 Qwen3 的 Spring Boot 大模型应用)

<properties>
    <!-- 项目使用的 jdk 版本 -->
    <java.version>17</java.version>
    <!-- spring ai alibaba 相关依赖统一使用的版本 -->
    <spring-ai-alibaba.version>1.1.0.0-m5</spring-ai-alibaba.version>
    <!-- spring ai 核心依赖统一使用的版本 -->
    <spring-ai.version>1.1.0</spring-ai.version>
</properties>
<dependencies>
    <!-- 基础 web 能力：提供 spring mvc / 内嵌容器等 -->
    <dependency>
        <groupid>org.springframework.boot</groupid>
        <artifactid>spring-boot-starter-web</artifactid>
    </dependency>
    <!-- 通过 spring ai 访问本地 ollama 大模型服务 -->
    <dependency>
        <groupid>org.springframework.ai</groupid>
        <artifactid>spring-ai-starter-model-ollama</artifactid>
    </dependency>
    <!-- 向量数据库：spring ai 对 pgvector 的封装 -->
    <dependency>
        <groupid>org.springframework.ai</groupid>
        <artifactid>spring-ai-starter-vector-store-pgvector</artifactid>
    </dependency>
    <!-- postgresql jdbc 驱动，用于访问数据库 -->
    <dependency>
        <groupid>org.postgresql</groupid>
        <artifactid>postgresql</artifactid>
    </dependency>
</dependencies>
<dependencymanagement>
    <dependencies>
        <!-- spring ai alibaba 统一版本管理（国内生态相关依赖） -->
        <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（核心抽象与 starter 的版本对齐） -->
        <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>

server:
  port: 8081                 # 应用监听端口
  servlet:
    context-path: /alibaba-ai  # 统一的服务前缀
spring:
  ai:
    ollama:
      base-url: http://localhost:11434  # 本地 ollama 服务地址
      chat:
        options:
          model: qwen3:0.6b             # 聊天用的 qwen3 模型名称
          temperature: 0.8              # 采样温度，越高回答越发散
      embedding:
        options:
          model: qwen3-embedding:0.6b   # 用于向量化的 embedding 模型
    vectorstore:
      pgvector:
        dimensions: 1024                # 向量维度，需要与 embedding 模型输出一致
        distance-type: cosine_distance  # 相似度度量方式
        initialize-schema: true         # 启动时自动创建 pgvector 表结构
  datasource:
    url: jdbc:postgresql://<your-host>:5432/postgres?servertimezone=asia/shanghai  # postgresql 连接串
    username: postgres
    password: ****                      # 建议通过环境变量或配置中心注入

@restcontroller
@requestmapping("/chatmodel")
public class chatmodelcontroller {
    // 注入由 spring ai 自动装配的 ollama chatmodel
    private final chatmodel ollamachatmodel;
    public chatmodelcontroller(chatmodel ollamachatmodel) {
        this.ollamachatmodel = ollamachatmodel;
    }
    @getmapping("/chat")
    public flux<string> chat(@requestparam("message") string message) {
        // message：用户输入的自然语言问题
        return ollamachatmodel.stream(new prompt(message))     // 以流式方式调用大模型
                .map(chatresponse::getresult)                  // 提取每个增量响应的结果对象
                .mapnotnull(result -> result.getoutput().gettext()); // 只保留最终输出的文本内容
    }
}

@restcontroller
@requestmapping("/chatclient")
public class chatclientcontroller {
    // 基于 chatmodel 封装的高级客户端，后续可以挂接 adviser、工具等能力
    private final chatclient ollamachatclient;
    public chatclientcontroller(chatclient ollamachatclient) {
        this.ollamachatclient = ollamachatclient;
    }
    @getmapping("/chat")
    public flux<string> stream(@requestparam("message") string message) {
        // 使用最简单的 prompt，直接将用户输入交给大模型，并以流式方式返回结果
        return ollamachatclient
                .prompt(new prompt(message))  // 构造 prompt 对象
                .stream()                     // 流式调用
                .content();                   // 提取文本内容
    }
    @getmapping("/prompt")
    public flux<string> prompt() {
        prompttemplate template = prompttemplate.builder()
                .template("请用简短中文回答：{question}") // 模板中定义占位符 {question}
                .variables(map.of())                   // 这里可以预先声明变量，也可以在 create 时传入
                .build();
        // 使用实际问题填充模板变量
        prompt prompt = template.create(map.of("question", "spring ai alibaba 有什么特点？"));
        return ollamachatclient.prompt(prompt).stream().content();
    }
}

@component
public class simplememories implements chatmemory {
    private static final map<string, list<message>> memories_cache = new hashmap<>();
    @override
    public void add(string conversationid, list<message> messages) {
        // conversationid：会话标识；messages：本轮新增的消息列表
        list<message> memories = memories_cache.getordefault(conversationid, new arraylist<>());
        if (messages != null && !messages.isempty()) {
            memories.addall(messages);
        }
        memories_cache.put(conversationid, memories);
    }
    @override
    public list<message> get(string conversationid) {
        // 根据会话 id 取出该会话的历史消息
        return memories_cache.getordefault(conversationid, new arraylist<>());
    }
    @override
    public void clear(string conversationid) {
        // 清空某个会话的记忆
        list<message> messages = memories_cache.get(conversationid);
        if (messages != null) {
            messages.clear();
        }
    }
}

@component
public class memoriesadviser implements baseadvisor {
    private static final map<string, list<message>> memories = new hashmap<>();
    // 用于在 chatclient 的上下文中标识当前会话 id 的 key
    private static final string chat_memories_session_id = "chat_memories_session_id";
    @override
    public chatclientrequest before(chatclientrequest request, advisorchain chain) {
        // 从上下文中读取会话 id，并取出其历史消息
        string sessionid = request.context().get(chat_memories_session_id).tostring();
        list<message> messages = memories.getordefault(sessionid, new arraylist<>());
        // 当前请求的消息放到历史消息后面，一起交给大模型
        messages.addall(request.prompt().getinstructions());
        prompt prompt = request.prompt().mutate().messages(messages).build();
        return request.mutate().prompt(prompt).build();
    }
    @override
    public chatclientresponse after(chatclientresponse response, advisorchain chain) {
        // 把本次大模型回复写回到对应会话的记忆中
        assistantmessage output = response.chatresponse().getresult().getoutput();
        string sessionid = response.context().get(chat_memories_session_id).tostring();
        list<message> messages = memories.getordefault(sessionid, new arraylist<>());
        messages.add(output);
        memories.put(sessionid, messages);
        return response;
    }
}

@restcontroller
@requestmapping("/rag")
public class ragchatclientcontroller {
    private final chatclient ragchatclient;
    private final pgvectorstore pgvectorstore;
    public ragchatclientcontroller(chatclient ragchatclient, pgvectorstore pgvectorstore) {
        this.ragchatclient = ragchatclient;
        this.pgvectorstore = pgvectorstore;
    }
    @getmapping("/embedding")
    public void embeddingcontent(@requestparam("message") string message) {
        // message：待向量化的原始文本内容
        tokentextsplitter splitter = tokentextsplitter.builder()
                .withchunksize(50)                 // 每个分片的最大 token 数
                .withkeepseparator(true)           // 是否保留分隔符（如换行符）
                .withmaxnumchunks(1024)            // 单次允许生成的最大分片数
                .withminchunklengthtoembed(20)     // 小于该长度的分片不入库，避免噪声
                .withminchunksizechars(10)         // 切分时的最小字符数，避免切得过碎
                .build();
        list<document> docs = splitter.split(document.builder().text(message).build()); // 将文本切分为多个 document
        pgvectorstore.add(docs); // 写入 pgvector 向量库
    }
}

@configuration
public class vectorchatclientconfig {
    @bean("ragchatclient")
    public chatclient ragchatclient(chatmodel chatmodel, vectorstore vectorstore) {
        vectorstoredocumentretriever retriever = vectorstoredocumentretriever.builder()
                .vectorstore(vectorstore)     // 具体使用的向量库实现，这里是 pgvector
                .topk(3)                      // 每次检索返回相似度最高的前 3 条文档
                .similaritythreshold(0.5)     // 相似度阈值，小于该值的文档会被过滤掉
                .build();
        retrievalaugmentationadvisor advisor = retrievalaugmentationadvisor.builder()
                .documentretriever(retriever) // 指定文档检索器
                .order(0)                     // adviser 执行顺序，越小越先执行
                .build();
        return chatclient.builder(chatmodel)
                .defaultadvisors(advisor)     // 默认启用 rag 能力
                .build();
    }
}

@component
public class zoomtool {
    @tool(description = "通过时区 id 获取当前时间")
    public string gettimebyzone(@toolparam(description = "时区 id，比如 asia/shanghai") string zone) {
        // zone：时区 id，示例：asia/shanghai、europe/berlin
        zoneid zoneid = zoneid.of(zone);
        zoneddatetime now = zoneddatetime.now(zoneid);
        return datetimeformatter.ofpattern("yyyy-mm-dd hh:mm:ss").format(now); // 返回格式化后的时间字符串
    }
}

@configuration
public class toolchatclientconfig {
    @bean("toolchatclient")
    public chatclient toolchatclient(chatmodel ollamachatmodel, zoomtool zoomtool) {
        // ollamachatmodel：底层使用的 qwen3 模型；zoomtool：提供获取时间的业务工具
        return chatclient.builder(ollamachatmodel)
                .defaultsystem(this.systemprompt()) // 设置默认的系统提示词，统一咖啡馆背景
                .defaulttools(zoomtool)             // 将 zoomtool 注册为可调用的工具
                .build();
    }
    private string systemprompt() {
        map<string, object> vars = new hashmap<>();
        vars.put("american", "1-3");          // 美式咖啡制作时间（分钟）
        vars.put("latte", "2");               // 拿铁咖啡制作时间（分钟）
        vars.put("time_zone", "asia/shanghai"); // 默认时区 id
        systemprompttemplate tpl = systemprompttemplate.builder()
                .template("欢迎光临 zhoubyte咖啡馆，... 默认时区：{time_zone}") // 系统提示词模板
                .variables(vars)                                          // 绑定上面的变量
                .build();
        return tpl.render(); // 渲染出包含具体变量值的系统提示词
    }
}

@restcontroller
@requestmapping("/tool")
public class toolchatcontroller {
    private final chatclient toolchatclient;
    public toolchatcontroller(chatclient toolchatclient) {
        this.toolchatclient = toolchatclient;
    }
    @getmapping("/chat")
    public flux<string> chat(@requestparam("message") string message) {
        return toolchatclient
                .prompt()          // 创建一次新的对话请求
                .user(message)     // 添加一条用户消息
                .stream()          // 流式调用大模型
                .content();        // 只提取文本内容返回
    }
}

@configuration
public class graphconfig {
    @bean("quickstartgraph")
    public compiledgraph quickstartgraph() throws graphstateexception {
        // "quickstartgraph"：图名称；后面的 map 用于定义状态 key 的合并策略
        stategraph graph = new stategraph("quickstartgraph", () -> map.of(
                "input", new replacestrategy(),  // 多次写入时，后写入的值覆盖之前的值
                "output", new replacestrategy()
        ));
        graph.addnode("node1", asyncnodeaction.node_async(state -> {
            // node1：设置初始 input 和 output
            return map.of("input", "graphconfig_addnode", "output", "graphconfig_output");
        }));
        graph.addnode("node2", asyncnodeaction.node_async(state -> {
            // node2：模拟业务处理，将 input 改为 zhoubyte
            return map.of("input", "zhoubyte", "output", "empty");
        }));
        // 定义执行顺序：start -> node1 -> node2 -> end
        graph.addedge(stategraph.start, "node1")
             .addedge("node1", "node2")
             .addedge("node2", stategraph.end);
        return graph.compile();
    }
}

@restcontroller
@requestmapping("/v1")
public class graphcontroller {
    @resource
    private compiledgraph quickstartgraph;
    @getmapping("/graph")
    public flux<string> startgraph() {
        // 这里传入空的初始状态 map，按定义好的 stategraph 顺序执行
        return quickstartgraph.stream(map.of())
                .map(nodeoutput::tostring); // 将每个节点的输出对象转换为字符串返回
    }
}

@configuration
public class conditionalgraphconfig {
    @bean("scoredecisiongraph")
    public compiledgraph scoredecisiongraph() throws graphstateexception {
        stategraph graph = new stategraph("scoredecisiongraph", () -> map.of(
                "score", new replacestrategy(),   // 保存当前评分
                "result", new replacestrategy()   // 保存决策结果
        ));
        // 读取或设置评分（示例中从 state 中读取，实际可由外部请求传入）
        graph.addnode("checkscore", asyncnodeaction.node_async(state -> {
            integer score = (integer) state.value("score").orelse(75); // 默认 75 分
            return map.of("score", score);
        }));
        // 三个业务分支节点：通过 / 复核 / 拒绝
        graph.addnode("pass", asyncnodeaction.node_async(state ->
                map.of("result", "pass")));
        graph.addnode("review", asyncnodeaction.node_async(state ->
                map.of("result", "review")));
        graph.addnode("reject", asyncnodeaction.node_async(state ->
                map.of("result", "reject")));
        // 起点先进入评分检查节点
        graph.addedge(stategraph.start, "checkscore");
        // 多条件边：根据 score 返回不同的“标签”，再由 mappings 决定下一跳节点
        graph.addconditionaledges("checkscore",
                asyncedgeaction.edge_async(state -> {
                    int score = (integer) state.value("score").orelse(0);
                    if (score >= 80) {
                        return "pass";
                    }
                    if (score >= 60) {
                        return "review";
                    }
                    return "reject";
                }),
                map.of(
                        "pass", "pass",
                        "review", "review",
                        "reject", "reject"
                )
        );
        // 三个结果节点最终都指向 end
        graph.addedge("pass", stategraph.end);
        graph.addedge("review", stategraph.end);
        graph.addedge("reject", stategraph.end);
        return graph.compile();
    }
}

<dependency>
    <groupid>com.alibaba.cloud.ai</groupid>
    <artifactid>spring-ai-alibaba-starter-dashscope</artifactid>
    <version>1.1.0.0-m5</version>
</dependency>

spring:
  ai:
    dashscope:
      api-key: ${dashscope_api_key}      # 从环境变量或配置中心读取 dashscope 的 api key
      endpoint: https://dashscope.aliyuncs.com
      chat:
        options:
          model: qwen-plus              # 使用的通义千问在线模型
          temperature: 0.8              # 采样温度
          max-tokens: 2048              # 单次回答的最大 token 数