> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 决策集成

> OpenAI Decisions API读取自然语言和图像，并返回类型化的答案和校准概率，而不是生成文本。

[OpenAI Decisions API](https://developers.openai.com/api/docs/guides/decisions)读取自然语言和图像，并返回类型化的答案和校准概率，而不是生成文本。

`OpenAIDecisions`将这些决策作为LangChain `Runnable`公开，因此您可以调用、批量处理或与其他可运行项组合它们。它接受字符串、结构化JSON和[LangChain消息对象](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/messages.md)，并在LangSmith中记录跟踪和Token使用情况。用于执行专注的决策，例如路由请求、选择模型或检查工具调用是否安全运行。

在LangChain中间件中使用OpenAI决策来控制`createAgent`行为，包括使用自定义中间件对智能体状态进行分类。参见[智能体中间件](#智能体中间件)了解示例。

> [!NOTE]
>
> `OpenAIDecisions`及其中间件处于Beta阶段，需要`@langchain/openai>=1.8.0`。中间件还需要`langchain>=1.6.0`。它们的API可能会未经通知而更改。

## 设置

```bash npm theme={null}
npm install @langchain/openai @langchain/core
```

```bash yarn theme={null}
yarn add @langchain/openai @langchain/core
```

```bash pnpm theme={null}
pnpm add @langchain/openai @langchain/core
```

在[OpenAI控制面板](https://platform.openai.com/api-keys)中创建API密钥并导出它：

```bash theme={null}
export OPENAI_API_KEY=...
```

> [!NOTE]
>
> 可选：设置`OPENAI_BASE_URL`以使用兼容的网关或测试服务器。默认是OpenAI API端点。
>
> ```bash theme={null}
> export OPENAI_BASE_URL=https://gateway.example.com/v1
> ```
>
> 要通过[LangSmith LLM网关](https://docs.langchain.com/langsmith/llm-gateway-decision-models#use-openai-decision-models)路由请求，设置`LANGSMITH_GATEWAY=true`。网关请求使用`LANGSMITH_GATEWAY_API_KEY`或`LANGSMITH_API_KEY`进行身份验证：
>
> ```bash theme={null}
> export LANGSMITH_GATEWAY=true
> export LANGSMITH_API_KEY=...
> ```

## 快速入门

创建一个带有决策模型的`OpenAIDecisions`实例，然后在每次调用中一起传递输入和命名问题。共享输入的问题在一个请求中回答：

```typescript theme={null}
import { OpenAIDecisions } from "@langchain/openai";

const decisions = new OpenAIDecisions("gpt-6-luna");

const response = await decisions.invoke({
  input:
    "The deploy failed twice and customers are seeing 500s. Can someone look now?",
  questions: {
    urgent: {
      type: "predicate",
      instructions: "Does this need attention right now?",
    },
    team: {
      type: "choice",
      instructions: "Which team should pick this up?",
      choices: {
        infra: "Deploys, availability, and on-call incidents.",
        billing: "Payments, invoices, and subscriptions.",
      },
    },
    severity: {
      type: "score",
      instructions: "How severe is the impact?",
      levels: [
        "Cosmetic",
        { label: "Degraded", description: "Degraded for some users." },
        { label: "Outage", description: "Full outage." },
      ],
    },
  },
});

const { urgent, team, severity } = response.answers;
if (urgent.type === "predicate") console.log(urgent.probability);
if (team.type === "choice") console.log(team.choice, team.confidence);
if (severity.type === "score") console.log(severity.score);
```

答案按您提供的问句名称进行键控，它们的类型由问句推断：`team.choice`被类型化为`"infra" | "billing"`。每个问句要么收到其自身类型的答案，要么收到拒绝，因此在读取类型化字段之前请检查`type`。响应还包含`model`（回答者）、`usage_metadata`中的Token使用情况以及OpenAI的`requestId`。

请求`input`可以是字符串、JSON对象或数组，或LangChain消息。消息（包括系统消息、AI消息和工具消息）被原生地作为对话发送，工具调用和工具结果作为函数调用项。文本和图像内容被保留。其他内容，如文件或音频，被替换为占位符或省略。JSON对象和数组作为结构化JSON在一个用户消息中发送，它们内部的任何消息都以相同的方式转换。

## 决策类型

每个问句是三种类型中的一种：

| 类型 | 询问 | 返回 | 在以下情况下使用 |
| - | - | - | - |
| `predicate` | 这是真的吗？ | `probability`，是的概率 | 您的代码根据`if`分支 |
| `choice` | 这些选项中哪个？ | `choice`，以及`probabilities`和`confidence` | 选项映射到不同的代码路径 |
| `score` | 哪个级别？ | `score`，以及`probabilities`和`confidence` | 答案是一个您要与之比较的阈值的范围 |

`predicate`是唯一没有`confidence`的类型，因为概率就是答案。对于范围，使用`score`而不是`predicate`：概率为`0.5`意味着在“是”和“否”之间均等，而不是“中等”。

`score`级别按从低到高的顺序排列，并从`0`开始索引。传递一个纯字符串表示仅标签的级别，或传递一个具有`label`和`description`的对象。返回的`score`是级别索引的概率加权平均值，因此它可能落在级别之间。`probabilities`中的每个条目都包含一个级别的索引作为`value`，其`label`和其`probability`。

当模型拒绝回答一个问句时，答案是`RefusalAnswer`，其中包含`type: "refusal"`而不是类型化的答案。

## 智能体中间件

`langchain`包包含两个Beta阶段的[中间件](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/middleware/overview.md)，将OpenAI决策放在智能体的决策点。从`langchain`导入它们。在使用它们之前，与OpenAI集成一起安装`langchain`：

```bash npm theme={null}
npm install langchain @langchain/openai @langchain/core
```

```bash yarn theme={null}
yarn add langchain @langchain/openai @langchain/core
```

```bash pnpm theme={null}
pnpm add langchain @langchain/openai @langchain/core
```

| 中间件 | 钩子 | 决策 |
| - | - | - |
| [`openAIModelRouterMiddleware`](#模型路由) | `beforeAgent`, `wrapModelCall` | 哪个模型处理运行 |
| [`openAIAutoModeMiddleware`](#工具风险门控) | `wrapToolCall` | 工具调用是否风险过高 |

这两个中间件都需要一个`model`：一个配置好的`OpenAIDecisions`实例。

### 模型路由

对您所有命名模型中的最新人类消息进行分类，并使用选定的模型处理运行中的每个模型调用。每个选择都配对了一个模型及其选择的依据：

```typescript theme={null}
import { createAgent, openAIModelRouterMiddleware } from "langchain";
import { OpenAIDecisions } from "@langchain/openai";

const router = openAIModelRouterMiddleware({
  choices: {
    fast: {
      model: "openai:gpt-6-luna",
      criteria:
        "Direct lookups, extraction, and localized changes with explicit targets.",
    },
    powerful: {
      model: "openai:gpt-6-sol",
      criteria:
        "Architecture, novel root-cause reasoning, and high-stakes decisions.",
    },
  },
  instructions: "Choose the least costly model that can complete the task safely.",
  model: new OpenAIDecisions("gpt-6-luna"),
});

const agent = createAgent({ model: "openai:gpt-6-luna", middleware: [router] });

const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content:
        "Design a Byzantine fault tolerant consensus protocol and prove its safety and liveness properties.",
    },
  ],
});
console.log(result.modelRoute?.choice);
```

答案存储在智能体状态下的`modelRoute`作为具有`choice`、`probabilities`和`confidence`的对象。当模型拒绝，或状态中没有人类消息时，`modelRoute`是`null`，模型调用使用智能体自己的模型。

### 工具风险门控

询问工具调用具有风险或授权不足的概率。概率为`0.5`或更高的调用返回错误`ToolMessage`而不是运行工具。仅分类您列出的工具。传递它们的名称或工具对象：

```typescript theme={null}
import { createAgent, openAIAutoModeMiddleware, tool } from "langchain";
import { OpenAIDecisions } from "@langchain/openai";
import * as z from "zod";

const deleteAllBackups = tool(async () => "Backups deleted.", {
  name: "delete_all_backups",
  description: "Delete every backup. This action cannot be undone.",
  schema: z.object({}),
});

const agent = createAgent({
  model: "openai:gpt-6-sol",
  tools: [deleteAllBackups],
  middleware: [
    openAIAutoModeMiddleware({
      tools: [deleteAllBackups],
      model: new OpenAIDecisions("gpt-6-luna"),
    }),
  ],
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Delete all backups." }],
});
console.log(result.messages.at(-1)?.text);
```

覆盖`instructions`以描述您自己的工具的风险。中间件采用封闭策略：拒绝会阻止调用，API错误会传播而不会运行工具。

> [!WARNING]
>
> 除非发送给OpenAI是可接受的，否则不要在工具参数或对话状态中放置秘密。此中间件拒绝风险调用。它不会请求批准。当您希望有人批准它们时，请将其与[人工参与中间件](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/middleware/built-in.md)配对。

### 自定义中间件

`OpenAIDecisions`直接接受LangChain消息对象，因此自定义中间件钩子可以在将其转换之前对智能体的对话状态进行分类。此示例在每次运行的开始时对对话进行一次分类，并将完整答案存储在智能体状态中：

```typescript theme={null}
import { createAgent, createMiddleware } from "langchain";
import { OpenAIDecisions } from "@langchain/openai";
import * as z from "zod";

const decisions = new OpenAIDecisions("gpt-6-luna");

const triageMiddleware = createMiddleware({
  name: "TriageMiddleware",
  stateSchema: z.object({
    triage: z
      .object({ choice: z.string(), confidence: z.number() })
      .optional(),
  }),
  beforeAgent: async (state) => {
    const { answers } = await decisions.invoke({
      input: state.messages,
      questions: {
        triage: {
          type: "choice",
          instructions: "Which team should handle this conversation?",
          choices: {
            billing: "Payments, invoices, and subscriptions.",
            infra: "Deploys, availability, and incidents.",
            other: "Requests that belong to another team.",
          },
        },
      },
    });
    if (answers.triage.type !== "choice") return;
    const { choice, confidence } = answers.triage;
    return { triage: { choice, confidence } };
  },
});

const agent = createAgent({
  model: "openai:gpt-6-luna",
  middleware: [triageMiddleware],
});
const result = await agent.invoke({
  messages: [{ role: "user", content: "Customers are seeing 500 errors." }],
});
console.log(result.triage?.choice, result.triage?.confidence);
```

使用与您的决策点匹配的任何生命周期钩子。例如，使用`beforeModel`在每次工具结果后重新分类，或使用`wrapToolCall`对拟议的操作进行分类。参见[自定义中间件](https://langchain-docs-zh.mintlify.site/langchain/oss/langchain/middleware/custom.md)了解所有钩子和状态模式。

## 跟踪

OpenAI决策在[LangSmith](https://docs.langchain.com/langsmith/home)中跟踪，因此您可以在智能体的其余部分旁边检查决策和Token使用情况。

## 参见

* [OpenAI决策指南](https://developers.openai.com/api/docs/guides/decisions)
* [OpenAI提供者概述](https://langchain-docs-zh.mintlify.site/langchain/oss/javascript/integrations/providers/openai.md)
* [LangChain OpenAI API参考](https://reference.langchain.com/javascript/langchain-openai)

***

> 官方原文：[src/oss/javascript/integrations/decision\_models/openai.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/javascript/integrations/decision_models/openai.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.