Azure OpenAI 聊天

Azure 的 OpenAI 產品,由 ChatGPT 提供支援,超越了傳統的 OpenAI 功能,提供了增強的 AI 驅動文字生成功能。Azure 提供了額外的 AI 安全和負責任的 AI 功能,正如其最新更新此處所強調的。

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

先決條件

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

Azure API 金鑰和終結點

要使用 API 金鑰訪問模型,請從 Azure 門戶的 Azure OpenAI 服務部分獲取您的 Azure OpenAI 終結點api-key

Spring AI 定義了兩個配置屬性

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

  2. spring.ai.azure.openai.endpoint:將其設定為在 Azure 中預配模型時獲取的終結點 URL。

您可以在application.propertiesapplication.yml檔案中設定這些配置屬性

spring.ai.azure.openai.api-key=<your-azure-api-key>
spring.ai.azure.openai.endpoint=<your-azure-endpoint-url>

為了在處理 API 金鑰等敏感資訊時增強安全性,您可以使用 Spring 表示式語言 (SpEL) 來引用自定義環境變數

# In application.yml
spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}
        endpoint: ${AZURE_OPENAI_ENDPOINT}
# In your environment or .env file
export AZURE_OPENAI_API_KEY=<your-azure-openai-api-key>
export AZURE_OPENAI_ENDPOINT=<your-azure-openai-endpoint-url>

OpenAI 金鑰

要透過 OpenAI 服務(非 Azure)進行身份驗證,請提供一個 OpenAI API 金鑰。這將自動將終結點設定為 api.openai.com/v1

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

在您的應用程式配置中

spring.ai.azure.openai.openai-api-key=<your-azure-openai-key>
spring.ai.azure.openai.chat.options.deployment-name=<openai-model-name>

使用 SpEL 環境變數

# In application.yml
spring:
  ai:
    azure:
      openai:
        openai-api-key: ${AZURE_OPENAI_API_KEY}
        chat:
          options:
            deployment-name: ${AZURE_OPENAI_MODEL_NAME}
# In your environment or .env file
export AZURE_OPENAI_API_KEY=<your-openai-key>
export AZURE_OPENAI_MODEL_NAME=<openai-model-name>

Microsoft Entra ID

對於使用 Microsoft Entra ID(以前稱為 Azure Active Directory)進行無金鑰身份驗證,設定spring.ai.azure.openai.endpoint配置屬性,而設定上述的 api-key 屬性。

僅找到終結點屬性後,您的應用程式將評估幾種不同的憑據檢索選項,並使用令牌憑據建立一個OpenAIClient例項。

不再需要建立TokenCredential bean;它已為您自動配置。

部署名稱

要使用 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 工件釋出在 Maven Central 和 Spring Snapshot 儲存庫中。請參閱 工件儲存庫 部分,將這些儲存庫新增到您的構建系統。

為了幫助管理依賴項,Spring AI 提供了一個 BOM(物料清單),以確保在整個專案中使用的 Spring AI 版本一致。請參閱 依賴項管理 部分,將 Spring AI BOM 新增到您的構建系統。

自動配置

Spring AI 自動配置、啟動模組的工件名稱發生了重大變化。請參閱 升級說明 以獲取更多資訊。

Spring AI 為 Azure OpenAI 聊天客戶端提供了 Spring Boot 自動配置。要啟用它,請將以下依賴項新增到您的專案的 Maven pom.xml 或 Gradle build.gradle 構建檔案中

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-azure-openai'
}
請參閱 依賴項管理 部分,將 Spring AI BOM 新增到您的構建檔案中。

Azure OpenAI 聊天客戶端使用 Azure SDK 提供的 OpenAIClientBuilder 建立。Spring AI 允許透過提供 AzureOpenAIClientBuilderCustomizer bean 來定製構建器。

例如,自定義器可以用於更改預設響應超時

@Configuration
public class AzureOpenAiConfig {

	@Bean
	public AzureOpenAIClientBuilderCustomizer responseTimeoutCustomizer() {
		return openAiClientBuilder -> {
			HttpClientOptions clientOptions = new HttpClientOptions()
					.setResponseTimeout(Duration.ofMinutes(5));
			openAiClientBuilder.httpClient(HttpClient.createDefault(clientOptions));
		};
	}

}

聊天屬性

字首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.model.chat為字首的頂級屬性進行配置。

要啟用,請設定 spring.ai.model.chat=azure-openai(預設已啟用)

要停用,請設定 spring.ai.model.chat=none(或任何不匹配 azure-openai 的值)

此更改是為了允許配置多個模型。

字首spring.ai.azure.openai.chat是配置 Azure OpenAI 的ChatModel實現的屬性字首。

財產 描述 預設值

spring.ai.azure.openai.chat.enabled(已移除且不再有效)

啟用 Azure OpenAI 聊天模型。

true

spring.ai.model.chat

啟用 Azure OpenAI 聊天模型。

azure-openai

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

在聊天完成中生成的最大令牌數。輸入令牌和生成令牌的總長度受模型上下文長度的限制。用於非推理模型(例如 gpt-4o, gpt-3.5-turbo)。不能與 maxCompletionTokens 一起使用。

-

spring.ai.azure.openai.chat.options.maxCompletionTokens

為完成生成的最大令牌數,包括可見輸出令牌和推理令牌。推理模型(例如 o1, o3, o4-mini 系列)必需。不能與 maxTokens 一起使用。

-

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

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

0.7

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

一種替代溫度取樣的核取樣方法。此值使模型考慮具有所提供機率質量的令牌結果。

-

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

GPT 令牌 ID 和偏差分數之間的對映,它影響特定令牌出現在完成響應中的機率。令牌 ID 透過外部分詞工具計算,而偏差分數介於 -100 到 100 之間,最小值和最大值分別對應於完全禁止或獨佔選擇令牌。給定偏差分數的精確行為因模型而異。

-

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

操作的呼叫者或終端使用者的識別符號。這可能用於跟蹤或速率限制目的。

-

spring.ai.azure.openai.chat.options.stream-usage

(僅限流式傳輸)設定為新增一個額外的塊,其中包含整個請求的令牌使用統計資訊。此塊的choices欄位是一個空陣列,所有其他塊也將包含一個 usage 欄位,但值為 null。

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

應為聊天完成響應生成的聊天完成選項的數量。

-

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

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

-

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

一個值,根據生成的文字中現有令牌的存在來影響生成令牌的機率。正值會使令牌在已存在時更不可能出現,並增加模型輸出新主題的可能性。

-

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

GPT-4oGPT-4o miniGPT-4 Turbo和所有比gpt-3.5-turbo-1106新的GPT-3.5 Turbo模型相容。JSON_OBJECT型別啟用 JSON 模式,保證模型生成的訊息是有效的 JSON。JSON_SCHEMA型別啟用結構化輸出,保證模型將匹配您提供的 JSON 模式。JSON_SCHEMA型別還需要設定responseFormat.schema屬性。

-

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

響應格式 JSON 模式。僅適用於responseFormat.type=JSON_SCHEMA

-

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

一個值,根據生成文字中生成令牌的累積頻率來影響其出現的機率。正值會使令牌在頻率增加時更不可能出現,並降低模型重複相同語句的可能性。

-

spring.ai.azure.openai.chat.options.tool-names

工具列表,透過其名稱標識,用於在單個提示請求中啟用函式呼叫。具有這些名稱的工具必須存在於 ToolCallback 登錄檔中。

-

spring.ai.azure.openai.chat.options.tool-callbacks

要註冊到 ChatModel 的工具回撥。

-

spring.ai.azure.openai.chat.options.internal-tool-execution-enabled

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

true

所有以spring.ai.azure.openai.chat.options為字首的屬性都可以在執行時透過向Prompt呼叫新增請求特定的 執行時選項 來覆蓋。

令牌限制引數:模型特定用法

Azure OpenAI 對令牌限制引數有模型特定的要求

模型家族 所需引數 備註

推理模型
(o1, o3, o4-mini 系列)

maxCompletionTokens

這些模型只接受maxCompletionTokens。使用maxTokens將導致 API 錯誤。

非推理模型
(gpt-4o, gpt-3.5-turbo 等)

maxTokens

傳統模型使用maxTokens進行輸出限制。使用maxCompletionTokens可能會導致 API 錯誤。

引數maxTokensmaxCompletionTokens互斥的。同時設定這兩個引數將導致 Azure OpenAI 返回 API 錯誤。當您設定其中一個引數時,Spring AI Azure OpenAI 客戶端將自動清除先前設定的引數,併發出警告訊息。
示例:推理模型使用 maxCompletionTokens
var options = AzureOpenAiChatOptions.builder()
    .deploymentName("o1-preview")
    .maxCompletionTokens(500)  // Required for reasoning models
    .build();
示例:非推理模型使用 maxTokens
var options = AzureOpenAiChatOptions.builder()
    .deploymentName("gpt-4o")
    .maxTokens(500)  // Required for non-reasoning models
    .build();

執行時選項

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()
            .deploymentName("gpt-4o")
            .temperature(0.4)
        .build()
    ));
除了模型特定的 AzureOpenAiChatOptions.java 之外,您還可以使用透過 ChatOptions#builder() 建立的行動式 ChatOptions 例項。

函式呼叫

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

多模態

多模態是指模型同時理解和處理來自各種來源(包括文字、影像、音訊和其他資料格式)資訊的能力。目前,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://docs.springframework.tw/spring-ai/reference/_images/multimodal.test.png");
String response = ChatClient.create(chatModel).prompt()
        .options(AzureOpenAiChatOptions.builder().deploymentName("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()
    .deploymentName("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-starter-model-azure-openai新增到您的 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 openAIClientBuilder = new OpenAIClientBuilder()
  .credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY")))
  .endpoint(System.getenv("AZURE_OPENAI_ENDPOINT"));

var openAIChatOptions = AzureOpenAiChatOptions.builder()
  .deploymentName("gpt-5")
  .temperature(0.4)
  .maxCompletionTokens(200)
  .build();

var chatModel = AzureOpenAiChatModel.builder()
				.openAIClientBuilder(openAIClientBuilder)
				.defaultOptions(openAIChatOptions)
				.build();

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

// Or with streaming responses
Flux<ChatResponse> streamingResponses = chatModel.stream(
  new Prompt("Generate the names of 5 famous pirates."));
gpt-4o實際上是 Azure AI 門戶中顯示的部署名稱
© . This site is unofficial and not affiliated with VMware.