深入Spring AI：6大核心概念带你入门AI开发

1、前言

前面我们快速了解了Spring AI的基础使用，以及他的分层体系。今天我们来了解一下他的几个核心概念，能够帮我们快速了解Spring AI的实现机制。

官方文档对这一块也做出了很详细的解释，但是因为是英文，为了方便学习，这里将以白话文的形式来更好的学习他们。

2、AI Models（AI模型）

AI models are algorithms designed to process and generate information, often mimicking human cognitive functions. By learning patterns and insights from large datasets, these models can make predictions, text, images, or other outputs, enhancing various applications across industries.

AI 模型是旨在处理和生成信息的算法，通常模仿人类的认知功能。通过从大型数据集中学习模式和见解，这些模型可以进行预测、文本、图像或其他输出，从而增强跨行业的各种应用程序。

There are many different types of AI models, each suited for a specific use case. While ChatGPT and its generative AI capabilities have captivated users through text input and output, many models and companies offer diverse inputs and outputs. Before ChatGPT, many people were fascinated by text-to-image generation models such as Midjourney and Stable Diffusion.

有许多不同类型的 AI 模型，每种模型都适用于特定的使用案例。虽然 ChatGPT 及其生成式 AI 功能通过文本输入和输出吸引了用户，但许多模型和公司都提供了不同的输入和输出。在 ChatGPT 之前，许多人对 Midjourney 和 Stable Diffusion 等文本到图像生成模型着迷。

看过我前面《Spring AI项目架构及分层体系》的兄弟们，应该有发现，Spring AI有一个models模块，他里面兼容了各大主流AI模型提供商的不同模型，如OpenAI，DeepSeek，huggingface等。不同的AI模型的输入输出都各有差异的情况下，要实现对于开发者来说进行开箱即用的快速集成，那么必然的需要一层抽象模型。这个就是Spring AI的 Models。

模型是 AI 应用程序的核心算法，负责处理输入数据并生成预测或内容。Spring AI 支持多种模型类型（如聊天、文本生成、图像生成等），并兼容主流提供商（如 OpenAI、Google Vertex AI 等），通过统一的 API 接口实现模型切换。其核心原理是通过抽象层封装不同模型的通信细节，开发者仅需关注业务逻辑。

这个是Spring AI官网给出来的不同模型分类：

Spring AI currently supports models that process input and output as language, image, and audio. The last row in the previous table, which accepts text as input and outputs numbers, is more commonly known as embedding text and represents the internal data structures used in an AI model. Spring AI has support for embeddings to enable more advanced use cases.

Spring AI 目前支持将输入和输出处理为语言、图像和音频的模型。上表中的最后一行接受文本作为输入并输出数字，通常称为嵌入文本，表示 AI 模型中使用的内部数据结构。Spring AI 支持嵌入以支持更高级的用例。

What sets models like GPT apart is their pre-trained nature, as indicated by the "P" in GPT---Chat Generative Pre-trained Transformer. This pre-training feature transforms AI into a general developer tool that does not require an extensive machine learning or model training background.

像 GPT 这样的模型的不同之处在于它们的预训练性质，如 GPT 中的"P"所示------聊天生成预训练转换器。此预训练功能将 AI 转换为不需要广泛的机器学习或模型训练背景的通用开发人员工具。

代码示例来看下：

@RestController
public class AiModelsController {


    private final ChatClient chatClient;
    public AiModelsController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @GetMapping("/chat")
    public String chat() {
        return chatClient.prompt().user("你是谁？").call().content();
    }
}

我们配置了阿里云千问的模型：

运行下结果：

如果想要变更不同的模型，我们只需要变更spring.ai.openai.chat.options.model的id即可，比如我这里改为deepseek：

运行结果：

对于开发者来说，更换不同的模型只需要配置不同的参数即可，Spring AI通过model支持将输入和输出处理为结构化输出，这个后面也会细讲。

3、Prompts（提示词）

Prompts serve as the foundation for the language-based inputs that guide an AI model to produce specific outputs. For those familiar with ChatGPT, a prompt might seem like merely the text entered into a dialog box that is sent to the API. However, it encompasses much more than that. In many AI Models, the text for the prompt is not just a simple string.

提示是基于语言的输入的基础，这些输入可指导 AI 模型生成特定输出。对于熟悉 ChatGPT 的人来说，提示可能看起来只是在发送到 API 的对话框中输入的文本。然而，它包含的远不止于此。在许多 AI 模型中，提示的文本不仅仅是一个简单的字符串。

ChatGPT's API has multiple text inputs within a prompt, with each text input being assigned a role. For example, there is the system role, which tells the model how to behave and sets the context for the interaction. There is also the user role, which is typically the input from the user.

ChatGPT 的 API 在一个提示中有多个文本输入，每个文本输入都分配了一个角色。例如，有 system 角色，它告诉模型如何行为并设置交互的上下文。还有 user role，通常是来自用户的 Importing。

Crafting effective prompts is both an art and a science. ChatGPT was designed for human conversations. This is quite a departure from using something like SQL to "ask a question". One must communicate with the AI model akin to conversing with another person.

制作有效的提示既是一门艺术，也是一门科学。ChatGPT 专为人类对话而设计。这与使用 SQL 之类的东西来 "ask a question" 完全不同。一个人必须与 AI 模型进行交流，类似于与另一个人交谈。

Such is the importance of this interaction style that the term "Prompt Engineering" has emerged as its own discipline. There is a burgeoning collection of techniques that improve the effectiveness of prompts. Investing time in crafting a prompt can drastically improve the resulting output.

正是这种交互方式的重要性，以至于"Prompt Engineering"一词已经成为一门独立的学科。有一系列新兴的技术可以提高提示的有效性。投入时间制作提示可以大大提高结果输出。

Sharing prompts has become a communal practice, and there is active academic research being done on this subject. As an example of how counter-intuitive it can be to create an effective prompt (for example, contrasting with SQL), a recent research paper found that one of the most effective prompts you can use starts with the phrase, "Take a deep breath and work on this step by step." That should give you an indication of why language is so important. We do not yet fully understand how to make the most effective use of previous iterations of this technology, such as ChatGPT 3.5, let alone new versions that are being developed.

分享提示已成为一种公共实践，并且正在积极地进行关于这一主题的学术研究。例如，创建有效的提示（例如，与 SQL 形成对比）是多么违反直觉，最近的一篇研究论文发现，您可以使用的最有效的提示之一以短语"深呼吸并逐步完成此工作"开头。这应该可以告诉你为什么语言如此重要。我们还不完全了解如何最有效地利用这项技术的先前迭代，例如 ChatGPT 3.5，更不用说正在开发的新版本了。

Prompts可能有些人比较陌生，但是如果说AI提示词，大家肯定不陌生。从ChatGPT风靡全网之后，吃到AI的第一波红利的就是提供关键提示词，甚至还有一些公司专门开设了提示词工程师。

简单的说，提示词就是用来引导大模型生成在特定输出结构的输入，也就是当你使用AI大模型为你工作的时候，你在输入框里面输入的文本。说白了，就类似你领导pua你时候的话术，只要加班加的好，领导的奔驰宝马少不了。

Spring AI 通过Prompt 作为用户与AI模型交互的指令载体。

3.1、Prompt结构化

Spring AI中 Prompt 的设计，不仅只是输入框的文本载体。Prompt 类通过封装多角色消息（如用户消息、系统消息）构建完整的上下文请求，实现对话逻辑的精确控制。
角色区分上： Spring AI角色区分为"普通用户"角色和"系统"角色，通过不同的角色定义不同的message，如UserMessage或SystemMessage区分用户输入指令和系统指令，借此帮助大模型理解对话场景。比如系统消息可设定 AI 的行为规范（如回答风格），用户消息传递具体问题。
多轮对话支持： 如果需要维护历史对话记录，可以使用List，模型会基于上下文生成连贯响应，适用于客服机器人等复杂场景。

简单代码示例如下，我们改造一下上面的示例代码。让AI介绍下自己，用户提示词还是问你是谁，增加一个系统角色，让他使用诙谐幽默的风格来介绍：

@GetMapping("/prompt")
public String prompt() {
  SystemMessage systemMessage = new SystemMessage("诙谐幽默风格");
  UserMessage userMessage = new UserMessage("你是谁？");

  List<Message> messages = List.of(systemMessage, userMessage);
  String content = chatClient.prompt(new Prompt(messages)).call().content();
  System.out.println(content);
  return content;
}

运行结果：

4、Prompt Templates（提示词模板）

Creating effective prompts involves establishing the context of the request and substituting parts of the request with values specific to the user's input.

创建有效的提示包括建立请求的上下文，并将请求的各个部分替换为特定于用户输入的值。

This process uses traditional text-based template engines for prompt creation and management. Spring AI employs the OSS library StringTemplate for this purpose.

此过程使用传统的基于文本的模板引擎进行提示创建和管理。Spring AI 为此使用了 OSS 库StringTemplate。

For instance, consider the simple prompt template: 例如，考虑简单的提示模板：

Tell me a {adjective} joke about {content}.

In Spring AI, prompt templates can be likened to the "View" in Spring MVC architecture. A model object, typically a java.util.Map, is provided to populate placeholders within the template. The "rendered" string becomes the content of the prompt supplied to the AI model.

在 Spring AI 中，提示模板可以比作 Spring MVC 架构中的 "视图"。提供模型对象（通常是 java.util.Map）来填充模板中的占位符。"rendered" 字符串成为提供给 AI 模型的提示的内容。

There is considerable variability in the specific data format of the prompt sent to the model. Initially starting as simple strings, prompts have evolved to include multiple messages, where each string in each message represents a distinct role for the model.

发送到模型的提示的特定数据格式存在相当大的变化。提示最初从简单字符串开始，现在已经发展到包含多条消息，其中每条消息中的每个字符串代表模型的不同角色。

Prompt Templates和 Prompt 的关键区别大概可以概括为"具体的生成内容"和"内容生成模板规则"。通常我们给到AI模型的提示词都不会是单一固定的，如上文让AI模型介绍自己时，所使用的语言风格。如果结合业务场景，用脚趾头想肯定也会需要他动态变更，我让你往东你就往东，让你往西你就往西。所以聪明的Spring AI自然也会想到这个场景，结合StringTemplate文本模板引擎，使用占位符替换的方式来进行提示词创建和管理。

我们来将上文的Prompt改造成使用Prompt Template方式：

@GetMapping("/promptTemplate")
public String promptTemplate() {
  // 使用系统消息预定好角色风格
  SystemPromptTemplate systemTemplate = new SystemPromptTemplate ("你是一位风格{style}的演说家");
  Message systemMessage = systemTemplate.createMessage(Map.of("style", "幽默诙谐"));

  // 用户消息动态注入参数
  PromptTemplate userTemplate = new PromptTemplate("请介绍一下自己的{store}");
  Message userMessage = userTemplate.createMessage(Map.of("store", "情感经历"));

  // 组合多角色消息
  List<Message> messages = List.of(systemMessage, userMessage);
  String content = chatClient.prompt(new Prompt(messages)).call().content();
  System.out.println(content);
  return content;
}

运行结果：

5、Embeddings （嵌入）

Embeddings are numerical representations of text, images, or videos that capture relationships between inputs.

嵌入是文本、图像或视频的数字表示形式，用于捕获输入之间的关系。

Embeddings work by converting text, image, and video into arrays of floating point numbers, called vectors. These vectors are designed to capture the meaning of the text, images, and videos. The length of the embedding array is called the vector's dimensionality.

嵌入的工作原理是将文本、图像和视频转换为浮点数数组（称为向量）。这些矢量旨在捕获文本、图像和视频的含义。嵌入数组的长度称为向量的维数。

By calculating the numerical distance between the vector representations of two pieces of text, an application can determine the similarity between the objects used to generate the embedding vectors.

通过计算两段文本的向量表示之间的数值距离，应用程序可以确定用于生成嵌入向量的对象之间的相似性。
As a Java developer exploring AI, it's not necessary to comprehend the intricate mathematical theories or the specific implementations behind these vector representations. A basic understanding of their role and function within AI systems suffices, particularly when you're integrating AI functionalities into your applications.

作为探索 AI 的 Java 开发人员，没有必要理解复杂的数学理论或这些向量表示背后的具体实现。对它们在 AI 系统中的角色和功能有基本的了解就足够了，尤其是在您将 AI 功能集成到应用程序中时。

Embeddings are particularly relevant in practical applications like the Retrieval Augmented Generation (RAG) pattern. They enable the representation of data as points in a semantic space, which is akin to the 2-D space of Euclidean geometry, but in higher dimensions. This means just like how points on a plane in Euclidean geometry can be close or far based on their coordinates, in a semantic space, the proximity of points reflects the similarity in meaning. Sentences about similar topics are positioned closer in this multi-dimensional space, much like points lying close to each other on a graph. This proximity aids in tasks like text classification, semantic search, and even product recommendations, as it allows the AI to discern and group related concepts based on their "location" in this expanded semantic landscape.

嵌入在 Retrieval Augmented Generation （RAG） 模式等实际应用中尤其相关。它们能够将数据表示为语义空间中的点，这类似于欧几里得几何的二维空间，但维度更高。这意味着就像欧几里得几何中平面上的点可以根据其坐标来接近或远一样，在语义空间中，点的接近反映了含义的相似性。在这个多维空间中，关于相似主题的句子被放置在更近的位置，就像图表上彼此靠近的点一样。这种接近有助于文本分类、语义搜索甚至产品推荐等任务，因为它允许 AI 根据相关概念在这个扩展的语义环境中的 "位置" 来识别和分组。

You can think of this semantic space as a vector. 您可以将此语义空间视为一个向量。

简单的说，Embedding 就是将我们给定的文本、图像等非结构化数据转为高纬向量表示。高纬向量表示？嗯，其实就是将其表示成一个连续的数值空间中的点，也就是一个N维的实值向量，目的是让机器更好的理解和处理这些非结构化数据。

5.1、Dimension（维）

在Embeddings技术中，既然是将文本和非结构化数据转成N维向量。那么必然会涉及到向量空间的坐标（特征）数量，坐标数量决定了嵌入向量的复杂度和语义表达能力，这里衡量坐标个数的值被定义为"维"。

举个简单例子： 描述一个牛马的特征，可能包含：是否有房贷车贷、是否愿意加班、性格、执行力...... 每个特征就是对应一个维度。维度越多，描述就越精细，但是相应的计算成本也越高。

当我们使用硅基流动使用AI模型时候，选择嵌入模型时，我们都会看到每个大模型都支持了不同的维：

Spring AI中，可以通过配置spring.ai.embedding.options.dimensions来配置强制输出的维。

5.2、简单示例

我们简单嵌入一段文本，生成嵌入：

@Autowired
private OpenAiEmbeddingModel openAiEmbeddingModel;


@GetMapping("/embedding")
public EmbeddingResponse embedding() {
  List<String> texts = List.of("Hello world", "Bye world");
  return openAiEmbeddingModel.embedForResponse(texts);
}

执行下，我们可以看到结果。这些就是生成的向量。这些向量就是方便用于机器理解并检索使用。

但是如果只到这里收尾，似乎有点草率。实际项目中咋用呢？

还是简单扩展下好了，这边将向量集成到向量库中，进行一个简单的搜索服务。代码如下：

package org.example.springaidemo.chart_03.controller;

import org.springframework.ai.document.Document;
import org.springframework.ai.openai.OpenAiEmbeddingModel;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.SimpleVectorStore;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
import java.util.Map;

@RestController
public class EmbeddingController {

  @Autowired
  private VectorStore vectorStore;

  @GetMapping("/embedding")
  public void embedding() {
      List<String> texts = List.of("Hello world", "Bye world", "banner", "apple");

      // 将文本与嵌入向量绑定后存储
      List<Document> documents = texts.stream()
              .map(text -> new Document(text, Map.of("source", "demo")))
              .toList();
      vectorStore.add(documents);
  }

  @GetMapping("/search")
  public List<String> search(@RequestParam String query) {
      SearchRequest request = SearchRequest.query(query).withTopK(5);
      List<Document> results = vectorStore.similaritySearch(request);
  
      // 提取文档内容（排除嵌入向量）
      List<String> res = results.stream()
              .map(Document::getContent)
              .toList();
      System.out.println("查询条件：" + query);
      System.out.println("查询结果：" + res);
      return res;
  }

}


/**
* 定义一个简单的向量库
*/
@Configuration
class VectorConfig {

  @Bean
  public SimpleVectorStore vectorStore(OpenAiEmbeddingModel embeddingModel) {
      return new SimpleVectorStore(embeddingModel);
  }
}

简单的说，我会通过/embedding这个接口，先将内置好的文本内容生成向量后存入向量库。

接着通过/search接口，传入筛选条件，查出相似度高的文本内容，通常适用于文本内容的检索。这里内置了两组差异性较大的文本，方便演示使用。

先调用/embedding接口，可以看到控制台分别生成了不同的向量文本ID：

接着调用/search?query=fruit，传入筛选条件查询水果的文本。执行结果：

换一个筛选条件，比如query=word，执行结果：

可以看到，文本会根据相似度进行排序后输出。这里我们就可以根据相似度来进行精准的搜索。

6、Tokens（令牌）

Tokens serve as the building blocks of how an AI model works. On input, models convert words to tokens. On output, they convert tokens back to words.

Tokens 是 AI 模型工作原理的构建块。在输入时，模型将单词转换为标记。在输出时，他们将标记转换回单词。

In English, one token roughly corresponds to 75% of a word. For reference, Shakespeare's complete works, totaling around 900,000 words, translate to approximately 1.2 million tokens.

在英语中，一个标记大约相当于一个单词的 75%。作为参考，莎士比亚全集总计约 900,000 字，可翻译成大约 120 万个Tokens。 Perhaps more important is that Tokens = Money. In the context of hosted AI models, your charges are determined by the number of tokens used. Both input and output contribute to the overall token count.

也许更重要的是Tokens = 货币。在托管 AI 模型的上下文中，您的费用由使用的令牌数量决定。输入和输出都会影响总令牌计数。

Also, models are subject to token limits, which restrict the amount of text processed in a single API call. This threshold is often referred to as the "context window". The model does not process any text that exceeds this limit.

此外，模型还受令牌限制的约束，这些限制限制了在单个 API 调用中处理的文本量。此阈值通常称为 "上下文窗口"。模型不会处理任何超过此限制的文本。

For instance, ChatGPT3 has a 4K token limit, while GPT4 offers varying options, such as 8K, 16K, and 32K. Anthropic's Claude AI model features a 100K token limit, and Meta's recent research yielded a 1M token limit model.

例如，ChatGPT3 有 4K Tokens 限制，而 GPT4 提供不同的选项，例如 8K、16K 和 32K。Anthropic 的 Claude AI 模型具有 100K Tokens 限制，而 Meta 最近的研究产生了 1M Tokens 限制模型。

To summarize the collected works of Shakespeare with GPT4, you need to devise software engineering strategies to chop up the data and present the data within the model's context window limits. The Spring AI project helps you with this task.

要使用 GPT4 总结莎士比亚的收藏作品，您需要制定软件工程策略来切碎数据并在模型的上下文窗口限制内呈现数据。Spring AI 项目可帮助您完成此任务。

简单的说，Token 是模型处理文本时的最小单位，可以是单词、子词（Subword）或符号（如标点）。比如:

"Hello World!"文本，OpenAI的token划分为，Hello -> 1 token， World -> 1 token，! -> 1 token

"你好"文本，Token划分为，你 -> 1 token，好 -> 1 token。当然这取决于中文的分词器。

可见，当处理长文本时，如果按照语法或语义来进行Token划分，那么越大的文档，token就会越多。而Token数量直接影响计算资源和相应时长。这也就是为什么AI大模型都会对目前的输入和输出Token进行限制的原因。

Spring AI中提供了一个文本分割器TokeenTextSplitter来按Token数进行文档分割，以满足大模型的输入限制。

7、Structured Output（结构化输出）

The output of AI models traditionally arrives as a java.lang.String, even if you ask for the reply to be in JSON. It may be a correct JSON, but it is not a JSON data structure. It is just a string. Also, asking "for JSON" as part of the prompt is not 100% accurate.

AI 模型的输出传统上以 java.lang.String 的形式到达，即使您要求以 JSON 格式回复也是如此。它可能是正确的 JSON，但不是 JSON 数据结构。它只是一个字符串。此外，在提示中请求 "for JSON" 并不是 100% 准确的。

This intricacy has led to the emergence of a specialized field involving the creation of prompts to yield the intended output, followed by converting the resulting simple string into a usable data structure for application integration.

这种复杂性导致了一个专业领域的出现，该领域涉及创建提示以产生预期的输出，然后将生成的简单字符串转换为可用于应用程序集成的数据结构。

结构化输出将模型的自由文本响应转换为特定数据结构（如 JSON），它允许开发者将 AI 模型生成的自由文本响应自动转换为预定义的 Java 对象结构。这种能力极大地简化了 AI 集成工作，特别是在需要处理复杂、结构化数据的场景中。

7.1、结构化输出 API

Spring AI提供了StructuredOutputConverter接口，他允许我们来扩展自己所需的结构化输出格式：

简单示例代码：

@RestController
public class StructuredOutputController {

  private final ChatClient chatClient;
  public StructuredOutputController(ChatClient.Builder chatClientBuilder) {
      this.chatClient = chatClientBuilder.build();
  }

  @GetMapping("/structuredOutput")
  public String structuredOutput() {
      SystemMessage systemMessage = new SystemMessage("诙谐幽默风格");
      UserMessage userMessage = new UserMessage("你是谁？");
      List<Message> messages = List.of(systemMessage, userMessage);
      String content = chatClient.prompt(new Prompt(messages)).call().content();
      String con = new MyOutputConverter().convert(content);
      System.out.println(con);
      return content;
  }
}

class MyOutputConverter implements StructuredOutputConverter<String> {

  @Override
  public String getFormat() {
      return "";
  }

  @Override
  public String convert(String source) {
      return """
              我是通过自定义结构化输出的内容：
              ============================================
              """ + source;
  }
}

运行结果：

当然，这里我们可以自由的定义我们需要的文本格式，不排除JSON，Bean等模式。Spring AI已经帮我们内置了一些成熟的转换器，如Map，Bean，List等。

8、小结

Spring AI的核心概念当然不止这些，但是这些是官网建议我们学习之前一定要深入理解的。因此这里结合官网文档以及自己的理解，配合一些简单demo，进行深入学习。demo代码，我已更新在github上：github.com/Shamee99/sp...