OpenAI

• OpenAI Decisions API 指南

OpenAI Decisions API（POST /v1/decisions）能以概率形式回答关于文本或图像输入的是/否、选择与量表问题。它在两个模块中实现了 DecisionModel API：

• langchain4j-open-ai 中的 OpenAiDecisionModel，使用 LangChain4j 的 HTTP 客户端
• langchain4j-open-ai-official 中的 OpenAiOfficialDecisionModel，使用官方的 OpenAI Java SDK

NOTE

Decisions API 处于公测阶段，本集成尚属实验性，未来版本可能变化。

Maven 依赖

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

或者，对于官方 SDK：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai-official</artifactId>
    <version>1.22.0-beta32</version>
</dependency>

用量

DecisionModel decisionModel = OpenAiDecisionModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName(OpenAiDecisionModelName.GPT_6_LUNA)
        .build();

DecisionRequest request = DecisionRequest.builder()
        .input("Help! My payouts have been failing for 3 days and nobody answers my emails.")
        .question("team", ChoiceQuestion.builder()
                .text("Which team should handle this ticket?")
                .option("billing", "Payments, payouts, invoices, refunds")
                .option("support", "Problems using the product")
                .option("sales", "Pricing, upgrades, new accounts")
                .build())
        .question("urgent", YesNoQuestion.of("Does this need attention today?"))
        .build();

DecisionResponse response = decisionModel.decide(request);

response.choice("team").value();          // "billing"
response.yesNo("urgent").probability();   // 0.93

使用官方 SDK 时，采用 OpenAiOfficialDecisionModel，它以 String 形式接受模型名：

DecisionModel decisionModel = OpenAiOfficialDecisionModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-6-luna")
        .build();

它与该模块的其他模型具有相同的客户端设置，例如 baseUrl、timeout、maxRetries 和 openAIClient。

Spring Boot

添加你所用模块的 starter：

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

或者对官方 SDK 用 langchain4j-open-ai-official-spring-boot4-starter。在 Spring Boot 3 上，请改用 langchain4j-open-ai-spring-boot-starter 或 langchain4j-open-ai-official-spring-boot-starter （参见 Spring Boot 集成）。

当在 application.properties 中设置了其 API 密钥时，会创建一个 OpenAiDecisionModel bean：

# Mandatory properties:
langchain4j.open-ai.decision-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.decision-model.model-name=gpt-6-luna

# Optional properties:
langchain4j.open-ai.decision-model.base-url=...
langchain4j.open-ai.decision-model.organization-id=...
langchain4j.open-ai.decision-model.project-id=...
langchain4j.open-ai.decision-model.timeout=...
langchain4j.open-ai.decision-model.max-retries=...
langchain4j.open-ai.decision-model.log-requests=...
langchain4j.open-ai.decision-model.log-responses=...
langchain4j.open-ai.decision-model.custom-headers...=...
langchain4j.open-ai.decision-model.custom-query-params...=...

使用官方 SDK starter 时，则会创建一个 OpenAiOfficialDecisionModel bean：

# Mandatory properties:
langchain4j.open-ai-official.decision-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai-official.decision-model.model-name=gpt-6-luna

# Optional properties:
langchain4j.open-ai-official.decision-model.base-url=...
langchain4j.open-ai-official.decision-model.organization-id=...
langchain4j.open-ai-official.decision-model.timeout=...
langchain4j.open-ai-official.decision-model.max-retries=...
langchain4j.open-ai-official.decision-model.custom-headers...=...

DecisionModelListener bean 会被自动注册到决策模型上。

对于 langchain4j-open-ai，starter 使用 Spring 的 RestClient，它不支持非阻塞调用： 此时 decideAsync(...) 会以 AsyncNotSupportedException 失败。若要异步决策，请提供一个名为 openAiDecisionModelHttpClientBuilder、且支持非阻塞调用的 HttpClientBuilder bean，例如 JdkHttpClient.builder()。

输入

输入可以是：

• 文本；
• 一个由命名值组成的 Map：每个值作为以其名称标注的文本部分发送，值为 JSON （comment: "..."），而每张图像紧跟在其名称所在的文本部分（photo:）之后；
• 一个由 TextContent 与 ImageContent 组成的列表，例如一张照片连同其描述：

DecisionRequest request = DecisionRequest.builder()
        .input(List.of(
                TextContent.from("The customer says the package arrived like this."),
                ImageContent.from(base64Image, "image/jpeg")))
        .question("damaged", YesNoQuestion.of("Is the item visibly damaged?"))
        .build();

图像必须是内联的：base64 数据，或一个 data: URL。以 http 或 https URL 引用的图像不被该 API 支持，并在调用前以 UnsupportedFeatureException 拒绝。支持细节级别 LOW、HIGH 与 AUTO；MEDIUM 与 ULTRA_HIGH 会以 UnsupportedFeatureException 拒绝。

问题与答案

DecisionModel	OpenAI	备注
YesNoQuestion	predicate	yesWhen 与 noWhen 会追加到问题后
ChoiceQuestion	choice	选项名作为取值发送，连同其描述
ScaleQuestion	score	各等级作为标签发送

选择与量表答案会包含每个选项或等级的概率，以及一个置信度。

该 API 可能拒绝对某个单独问题作答，例如因为它违背 OpenAI 的使用政策。 对其余问题的答案仍会返回，而对被拒的问题 response.isRefused(name) 返回 true （参见拒答）。

词元用量

response.tokenUsage() 是一个 OpenAiTokenUsage（或 OpenAiOfficialTokenUsage），它包含缓存的 输入词元数。