跳到主要内容

OpenAI 官方 SDK

备注

这是 OpenAI 官方 SDK 集成的文档，它使用 官方 OpenAI Java SDK。

LangChain4j 提供了 4 种不同的与 OpenAI 集成的方式来使用聊天模型，这是第 2 种：

  • 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 Inference API 访问 GitHub Models。

此集成的用例​

此集成使用 OpenAI Java SDK GitHub 仓库，适用于由以下提供的所有 OpenAI 模型：

  • OpenAI
  • Azure OpenAI
  • GitHub Models

它也适用于支持 OpenAI API 的模型，如 DeepSeek。

OpenAI 文档​

Maven 依赖​

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-official</artifactId>
    <version>1.0.0-beta3</version>
</dependency>

配置模型​

备注

此配置以及下一节关于其使用的内容是针对非流式模式（也称为"阻塞"或"同步"模式）。 流式模式在下面 2 个部分中详细说明：它允许与模型进行实时聊天，但使用起来更复杂。

要使用 OpenAI 模型，您通常需要一个端点 URL、API 密钥和模型名称。这取决于模型托管的位置，此集成尝试通过一些自动配置使其更容易：

通用配置​

import com.openai.models.ChatModel;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openaiofficial.OpenAiOfficialChatModel;

// ....

ChatLanguageModel model = OpenAiOfficialChatModel.builder()
        .baseUrl(System.getenv("OPENAI_BASE_URL"))
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName(ChatModel.GPT_4O_MINI)
        .build();

OpenAI 配置​

OpenAI 的 baseUrl（https://api.openai.com/v1）是默认值，所以您可以省略它：

ChatLanguageModel model = OpenAiOfficialChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName(ChatModel.GPT_4O_MINI)
        .build();

Azure OpenAI 配置​

通用配置​

对于 Azure OpenAI，设置 baseUrl 是必须的，如果该 URL 以 openai.azure.com 结尾，则会自动检测 Azure OpenAI：

ChatLanguageModel model = OpenAiOfficialChatModel.builder()
        .baseUrl(System.getenv("AZURE_OPENAI_ENDPOINT"))
        .apiKey(System.getenv("AZURE_OPENAI_KEY"))
        .modelName(ChatModel.GPT_4O_MINI)
        .build();

如果您想强制使用 Azure OpenAI，您也可以使用 isAzure() 方法：

ChatLanguageModel model = OpenAiOfficialChatModel.builder()
        .baseUrl(System.getenv("AZURE_OPENAI_ENDPOINT"))
        .apiKey(System.getenv("AZURE_OPENAI_KEY"))
        .isAzure(true)
        .modelName(ChatModel.GPT_4O_MINI)
        .build();

无密码认证​

您可以使用"无密码"认证来验证 Azure OpenAI，这更安全，因为您不需要管理 API 密钥。

为此，您必须首先配置 Azure OpenAI 实例以支持托管身份，然后授予此应用程序访问权限，例如：

# 在 Azure OpenAI 实例上启用系统托管身份
az cognitiveservices account identity assign \
    --name <your-openai-instance-name> \
    --resource-group <your-resource-group>

# 获取您登录的身份
az ad signed-in-user show \
    --query id -o tsv
    
# 授予 Azure OpenAI 实例的访问权限
az role assignment create \
    --role "Cognitive Services OpenAI User" \
    --assignee <your-logged-identity-from-the-previous-command> \
    --scope "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>"

然后，您需要将 azure-identity 依赖项添加到您的 Maven pom.xml：

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

当没有配置 API 密钥时，LangChain4j 将自动使用 Azure OpenAI 的无密码认证。

GitHub Models 配置​

对于 GitHub Models，您可以使用默认的 baseUrl（https://models.inference.ai.azure.com）：

ChatLanguageModel model = OpenAiOfficialChatModel.builder()
        .baseUrl("https://models.inference.ai.azure.com")
        .apiKey(System.getenv("GITHUB_TOKEN"))
        .modelName(ChatModel.GPT_4O_MINI)
        .build();

或者您可以使用 isGitHubModels() 方法强制使用 GitHub Models，这将自动设置 baseUrl：

ChatLanguageModel model = OpenAiOfficialChatModel.builder()
        .apiKey(System.getenv("GITHUB_TOKEN"))
        .modelName(ChatModel.GPT_4O_MINI)
        .isGitHubModels(true)
        .build();

由于 GitHub Models 通常使用 GITHUB_TOKEN 环境变量配置，该变量在使用 GitHub Actions 或 GitHub Codespaces 时会自动填充，因此会自动检测：

ChatLanguageModel model = OpenAiOfficialChatModel.builder()
        .modelName(ChatModel.GPT_4O_MINI)
        .isGitHubModels(true)
        .build();

这种最后的配置更容易使用，也更安全，因为 GITHUB_TOKEN 环境变量不会在代码或 GitHub 日志中暴露。

使用模型​

在上一节中，创建了一个实现 ChatLanguageModel 接口的 OpenAiOfficialChatModel 对象。

它可以由 AI Service 使用，或直接在 Java 应用程序中使用。

在此示例中，它作为 Spring Bean 自动装配：

@RestController
class ChatLanguageModelController {

    ChatLanguageModel chatLanguageModel;

    ChatLanguageModelController(ChatLanguageModel chatLanguageModel) {
        this.chatLanguageModel = chatLanguageModel;
    }

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

结构化输出​

结构化输出功能支持 工具和响应格式。

有关结构化输出的更多信息，请参见此处。

工具的结构化输出​

要为工具启用结构化输出功能，在构建模型时设置.strictTools(true)：

OpenAiOfficialChatModel.builder()
        // ...
        .strictTools(true)
        .build();

请注意，这将自动使所有工具参数成为必需的（json schema中的required） 并为json schema中的每个object设置additionalProperties=false。这是由于当前OpenAI的限制。

响应格式的结构化输出​

要在使用AI服务时为响应格式启用结构化输出功能， 在构建模型时设置supportedCapabilities(Set.of(RESPONSE_FORMAT_JSON_SCHEMA))和.strictJsonSchema(true)：

import static dev.langchain4j.model.chat.Capability.RESPONSE_FORMAT_JSON_SCHEMA;

// ...

OpenAiChatModel.builder()
        // ...
        .supportedCapabilities(Set.of(RESPONSE_FORMAT_JSON_SCHEMA))
        .strictJsonSchema(true)
        .build();

在这种情况下，AI服务将自动从给定的POJO生成JSON schema并将其传递给LLM。

配置流式模型​

备注

在上面两节中，我们详细介绍了如何配置非流式模式（也称为"阻塞"或"同步"模式）的模型。 本节是关于流式模式的，它允许与模型进行实时聊天，但使用起来更复杂。

这与非流式模式类似，但您需要使用OpenAiOfficialStreamingChatModel类而不是OpenAiOfficialChatModel：

StreamingChatLanguageModel model = OpenAiOfficialStreamingChatModel.builder()
        .baseUrl(System.getenv("OPENAI_BASE_URL"))
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName(ChatModel.GPT_4O_MINI)
        .build();

您也可以使用特定的isAzure()和isGitHubModels()方法强制使用Azure OpenAI或GitHub Models，如非流式配置部分所述。