Spring AI提示词与消息对象实战解析

1. Spring AI 提示词与消息对象深度解析

作为一名长期从事企业级AI应用开发的工程师，我深刻理解在复杂业务场景中构建高质量对话系统的重要性。Spring AI提供的Prompt和Message体系，正是解决这一问题的利器。本文将带你深入掌握这套工具链的核心设计理念与实战技巧。

2. 提示词（Prompt）体系详解

2.1 Prompt的设计哲学

Spring AI中的Prompt对象本质上是一个消息容器，其核心设计体现了三个关键原则：

1. 不可变性：所有Message对象都是不可变的（Immutable），这保证了在多线程环境下的安全性
2. 组合优于继承：通过组合不同的Message类型实现复杂交互，而非使用复杂的继承体系
3. 建造者模式：采用Builder模式提供灵活的构造方式

这种设计特别适合AI交互场景，因为：

• 对话上下文需要保持一致性
• 消息组合方式千变万化
• 配置参数需要灵活调整

2.2 实战：构建专业级Prompt

2.2.1 基础构造方式

java复制// 简单文本构造（内部自动转换为UserMessage）
Prompt simplePrompt = new Prompt("解释量子计算基础");

// 显式指定Message类型
SystemMessage systemMsg = new SystemMessage("你是一位物理学教授");
UserMessage userMsg = new UserMessage("用通俗语言解释量子纠缠");
Prompt academicPrompt = new Prompt(List.of(systemMsg, userMsg));

2.2.2 Builder模式进阶用法

Builder模式在实际开发中更为推荐，特别是在需要添加元数据或模型参数时：

java复制// 创建带有元数据的Prompt
Prompt marketingPrompt = Prompt.builder()
    .messages(
        new SystemMessage("你是资深市场营销专家"),
        new UserMessage("为新产品撰写广告语")
    )
    .metadata(Map.of(
        "campaignId", "2024Q3-001",
        "targetAudience", "25-35岁都市女性"
    ))
    .build();

// 带模型参数的Prompt
ChatOptions options = ChatOptions.builder()
    .temperature(0.7f)
    .maxTokens(500)
    .topP(0.9f)
    .build();

Prompt controlledPrompt = Prompt.builder()
    .messages(new UserMessage("生成技术方案"))
    .chatOptions(options)
    .build();

关键经验：在需要严格控制的场景（如客服系统），建议将temperature设为0.1-0.3；在创意场景可以设为0.7-1.0

2.3 Prompt的实用方法解析

2.3.1 消息增强（augmentUserMessage）

这个方法在实际业务中非常有用，特别是在需要保持上下文的情况下追加用户输入：

java复制Prompt original = new Prompt("列出Spring的核心模块");
Prompt enhanced = original.augmentUserMessage("特别说明IoC和AOP的关系");

// 等效于：
List<Message> newMessages = new ArrayList<>(original.getMessages());
newMessages.add(new UserMessage("特别说明IoC和AOP的关系"));
Prompt manualEnhanced = new Prompt(newMessages);

2.3.2 深拷贝与修改

在需要修改现有Prompt时，正确的做法是：

java复制Prompt original = new Prompt("初始问题");

// 错误方式（会抛出UnsupportedOperationException）
// original.getMessages().add(new UserMessage("新问题")); 

// 正确方式1：使用mutate()
Prompt modified = original.mutate()
    .messages(new UserMessage("修改后的问题"))
    .build();

// 正确方式2：使用copy() + 新建List
Prompt copied = original.copy();
List<Message> newMsgs = new ArrayList<>(copied.getMessages());
newMsgs.add(new UserMessage("追加问题"));
Prompt appended = new Prompt(newMsgs);

3. 消息类型深度剖析

3.1 用户消息（UserMessage）实战技巧

3.1.1 多媒体消息处理

现代AI系统常需要处理多媒体输入，UserMessage提供了完善的支持：

java复制// 处理本地文件
Resource pdfResource = new FileSystemResource("spec.pdf");
UserMessage fileMessage = UserMessage.builder()
    .resource(pdfResource)
    .metadata(Map.of("fileType", "PDF"))
    .build();

// 处理网络图片
Media imageMedia = new Media("image/jpeg", "https://example.com/product.jpg");
UserMessage mediaMessage = UserMessage.builder()
    .media(imageMedia)
    .text("分析这张图片中的主要元素")
    .build();

避坑指南：不同AI提供商对文件类型的支持差异很大，建议在metadata中明确标注文件类型，并在调用前检查模型能力

3.1.2 元数据的最佳实践

元数据在以下场景特别有用：

• 请求追踪（requestId）
• 用户会话管理（sessionId）
• 业务上下文传递（productId等）

java复制UserMessage trackedMessage = UserMessage.builder()
    .text("查询订单状态")
    .metadata(Map.of(
        "requestId", UUID.randomUUID().toString(),
        "userId", "user_12345",
        "timestamp", Instant.now().toString()
    ))
    .build();

3.2 系统消息（SystemMessage）高级用法

3.2.1 全局系统消息配置

在企业级应用中，全局系统消息可以确保所有交互遵循统一规则：

java复制@Configuration
public class AiConfig {
    
    @Bean
    public ChatClient chatClient(ChatModel model) {
        return ChatClient.builder(model)
            .defaultSystem("""
                你是企业级AI助手，必须遵守：
                1. 回复使用专业商务语气
                2. 数据需准确注明来源
                3. 禁止提供法律/医疗建议
                4. 遇到不确定的问题应明确说明
                """)
            .build();
    }
}

3.2.2 动态系统消息策略

在某些场景下，需要根据用户特征动态调整系统消息：

java复制public Prompt buildDynamicPrompt(UserProfile profile) {
    String systemMessage = switch(profile.getUserType()) {
        case "VIP" -> "你是专属VIP顾问，提供深度个性化服务";
        case "NEW" -> "你是新手引导助手，解释需详细耐心";
        default -> "你是标准客服助手";
    };
    
    return Prompt.builder()
        .messages(
            new SystemMessage(systemMessage),
            new UserMessage(profile.getQuestion())
        )
        .build();
}

3.3 助手消息（AssistantMessage）的工程实践

3.3.1 处理复杂响应

现代AI模型可能返回多种类型的响应，需要妥善处理：

java复制ChatResponse response = chatClient.prompt()
    .user("查询北京天气")
    .call()
    .chatResponse();

AssistantMessage assistantMsg = response.getResult().getOutput();

if (assistantMsg.hasToolCalls()) {
    // 处理工具调用
    assistantMsg.getToolCalls().forEach(tool -> {
        System.out.println("需要调用工具: " + tool.name());
        // 执行具体工具逻辑...
    });
} else {
    // 处理普通文本响应
    System.out.println("AI回复: " + assistantMsg.getText());
}

3.3.2 构建对话历史

实现连贯的多轮对话需要精心管理上下文：

java复制// 对话历史缓存
List<Message> conversationHistory = new ArrayList<>();

// 第一轮
UserMessage userMsg1 = new UserMessage("推荐适合的程序员笔记本电脑");
AssistantMessage assistantMsg1 = chatClient.prompt()
    .messages(userMsg1)
    .call()
    .getResult()
    .getOutput();
    
conversationHistory.add(userMsg1);
conversationHistory.add(assistantMsg1);

// 第二轮
UserMessage userMsg2 = new UserMessage("预算不超过8000元");
conversationHistory.add(userMsg2);

AssistantMessage assistantMsg2 = chatClient.prompt()
    .messages(conversationHistory)
    .call()
    .getResult()
    .getOutput();

性能提示：长时间对话要注意Token消耗，可考虑实现自动摘要机制压缩历史

3.4 工具响应消息（ToolResponseMessage）集成模式

当AI需要调用外部工具时，完整的交互流程如下：

java复制// 1. AI请求工具调用
AssistantMessage toolCallMsg = chatClient.prompt()
    .user("查询上海浦东的当前温度")
    .call()
    .getResult()
    .getOutput();

// 2. 解析工具调用
AssistantMessage.ToolCall weatherTool = toolCallMsg.getToolCalls().get(0);
Map<String, Object> args = parseJson(weatherTool.arguments());
String location = (String) args.get("location");

// 3. 执行实际工具
WeatherService weatherService = new WeatherService();
float temperature = weatherService.getCurrentTemperature(location);

// 4. 构建工具响应
ToolResponseMessage toolResponse = ToolResponseMessage.builder()
    .toolCallId(weatherTool.id())
    .content(String.valueOf(temperature))
    .build();

// 5. 将响应传回AI
AssistantMessage finalResponse = chatClient.prompt()
    .messages(toolCallMsg, toolResponse)
    .call()
    .getResult()
    .getOutput();

4. 生产环境中的常见问题与解决方案

4.1 消息顺序陷阱

问题现象：AI对上下文理解出现偏差

错误示例：

java复制// 错误的顺序会导致理解混乱
Prompt confusedPrompt = new Prompt(List.of(
    assistantMsg,  // 先放AI回复
    userMsg        // 后放用户问题
));

解决方案：严格遵循"系统消息→用户消息→助手消息"的时间顺序

4.2 Token限制处理

问题现象：请求因超出Token限制被拒绝

优化策略：

java复制// 自动截断长消息
public Message truncateMessage(Message original, int maxTokens) {
    String text = original.getText();
    if (text.length() > maxTokens * 3) { // 粗略估算
        return original.mutate()
            .text(text.substring(0, maxTokens * 3))
            .metadata(Map.of("truncated", "true"))
            .build();
    }
    return original;
}

4.3 多模态支持差异

兼容性处理方案：

java复制public void validateMediaSupport(ChatModel model, Media media) {
    if (model instanceof OpenAiChatModel) {
        if (!Set.of("image/jpeg", "image/png").contains(media.getMimeType())) {
            throw new UnsupportedMediaType("OpenAI仅支持JPEG/PNG");
        }
    }
    // 其他模型检查...
}

5. 性能优化与高级技巧

5.1 消息预处理流水线

java复制public class MessagePreprocessor {
    private final List<Function<Message, Message>> processors = List.of(
        this::sanitizeContent,
        this::injectMetadata,
        this::checkLength
    );
    
    public Message process(Message original) {
        Message result = original;
        for (var processor : processors) {
            result = processor.apply(result);
        }
        return result;
    }
    
    private Message sanitizeContent(Message msg) {
        // 实现内容清洗逻辑
    }
}

5.2 智能上下文管理

java复制public class ConversationManager {
    private final Deque<Message> history = new ArrayDeque<>();
    private final int maxHistoryLength;
    
    public void addMessage(Message msg) {
        history.addLast(msg);
        while (history.size() > maxHistoryLength) {
            history.removeFirst();
        }
    }
    
    public Prompt buildCurrentPrompt() {
        return new Prompt(new ArrayList<>(history));
    }
}

5.3 消息压缩策略

对于长对话历史，可以采用以下压缩方法：

1. 删除不重要的中间对话
2. 对旧消息生成摘要
3. 使用向量数据库存储历史

java复制public List<Message> compressHistory(List<Message> fullHistory) {
    if (fullHistory.size() <= 10) return fullHistory;
    
    List<Message> compressed = new ArrayList<>();
    // 保留最重要的首尾消息
    compressed.add(fullHistory.get(0));
    compressed.add(fullHistory.get(fullHistory.size()-1));
    
    // 对中间部分生成摘要
    String summary = generateSummary(fullHistory.subList(1, fullHistory.size()-1));
    compressed.add(1, new SystemMessage("先前对话摘要：" + summary));
    
    return compressed;
}

掌握Spring AI的消息体系需要理解其设计哲学，并在实践中不断积累经验。我建议从简单场景开始，逐步尝试更复杂的消息组合方式，同时注意记录不同消息结构对AI输出的影响，这样才能真正发挥这套工具的强大威力。