Spring-AI Tool Calling 过程中字符串与对象间的转换

最新推荐文章于 2025-12-20 19:32:34 发布

原创

最新推荐文章于 2025-12-20 19:32:34 发布 · 768 阅读

11 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能 #spring #python #SpringAI

如何让小智AI成为你的第二大脑——“免费”送小智AI智能音箱征文活动 10w+人浏览 428人参与

AI助手已提取文章相关产品：

在 Spring AI 的 Tool Calling 过程中，字符串与对象之间的转换主要发生在数据进入 Java 方法之前（反序列化/入参转换）和数据返回给 LLM 之前（序列化/结果转换）两个阶段
另外就是给LLM提供所能使用工具转换为 LLM 能识别的 ToolDefinition 对象

转换方向	源数据类型 (Source)	目标数据类型 (Target)	触发时机	作用
反序列化	JSON String (LLM Output)	Map / POJO (Java Args)	LLM 返回工具调用请求时	让 Java 方法能接收到结构化参数
序列化	POJO / Any Object (Java Return)	JSON String (LLM Input)	Java 方法执行完成后	让 LLM 能读懂工具的执行结果
元数据构建	Java Annotations (Code)	JSON Schema (Model Input)	ChatClient 初始化/调用前	告诉 LLM 有哪些工具可用及参数格式

将Tool Call返回值转换：从 Java 对象到字符串

当 Java 工具方法执行完毕后，其返回结果需要被转换为字符串（通常是 JSON），以便 LLM 能够理解并将其整合到最终回复中。

Java 对象 →→ JSON 字符串
- 场景：工具方法执行后返回了一个 POJO、Record、集合或复杂对象。
- 转换逻辑：这是最核心的转换环节。Spring AI 使用 ToolCallResultConverter 接口来处理此过程。
- 默认实现：DefaultToolCallResultConverter 会使用 JsonParser.toJson(result) 将对象序列化为 JSON 字符串。
- 特殊处理：
  - 如果返回类型是 Void 或 void，默认转换器会将其转为简单的字符串 "Done"。
  - 如果返回的是原始类型（如 String, Integer），通常直接调用 .toString() 或序列化为 JSON 基元。
自定义结果转换器
- 场景：你不想把整个对象都发给 LLM，或者需要特定的格式（如 XML、纯文本摘要）。
- 转换逻辑：你可以通过 @Tool(resultConverter = CustomConverter.class) 指定自定义的 ToolCallResultConverter，从而控制对象转字符串的逻辑。

FunctionToolCallback

默认使用DefaultToolCallResultConverter将工具调用的结果转换为String实例

	public FunctionToolCallback(ToolDefinition toolDefinition, @Nullable ToolMetadata toolMetadata, Type toolInputType,
			BiFunction<I, ToolContext, O> toolFunction, @Nullable ToolCallResultConverter toolCallResultConverter) {
   
   
		Assert.notNull(toolDefinition, "toolDefinition cannot be null");
		Assert.notNull(toolInputType, "toolInputType cannot be null");
		Assert.notNull(toolFunction, "toolFunction cannot be null");
		this.toolDefinition = toolDefinition;
		this.toolMetadata = toolMetadata != null ? toolMetadata : DEFAULT_TOOL_METADATA;
		this.toolFunction = toolFunction;
		this.toolInputType = toolInputType;
		this.toolCallResultConverter = toolCallResultConverter != null ? toolCallResultConverter
				: DEFAULT_RESULT_CONVERTER;
	}
	
   	@Override
	public String call(String toolInput, @Nullable ToolContext toolContext) {
   
   
		Assert.hasText(toolInput, "toolInput cannot be null or empty");

		logger.debug("Starting execution of tool: {}", this.toolDefinition.name());

		I request = JsonParser.fromJson(toolInput, this.toolInputType);
		O response = callMethod(request, toolContext);

		logger.debug("Successful execution of tool: {}", this.toolDefinition.name());

		return this.toolCallResultConverter.convert(response, null);
	}

MethodToolCallback

默认使用DefaultToolCallResultConverter将工具调用的结果转换为String实例

	public MethodToolCallback(ToolDefinition toolDefinition, @Nullable ToolMetadata toolMetadata, Method toolMethod,
			@Nullable Object toolObject, @Nullable ToolCallResultConverter toolCallResultConverter) {
   
   
		Assert.notNull(toolDefinition, "toolDefinition cannot be null");
		Assert.notNull(toolMethod, "toolMethod cannot be null");
		Assert.isTrue(Modifier.isStatic(toolMethod.getModi