核心概念速览

3.1 模型：AI 能力的提供者

模型（Model）是处理输入、生成输出的算法。大模型是预训练出来的，你不需要懂机器学习也能使用它。GPT 这个名字里的 P 就是 Pre-trained（预训练），预训练把模型变成了通用工具，开发者拿来就能用。

按输入输出类型，Spring AI 把模型分成几类：

模型接口	输入	输出	典型场景
ChatModel	文本	文本	对话、问答、写作
EmbeddingModel	文本/图像	向量（数字数组）	语义搜索、相似度计算
ImageModel	文本	图像	文生图
AudioModel（Transcription / Speech）	音频 / 文本	文本 / 音频	语音转文字、语音合成
ModerationModel	文本	分类结果	内容审核

每个接口对应一类能力，每个厂商提供各自的实现。你面向接口编程，换厂商只换依赖和配置，业务代码不动。嵌入（Embedding）稍微特殊：它把文本变成一串浮点数，语义相近的文本，这串数在空间里也离得近。向量库、RAG 都建立在它之上。

3.2 Message：对话里的每条消息

模型接收的不是一个字符串，而是一组带角色的消息。Spring AI 中每条消息是一个 Message 对象，常见四种类型：

• SystemMessage（系统消息）：设定模型的身份和行为，比如”你是一个 Java 面试官”。
• UserMessage（用户消息）：用户的输入。
• AssistantMessage（助手消息）：模型的回答。
• ToolResponseMessage（工具消息）：工具调用的返回结果，后面工具调用章节细讲。

角色决定了模型怎么理解这句话。系统消息的影响力最大，通常放在消息列表最前面。一条消息大概长这样：内容是文本，类型是角色，还可以挂一些自定义元信息，比如发送时间。

3.3 Prompt：一次完整请求

Prompt 是发给模型的一次完整请求，由两部分组成：消息列表 List，以及控制参数 ChatOptions（模型名、temperature、maxTokens 等）。temperature 控制回答的随机性，值越低越保守，越高越有创意。

为什么是消息列表？因为大模型是无状态的。它不记得你上一轮问了什么。想让它”记得”，就得把历史消息一起塞进这次请求。多轮对话的本质，就是不断把新旧消息拼进列表。

Token 是模型处理文本的最小单位，也直接决定费用。输入输出都计费。模型一次能处理的 Token 数有限，这个上限叫上下文窗口，超出的部分模型不会处理。写提示词时要注意别超窗。

提示词模板（PromptTemplate）是带占位符的文本，运行时把参数填进去。Spring AI 用 StringTemplate 引擎渲染，比如”给我讲一个关于 {topic} 的笑话”，就像 Spring MVC 里的 View 层。一次请求的组装，就是把消息列表和选项拼成 Prompt 对象，ChatClient 替你完成这部分。

3.4 三个核心 API：ChatModel、ChatClient、Advisor

ChatModel 是最底层的接口，核心方法就一个：ChatResponse call(Prompt prompt)。厂商 SDK 都实现它，你注入的是厂商的实现类 Bean。

ChatClient 是日常使用的主入口，Fluent API 风格。它封装了 ChatModel，并在调用前后插入 Advisor 链。打个比方：ChatModel 相当于 JDBC，ChatClient 相当于 JdbcClient。前者是底层标准，后者在标准之上封装了常用能力，日常开发用后者更顺手。

Advisor 是拦截器，类似 Spring AOP 的环绕通知。它在请求发给模型前、响应返回后各插一脚，用来做日志、记忆、RAG 等横切的事。第 5 章专讲。

3.5 数据接入：Embedding、VectorStore、RAG、Tool Calling、MCP

模型训练数据有截止日期，也不认识你的业务数据。比如 GPT-3.5/4.0 的训练数据只到 2021 年 9 月，之后的事它一概不知。把外部数据接进模型，主流手段有几种：

• Embedding：把文本变成向量。语义相近的文本，向量距离也近。
• VectorStore：向量数据库，负责存向量、按相似度检索。Spring AI 统一抽象成 VectorStore 接口，支持 20 余种实现。
• RAG（检索增强生成）：先按问题去向量库检索相关文档，再连同问题一起发给模型，回答就有了依据。文档要先进库，这一过程是 ETL 管道。
• Tool Calling：把 Java 方法注册成工具，模型需要实时数据时会主动调用。2.0 里用 @Tool 注解。
• MCP：工具调用的标准化协议，让模型能力接入外部工具生态，通过 Boot Starter 一键启用。

两者的关系可以这样理解：Tool Calling 是框架内的机制，MCP 是跨应用的协议。自己项目里的方法用前者，要对接外部系统时用后者。

这五样东西解决的是同一个问题：让模型拿到它训练时没见过、也没法自己获取的数据。另外还有一条路叫微调（Fine-Tuning），直接改模型权重，代价高、门槛高，一般项目用不上。

3.6 结构化输出与 Agent

结构化输出（StructuredOutput）解决”模型返回的是字符串，不是对象”的问题。用 .entity() 或 StructuredOutputConverter，把输出映射成 Java record 或 POJO。背后是精心设计的提示词加转换器，让模型吐出的 JSON 变成可用类型。

Agent（智能体）是组合出来的：模型加工具、记忆、RAG，加上循环决策，让模型能自主完成多步任务。比如先查库存、再算价格、最后生成订单。Spring AI 里没有单独的 Agent 类，它是这些能力的组合。官方还提供了 Agent 模式指南和动态工具发现这类进阶组件，学到后面自然会串起来。

3.7 小结

这一章没有代码，但都是地基。一条用户消息从 ChatClient 进去，经过 Advisor 链增强，由 ChatModel 发给厂商模型，响应再原路返回。后面每章的代码，都能在术语表里找到归属。遇到忘了的，回来翻这一章。