基础概念 Basic Concepts

官网 Website 

Spring AI

Spring AI 是一个旨在简化将人工智能功能集成到应用程序中的开发框架。它提供统一的 API 抽象，支持聊天、文本生成图像、嵌入等模型，兼容 OpenAI、Anthropic、Microsoft、Google 等主流 AI 提供商，帮助开发者轻松集成和切换不同 AI 服务，致力于减少不必要的复杂性。

Spring AI is a development framework designed to simplify the integration of artificial intelligence capabilities into applications. It provides a unified API abstraction that supports models for chat, text generation, image generation, embeddings, and more. It is compatible with major AI providers such as OpenAI, Anthropic, Microsoft, and Google, enabling developers to easily integrate and switch between different AI services. The framework aims to reduce unnecessary complexity.

模型（Model）

• AI模型的作用：模仿人类认知，通过学习大量数据来生成文本、图像、音频等多种输出。

• 模型类型多样：不同模型适用于不同输入与输出，例如文本生成图像（如 Midjourney）、文本生成文本（如 ChatGPT）。

• Spring AI 支持：支持语言、图像、音频等输入输出方式，还支持文本嵌入（将文本转为数字）以支持更复杂的应用。

• GPT模型的特点：预训练（Pre-trained）是其核心优势，使得开发者无需专业背景也能使用强大的 AI 功能。

• Imitating Human Cognition:AI models simulate human cognitive abilities by learning from large volumes of data to generate various outputs such as text, images, and audio.

• Diverse Model Types:Different models are suited for different input and output scenarios — for example, text-to-image generation (like Midjourney) or text-to-text generation (like ChatGPT).

• Spring AI Support:Spring AI supports multiple input and output modalities, including language, image, and audio. It also supports text embeddings (converting text into numerical vectors) to enable more advanced applications.

• GPT Model Characteristics:The key strength of GPT models lies in their pre-training, which allows developers to leverage powerful AI capabilities without requiring deep domain expertise.

提示词（Prompts）

• 提示词的作用：它们是引导 AI 模型生成内容的核心，不仅仅是简单的文本输入。

• 提示词结构：如 ChatGPT 的 API，提示由多个角色组成，如系统角色设定行为、用户角色提供输入。

• 提示词工程：编写提示词是一种技能，既需要逻辑也需要语言技巧，已发展成独立领域。

• Core of AI Content Generation: Prompts are the key to guiding AI models in generating content — they are far more than just simple text inputs.

• Prompt Structure: In APIs like ChatGPT, a prompt typically consists of multiple roles. For example, the system role defines the model’s behavior, while the user role provides the input.

• Prompt Engineering: Writing effective prompts is a skill that requires both logical thinking and language proficiency. Over time, it has evolved into an independent discipline.

在 Spring AI 中，提示模板可以类比于 Spring MVC 架构中的 “View”（视图）。一个模型对象（通常是 java.util.Map）会被用来填充模板中的占位符。最终“渲染”出来的字符串就是传递给 AI 模型的提示内容。 

提示词发送给模型时的数据格式有很大差异。虽然最初只是简单的字符串，但现在已经发展为包含多个消息的结构，其中每条消息中的字符串代表模型的不同“角色”。

In Spring AI, prompt templates are analogous to views in the Spring MVC architecture. A model object (usually a java.util.Map) is used to populate placeholders within the template. The final rendered string is the actual prompt sent to the AI model. The data format used to send prompts to models has changed significantly. While early prompts were simple strings, modern prompts are structured as sequences of messages, with each message representing a different role in the conversation.

嵌入（Embeddings）

嵌入通过将文本、图像和视频转换为浮点数数组（称为向量）来工作。这些向量旨在捕捉这些输入的“含义”。嵌入数组的长度被称为该向量的维度（dimensionality）。 

通过计算两个嵌入向量之间的数值距离，应用程序可以判断它们之间的相似性。也就是说，越相近的向量表示内容含义越相似。 就像欧几里得几何中平面上的点可以根据坐标远近判断距离一样，在语义空间中，点之间的距离代表意义上的相似程度。关于相似主题的句子在这个多维空间中会更“接近”，就像图上的点靠得更近一样。 

这种“接近”对诸如文本分类、语义搜索、产品推荐等任务非常有帮助，因为它使 AI 能根据这些向量在语义空间中的“位置”来识别和聚类相关概念。

Embeddings work by converting text, images, or videos into arrays of floating-point numbers, known as vectors. These vectors are designed to capture the meaning of the input. The length of the embedding array is referred to as the dimensionality of the vector.

By calculating the numerical distance between two embedding vectors, applications can determine how similar the inputs are. In other words, vectors that are closer together represent content with more similar meaning.Just as points on a plane in Euclidean geometry can be measured by their coordinate distance, in semantic space, the distance between points represents the degree of similarity in meaning. Sentences about similar topics will be positioned closer together in this multidimensional space, much like nearby points on a graph.

This notion of "closeness" is extremely useful for tasks such as text classification, semantic search, and product recommendation, as it allows AI systems to identify and group related concepts based on their positions within the semantic space.

Tokens（令牌）

• Token 是模型处理文本的基本单位，约等于英文中的 3/4 个单词。

• 费用与 token 数量直接相关，输入输出都会计费。

• 模型有 token 限制，每次调用必须在这个“上下文窗口”内完成。

• 要处理大文本（如莎士比亚全集），需将其拆分后分批处理。

• 可以借助工具（如 Spring AI）实现自动化处理。

• Tokens are the basic units of text that a model processes, roughly equivalent to 3/4 of an English word.

• The cost of using an AI model is directly related to the number of tokens — both input and output tokens are counted and billed.

• Each model has a token limit, meaning that every request must stay within a fixed “context window.”

• To handle large texts (such as the complete works of Shakespeare), the content must be split and processed in smaller chunks.

• Tools like Spring AI can help automate this process efficiently.

结构化输出（Structured Output）

• AI 模型的输出本质上是字符串（String），即使格式像 JSON，也不是实际的数据结构。在提示中要求“输出 JSON”不一定可靠，可能仍需后处理。因此，开发者需要设计技巧性的 prompt，并配合多次调用模型，以获得结构化的输出。

• 结构化输出转换架构（Structured Output Converter）就是为了解决这一问题而出现的技术方案，目的是将文本结果转为可用的数据结构，用于系统集成与自动化处理。

• The output of an AI model is essentially a string, even if it looks like JSON — it is not a true data structure. When you prompt the model to "output JSON", the result may not always be reliable and often requires post-processing. Therefore, developers need to craft clever prompts and sometimes perform multiple model calls to obtain structured and usable output.

• The Structured Output Converter is a technical solution designed to address this challenge. Its purpose is to transform raw text outputs into structured data formats that can be integrated into systems or used for automated processin

嵌入（Embeddings）

GPT 的知识有深度和广度限制，但无法直接获取专业领域知识。但目前三种方法可以让模型“接入”你的数据和系统：

1. Fine Tuning（微调）：高成本、高技术门槛，不适合所有场景；

2. Prompt Stuffing / RAG：将数据直接写入提示词中，实用且广泛使用；

3. Tool Calling：让模型调用外部 API 来动态获取信息，适合集成业务系统。

Spring AI 提供了对 Prompt Stuffing 和 Tool Calling 的支持，简化了开发流程。

GPT has limitations in both the depth and breadth of its knowledge, and cannot directly access domain-specific information. However, there are currently three main ways to “connect” the model to your data and systems:

• Fine Tuning: High cost and high technical barrier — not suitable for all use cases.

• Prompt Stuffing / RAG: Embedding data directly into prompts — practical and widely used.

• Tool Calling: Allowing the model to call external APIs to dynamically retrieve information — ideal for integrating with business systems.

Spring AI supports both Prompt Stuffing and Tool Calling, helping streamline the development process.

检索增强生成（Retrieval Augmented Generation, RAG）

RAG 是一种结合数据检索与生成式 AI 的技术，能显著提升模型回答的准确性，核心流程如下：

1. 提取非结构化文档；

2. 拆分内容（保持语义 + 控制大小）；

3. 存入向量数据库；

4. 用户提问时检索相似内容；

5. 将问题 + 相似内容填入 prompt 发送给模型回答。

Spring AI 提供完整的支持，包括 ETL 管道与问答接口，帮助你快速实现 RAG 能力。

RAG is a technique that combines data retrieval with generative AI, significantly improving the accuracy of model responses. The core process is as follows:

• Extract unstructured documents

• Split the content (preserving semantics and controlling size)

• Store the chunks in a vector database

• When a user asks a question, retrieve similar content

• Fill the prompt with the question and relevant content, then send it to the model for an answer

Spring AI provides full support for this process, including ETL pipelines and Q&A interfaces, helping you quickly implement RAG capabilities.

评估 AI 回应（Evaluating AI responses）

• 评估 AI 回应的质量是确保 AI 应用可靠性的关键步骤。

• 评估指标包括：相关性、连贯性、事实正确性。

• 可以利用模型自身判断输出是否合理。

• 向量数据库中的信息可作为辅助依据，增强评估精准度。

• Spring AI 提供 Evaluator API 来执行这些评估任务，可参考其文档获取更多信息。

• Evaluating the quality of AI responses is a key step in ensuring the reliability of AI applications.

• Evaluation metrics include: relevance, coherence, and factual accuracy.

• The model itself can be used to judge whether the output is reasonable.

• Information from the vector database can serve as supporting evidence to enhance evaluation accuracy.

• Spring AI provides an Evaluator API to perform these evaluation tasks. You can refer to its documentation for more information.

快速入门示例 Quick Start Example

可以使用链接，快速生成和下载一个springboot项目，里面要添加openai的依赖

You can use this link to quickly generate and download a Spring Boot project, with the OpenAI dependency already included. After downloading the project, open it with IntelliJ IDEA. You’ll see that the basic structure has already been set up:

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.5</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <properties>
        <java.version>17</java.version>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <spring-ai.version>1.0.0-M8</spring-ai.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-openai</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <dependencyManagement>
        <dependencies>
            <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>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

简单配置application.properties，里面填上对应的url和apiKey

Simply configure application.properties by adding your corresponding URL and API key:

spring.application.name=demo

spring.ai.openai.base-url=

spring.ai.openai.api-key=

写一个Controller，里面引入SpringAI的类ChatClient，可以轻松调用接口

Create a simple Controller, and use Spring AI's ChatClient class to easily call the API:

@RestController

class DemoController {

   private final ChatModel chatModel;

   public DemoController(ChatClient.Builder chatClientBuilder, ChatModel chatModel) {

       this.chatModel = chatModel;

   }

   @GetMapping("/hello")

   String hello() {

       return chatModel.call("hello, how are you?");

   }

}

完成后运行项目，访问对应的链接：localhost:8080/hello即可

Once done, run the project and visit the following URL in your browser: localhost:8080/hello，You should see the AI response displayed.