Ollama 函数调用 (已弃用)
| 您需要 Ollama 0.2.8 或更高版本才能使用函数调用功能，需要 Ollama 0.4.6 或更高版本才能在流式模式下使用这些功能。 |
您需要预训练支持 Tools 的模型。通常，这类模型会带有 Tools 标签。 |
您可以使用 OllamaChatModel 注册自定义 Java 函数，并让 Ollama 部署的模型智能地选择输出一个 JSON 对象，其中包含调用一个或多个注册函数的参数。这使您可以将 LLM 功能与外部工具和 API 连接起来。带有 Tools 标签的 Ollama 模型（参阅完整列表）经过训练，能够检测何时应调用函数，并响应符合函数签名的 JSON。
Ollama API 不直接调用函数；相反，模型会生成 JSON，您可以使用该 JSON 在代码中调用函数，并将结果返回给模型以完成对话。Spring AI 提供了灵活且用户友好的方式来注册和调用自定义函数。通常，自定义函数需要提供一个函数 name、description 以及函数调用 signature（作为 JSON schema），以便让模型知道函数需要哪些参数。description 有助于模型理解何时应调用该函数。
作为开发者，您需要实现一个函数，该函数接收 AI 模型发送的函数调用参数，并将结果响应回模型。您的函数可以进一步调用其他第三方服务来提供结果。
Spring AI 使这变得非常简单，只需定义一个返回 java.util.Function 的 @Bean 定义，并在调用 ChatModel 时将 bean 名称作为选项提供即可。
在底层，Spring 使用适当的适配器代码包装您的 POJO（即函数），从而实现与 AI 模型的交互，避免您编写繁琐的样板代码。底层基础设施的基础是 ToolCallback.java 接口以及配套的 Builder 工具类，用于简化 Java 回调函数的实现和注册。
工作原理
假设我们希望 AI 模型响应它不具备的信息，例如给定地点的当前温度。
我们可以向 AI 模型提供有关我们自己的函数的元数据，模型可以在处理您的 prompt 时使用这些元数据来检索信息。
例如，如果在处理 prompt 期间，AI 模型确定需要关于给定地点温度的额外信息，它将启动一个由服务器端生成的请求/响应交互。AI 模型会调用客户端函数。AI 模型提供方法的调用详细信息（格式为 JSON），客户端负责执行该函数并返回响应。
模型与客户端的交互在 Spring AI 函数调用流程图 中有所阐述。
Spring AI 大大简化了您需要编写的用于支持函数调用的代码。它为您代理函数调用对话。您只需将函数定义作为 @Bean 提供，然后在您的 prompt 选项中提供该函数的 bean 名称即可。您也可以在您的 prompt 中引用多个函数 bean 名称。
快速入门
让我们创建一个聊天机器人，通过调用我们自己的函数来回答问题。为了支持聊天机器人的响应，我们将注册一个函数，该函数接收一个地点并返回该地点的当前天气。
当模型需要回答诸如“波士顿天气怎么样？”的问题时，AI 模型将调用客户端，将地点值作为参数传递给函数。这种类似 RPC 的数据以 JSON 格式传递。
我们的函数会调用基于 SaaS 的天气服务 API，并将天气响应返回给模型以完成对话。在此示例中，我们将使用一个名为 MockWeatherService 的简单实现，它对不同地点的温度进行硬编码。
以下 MockWeatherService.java 代表天气服务 API
public class MockWeatherService implements Function<Request, Response> {
public enum Unit { C, F }
public record Request(String location, Unit unit) {}
public record Response(double temp, Unit unit) {}
public Response apply(Request request) {
return new Response(30.0, Unit.C);
}
}将函数注册为 Bean
通过 OllamaChatModel Auto-Configuration，您可以通过多种方式将自定义函数注册为 Spring 上下文中的 bean。
我们首先介绍最 POJO 友好的选项。
普通 Java 函数
在这种方法中，您可以在应用程序上下文中像定义任何其他 Spring 管理的对象一样定义一个 @Bean。
在内部，Spring AI ChatModel 将创建一个 ToolCallback 实例，该实例添加了通过 AI 模型调用它的逻辑。@Bean 的名称作为 ChatOption 传递。
@Configuration
static class Config {
@Bean
@Description("Get the weather in location") // function description
public Function<MockWeatherService.Request, MockWeatherService.Response> currentWeather() {
return new MockWeatherService();
}
}@Description 注解是可选的，它提供函数描述，帮助模型理解何时应调用该函数。这是一个重要的属性，有助于 AI 模型确定要调用哪个客户端函数。
提供函数描述的另一种选项是在 MockWeatherService.Request 上使用 @JsonClassDescription 注解
@Configuration
static class Config {
@Bean
public Function<Request, Response> currentWeather() { // bean name as function name
return new MockWeatherService();
}
}
@JsonClassDescription("Get the weather in location") // // function description
public record Request(String location, Unit unit) {}最佳实践是用信息注解请求对象，以便该函数生成的 JSON schema 尽可能具有描述性，帮助 AI 模型选择正确的函数进行调用。
ToolCallback
另一种注册函数的方法是创建 ToolCallback，如下所示：
@Configuration
static class Config {
@Bean
public FunctionToolCallback weatherFunctionInfo() {
return FunctionToolCallback.builder("CurrentWeather", new MockWeatherService()) // (1) function name
.description("Get the weather in location") // (2) function description
.inputType(MockWeatherService.Request.class) // (3) function signature
.build();
}
}它封装了第三方 MockWeatherService 函数，并将其注册为 OllamaChatModel 的 CurrentWeather 函数。它还提供描述 (2) 和函数签名 (3)，以便模型知道函数需要哪些参数。
| 默认情况下，响应转换器会执行 Response 对象的 JSON 序列化。 |
FunctionToolCallback 内部根据 MockWeatherService.Request 类解析函数调用签名。 |
在聊天选项中指定函数
要让模型知道并调用您的 CurrentWeather 函数，您需要在 prompt 请求中启用它
OllamaChatModel chatModel = ...
UserMessage userMessage = new UserMessage("What's the weather like in San Francisco, Tokyo, and Paris?");
ChatResponse response = this.chatModel.call(new Prompt(this.userMessage,
OllamaOptions.builder().tools("CurrentWeather").build())); // Enable the function
logger.info("Response: {}", response);以上用户问题将触发对 CurrentWeather 函数的 3 次调用（每个城市一次），最终响应将如下所示：
Here is the current weather for the requested cities: - San Francisco, CA: 30.0°C - Tokyo, Japan: 10.0°C - Paris, France: 15.0°C
OllamaFunctionCallbackIT.java 测试演示了这种方法。
使用 Prompt 选项注册/调用函数
除了自动配置，您还可以使用 Prompt 请求动态注册回调函数
OllamaChatModel chatModel = ...
UserMessage userMessage = new UserMessage("What's the weather like in San Francisco, Tokyo, and Paris?");
var promptOptions = OllamaOptions.builder()
.toolCallbacks(List.of(FunctionToolCallback.builder("CurrentWeather", new MockWeatherService()) // (1) function name and instance
.description("Get the weather in location") // (2) function description
.inputType(MockWeatherService.Request.class) // (3) function signature
.build())) // function code
.build();
ChatResponse response = this.chatModel.call(new Prompt(this.userMessage, this.promptOptions));| 默认情况下，在本次请求期间，prompt 中注册的函数是启用的。 |
这种方法允许您根据用户输入动态选择要调用的不同函数。
FunctionCallbackInPromptIT.java 集成测试提供了如何在 OllamaChatModel 中注册函数并在 prompt 请求中使用它的完整示例。
