Azure OpenAI 聊天

Azure 的 OpenAI 產品,由 ChatGPT 提供技術支援,不僅擴展了傳統 OpenAI 的功能,還提供了具有增強功能的人工智慧驅動文字生成。Azure 提供了額外的 AI 安全性和負責任的 AI 功能,如他們最近的更新 此處 所強調。

Azure 為 Java 開發人員提供了利用 AI 的全部潛力的機會,透過將其與一系列 Azure 服務整合,其中包括 AI 相關資源,例如 Azure 上的向量儲存體。

先決條件

Azure OpenAI 用戶端提供三個連線選項:使用 Azure API 金鑰、使用 OpenAI API 金鑰或使用 Microsoft Entra ID。

Azure API 金鑰和端點

Azure 入口網站 上的 Azure OpenAI 服務區段取得您的 Azure OpenAI endpointapi-key

Spring AI 定義了兩個組態屬性

  1. spring.ai.azure.openai.api-key:將此設定為從 Azure 取得的 API 金鑰 值。

  2. spring.ai.azure.openai.endpoint:將此設定為在 Azure 中佈建模型時取得的端點 URL。

您可以透過匯出環境變數來設定這些組態屬性

export SPRING_AI_AZURE_OPENAI_API_KEY=<INSERT AZURE KEY HERE>
export SPRING_AI_AZURE_OPENAI_ENDPOINT=<INSERT ENDPOINT URL HERE>

OpenAI 金鑰

若要使用 OpenAI 服務(而非 Azure)進行驗證,請提供 OpenAI API 金鑰。這會自動將端點設定為 api.openai.com/v1

使用此方法時,請將 spring.ai.azure.openai.chat.options.deployment-name 屬性設定為您想要使用的 OpenAI 模型 名稱。

export SPRING_AI_AZURE_OPENAI_OPENAI_API_KEY=<INSERT OPENAI KEY HERE>

Microsoft Entra ID

若要使用 Microsoft Entra ID(先前稱為 Azure Active Directory)進行驗證,請在您的組態中建立 TokenCredential bean。如果此 bean 可用,則將使用權杖認證建立 OpenAIClient 實例。bd === 部署名稱

若要使用 Azure AI 應用程式,您需要透過 Azure AI 入口網站 建立 Azure AI 部署。在 Azure 中,每個用戶端都必須指定一個 部署名稱 才能連線到 Azure OpenAI 服務。請務必注意,部署名稱 與您選擇部署的模型不同。例如,名為 'MyAiDeployment' 的部署可以設定為使用 GPT 3.5 Turbo 模型或 GPT 4.0 模型。

若要開始使用,請依照下列步驟使用預設設定建立部署

Deployment Name: `gpt-4o`
Model Name: `gpt-4o`

此 Azure 組態與 Spring Boot Azure AI Starter 及其自動組態功能的預設組態一致。如果您使用不同的部署名稱,請務必相應地更新組態屬性

spring.ai.azure.openai.chat.options.deployment-name=<my deployment name>

Azure OpenAI 和 OpenAI 的不同部署結構導致 Azure OpenAI 用戶端程式庫中有名為 deploymentOrModelName 的屬性。這是因為在 OpenAI 中沒有 部署名稱,只有 模型名稱

屬性 spring.ai.azure.openai.chat.options.model 已重新命名為 spring.ai.azure.openai.chat.options.deployment-name
如果您決定連線到 OpenAI 而不是 Azure OpenAI,方法是設定 spring.ai.azure.openai.openai-api-key=<您的 OpenAI 金鑰> 屬性,則 spring.ai.azure.openai.chat.options.deployment-name 會被視為 OpenAI 模型 名稱。

存取 OpenAI 模型

您可以將用戶端組態為直接使用 OpenAI 而不是 Azure OpenAI 部署的模型。為此,您需要設定 spring.ai.azure.openai.openai-api-key=<您的 OpenAI 金鑰> 而不是 spring.ai.azure.openai.api-key=<您的 Azure OpenAi 金鑰>

新增儲存庫和 BOM

Spring AI 成品發佈在 Spring Milestone 和 Snapshot 儲存庫中。請參閱 儲存庫 章節,將這些儲存庫新增至您的建置系統。

為了協助進行依賴性管理,Spring AI 提供了 BOM(物料清單),以確保在整個專案中使用一致版本的 Spring AI。請參閱 依賴性管理 章節,將 Spring AI BOM 新增至您的建置系統。

自動組態

Spring AI 為 Azure OpenAI 聊天用戶端提供 Spring Boot 自動組態。若要啟用它,請將下列依賴性新增至您專案的 Maven pom.xml 或 Gradle build.gradle 建置檔案

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai-spring-boot-starter'
}
請參閱 依賴性管理 章節,將 Spring AI BOM 新增至您的建置檔案。

聊天屬性

前綴 spring.ai.azure.openai 是用於組態與 Azure OpenAI 連線的屬性前綴。

屬性 描述 預設值

spring.ai.azure.openai.api-key

來自 Azure AI OpenAI 金鑰和端點 區段(位於 資源管理 下)的金鑰

-

spring.ai.azure.openai.endpoint

來自 Azure AI OpenAI 金鑰和端點 區段(位於 資源管理 下)的端點

-

spring.ai.azure.openai.openai-api-key

(非 Azure)OpenAI API 金鑰。用於向 OpenAI 服務(而非 Azure OpenAI)進行驗證。這會自動將端點設定為 api.openai.com/v1。請使用 api-keyopenai-api-key 屬性。使用此組態時,spring.ai.azure.openai.chat.options.deployment-name 會被視為 OpenAi 模型 名稱。

-

spring.ai.azure.openai.custom-headers

要包含在 API 請求中的自訂標頭對應。對應中的每個條目都代表一個標頭,其中鍵是標頭名稱,值是標頭值。

空對應

前綴 spring.ai.azure.openai.chat 是用於組態 Azure OpenAI 的 ChatModel 實作的屬性前綴。

屬性 描述 預設值

spring.ai.azure.openai.chat.enabled

啟用 Azure OpenAI 聊天模型。

true

spring.ai.azure.openai.chat.options.deployment-name

與 Azure 搭配使用時,這指的是模型的「部署名稱」,您可以在 oai.azure.com/portal 找到它。務必注意,在 Azure OpenAI 部署中,「部署名稱」與模型本身不同。圍繞這些術語的混淆源於使 Azure OpenAI 用戶端程式庫與原始 OpenAI 端點相容的意圖。Azure OpenAI 和 Sam Altman 的 OpenAI 提供的部署結構顯著不同。部署模型名稱以作為此完成請求的一部分提供。

gpt-4o

spring.ai.azure.openai.chat.options.maxTokens

要產生的最大 token 數。

-

spring.ai.azure.openai.chat.options.temperature

要使用的取樣溫度,用於控制產生完成項的明顯創造力。較高的值會使輸出更隨機,而較低的值會使結果更集中和確定。不建議為相同的完成請求修改溫度和 top_p,因為這兩個設定的交互作用難以預測。

0.7

spring.ai.azure.openai.chat.options.topP

使用稱為核取樣的溫度取樣的替代方法。此值會使模型考慮具有提供機率質量的 token 結果。

-

spring.ai.azure.openai.chat.options.logitBias

GPT token ID 和偏差分數之間的對應,會影響特定 token 出現在完成回應中的機率。Token ID 是透過外部 tokenizer 工具計算的,而偏差分數的範圍在 -100 到 100 之間,最小值和最大值分別對應於完全禁止或獨佔選擇 token。給定偏差分數的確切行為因模型而異。

-

spring.ai.azure.openai.chat.options.user

操作的呼叫者或最終使用者的識別碼。這可以用於追蹤或速率限制目的。

-

spring.ai.azure.openai.chat.options.n

應該為聊天完成回應產生的聊天完成選項數量。

-

spring.ai.azure.openai.chat.options.stop

將結束完成產生的文字序列集合。

-

spring.ai.azure.openai.chat.options.presencePenalty

一個值,用於根據產生的文字中已存在的 token 出現機率來影響產生的 token 出現機率。正值會使 token 在已經存在時不太可能出現,並增加模型輸出新主題的可能性。

-

spring.ai.azure.openai.chat.options.responseFormat

指定模型必須輸出的格式的物件。使用 AzureOpenAiResponseFormat.JSON 啟用 JSON 模式,這保證模型產生的訊息是有效的 JSON。使用 AzureOpenAiResponseFormat.TEXT 啟用 TEXT 模式。

-

spring.ai.azure.openai.chat.options.frequencyPenalty

一個值,用於根據產生的文字中累積的頻率來影響產生的 token 出現機率。正值會使 token 隨著頻率的增加而不太可能出現,並降低模型逐字重複相同陳述的可能性。

-

spring.ai.azure.openai.chat.options.proxy-tool-calls

如果為 true,Spring AI 將不會在內部處理函數呼叫,而是將其代理到用戶端。然後,用戶端有責任處理函數呼叫、將其分派到適當的函數並傳回結果。如果為 false(預設值),Spring AI 將在內部處理函數呼叫。僅適用於支援函數呼叫的聊天模型

false

所有以 spring.ai.azure.openai.chat.options 為前綴的屬性都可以在執行階段透過將請求特定的 執行階段選項 新增至 Prompt 呼叫來覆寫。

執行階段選項

AzureOpenAiChatOptions.java 提供了模型組態,例如要使用的模型、溫度、頻率懲罰等。

在啟動時,可以使用 AzureOpenAiChatModel(api, options) 建構函式或 spring.ai.azure.openai.chat.options.* 屬性組態預設選項。

在執行階段,您可以透過將新的、請求特定的選項新增至 Prompt 呼叫來覆寫預設選項。例如,若要覆寫特定請求的預設模型和溫度

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        AzureOpenAiChatOptions.builder()
            .withDeploymentName("gpt-4o")
            .withTemperature(0.4)
        .build()
    ));
除了模型特定的 AzureOpenAiChatOptions.java,您可以使用可移植的 ChatOptions 實例,使用 ChatOptionsBuilder#builder() 建立。

函數呼叫

您可以向 AzureOpenAiChatModel 註冊自訂 Java 函數,並讓模型智慧地選擇輸出 JSON 物件,其中包含呼叫一個或多個已註冊函數的引數。這是一種將 LLM 功能與外部工具和 API 連線的強大技術。閱讀更多關於 Azure OpenAI 函數呼叫 的資訊。

多模態

多模態是指模型同時理解和處理來自各種來源資訊的能力,包括文字、影像、音訊和其他資料格式。目前,Azure OpenAI gpt-4o 模型提供多模態支援。

Azure OpenAI 可以將 base64 編碼影像或影像 URL 清單與訊息結合。Spring AI 的 Message 介面透過引入 Media 類型來促進多模態 AI 模型。此類型包含有關訊息中媒體附件的資料和詳細資訊,利用 Spring 的 org.springframework.util.MimeTypejava.lang.Object 作為原始媒體資料。

以下程式碼範例摘錄自 OpenAiChatModelIT.java,說明如何使用 GPT_4_O 模型將使用者文字與影像融合。

URL url = new URL("https://spring-docs.dev.org.tw/spring-ai/reference/_images/multimodal.test.png");
String response = ChatClient.create(chatModel).prompt()
        .options(AzureOpenAiChatOptions.builder().withDeploymentName("gpt-4o").build())
        .user(u -> u.text("Explain what do you see on this picture?").media(MimeTypeUtils.IMAGE_PNG, this.url))
        .call()
        .content();
您也可以傳遞多個影像。

它將 multimodal.test.png 影像作為輸入

Multimodal Test Image

以及文字訊息「Explain what do you see on this picture?」(解釋你在這張圖片上看到什麼?),並產生如下的回應

This is an image of a fruit bowl with a simple design. The bowl is made of metal with curved wire edges that
create an open structure, allowing the fruit to be visible from all angles. Inside the bowl, there are two
yellow bananas resting on top of what appears to be a red apple. The bananas are slightly overripe, as
indicated by the brown spots on their peels. The bowl has a metal ring at the top, likely to serve as a handle
for carrying. The bowl is placed on a flat surface with a neutral-colored background that provides a clear
view of the fruit inside.

您也可以傳入類別路徑資源而不是 URL,如下例所示

Resource resource = new ClassPathResource("multimodality/multimodal.test.png");

String response = ChatClient.create(chatModel).prompt()
    .options(AzureOpenAiChatOptions.builder()
    .withDeploymentName("gpt-4o").build())
    .user(u -> u.text("Explain what do you see on this picture?")
    .media(MimeTypeUtils.IMAGE_PNG, this.resource))
    .call()
    .content();

範例控制器

建立 新的 Spring Boot 專案,並將 spring-ai-azure-openai-spring-boot-starter 新增至您的 pom (或 gradle) 依賴性。

src/main/resources 目錄下新增 application.properties 檔案,以啟用和組態 OpenAi 聊天模型

spring.ai.azure.openai.api-key=YOUR_API_KEY
spring.ai.azure.openai.endpoint=YOUR_ENDPOINT
spring.ai.azure.openai.chat.options.deployment-name=gpt-4o
spring.ai.azure.openai.chat.options.temperature=0.7
api-keyendpoint 替換為您的 Azure OpenAI 認證。

這將建立一個 AzureOpenAiChatModel 實作,您可以將其注入到您的類別中。以下是一個簡單的 @Controller 類別範例,該類別使用聊天模型進行文字生成。

@RestController
public class ChatController {

    private final AzureOpenAiChatModel chatModel;

    @Autowired
    public ChatController(AzureOpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
	public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}

手動組態

AzureOpenAiChatModel 實作 ChatModelStreamingChatModel,並使用 Azure OpenAI Java 用戶端

若要啟用它,請將 spring-ai-azure-openai 依賴性新增至您專案的 Maven pom.xml 檔案

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-azure-openai</artifactId>
</dependency>

或新增至您的 Gradle build.gradle 建置檔案。

dependencies {
    implementation 'org.springframework.ai:spring-ai-azure-openai'
}
請參閱 依賴性管理 章節,將 Spring AI BOM 新增至您的建置檔案。
spring-ai-azure-openai 依賴性也提供對 AzureOpenAiChatModel 的存取權。有關 AzureOpenAiChatModel 的更多資訊,請參閱 Azure OpenAI 聊天 章節。

接下來,建立 AzureOpenAiChatModel 實例並使用它來產生文字回應

var openAIClient = new OpenAIClientBuilder()
  .credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
  .endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"))
  .buildClient();

var openAIChatOptions = AzureOpenAiChatOptions.builder()
  .withDeploymentName("gpt-4o")
  .withTemperature(0.4)
  .withMaxTokens(200)
  .build();

var chatModel = new AzureOpenAiChatModel(this.openAIClient, this.openAIChatOptions);

ChatResponse response = this.chatModel.call(
  new Prompt("Generate the names of 5 famous pirates."));

// Or with streaming responses
Flux<ChatResponse> response = this.chatModel.stream(
  new Prompt("Generate the names of 5 famous pirates."));
gpt-4o 實際上是在 Azure AI 入口網站中顯示的 部署名稱