Azure OpenAI

注

这是 Azure OpenAI 集成的文档，使用 Microsoft 的 Azure SDK，适用于使用 Microsoft Java 技术栈（包括高级 Azure 认证机制）的场景。

LangChain4j 提供了 4 种不同的 OpenAI 集成方式以使用聊天模型，本文档介绍的是第 3 种：

• OpenAI 使用 OpenAI REST API 的自定义 Java 实现，适用于 Quarkus（使用 Quarkus REST 客户端）和 Spring（使用 Spring 的 RestClient）。
• OpenAI 官方 SDK 使用官方 OpenAI Java SDK。
• Azure OpenAI 使用 Microsoft 的 Azure SDK，适用于 Microsoft Java 技术栈，包括高级 Azure 认证机制。
• GitHub Models 使用 Azure AI 推理 API 访问 GitHub Models。

Azure OpenAI 提供托管在 Azure 上的 OpenAI 语言模型（gpt-4、gpt-4o 等），使用 Azure OpenAI Java SDK。

Azure OpenAI 文档

• Azure OpenAI 文档

Maven 依赖

纯 Java

langchain4j-azure-open-ai 库可在 Maven Central 获取。

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-azure-open-ai</artifactId>
    <version>1.5.0</version>
</dependency>

Spring Boot

提供 Spring Boot starter 以便更轻松地配置 langchain4j-azure-open-ai 库。

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-azure-open-ai-spring-boot-starter</artifactId>
    <version>1.5.0-beta11</version>
</dependency>

注

在使用 Azure OpenAI 模型之前，您需要先部署这些模型。

使用 API 密钥创建 AzureOpenAiChatModel

纯 Java

ChatModel model = AzureOpenAiChatModel.builder()
        .endpoint(System.getenv("AZURE_OPENAI_URL"))
        .apiKey(System.getenv("AZURE_OPENAI_KEY"))
        .deploymentName("gpt-4o")
        ...
        .build();

这将创建一个具有指定端点、API 密钥和部署名称的 AzureOpenAiChatModel 实例。其他参数可以通过 builder 提供自定义值。

Spring Boot

在 application.properties 中添加以下配置：

langchain4j.azure-open-ai.chat-model.endpoint=${AZURE_OPENAI_URL}
langchain4j.azure-open-ai.chat-model.service-version=...
langchain4j.azure-open-ai.chat-model.api-key=${AZURE_OPENAI_KEY}
langchain4j.azure-open-ai.chat-model.non-azure-api-key=${OPENAI_API_KEY}
langchain4j.azure-open-ai.chat-model.deployment-name=gpt-4o
langchain4j.azure-open-ai.chat-model.max-tokens=...
langchain4j.azure-open-ai.chat-model.temperature=...
langchain4j.azure-open-ai.chat-model.top-p=...
langchain4j.azure-open-ai.chat-model.logit-bias=...
langchain4j.azure-open-ai.chat-model.user=...
langchain4j.azure-open-ai.chat-model.stop=...
langchain4j.azure-open-ai.chat-model.presence-penalty=...
langchain4j.azure-open-ai.chat-model.frequency-penalty=...
langchain4j.azure-open-ai.chat-model.seed=...
langchain4j.azure-open-ai.chat-model.strict-json-schema=...
langchain4j.azure-open-ai.chat-model.timeout=...
langchain4j.azure-open-ai.chat-model.max-retries=...
langchain4j.azure-open-ai.chat-model.log-requests-and-responses=...
langchain4j.azure-open-ai.chat-model.user-agent-suffix=...
langchain4j.azure-open-ai.chat-model.custom-headers=...

有关上述部分参数的描述，请参阅此处。

此配置将创建一个带有默认模型参数的 AzureOpenAiChatModel bean，可以用于 AI 服务 或在需要时进行自动注入，例如：

@RestController
class ChatModelController {

    ChatModel chatModel;

    ChatModelController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/model")
    public String model(@RequestParam(value = "message", defaultValue = "Hello") String message) {
        return chatModel.chat(message);
    }
}

使用 Azure 凭据创建 AzureOpenAiChatModel

API 密钥可能存在一些安全问题（例如可能被提交到代码库或被传递）。为提高安全性，建议使用 Azure 凭据。为此，需要在项目中添加 azure-identity 依赖：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <scope>compile</scope>
</dependency>

然后，您可以使用 DefaultAzureCredentialBuilder API 创建 AzureOpenAiChatModel：

ChatModel model = AzureOpenAiChatModel.builder()
        .deploymentName("gpt-4o")
        .endpoint(System.getenv("AZURE_OPENAI_URL"))
        .tokenCredential(new DefaultAzureCredentialBuilder().build())
        .build();

注

请注意，您需要使用托管身份（Managed Identities）来部署模型。有关更多信息，请查看 Azure CLI 部署脚本。

工具

支持工具（也称为“函数调用”），允许模型调用 Java 代码中的方法，包括并行工具调用。OpenAI 的“函数调用”文档请参阅此处。

注

有关在 LangChain4j 中使用“函数调用”的完整教程，请参阅此处。

可以使用 ToolSpecification 类指定函数，或者更简单地使用 @Tool 注解，例如以下示例：

class StockPriceService {

    private Logger log = Logger.getLogger(StockPriceService.class.getName());

    @Tool("Get the stock price of a company by its ticker")
    public double getStockPrice(@P("Company ticker") String ticker) {
        log.info("Getting stock price for " + ticker);
        if (Objects.equals(ticker, "MSFT")) {
            return 400.0;
        } else {
            return 0.0;
        }
    }
}

然后，您可以在 AI Assistant 中使用 StockPriceService，如下所示：

interface Assistant {
    String chat(String userMessage);
}

public class Demo {
    String functionCalling(Model model) {
        String question = "Is the current Microsoft stock higher than $450?";
        StockPriceService stockPriceService = new StockPriceService();

        Assistant assistant = AiServices.builder(Assistant.class)
                .chatModel(model)
                .tools(stockPriceService)
                .build();

        String answer = assistant.chat(question);

        model.addAttribute("answer", answer);
        return "demo";
    }
}

结构化输出

结构化输出确保模型的响应遵循 JSON 模式。

注

有关在 LangChain4j 中使用结构化输出的文档，请参阅此处，以下是 Azure OpenAI 特定的信息。

需要将模型的 strictJsonSchema 参数设置为 true，以强制遵循 JSON 模式：

ChatModel model = AzureOpenAiChatModel.builder()
        .endpoint(System.getenv("AZURE_OPENAI_URL"))
        .apiKey(System.getenv("AZURE_OPENAI_KEY"))
        .deploymentName("gpt-4o")
        .strictJsonSchema(true)
        .supportedCapabilities(Set.of(RESPONSE_FORMAT_JSON_SCHEMA))
        .build();

注

如果 strictJsonSchema 设置为 false 并且提供了 JSON 模式，模型仍会尝试生成遵循该模式的响应，但如果响应不遵循模式，请求不会失败。这样做的原因之一是为了提高性能。

您可以随后通过高级 Assistant API 或低级 ChatModel API 使用此模型，详情如下所述。使用高级 Assistant API 时，需配置 supportedCapabilities(Set.of(RESPONSE_FORMAT_JSON_SCHEMA)) 以启用 JSON 模式的结构化输出。

使用高级 Assistant API

与上一节中的工具类似，结构化输出可以自动用于 AI Assistant：

interface PersonAssistant {
    Person extractPerson(String message);
}

class Person {
    private final String name;
    private final List<String> favouriteColors;

    public Person(String name, List<String> favouriteColors) {
        this.name = name;
        this.favouriteColors = favouriteColors;
    }

    public String getName() {
        return name;
    }

    public List<String> getFavouriteColors() {
        return favouriteColors;
    }
}

此 Assistant 将确保响应遵循 Person 类对应的 JSON 模式，如以下示例：

String question = "Julien likes the colors blue, white and red";

PersonAssistant assistant = AiServices.builder(PersonAssistant.class)
                .chatModel(chatModel)
                .build();

Person person = assistant.extractPerson(question);

使用低级 ChatModel API

此过程与高级 API 类似，但需要手动配置 JSON 模式，并将 JSON 响应映射到 Java 对象。

模型配置完成后，必须在每个请求的 ChatRequest 对象中指定 JSON 模式。模型将生成遵循该模式的响应，如以下示例：

ChatRequest chatRequest = ChatRequest.builder()
    .messages(UserMessage.from("Julien likes the colors blue, white and red"))
    .responseFormat(ResponseFormat.builder()
        .type(JSON)
        .jsonSchema(JsonSchema.builder()
            .name("Person")
            .rootElement(JsonObjectSchema.builder()
                .addStringProperty("name")
                .addProperty("favouriteColors", JsonArraySchema.builder()
                    .items(new JsonStringSchema())
                    .build())
                .required("name", "favouriteColors")
                .build())
            .build())
        .build())
    .build();

String answer = chatModel.chat(chatRequest).aiMessage().text();

在此示例中，answer 将为：

{
  "name": "Julien",
  "favouriteColors": ["blue", "white", "red"]
}

此 JSON 响应通常会使用 Jackson 等库反序列化为 Java 对象。

创建 AzureOpenAiStreamingChatModel 以流式传输结果

此实现与上述 AzureOpenAiChatModel 类似，但它会逐个 token 流式传输响应。

纯 Java

StreamingChatModel model = AzureOpenAiStreamingChatModel.builder()
        .endpoint(System.getenv("AZURE_OPENAI_URL"))
        .apiKey(System.getenv("AZURE_OPENAI_KEY"))
        .deploymentName("gpt-4o")
        ...
        .build();

Spring Boot

在 application.properties 中添加以下配置：

langchain4j.azure-open-ai.streaming-chat-model.endpoint=${AZURE_OPENAI_URL}
langchain4j.azure-open-ai.streaming-chat-model.service-version=...
langchain4j.azure-open-ai.streaming-chat-model.api-key=${AZURE_OPENAI_KEY}
langchain4j.azure-open-ai.streaming-chat-model.deployment-name=gpt-4o
langchain4j.azure-open-ai.streaming-chat-model.max-tokens=...
langchain4j.azure-open-ai.streaming-chat-model.temperature=...
langchain4j.azure-open-ai.streaming-chat-model.top-p=...
langchain4j.azure-open-ai.streaming-chat-model.logit-bias=...
langchain4j.azure-open-ai.streaming-chat-model.user=...
langchain4j.azure-open-ai.streaming-chat-model.stop=...
langchain4j.azure-open-ai.streaming-chat-model.presence-penalty=...
langchain4j.azure-open-ai.streaming-chat-model.frequency-penalty=...
langchain4j.azure-open-ai.streaming-chat-model.seed=...
langchain4j.azure-open-ai.streaming-chat-model.timeout=...
langchain4j.azure-open-ai.streaming-chat-model.max-retries=...
langchain4j.azure-open-ai.streaming-chat-model.log-requests-and-responses=...
langchain4j.azure-open-ai.streaming-chat-model.user-agent-suffix=...
langchain4j.azure-open-ai.streaming-chat-model.customHeaders=...

音频转录

Azure OpenAI 现在支持音频转录，使您能够使用 Azure 托管的先进模型将音频文件中的口语转换为文本。

Maven 依赖

音频转录功能包含在主要的 langchain4j-azure-open-ai 包中：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-azure-open-ai</artifactId>
    <version>1.5.0</version>
</dependency>

纯 Java 使用

您可以使用 AzureOpenAiAudioTranscriptionModel 转录音频文件：

import dev.langchain4j.data.audio.Audio;
import dev.langchain4j.model.audio.AudioTranscriptionRequest;
import dev.langchain4j.model.audio.AudioTranscriptionResponse;
import java.io.File;
import java.nio.file.Files;

AzureOpenAiAudioTranscriptionModel model = AzureOpenAiAudioTranscriptionModel.builder()
    .endpoint(System.getenv("AZURE_OPENAI_URL"))
    .apiKey(System.getenv("AZURE_OPENAI_KEY"))
    .deploymentName("your-audio-model-deployment-name") // 例如，"whisper"
    .build();

// 读取音频文件为二进制数据
File audioFile = new File("path/to/audio-file.wav");
byte[] audioData = Files.readAllBytes(audioFile.toPath());

// 创建带有二进制数据的 Audio 对象
Audio audio = Audio.builder()
    .binaryData(audioData)
    .build();

// 创建转录请求
AudioTranscriptionRequest request = AudioTranscriptionRequest.builder()
    .audio(audio)
    .prompt("This is an audio file containing ...") // 可选
    .language("en") // 可选
    .temperature(0.0) // 可选
    .build();

// 转录音频
AudioTranscriptionResponse response = model.transcribe(request);
String transcript = response.text();
System.out.println(transcript);

注意事项

• 部署：您必须在 Azure OpenAI 资源中部署音频转录模型（例如 Whisper）。有关详情，请参阅 Azure OpenAI 文档。
• 支持的格式：支持常见的音频格式，如 WAV、MP3 和 FLAC。
• 配额和定价：音频转录会消耗您的 Azure 订阅资源。请在 Azure 门户中查看适用的配额和定价。

示例

• Azure OpenAI 示例
• AzureOpenAiSecurityExamples 及其 Azure CLI 部署脚本