Spring AI 系列3: Promt提示词

一、Promt提示词

Promt提示是引导 AI 模型生成特定输出的输入，提示的设计和措辞会显著影响模型的响应。

在 Spring AI 中与 AI 模型交互的最低层级，处理提示有点类似于在 Spring MVC 中管理”视图”。这涉及创建带有动态内容占位符的大段文本。这些占位符随后会根据用户请求或应用程序中的其他代码进行替换。另一个类比是包含某些表达式占位符的 SQL 语句。

随着 Spring AI 的发展，它将引入更高级别的与 AI 模型交互的抽象。本节描述的基础类在其角色和功能上可以类比为 JDBC。例如，ChatModel 类类似于 JDK 中的核心 JDBC 库。 ChatClient 类类似于 JdbcClient，它构建在 ChatModel 之上，并通过 Advisor 提供更高级的构造，能够考虑与模型的历史交互、用额外的上下文文档增强提示，并引入代理行为。

提示的结构在 AI 领域内随着时间的推移而演变。最初，提示只是简单的字符串。随着时间的推移，它们发展为包含特定输入占位符，如”USER:“，AI 模型能够识别。 OpenAI 通过在处理前将多条消息字符串分类为不同角色，为提示引入了更多结构。

prompt()

这个无参数方法让您开始使用流畅 API，允许您构建用户、系统和其他提示部分。

prompt(Prompt prompt)

这个方法接受 Prompt 参数，让您传入使用 Prompt 的非流畅 API 创建的 Prompt 实例。

prompt(String content)

这是一个类似于前一个重载的便捷方法。它接受用户的文本内容。

二、Prompt API 概述

2.1 、Prompt

通常会使用 ChatModel 的 call() 方法，该方法接受一个 Prompt 实例并返回一个 ChatResponse。

Prompt 类作为有序 Message 对象序列和请求 ChatOptions 的容器。每个 Message 在提示中都具有独特的角色，内容和意图各不相同。这些角色可以包含多种元素，从用户提问到 AI 生成的响应，再到相关的背景信息。这种安排使与 AI 模型的交互变得复杂且详细，因为提示由多个消息构建，每个消息在对话中扮演特定角色。

下面是 Prompt 类的简化版本，省略了构造函数和工具方法：

public class Prompt implements ModelRequest<List<Message>> {

    private final List<Message> messages;

    private ChatOptions chatOptions;
}

2.2、Message

Message 接口封装了提示的文本内容、元数据属性集合和称为 MessageType 的分类。

public interface Content {

	String getContent();

	Map<String, Object> getMetadata();
}

public interface Message extends Content {

	MessageType getMessageType();
}

多模态消息类型还实现了 MediaContent 接口，提供 Media 内容对象列表。

public interface MediaContent extends Content {

	Collection<Media> getMedia();

}

Message 接口有多种实现，对应于 AI 模型可以处理的不同类别的消息。模型根据对话角色区分消息类别。

2.3 、 `MessageType` 消息角色

这些角色由 MessageType 有效映射。每条消息都被分配了一个特定角色。这些角色对消息进行分类，为 AI 模型澄清每个提示片段的上下文和目的。这种结构化方法增强了与 AI 的交流的细致性和有效性，因为提示的每一部分在交互中都扮演着独特且明确定义的角色。

系统角色

指导 AI 的行为和响应风格，设置参数或规则，规定 AI 如何解释和回复输入。类似于在开始对话前为 AI 提供指令。

用户角色

代表用户的输入——他们对 AI 的问题、命令或陈述。这个角色是基础，因为它构成了 AI 响应的依据。

助手角色

AI 对用户输入的响应。不仅仅是答案或反应，对于维持对话的流畅性至关重要。通过跟踪 AI 先前的响应（其”助手角色”消息），系统确保交互的连贯性和上下文相关性。助手消息还可能包含函数工具调用请求信息。这就像 AI 的一个特殊功能，在需要时用于执行特定功能，如计算、获取数据或其他超出对话的任务。

工具/函数角色

工具/函数角色专注于响应工具调用助手消息时返回额外信息。

角色在 Spring AI 中以枚举方式表示

public enum MessageType {

	USER("user"),

	ASSISTANT("assistant"),

	SYSTEM("system"),

	TOOL("tool");

    ...
}

2.4、PromptTemplate

Spring AI 中提示模板的关键组件是 PromptTemplate 类，旨在便于创建结构化提示，然后将其发送给 AI 模型进行处理。

public class PromptTemplate implements PromptTemplateActions, PromptTemplateMessageActions {

    // 其他方法后续讨论
}

该类使用 TemplateRenderer API 渲染模板。默认情况下，Spring AI 使用基于 Terence Parr 开发的开源 StringTemplate 引擎的 StTemplateRenderer 实现。模板变量由 {} 语法标识，但您也可以配置分隔符以使用其他语法。

public interface TemplateRenderer extends BiFunction<String, Map<String, Object>, String> {

	@Override
	String apply(String template, Map<String, Object> variables);

}

Spring AI 使用 TemplateRenderer 接口处理变量到模板字符串的实际替换。默认实现使用 StringTemplate。如果需要自定义逻辑，您可以提供自己的 TemplateRenderer 实现。对于不需要模板渲染的场景（例如模板字符串已完整），可以使用提供的 NoOpTemplateRenderer。

PromptTemplate promptTemplate = PromptTemplate.builder()
    .renderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
    .template("""
            告诉我 5 部由 <composer> 作曲的电影名称。
            """)
    .build();

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

该类实现的接口支持提示创建的不同方面：

PromptTemplateStringActions 专注于创建和渲染提示字符串，代表最基本的提示生成形式。
PromptTemplateMessageActions 针对通过生成和操作 Message 对象进行提示创建。
PromptTemplateActions 旨在返回 Prompt 对象，可传递给 ChatModel 以生成响应。

虽然这些接口在许多项目中可能不会被广泛使用，但它们展示了提示创建的不同方法。

实现的接口如下：

public interface PromptTemplateStringActions {

	String render();

	String render(Map<String, Object> model);

}

PromptTemplateStringActions 方法

public interface PromptTemplateMessageActions {

	Message createMessage();

    Message createMessage(List<Media> mediaList);

	Message createMessage(Map<String, Object> model);

}

PromptTemplateMessageActions 方法

public interface PromptTemplateActions extends PromptTemplateStringActions {

	Prompt create();

	Prompt create(ChatOptions modelOptions);

	Prompt create(Map<String, Object> model);

	Prompt create(Map<String, Object> model, ChatOptions modelOptions);

}

PromptTemplateActions 方法

Prompt create()：生成不带外部数据输入的 Prompt 对象，适用于静态或预定义的提示。
Prompt create(ChatOptions modelOptions)：生成不带外部数据输入且带有特定聊天请求选项的 Prompt 对象。
Prompt create(Map<String, Object> model)：扩展提示创建能力以包含动态内容，接受 Map<String, Object>，每个 map 条目是提示模板中的占位符及其关联的动态值。
Prompt create(Map<String, Object> model, ChatOptions modelOptions)：扩展提示创建能力以包含动态内容，接受 Map<String, Object>，每个 map 条目是提示模板中的占位符及其关联的动态值，并带有特定的聊天请求选项。

2.5、示例用法

PromptTemplate promptTemplate = new PromptTemplate("Tell me a {adjective} joke about {topic}");

Prompt prompt = promptTemplate.create(Map.of("adjective", adjective, "topic", topic));

return chatModel.call(prompt).getResult();

三、构建提示（Prompt）的三种模式

提示是引导模型输出的关键，ChatClient支持三种构建方式，满足不同复杂度需求：

3.1、逐层构建（复杂场景）

显式添加系统消息、用户消息，支持动态参数替换：

String response = chatClient.prompt()  
    .system(s -> s.text("以{style}风格回答").param("style", "古风"))  // 系统消息含占位符  
    .user("解释什么是人工智能")  // 用户消息  
    .option(OpenAiChatOptions.builder().temperature(0.8).build())  // 模型参数（如OpenAI特有参数）  
    .call()  
    .content();

优势：细粒度控制消息结构，支持多轮对话历史拼接。

3.2、预构建Prompt对象（批量处理）

适用于提示模板化场景，提前组装消息列表：

// 定义提示模板  
Prompt promptTemplate = Prompt.builder()  
    .systemMessage("你是一个幽默的助手")  
    .userMessage("讲一个{topic}相关的笑话")  
    .build();  

// 运行时填充参数  
Prompt dynamicPrompt = promptTemplate.replaceParams(Map.of("topic", "程序员"));  
ChatResponse response = chatClient.prompt(dynamicPrompt).call().chatResponse();

最佳实践：将常用提示模板存入数据库或配置中心，实现动态加载。

3.3、快捷方式（极简场景）

单行代码完成用户消息提交，适用于简单问答：

String answer = chatClient.prompt("如何煮咖啡").call().content();

注意：此模式默认无系统消息，模型行为依赖其基础训练数据。

四、ChatClient响应处理：从文本到结构化数据

4.1、获取完整元数据（性能监控和Token消耗计算）

通过chatResponse()获取包含令牌消耗、生成结果列表的完整响应：

ChatResponse response = chatClient.prompt()  
    .user("计算1+1等于多少")  
    .call()  
    .chatResponse();  

System.out.println("总令牌数：" + response.getMetadata().getUsage().getTotalTokens());  
System.out.println("生成结果：" + response.getResults().get(0).getOutput());

关键元数据：

totalTokens：请求+响应的总令牌数（影响调用成本）。
completionTokens：响应生成的令牌数。
promptTokens：提示内容的令牌数。

4.2、自动映射Java对象（结构化输出）

通过entity()方法将模型输出转为自定义实体，需确保输出格式符合JSON规范：

// 定义目标实体  
record Recipe(String dish, List<String> ingredients) {}  

// 生成食谱并映射  
Recipe salad = chatClient.prompt()  
    .user("生成一份蔬菜沙拉食谱，以JSON格式输出")  
    .call()  
    .entity(Recipe.class);  // 自动解析JSON为对象  

System.out.println("菜名：" + salad.dish());  
System.out.println("食材：" + salad.ingredients());

进阶技巧：结合StructuredOutputConverter自定义解析逻辑，处理非标准格式。