1. 基础知识

1.1 Token

Token（词符） 在 AI 模型处理文本时至关重要，它是连接人类自然语言与模型可处理格式的桥梁。这种转换主要分为两个阶段：

• 输入时，文本会被转换成 Token。
• 模型输出后，这些 Token 再被还原回可读的文本。

分词（Tokenization）也就是将文本拆分为 Token 的过程，是 AI 模型理解与处理语言的基础。模型正是通过这种分词格式来理解并响应提示词。

为了更直观地理解 Token ，可以把它看作词语的基本单元，通常一个英文单词会对应 1～多个 Token，平均 1 个英文词汇约占 3/4 个 Token，1 个汉字约占 0.5 个 Token，标点符号、数字、字母也按单个字符算。因为不同模型的分词不同，所以存在一定的差异。

Token 除了在 AI 处理中的技术作用外，还有非常实际的业务意义，尤其体现在计费和模型能力两个方面：

• 计费规则：AI 服务一般按 Token 使用量计费。输入（提示词）和输出（模型回复）都会计入总 Token 数量，因此更简洁的提示词通常成本更低。
• 模型上下文限制：不同 AI 模型有不同的 Token 上限，这个上限决定了它的上下文窗口，即模型一次能处理的最大信息量。
• 上下文窗口：模型的 Token 上限直接决定上下文窗口大小，超过窗口长度的内容将无法被处理。因此在实际使用中，只需要发送最关键、最有效的信息。
• 响应元数据：AI 模型返回的响应元数据中，通常会包含本次请求消耗的 Token 数量，这是管控使用量与成本的重要依据。

1.2 提示词工程

提示词（Prompt）是用来引导 AI 模型生成特定输出的输入内容，这些提示词的设计与措辞会显著影响模型的回复。

AI 模型本身没有 “理解” 能力，它是根据你提供的提示词来生成内容的。提示词写得越清晰、具体，AI 的回答就越精准、越符合你的预期。

提示词工程（Prompt Engineering）是一门系统性设计和优化输入提示词（Prompt）的技术，旨在让大语言模型（LLM）更可靠、高效地生成符合预期的输出。

关于提示词相关知识，可以访问全球最权威、最系统的提示工程（Prompt Engineering）开源学习平台，由 DAIR.AI 团队维护，是 AI 开发者、产品经理、研究者必备的提示词学习与实战手册。

1.3 Chat Completions API

2023 年 3 月，OpenAI 正式推出 Chat Completions API （对话补全 API），它的核心在于采用结构化消息列表替代传统的单一文本提示，通过明确的角色划分实现更自然、可控的对话交互。

其中消息列表（Message List）是一个包含多个消息对象的数组，每个消息必须包含两个属性：

• role：消息发送者角色。
• content：消息内容文本。

2023 年 6 月， OpenAI 又新增了 function 角色以及配套的函数调用（Function Calling）功能，专门用来实现大模型调用外部工具 / 接口 / 函数的能力，让 AI 不只是 “聊天”，还能真正操作外部世界（查天气、查数据库、调接口、查实时信息等）。随着技术的发展，Function Calling 延伸与优化为 Tool Calling ， function 角色也演变为 tool 角色。

四大消息角色简单解释：

角色	作用	优先级	典型应用场景
system	设定AI的身份、行为规则、语气、回答约束，贯穿整轮对话	最高	定义:你是专业Python助手
user	用户的提问、指令、输入内容，是模型要响应的对象	中	问问题、发需求、给上下文、提要求
assistant	模型之前的回复，用于保留对话历史，让模型“记住上下文”	低	把上一轮AI回答存回去，实现多轮聊天
tool	存放工具/函数调用的返回结果，供模型继续整理回答	中	查天气、查数据库、调接口后把结果回传给模型

2025 年 3 月，OpenAI 正式推出了全新的 Responses API ，并计划在未来一段时间，逐渐代替 Chat Completion API。

相较于 Chat Completions API 的主要优势：

• 内置工具：内置联网搜索、网页抓取、代码解释器、文搜图、图搜图、知识库搜索等工具，可在处理复杂任务时获得更优效果。
• 更灵活的输入：支持直接传入字符串作为模型输入，也兼容 Chat 格式的消息数组。
• 有状态会话：通过传递上一轮响应的 previous_response_id，无需手动构建完整的消息历史数组。
• 多模态原生支持：支持文本、图像、音频等输入输出，无缝构建复杂多模态流水线。

重要提示：目前 Chat Completions 仍是主流的通用接口标准，仅仅少部分大模型厂商支持 Responses API ，国内的通义千问 3.5 已兼容，DeepSeek、GLM、Minimax 等仍以 Chat Completions 为主要接口。

2. Prompts API

提示词 API 是 Spring AI 框架中的核心模块，专门用于标准化、结构化构建大模型提示词，解决原生字符串拼接提示词的混乱、不可维护问题，同时无缝适配 OpenAI、Azure OpenAI、千问、DeepSeek 等主流大模型的提示词格式。

2.1 Prompt

Prompt 是顶层的提示词对象，封装一组 Message 消息列表，以及可附加的模型配置。

核心源码如下：

public class Prompt implements ModelRequest<List<Message>> {
    private final List<Message> messages;
    @Nullable
    private ChatOptions chatOptions;

其中，ChatOptions 是统一配置大模型调用参数的核心接口，定义大模型生成响应时的所有行为参数（随机性、长度、工具调用策略、响应格式等），与 Prompt（提示词）配合构成大模型调用的完整入参。

部分源码如下：

public interface ChatOptions extends ModelOptions {
    @Nullable
    String getModel();

    @Nullable
    Double getFrequencyPenalty();

    @Nullable
    Integer getMaxTokens();

    @Nullable
    Double getPresencePenalty();
    //....
}

2.2 Message

Message 继承了 Content 接口，是所有消息类型的抽象接口，封装了 Prompt 文本内容、一组元数据属性以及 MessageType 的消息角色分类枚举。

接口定义如下：

public interface Content {
    // 消息内容
    String getContent();

    Map<String, Object> getMetadata();
}

public interface Message extends Content {
    // 消息角色
    MessageType getMessageType();
}

继承关系如下：

Message 接口的不同实现对应 AI 模型可处理的各类消息：

• SystemMessage：给大模型设定角色和规则，是优先级最高的消息，模型会优先遵循该消息的约束生成回答。
• UserMessage：封装用户的所有输入（提问、需求、上下文补充等），表示用户输入和与模型的交互。
• AssistantMessage：模型生成的响应，包括文本内容、工具调用和元数据。
• ToolResponseMessage：表示工具执行/ 函数调用的输出，结果会回传给模型，支撑模型生成最终回答，对应 Chat Completions API 的 tool 角色。

其中 MessageType 是一个消息角色枚举类：

public enum MessageType {
    USER("user"),
    ASSISTANT("assistant"),
    SYSTEM("system"),
    TOOL("tool");
    // ......
}

另外 MediaContent 是多模态消息类型接口，提供 Media 内容对象列表：

public interface MediaContent extends Content {

    Collection<Media> getMedia();

}

官方提供的 Message 类图如下：

示例 1 ，创建系统、用户消息：

SystemMessage systemMsg = new SystemMessage("你是专业的Python助手，回答简洁明了");
UserMessage userMsg = new UserMessage("解释列表推导式，举1个例子");
// 验证角色
System.out.println(userMsg.getRole());// 输出：user
System.out.println(userMsg.getContent());// 输出：解释什么是列表推导式...

2.3 PromptTemplate

PromptTemplate 是用于模板化、参数化构建提示词的核心类，解决了原生字符串拼接提示词的混乱、不可维护、复用性差的问题。

PromptTemplate 将提示词拆分为「固定模板（含占位符）」+「动态参数」，支持参数绑定、格式校验、多场景复用，最终生成可直接调用大模型的 Prompt 对象。

PromptTemplate 类实现了 PromptTemplateActions 与 PromptTemplateMessageActions 接口，依赖模板渲染器（TemplateRenderer）完成模板的动态渲染：

public class PromptTemplate implements PromptTemplateActions, PromptTemplateMessageActions {
    // 核心渲染与构建逻辑
    private static final TemplateRenderer DEFAULT_TEMPLATE_RENDERER = StTemplateRenderer.builder().build();
}

模板渲染的核心接口为 TemplateRenderer，该接口抽象了模板字符串与变量映射的绑定逻辑，其本质是一个二元函数（BiFunction），定义如下：

public interface TemplateRenderer extends BiFunction<String, Map<String, Object>, String> {
    @Override
    String apply(String template, Map<String, Object> variables);
}

Spring AI 默认采用 StTemplateRenderer 作为渲染器实现，该实现基于 Terence Parr 开发的开源 StringTemplate 引擎。模板变量默认通过 {} 语法标识，支持自定义分隔符以适配不同语法规范。若业务场景无需模板渲染（如静态提示字符串），可直接使用框架提供的 NoOpTemplateRenderer 空实现。

自定义渲染器示例（配置 <> 作为变量分隔符）：

PromptTemplate promptTemplate = PromptTemplate.builder()
    .renderer(StTemplateRenderer.builder()
        .startDelimiterToken('<')
        .endDelimiterToken('>')
        .build())
    .template("Tell me the names of 5 movies whose soundtrack was composed by <composer>.")
    .build();

String prompt = promptTemplate.render(Map.of("composer", "John Williams"));

PromptTemplate 实现的接口体系从不同维度抽象了提示创建能力，覆盖字符串渲染、消息对象构建、完整 Prompt 对象生成三个层级：

• PromptTemplateStringActions
• PromptTemplateMessageAction
• PromptTemplateActions

PromptTemplateStringActions 接口聚焦于提示模板到最终字符串的渲染，是最基础的提示生成能力：

public interface PromptTemplateStringActions {
    // 渲染无动态变量的静态模板
    String render();
    // 基于变量映射渲染动态模板（键为占位符名称，值为待填充内容）
    String render(Map<String, Object> model);
}

PromptTemplateMessageAction 接口扩展至消息对象（Message）的创建，支持静态内容、媒体内容及动态变量的整合：

public interface PromptTemplateMessageActions {
    // 创建无额外数据的静态消息对象
    Message createMessage();
    // 创建包含静态文本与媒体内容的消息对象
    Message createMessage(List<Media> mediaList);
    // 基于变量映射创建动态消息对象
    Message createMessage(Map<String, Object> model);
}

PromptTemplateActions 接口继承 PromptTemplateStringActions，进一步封装为可直接传递给聊天模型的 Prompt 对象，支持聊天请求配置（ChatOptions）的绑定：

public interface PromptTemplateActions extends PromptTemplateStringActions {
    // 创建无动态变量的静态 Prompt 对象
    Prompt create();
    // 创建带聊天请求配置的静态 Prompt 对象
    Prompt create(ChatOptions modelOptions);
    // 基于变量映射创建动态 Prompt 对象
    Prompt create(Map<String, Object> model);
    // 基于变量映射 + 聊天请求配置创建动态 Prompt 对象
    Prompt create(Map<String, Object> model, ChatOptions modelOptions);
}