BytesRouter

主题

LangChain4j 文档版本 1.22.0 源快照 b4069c27 更新于 2026-10-14

Azure OpenAI

NOTE

这是 Azure OpenAI 集成的文档，它使用微软的 Azure SDK，最适合在你使用微软 Java 技术栈（包括高级 Azure 认证机制）时。

LangChain4j 提供了 3 种不同的 OpenAI 集成来使用聊天模型，这里是第 3 种：

  • OpenAI 使用对 OpenAI REST API 的自定义 Java 实现，最适合与 Quarkus（因其使用 Quarkus REST 客户端）以及 Spring（因其使用 Spring 的 RestClient）搭配。
  • OpenAI 官方 SDK 使用官方的 OpenAI Java SDK。
  • Azure OpenAI 使用微软的 Azure SDK，最适合在你使用微软 Java 技术栈（包括高级 Azure 认证机制）时。

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

Azure OpenAI 文档

Maven 依赖

纯 Java

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

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

Spring Boot

有一个 Spring Boot starter 可更轻松地配置 langchain4j-azure-open-ai 库。

xml
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-azure-open-ai-spring-boot4-starter</artifactId>
    <version>1.22.0-beta32</version>
</dependency>

NOTE

该 starter 需要 Spring Boot 4。在 Spring Boot 3 上，请改用 langchain4j-azure-open-ai-spring-boot-starter。 详见 Spring Boot 集成。

NOTE

在使用任何 Azure OpenAI 模型之前，你需要先部署它们。

用 API 密钥创建 AzureOpenAiChatModel

纯 Java

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：

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-completion-tokens=...
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=...
langchain4j.azure-open-ai.chat-model.reasoningEffort=...

部分参数的说明见这里。

该配置会创建一个 AzureOpenAiChatModel bean（带默认模型参数）， 它可被某个 AI 服务使用，或在需要处自动注入，例如：

java
@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 依赖添加到项目中。

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

然后，你可以使用 DefaultAzureCredentialBuilder API 创建一个 AzureOpenAiChatModel：

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

NOTE

请注意，你需要使用托管标识（Managed Identities）来部署模型。更多信息参见 Azure CLI 部署脚本。

工具

工具，又称"函数调用（Function Calling）"，受支持，它让模型能调用你 Java 代码中的方法，包括并行工具调用。"函数调用"在 OpenAI 文档这里有描述。

NOTE

关于如何在 LangChain4j 中使用"函数调用"的完整教程在这里。

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

java
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：

java

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";
    }
}

结构化输出

结构化输出（Structured Outputs）确保模型的响应遵循一个 JSON schema。

NOTE

关于在 LangChain4j 中使用结构化输出的文档在这里，下节你会找到 Azure OpenAI 专有的信息。

模型需要将 strictJsonSchema 参数设为 true，才能强制遵循 JSON Schema：

java
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();

NOTE

如果 strictJsonSchema 设为 false 而你提供了一个 JSON Schema，模型仍会尝试生成遵循该 schema 的响应，但若响应不遵循也不会失败。这样做的一个理由是为了更好的性能。

随后你可以用高层的 Assistant API 或低层的 ChatModel API 使用这个模型，如下所述。当使用高层 Assistant API 时，配置 supportedCapabilities(Set.of(RESPONSE_FORMAT_JSON_SCHEMA)) 以启用带 JSON schema 的结构化输出。

使用高层 Assistant API

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

java

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 schema，如下例：

java
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 schema，以及将 JSON 响应映射为一个 Java 对象。

模型配置好后，必须在每个请求的 ChatRequest 对象中指定 JSON Schema。随后模型会生成一个遵循该 schema 的响应，如下例：

java
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 将会是：

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

这个 JSON 响应随后通常会用 Jackson 这类库反序列化为一个 Java 对象。

创建 AzureOpenAiStreamingChatModel 以流式返回结果

该实现与上面的 AzureOpenAiChatModel 类似，但它逐词元地流式返回响应。

纯 Java

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：

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-completion-tokens=...
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=...
langchain4j.azure-open-ai.streaming-chat-model.reasoningEffort=...

音频转写

Azure OpenAI 现已支持音频转写，让你能用托管在 Azure 上的最先进模型，把音频文件中口语转换为文本。

Maven 依赖

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

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

纯 Java 用法

你可以用 AzureOpenAiAudioTranscriptionModel 转写音频文件：

java
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") // e.g., "whisper"
    .build();

// Read audio file as binary data
File audioFile = new File("path/to/audio-file.wav");
byte[] audioData = Files.readAllBytes(audioFile.toPath());

// Create Audio object with binary data
Audio audio = Audio.builder()
    .binaryData(audioData)
    .build();

// Create transcription request
AudioTranscriptionRequest request = AudioTranscriptionRequest.builder()
    .audio(audio)
    .prompt("This is an audio file containing ...") // optional
    .language("en") // optional
    .temperature(0.0) // optional
    .build();

// Transcribe audio
AudioTranscriptionResponse response = model.transcribe(request);
String transcript = response.text();
System.out.println(transcript);

注

  • 部署：你必须在 Azure OpenAI 资源中部署一个音频转写模型（例如 Whisper）。细节参见 Azure OpenAI 文档。
  • 支持的格式：支持 WAV、MP3 与 FLAC 等常见音频格式。
  • 配额与定价：音频转写会消耗你 Azure 订阅中的资源。请在 Azure 门户查看适用的配额与定价。

示例

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可