Spring AI
=========

环境搭建
------------------

在pom.xml中添加以下配置仓库的代码

.. code-block:: xml

    <repositories>
        <repository>
            <id>spring-snapshots</id>
            <name>Spring Snapshots</name>
            <url>https://repo.spring.io/snapshot</url>
            <releases>
                <enabled>false</enabled>
            </releases>
        </repository>
        <repository>
            <name>Central Portal Snapshots</name>
            <id>central-portal-snapshots</id>
            <url>https://central.sonatype.com/repository/maven-snapshots/</url>
            <releases>
                <enabled>false</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>

修改maven的setting.xml文件，添加以下配置，主要是解决spring仓库不需要走镜像。

url可以设置成阿里云的镜像地址。

.. code-block:: xml

    <mirror>
        <id>my-mirror</id>
        <mirrorOf>*,!spring-snapshots,!central-portal-snapshots</mirrorOf>
        <url>https://my-company-repository.com/maven</url>
    </mirror>

在pom.xml中添加以下仓库管理的配置：

.. code-block:: xml

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>1.0.0-SNAPSHOT</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>


在pom.xml中添加以下依赖：

.. code-block:: xml

    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-deepseek</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>


    
要理理解Spring AI的消息模型
--------------------------------

.. image:: https://docs.spring.io/spring-ai/reference/_images/spring-ai-message-api.jpg
    :alt: Spring AI消息模型
    :width: 100%
    :align: center


以下流程图说明了 Spring AI 如何处理 Chat 模型的配置和执行过程，结合了启动时和运行时的配置选项：

.. image:: https://docs.spring.io/spring-ai/reference/_images/chat-options-flow.jpg
    :alt: Spring AI如何处理Chat模型的配置和执行过程
    :width: 100%
    :align: center


- 启动配置 - ChatModel/StreamingChatModel 在初始化时会使用“启动”聊天选项。这些选项在模型初始化期间设置，作为默认配置使用。
- 运行时配置 - 对于每个请求，Prompt（提示）可以包含运行时聊天选项：这些选项可以覆盖启动时的配置。
- 选项合并过程 - “选项合并”步骤会将启动配置和运行时配置合并。如果提供了运行时配置，则它们优先于启动配置。
- 输入处理 - “输入转换”步骤将输入的指令转换为模型特定的原生格式。
- 输出处理 - “输出转换”步骤将模型的响应转换为标准化的 ChatResponse 格式。


该图展示了统一的接口 —— ChatModel 和 StreamingChatModel —— 被用于与来自不同提供商的各种 AI 聊天模型交互。这种设计使得在不同 AI 服务之间轻松集成与切换成为可能，同时为客户端应用程序保持一致的 API 接口。

.. image:: https://docs.spring.io/spring-ai/reference/_images/spring-ai-chat-completions-clients.jpg
    :alt: Available Implementations
    :width: 100%
    :align: center

Spring AI 聊天模型 API 构建于 Spring AI 通用模型 API 之上，提供了针对聊天功能的抽象和实现。这使得在不同的 AI 服务之间能够轻松集成与切换，同时为客户端应用程序保持一致的 API 接口。下图的类图展示了 Spring AI 聊天模型 API 的主要类和接口。

.. image:: https://docs.spring.io/spring-ai/reference/_images/spring-ai-chat-api.jpg
    :alt: Chat Model API
    :width: 100%
    :align: center

Prompts
--------------------------------

提示词（Prompts）是引导 AI 模型生成特定输出的输入内容。提示词的设计与措辞对模型的响应结果有着显著影响。

在 Spring AI 中，与 AI 模型交互的最低层面就是处理提示词。这种处理方式与在 Spring MVC 中管理“视图（View）”有些类似：你需要编写包含占位符的大段文本，这些占位符会根据用户请求或应用中的其他代码动态替换。另一个类比是 SQL 语句中用于动态表达式的占位符。

随着 Spring AI 的不断发展，它将引入更高层次的抽象方式来与 AI 模型交互。当前本节介绍的基础类可以类比为 JDBC 在 Java 中的地位和作用。例如，ChatModel 类就类似于 JDK 中核心的 JDBC 库；而 ChatClient 类则类似于 JdbcClient，它构建在 ChatModel 之上，并通过 Advisor 提供了更高级的功能，如：结合模型的历史交互记录、扩展提示词以引入额外的上下文文档，以及实现代理式行为（agentic behavior）。

在 AI 领域中，提示词的结构也经历了演变过程。最初，提示词只是简单的字符串。后来，逐渐引入了用于特定输入的占位符，如 "USER:"，让 AI 模型能识别不同部分的语义。OpenAI 更进一步地规范了提示词的结构，将多条消息字符串按不同“角色”分类，在交由模型处理前明确每条信息的来源和作用。

结构化输出转换
--------------------------------

参考：https://docs.spring.io/spring-ai/reference/api/structured-output-converter.html

.. image:: https://docs.spring.io/spring-ai/reference/_images/structured-output-architecture.jpg
    :alt: 结构化输出转换
    :width: 100%
    :align: center






模型
--------------------------------



聊天记忆
--------------------------------

参考：https://docs.spring.io/spring-ai/reference/api/chat-memory.html


大型语言模型（LLMs）是无状态的，意味着它们不会记住之前的交互信息。这在需要跨多轮对话保持上下文或状态时可能成为一个限制。为了解决这一问题，Spring AI 提供了聊天记忆（Chat Memory）功能，允许在与 LLM 的多轮交互中存储和提取信息。

ChatMemory 抽象允许你实现多种类型的记忆机制，以支持不同的使用场景。消息的底层存储由
ChatMemoryRepository 处理，其唯一职责是存储和读取消息。至于保留哪些消息以及何时删除，由具体的 ChatMemory 实现来决定。常见策略包括：保留最近的 N 条消息、保留一定时间范围内的消息，或保留一定 Token 限制以内的消息。

在选择记忆类型之前，理解聊天记忆（Chat Memory）与聊天历史（Chat History）之间的区别非常重要：

聊天记忆：指的是大型语言模型在对话过程中保留并用于维持上下文感知的信息。

聊天历史：是指整个对话的历史记录，包括用户和模型之间交换的所有消息。

ChatMemory 抽象专为管理聊天记忆而设计，允许你存储和提取与当前对话上下文相关的消息。但它并不适合用于存储完整的聊天历史。如果你需要保留完整的消息记录，建议使用其他方式，例如依赖 Spring Data 来高效存储和检索完整的聊天历史。


Tool Calling
------------------------------------

参考：https://docs.spring.io/spring-ai/reference/api/tools.html

工具调用（Tool Calling，也称为函数调用）是 AI 应用中的一种常见模式，它允许模型与一组 API 或工具进行交互，从而增强模型的能力。

工具的主要用途包括：


信息检索（Information Retrieval）
此类工具可用于从外部来源检索信息，如数据库、Web 服务、文件系统或搜索引擎。其目的是增强模型的知识，使其能够回答原本无法回答的问题。因此，它们常用于检索增强生成（RAG）场景中。例如，可以使用工具获取某地的实时天气、检索最新的新闻文章，或查询数据库中的特定记录。

执行操作（Taking Action）
此类工具可用于在软件系统中执行具体操作，例如发送邮件、在数据库中创建新记录、提交表单或触发工作流。其目标是自动化那些本需人工干预或显式编程才能完成的任务。例如，工具可以帮助与聊天机器人互动的客户预订航班、填写网页表单，或在代码生成场景中根据自动化测试（TDD）实现一个 Java 类。

虽然我们通常将“工具调用”描述为模型的一项能力，但实际上由客户端应用负责实现工具调用的逻辑。模型只能发出工具调用请求并提供输入参数，而工具的实际执行和结果返回是由应用程序负责完成的。模型永远无法直接访问作为工具提供的 API，这一点对于安全性至关重要。

Spring AI 提供了便捷的 API 来定义工具、解析模型发起的工具调用请求，并执行工具调用。以下各节将介绍 Spring AI 中工具调用功能的整体概况。


MCP
------------------------------------

参考：https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html


RAG
------------------------------------

参考：https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html