Spring AI中Prompt对象元数据传递问题的分析与解决

在Spring AI框架的使用过程中，开发者可能会遇到一个关于元数据传递的典型问题：当通过AdvisedRequest.toPrompt()方法获取Prompt对象时，原始消息中设置的元数据会意外丢失。这个问题在早期版本中尤为明显，但理解其背后的机制对于正确使用Spring AI至关重要。

问题现象

当开发者尝试在Spring AI中为消息添加元数据时，通常会这样操作：

Map<String, Object> metadata = new HashMap<>();
metadata.put("conversationId", "12345");
metadata.put("userId", "user1");

UserMessage userMessage = new UserMessage("查询内容", Collections.emptyList(), metadata);

然而，在后续的调用链中，特别是在自定义的Advisor实现中，当通过request.toPrompt()获取Prompt对象时：

Prompt prompt = request.toPrompt();
Message lastMessage = prompt.getMessages().get(prompt.getMessages().size()-1);
Map<String, Object> metadata = lastMessage.getMetadata(); // 返回null

开发者会发现原本设置的元数据已经丢失，这会导致依赖于这些元数据的业务逻辑无法正常工作。

问题根源

这个问题的本质在于Spring AI早期版本(M6及之前)中Prompt对象的构建方式。当调用toPrompt()方法时，框架会创建一个新的消息对象，而在这个过程中没有正确处理原始消息中的元数据，导致这些附加信息被丢弃。

这种设计在需要跟踪对话上下文(如conversationId)或用户身份(userId)的场景下尤为不利，因为这些信息对于构建连贯的对话体验至关重要。

解决方案演进

Spring AI团队在后续版本(M8)中重构了这部分逻辑，主要改进包括：

1. 引入了新的ChatClientRequest对象替代原有的AdvisedRequest
2. 直接传递完整的Prompt对象而非重新构建
3. 确保所有消息属性(包括元数据)在调用链中完整传递

在新的实现中，开发者可以这样获取Prompt对象：

@Override
ChatClientResponse adviseCall(ChatClientRequest chatClientRequest, CallAdvisorChain callAdvisorChain) {
    Prompt prompt = chatClientRequest.prompt(); // 获取完整的Prompt对象
    // 现在可以正确访问元数据
    Map<String, Object> metadata = prompt.getMessages().get(0).getMetadata();
    return callAdvisorChain.next(chatClientRequest);
}

最佳实践建议

1. 版本选择：对于新项目，建议直接使用Spring AI M8或更高版本，避免遇到元数据丢失问题

2. 元数据处理：

   • 对于关键业务元数据，建议在多个层面进行验证
   • 考虑添加日志记录，确保元数据按预期传递
   • 对于敏感信息，注意不要在日志中直接输出

3. 升级注意事项：

   • 从M6升级到M8时，需要重写Advisor实现
   • 注意API的变化，特别是AdvisedRequest到ChatClientRequest的转变
   • 测试所有依赖元数据的业务逻辑

4. 设计思考：

   • 元数据的设计应该遵循最小必要原则
   • 考虑元数据的生命周期和传递范围
   • 对于复杂的对话状态，可以考虑外部存储方案

总结

Spring AI框架在演进过程中不断完善其消息传递机制。元数据丢失问题从M6到M8的改进，体现了框架对开发者实际需求的响应。理解这一变化背后的设计思想，有助于开发者更好地构建基于Spring AI的对话应用，特别是在需要维护对话上下文和用户状态的复杂场景中。

对于仍在使用早期版本的开发者，建议尽快升级以利用这些改进。同时，这也提醒我们在使用任何框架时，都需要关注其核心对象的生命周期和传递机制，特别是在涉及自定义扩展点的时候。