Mistral AI 函式呼叫（已棄用）

本頁描述了函式呼叫 API 的舊版本，該版本已棄用，並標記為在下一版本中移除。當前版本可在 工具呼叫 檢視。更多資訊請參見 遷移指南。

您可以使用 MistralAiChatModel 註冊自定義 Java 函式，並讓 Mistral AI 模型智慧地選擇輸出一個 JSON 物件，其中包含呼叫一個或多個已註冊函式的引數。這使得您可以將 LLM 能力與外部工具和 API 連線起來。open-mixtral-8x22b、mistral-small-latest 和 mistral-large-latest 模型經過訓練，可以檢測何時應該呼叫函式並響應符合函式簽名的 JSON。

Mistral AI 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 極大地簡化了您需要編寫的支援函式呼叫的程式碼。它為您代理了函式呼叫對話。您可以簡單地將您的函式定義作為 @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

使用 MistralAiChatModel 自動配置，您可以透過多種方式將自定義函式註冊為 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 模型選擇正確的函式進行呼叫。

PaymentStatusBeanIT.java 演示了這種方法。

Mistral AI 的 PaymentStatusBeanOpenAiIT 使用 OpenAI API 實現了相同的功能。在這方面，Mistral AI 與 OpenAI 幾乎相同。

ToolCallback 包裝器

註冊函式的另一種方法是建立一個 FunctionToolCallback，如下所示

@Configuration
static class Config {

	@Bean
	public FunctionToolCallback weatherFunctionInfo() {

    return 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();
	}

}

它包裝了第三方 MockWeatherService 函式，並將其作為 CurrentWeather 函式註冊到 MistralAiChatModel。它還提供了描述 (2) 和函式簽名 (3)，以告知模型函式期望哪些引數。

預設情況下，響應轉換器會執行 Response 物件的 JSON 序列化。
FunctionToolCallback 內部根據 MockWeatherService.Request 類解析函式呼叫簽名。

在 Chat 選項中指定函式

為了讓模型知道並呼叫您的 CurrentWeather 函式，您需要在您的 prompt 請求中啟用它

MistralAiChatModel chatModel = ...

UserMessage userMessage = new UserMessage("What's the weather like in Paris?");

ChatResponse response = this.chatModel.call(new Prompt(this.userMessage,
		MistralAiChatOptions.builder().tools("CurrentWeather").build())); // Enable the function

logger.info("Response: {}", response);

上述使用者問題將觸發對 CurrentWeather 函式的 3 次呼叫（每個城市一次），最終的響應將是這樣的

使用 Prompt 選項註冊/呼叫函式

除了自動配置，您還可以動態地使用您的 Prompt 請求註冊回撥函式

MistralAiChatModel chatModel = ...

UserMessage userMessage = new UserMessage("What's the weather like in Paris?");

var promptOptions = MistralAiChatOptions.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 中註冊的函式預設是啟用的。

這種方法允許根據使用者輸入動態選擇要呼叫的不同函式。

PaymentStatusPromptIT.java 整合測試提供了一個完整的示例，演示瞭如何使用 MistralAiChatModel 註冊函式並在 prompt 請求中使用它。

附錄

（部落格）使用最新的 Mistral AI API 在 Java 和 Spring AI 中進行函式呼叫

Mistral AI API 函式呼叫流程

下圖說明了 Mistral AI 低階 API 的 函式呼叫 流程

mistral ai function calling flow

PaymentStatusFunctionCallingIT.java 提供瞭如何使用 Mistral AI API 函式呼叫的完整示例。它基於 Mistral AI 函式呼叫教程。