# @flink-app/openai-adapter 中文文档

规范地址：https://npmcn.com/package/%40flink-app/openai-adapter/

版本：2\.0\.0-alpha\.134
npm 元数据更新时间：2026-11-07T11:33:24.705Z
中文译文更新时间：2026-11-14T23:11:53.261Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flink-app/openai-adapter
原文对照：https://npmcn.com/package/%40flink-app/openai-adapter/?lang=original
项目主页：https://github.com/FrostDigital/flink-framework#readme
源码仓库：https://github.com/FrostDigital/flink-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：113 kB，15 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@flink-app/flink \>=2\.0\.0-alpha\.134
- 首次发布：2026-02-10T13:29:38.779Z
- 最新版本发布：2026-11-07T11:30:17.352Z
- 近 30 天下载量：3518（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：86（近 12 个月 86 个）

## 中文简介

Flink AI 框架的 OpenAI 适配器

## 安装

```sh
npm install @flink-app/openai-adapter
```

也可以使用：`pnpm add @flink-app/openai-adapter`、`yarn add @flink-app/openai-adapter`、`bun add @flink-app/openai-adapter`

## README

# @flink-app/openai-适应器

使用 : **反应 API** - OpenAI的现代API,提供步骤意识推理,明确工具引用,以及更好的性能.

## 为什么是回应API?

这个适配器使用 OpenAI 的 **反应 API** 而不是更古老的Chat Professions API,提供:

-   **\* 步入意识推理**: 模型返回多个工具调用, 作为明确、 键入的单个响应项目
-   **\* 业绩更好**: SWE-bench 有3%的改进,TAU Bench vs Chat 完成 5%
-   **一级工具步骤**: 工具调用和结果是结构化项目,而不是消息黑客
-   **防止未来**: 所有新的 OpenAI 特性将首先登陆响应 API

## 重要: 理解代理循环

**响应 API 不运行您的代理循环 .**

它所提供的:

-   多个工具调用 **一个答复** (你仍然执行他们)
-   结构化的阶梯类型(消息,函数 调用,函数 调用 输出)

什麽 **闪烁手柄** (通过代理Runner):

-   工具执行
-   多回合循环(API ) 执行工具 (API ) 执行工具 (已完成)
-   决定何时停止
-   管理谈话状态

这种分离是有意的 - 它让你完全控制代理行为 同时利用更好的API原始人.

## 安装

```bash
npm install @flink-app/openai-adapter
# or
pnpm add @flink-app/openai-adapter
```

这个 `openai` 软件包包含为依赖,所以不需要单独安装.

## 使用量

### 基本设置

```typescript
import { OpenAIAdapter } from "@flink-app/openai-adapter";
import { FlinkApp } from "@flink-app/flink";

const app = new FlinkApp({
  ai: {
    llms: {
      default: new OpenAIAdapter({
        apiKey: process.env.OPENAI_API_KEY!,
        model: "gpt-6-luna",
        reasoning: { effort: "none" }, // lowest latency for request/response use
      }),
    },
  },
});

await app.start();
```

**遗产 API( 仍然支持 ):**

```typescript
// Backward-compatible constructor
new OpenAIAdapter(process.env.OPENAI_API_KEY!, "gpt-5")
```

### 代理指令

使用 `instructions` 属性 :

```typescript
// src/agents/support_agent.ts
export const Agent: FlinkAgentProps = {
  name: "support_agent",
  instructions: "You are a helpful customer support agent.",
  tools: ["get_order_status"],
  model: { adapterId: "default" },
};
```

**如何运作:**

-   指令是作为系统信息准备给每个对话
-   遵循 Vercel AI SDK 一致性模式
-   在所有相互作用中提供稳定的代理行为

#### 带有系统信件的动态上下文

对于每个请求上下文,在对话中添加系统消息:

```typescript
const result = await ctx.agents.myAgent.execute({
  message: [
    { role: "system", content: "Current user tier: Premium" },
    { role: "user", content: "What can I do?" }
  ]
});
```

**发送到 OpenAI 的信件顺序 :**

1.  探员 `instructions` (作为系统消息)
2.  用户提供的系统信息(如果有的话)
3.  对话消息

这给您带来了静态代理行为和动态的每个请求上下文.

### 结构化产出

启用带有 JSON schema 的结构化输出, 以输出格式实现100%的可靠性 :

```typescript
import { OpenAIAdapter } from "@flink-app/openai-adapter";

const adapter = new OpenAIAdapter({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-5",
  structuredOutput: {
    type: "json_schema",
    name: "car_analysis",
    description: "Analysis of car specifications",
    schema: {
      type: "object",
      properties: {
        brand: { type: "string" },
        model: { type: "string" },
        year: { type: "number" },
        features: {
          type: "array",
          items: { type: "string" }
        }
      },
      required: ["brand", "model", "year"],
      additionalProperties: false
    },
    strict: true // Enforces 100% schema adherence
  }
});
```

适配器选项是每个通过此适配器调用时的默认. 代理人要求的结构化产出( A)`model.structuredOutput`,或 `execute({ model: { structuredOutput } })`)优先,因此,一个适配器可以服务于任意数量的计数器;解析后的答复作为 `result.structured`. 逐个调用计划被消毒到 OpenAI 的严格子集 与工具计划一样`additionalProperties: false`,所有需要的属性,去除数字/字符串限制;通过 `strict: false` 以逐字发送。 构造器选项是按给定发送的,与先前的释放没有变化.

经纪人的 `model.toolChoice` 以 `tool_choice` (单位:千美元)`"auto"`, (中文(简体) ), `"none"`, (中文(简体) ), `"required"` 或者说 `{ type: "function", name }`当请求载有工具时.

**结构化产出的好处:**

-   100%可靠性(vs~95%使用JSON模式)
-   不需要重试逻辑或手动验证
-   生成时自动验证计划
-   支持所有现代模式: `gpt-6-*`, (中文(简体) ), `gpt-5.x`, (中文(简体) ), `gpt-4.1`, (中文(简体) ), `o4-mini`, (中文(简体) ), `o3`

### 理由

合理模型(o-序列、gpt-5、gpt-6和后期)按适配器配置 `reasoning` 选项,逐字通过 `reasoning` 参数( SDK 类型, 因此新的工作级别或摘要模式不需要修改适配器) :

```typescript
const adapter = new OpenAIAdapter({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-6-luna",
  reasoning: { effort: "high", summary: "auto" }, // optional
  verbosity: "low", // optional, sent as text.verbosity
});
```

-   `effort` 接受SDK的游戏 `ReasoningEffort` 值 : `"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"` (所支持的集是模型特异性的). 使用 `"none"` 或者说 `"low"` 用于进行RAG聊天,以及在先入后出和输出令牌重要的情况下进行其他请求/答复.
    
-   `verbosity` (单位:千美元)`"low" | "medium" | "high"`, gpt-5 并随后发送) `text.verbosity` ,并附带任何结构化输出格式.
    
-   **温度**: 拒绝推理模型 `temperature`,因此适配器只向已知的非合理型号发送代理人所配置的温度(`gpt-4*`, (中文(简体) ), `gpt-3.5*`, (中文(简体) ), `*chat-latest`) (中文(简体) ). 对于包括未知未来身份在内的所有其他型号,都会丢弃并记录出警告.
    
-   `summary` 使模型返回推理摘要,流出为 `reasoning` 块并被物剂浮出水面 `reasoning_delta` 活动 `fullStream`它从未出现在 `textStream` 或者说 `result.message`。 。 。 .
    
-   何时 `reasoning` 已经设定, `include: ["reasoning.encrypted_content"]` 添加后, 推理项目甚至可以重放 `store: false`。 。 。 .
    
-   由模型返回的理由项目(id,摘要,加密内容)在助理信息上进行逐字记录(`providerData.openai.reasoningItems`和 **在功能前重播后期制作的调用**,如OpenAI建议的工具调用质量。 其它提供者的追踪没有 OpenAI 项 ID 并被跳过 .
    

### 对话持久性(建议)

用于多回合对话 `ConversationAgent` 自动保存对话历史 :

```typescript
// src/agents/ChatAgent.ts
import { ConversationAgent, ConversationData } from "@flink-app/flink";

export default class ChatAgent extends ConversationAgent<AppContext> {
    id = "chat-agent";
    description = "Chat assistant with automatic conversation persistence";
    instructions = "You are a helpful assistant...";
    tools = ["search-knowledge"];

    // Load conversation from your storage backend
    protected async loadConversation(conversationId: string) {
        const conv = await this.ctx.repos.conversationRepo.getById(conversationId);
        return conv ? {
            messages: conv.messages,
            providerMetadata: conv.providerMetadata // ← Preserved for tracking
        } : null;
    }

    // Save conversation with updated metadata
    protected async saveConversation(conversationId: string, data: ConversationData) {
        await this.ctx.repos.conversationRepo.upsert({
            _id: conversationId,
            messages: data.messages,
            providerMetadata: data.providerMetadata // ← Saved automatically
        });
    }
}
```

**这使得:**

1.  **自动历史管理**:框架处理完整的对话历史
2.  **元数据跟踪**: 保存供调试和未来使用的提供者元数据
3.  **储存灵活性**: 与MongoDB、Redis、内存或后端工作
4.  **类型安全**:摘要方法强制执行一致的执行

**示例存储后端 :**

-   [蒙戈DB](https://npmcn.com/package/packages/demo-app/src/agents/CarPersistentAgent.ts) - 生产准备持续储存
-   [记忆](https://npmcn.com/package/packages/demo-app/src/agents/examples/InMemoryPersistentAgent.ts) - 开发/试验

**提供者元数据如何工作:**

1.  第一回合:代理执行,适配器可能返回提供者特有的元数据
2.  `saveConversation()` 存储消息+元数据
3.  第二轮: `loadConversation()` 返回消息+元数据
4.  框架组合 `input.providerMetadata` 用于跟踪/调试
5.  完全对话的历史总是被发送到可靠性

**说明:** 提供者元数据通过适配器命名(例如, `{ openai: {...}, anthropic: {...} }`用于多供应商支助.

## 图像模型

`OpenAIImageModel` 执行 Flink 的 `ImageModel` 图像 API 上的接口(`images.generate` 编号 : `images.edit`用于 `gpt-image-*` 模特们 登记在 `ai.images` 并使用从 `ctx.ai.images`数字 :

```typescript
import { OpenAIImageModel } from "@flink-app/openai-adapter";

const app = new FlinkApp<AppCtx>({
    ai: {
        images: {
            default: new OpenAIImageModel({
                apiKey: process.env.OPENAI_API_KEY!,
                model: "gpt-image-2",
                quality: "high", // optional defaults: quality, background, outputFormat
            }),
        },
    },
});

const { images, usage } = await ctx.ai.images.default.edit({
    prompt: "Replace the sky with a thunderstorm",
    images: [imageFromBuffer(file, "image/png")], // up to 16 reference images, the first is the edit target
    mask: imageFromBuffer(maskPng, "image/png"),  // optional, transparent areas are replaced
});
```

-   `aspectRatio` `1:1` 编号 : `3:2` 编号 : `2:3` 映射到图像 API 大小; `seed` 不支持( 两种产品 `warnings`(中文(简体) )
-   其他参数通过 `providerOptions.openai` (单位:千美元)`moderation`, (中文(简体) ), `output_compression`, (...) (中文(简体) )
-   失败的是 `ImageModelError`s; 高尔夫球队; `retryable` 429 / 5xx 为真
-   见 [图像模型指南](https://npmcn.com/package/docs/ai/image-models/README.md)

## 除错日志

适配器包括特定组件的日志,以帮助调试 API 请求和响应 :

```typescript
const adapter = new OpenAIAdapter({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-5",
  debug: true // Enable debug logging for this adapter
});
```

**记录的内容 :**

何时 `debug: true`数字 :

-   初始化确认
-   QQ 请求元数据( 模式、 消息计数、 工具计数、 符号限制)
-   QQ 发送给 OpenAI 的全部请求参数
-   \* LLM作出的工具调用决定
-   数据使用和业绩计量
-   QQ 继续对话的响应ID
-   QQ 错误细节与上下文

何时 `debug: false` (默认) :

-   QQ 请求以符号使用完成( info 关卡)
-   存在上下文错误

**日志输出示例 :**

```bash
2026-02-15 [OpenAI] [INFO] OpenAI adapter initialized with debug logging enabled
2026-02-15 [OpenAI] [DEBUG] Starting OpenAI stream request {"model":"gpt-5","messageCount":2,"toolCount":3}
2026-02-15 [OpenAI] [DEBUG] Stream connection established
2026-02-15 [OpenAI] [DEBUG] LLM decided to call tool {"name":"get_weather","call_id":"call_abc123"}
2026-02-15 [OpenAI] [INFO] OpenAI request completed {"inputTokens":150,"outputTokens":80,"totalTokens":230}
```

**环境配置 :**

您也可以在不修改代码的情况下通过环境变量启用调试日志 :

```bash
# Enable debug for OpenAI adapter specifically
DEBUG=OpenAI npm start

# Enable debug for multiple components
DEBUG=OpenAI,Database npm start

# Set global log level
LOG_LEVEL=debug npm start
```

**程序控制 :**

对于运行时的动态控制 :

```typescript
import { FlinkLogFactory } from "@flink-app/flink";

// Enable debug for OpenAI adapter
FlinkLogFactory.setComponentLevel("OpenAI", "debug");

// Later, disable it
FlinkLogFactory.setComponentLevel("OpenAI", "info");
```

**福利:**

-   QQ 调试 API 请求而不淹没其他日志
-   每个请求的音轨符号使用量
-   调查调用问题的工具
-   \* 监测业绩和延迟情况
-   QQ 特定组件日志( OpenAI 日志不影响数据库、 快取等)

见 [链接日志指南](https://npmcn.com/package/docs/LOGGING.md) 关于特定组成部分的伐木的更详细资料.

## 缓存计量和成本优化

OpenAI适配器会自动抓取详细的缓存度量衡来帮助您优化成本并理解性能:

```typescript
const result = await ctx.agents.myAgent.execute({
  message: "What's the weather?"
});

console.log(result.usage);
// {
//   inputTokens: 2006,
//   outputTokens: 300,
//   cachedInputTokens: 1920  // 95% cache hit!
// }

// Calculate actual billed input tokens
const billedInputTokens = result.usage.inputTokens - (result.usage.cachedInputTokens || 0);
console.log(`Only ${billedInputTokens} tokens charged at full rate`);
// "Only 86 tokens charged at full rate"

// Estimate cost savings (cached tokens are ~10% of regular cost)
const regularCost = billedInputTokens * 1.0;
const cachedCost = (result.usage.cachedInputTokens || 0) * 0.1;
const totalCost = regularCost + cachedCost;
console.log(`Estimated cost factor: ${totalCost} (vs ${result.usage.inputTokens} without caching)`);
// "Estimated cost factor: 278 (vs 2006 without caching)" - 86% savings!
```

**缓存量表 :**

-   `inputTokens`: 总输入符 (包括缓存)
-   `outputTokens`: 总产出符号
-   `cachedInputTokens`: 从缓存中发送输入符( 10% 成本)

**OpenAI 缓存 :**

-   缓存的代币价值为正版代币的10%
-   重复上下文的自动缓存
-   不需要配置 - OpenAI 自动处理

**当缓存帮助最多时 :**

-   对请求使用长的系统提示
-   多回合对话中重复上下文
-   提示中少见的例子
-   二. 大的知识基础

**日志 :** 当调试模式被启用时,缓存度量自动被登录 :

```bash
2026-02-23 [flink.ai.openai] [INFO] OpenAI request completed {
  "inputTokens": 2006,
  "outputTokens": 300,
  "cachedInputTokens": 1920,
  "totalTokens": 2306,
  "status": "completed",
  "model": "gpt-5"
}
```

## 多个适配器

您可以注册多个配置不同的 OpenAI 适配器 :

```typescript
import { OpenAIAdapter } from "@flink-app/openai-adapter";
import { FlinkApp } from "@flink-app/flink";

const app = new FlinkApp({
  ai: {
    llms: {
      // Default GPT-6 - best for general tasks
      default: new OpenAIAdapter({
        apiKey: process.env.OPENAI_API_KEY!,
        model: "gpt-6-luna",
        reasoning: { effort: "low" }
      }),

      // Fast reasoning model - cost-efficient
      fast: new OpenAIAdapter({
        apiKey: process.env.OPENAI_API_KEY!,
        model: "o4-mini"
      }),

      // Maximum intelligence for complex reasoning
      smart: new OpenAIAdapter({
        apiKey: process.env.OPENAI_API_KEY!,
        model: "o3"
      }),

      // With structured output
      structured: new OpenAIAdapter({
        apiKey: process.env.OPENAI_API_KEY!,
        model: "gpt-6-luna",
        structuredOutput: {
          type: "json_schema",
          name: "response",
          schema: { /* your schema */ },
          strict: true
        }
      }),
    },
  },
});
```

## 用于代理

在代理配置中引用适配器注册的ID:

```typescript
// src/agents/support_agent.ts
import { FlinkAgentProps } from "@flink-app/flink";

export const Agent: FlinkAgentProps = {
  name: "support_agent",
  description: "Customer support assistant",
  instructions: "You are a helpful customer support agent.",
  tools: ["get_order_status", "search_knowledge_base"],
  model: {
    adapterId: "default", // Uses the "default" adapter
    maxTokens: 2000,
    temperature: 0.7, // ignored (with a warning) on reasoning models
  },
};
```

## 支持的模式

这个适配器与所有通过响应API提供的OpenAI模型相配合. 最新的模型(截至2026年)提供了重大的改进:

### GPT-6系列(建议)

-   `gpt-6-astra`, (中文(简体) ), `gpt-6.1-sol`, (中文(简体) ), `gpt-6-sol`, (中文(简体) ), `gpt-6-luna`
    -   OpenAI 当前的行; 所有都是推理模型
    -   `reasoning.effort` 接受 `none`, (中文(简体) ), `low`, (中文(简体) ), `medium` (违约), `high`, (中文(简体) ), `xhigh` 财务报告和审定财务报表 `max`

### GPT-5系列

-   **GPT-5.6 常规**数字 : `gpt-5.6` - 推理模型,推荐替代GPT-6
-   **GPT-5 常规**数字 : `gpt-5`, (中文(简体) ), `gpt-5-mini`, (中文(简体) ), `gpt-5-nano` - 2026-12-11关闭

### GPT-4.1系列

-   **GPT-4.1 (韩语)**数字 : `gpt-4.1`
    
    -   最聪明的非理性模式
    -   出色的编码任务
    -   严格准确的指示如下:
    -   最佳网络开发和技术任务
-   **GPT-4.1 微型**数字 : `gpt-4.1-mini`
    
    -   更小,更快,成本效益更高
    -   能力和费用的良好平衡
-   **GPT-4.1纳米**数字 : `gpt-4.1-nano`
    
    -   超快和高成本效益
    -   简单、量大的任务最好

### O-系列理性模型

-   **o4- mini 数据**数字 : `o4-mini` (为推理任务推荐)
    
    -   快速、成本效益高的推理模式
    -   A. 2024年和2025年非洲工业化企业基准业绩最佳
    -   优化数学和逻辑推理
-   **单位3**数字 : `o3`
    
    -   复杂任务的高级推理模式
    -   编码、数学和科学方面的最新业绩
    -   优秀的密码部队,SWE-bench和MMMU
-   **o3-亲**数字 : `o3-pro`
    
    -   Premium 推理模型(仅限Pro用户)
    -   设计思考时间较长,提供最可靠的对策

### 遗产模式

对于后向兼容性 :

-   **GPT-4 涡轮**数字 : `gpt-4-turbo`
-   **GPT-4 常规**数字 : `gpt-4`
-   **GPT-3.5 涡轮**数字 : `gpt-3.5-turbo`

**说明**:每个GPT-4.1和GPT-4o型号在2027-01-14上关闭. 迁移到GPT-6或GPT-5.6(见 [OpenAI 折旧](https://developers.openai.com/api/docs/deprecations)) (中文(简体) ).

## 选择指南范本

| 使用大小写 | 推荐模式 | 为什么 |
| --- | --- | --- |
| 一般发展 | `gpt-6-luna` | 当代 |
| 低频聊天/ RAG | `gpt-6-luna` 与 `effort: "none"` | 最小推理费 |
| 编码和技术 | `gpt-4.1` | 后续最佳教学 |
| 量大的任务 | `gpt-4.1-mini` | 具有良好业绩的成本效益 |
| 数学推理 | `o4-mini` | 优化数学、快速和成本效益 |
| 复杂问题的解决 | `o3` | 最新推理 |
| 关键任务 | `o3-pro` | 最大可靠性(Pro用户) |

## 特征

-   ✅ **基于步骤的工具调用** - 多个工具作为打出的项目在一个响应中调用
-   ✅ **事件流** - 适当的事件分类学(不只是信号流)
-   ✅ **结构化产出** jSON 计划(100%可靠性)
-   ✅ **理由** - 说吧 `reasoning` 通过,摘要流出为 `reasoning_delta`,在交替播放的推理项目
-   ✅ **一等工具步骤** - 函数 调用和函数 调用 输出为明确类型
-   支持所有 OpenAI 模型(GPT-6、GPT-5.x、GPT-4.1, o系列)
-   与聊天完成相比,业绩提高了3-5%

### 是什么使反应 API 不同

关键区别在于 **工具调用如何显示**,而不是执行者:

**聊天补全( 旧) :**

```
Response: {
  message: {
    content: "...",
    tool_calls: [...]  // Tool calls embedded in message
  }
}

You: Extract tool calls, execute them, create new messages, call API again
```

**答复 API(新):**

```
Response: {
  output: [
    { type: "message", content: "..." },
    { type: "function_call", name: "...", call_id: "..." },
    { type: "function_call", name: "...", call_id: "..." }  // Multiple calls!
  ]
}

You: Extract tool calls, execute them, create function_call_output items, call API again
```

**主要改进:**

-   **每个响应都使用多个工具呼叫**: 模型可以同时请求多个工具
-   **明确的步骤类型**: 不再留言角色体操
-   **结构较好**: 函数 call output vs 挤入用户信件
-   **更清晰的语义**: 步骤是一等, 而不是消息元数据

**还是你的责任:**

-   执行工具
-   决定何时停止循环
-   管理对话历史

## API 密码

### `OpenAIAdapter`

```typescript
interface OpenAIAdapterOptions {
  apiKey: string;
  model: string;
  structuredOutput?: {
    type: "json_schema";
    name: string;
    description?: string;
    schema: Record<string, any>;
    strict?: boolean;
  };
  reasoning?: Reasoning; // SDK type: { effort?: ReasoningEffort; summary?: "auto" | "concise" | "detailed" }
  verbosity?: "low" | "medium" | "high"; // SDK ResponseTextConfig["verbosity"]
  debug?: boolean;
}

class OpenAIAdapter implements LLMAdapter {
  constructor(options: OpenAIAdapterOptions);
  constructor(apiKey: string, model: string); // Legacy
}
```

#### 参数

-   `apiKey`: 您的 OpenAI API 密钥
-   `model`:要使用的OpenAI模型(如"gpt-6-luna","gpt-5.6","o4-mini")
-   `structuredOutput`:结构化产出的可选 JSON 方案
-   `reasoning`: 可选推理配置, 逐字发送为 `reasoning`
-   `verbosity`: 可选输出动词,作为 `text.verbosity`
-   `debug`: 可选调试日志( 默认) `false`(中文(简体) )

## 结构说明

### API 对聊天补全

这个适配器使用 OpenAI 的 **反应 API**,这在几个方面与聊天补全不同:

**请求格式 :**

-   聊天补全 : `messages` 带有系统/用户/助手角色的阵列
-   反应 API : `input` 有已键入项目(消息、函数 调用 输出等)的数组 + 单独 `instructions` 字段

**响应格式 :**

-   聊天补全 : `choices[0].message.content`
-   反应 API : `output` 类型项目数组 `message`, (中文(简体) ), `function_call`等 (中文(简体) ).

**工具/功能格式 :**

-   聊天补全: 外部标记 `{ type: "function", function: {...} }`
-   答复 API:内部标记 `{ type: "function", name: "...", ... }` (默认限制)

**结构化产出:**

-   聊天补全 : `response_format: { type: "json_schema", json_schema: {...} }`
-   反应 API : `text: { format: { type: "json_schema", ... } }`

### Flink 整合

适配器与Flink的无缝融合 `LLMAdapter` 接口 :

-   闪闪发光 `instructions` - 反应API `instructions`
-   闪闪发光 `messages` − 转换为反应API `input` 项目(类型步骤)
-   Flink 工具 schema – 转换为响应 API 函数格式(内部标记,默认严格)
-   回应 `output` - 被提取到Flink家 `LLMResponse` 格式

**每一次API呼叫都是一个转弯:**

-   闪烁电话 `adapter.execute()` - 一个答复API请求
-   答复可能包含多个工具呼叫(作为单独项目)
-   Flink的代理Runner 执行这些工具
-   闪烁电话 `adapter.execute()` 使用工具结果 – 另一个响应 API 请求
-   重复直到不再调用工具

这是现代框架(LangGraph,Vercel AI SDK等)使用的标准代理循环架构

## 从聊天补全中移入

如果你来自查特完成API,好消息是: **不需要更改代码!**

适配器在内部处理所有差异 :

```typescript
// This works the same way with both APIs
const app = new FlinkApp({
  ai: {
    llms: {
      default: new OpenAIAdapter({
        apiKey: process.env.OPENAI_API_KEY!,
        model: "gpt-5" // Just update the model
      }),
    },
  },
});
```

升级的好处:

-   QQ 步入意识推理(每次响应多工具呼叫)
-   业绩更好(基准改进了3-5%)
-   QQ 一等工具步骤( 比信件角色黑客更干净)
-   ■ 未来防(新地物先在此地取地)

## 所需资源

-   节点.js 18
-   @flink-app/flink >= 1.0.0
-   openai QQ 4.77.0 (在响应 API 的支持下)

## 许可证

麻省理工学院

## 资源

-   [OpenAI 响应 API 文档](https://platform.openai.com/docs/api-reference/responses)
-   [迁移到响应 API 指南](https://platform.openai.com/docs/guides/migrate-to-responses)
-   [为什么我们建立反应API](https://developers.openai.com/blog/responses-api/)
-   [结构化产出指南](https://platform.openai.com/docs/guides/structured-outputs)

## 常见问题

### @flink-app/openai-adapter 是什么？

Flink AI 框架的 OpenAI 适配器

### 如何安装 @flink-app/openai-adapter？

在项目目录运行 npm install @flink-app/openai-adapter，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@flink-app/flink（\>=2\.0\.0-alpha\.134）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @flink-app/openai-adapter 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @flink-app/openai-adapter 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @flink-app/openai-adapter 可以商用吗？

@flink-app/openai-adapter 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @flink-app/openai-adapter 的下载量有多少？

根据 npm 官方下载统计，@flink-app/openai-adapter 在 2026/10/15 – 2026/11/13 这 30 天内被下载 3,518 次，日均约 117 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flink-app/openai-adapter 还在维护吗？

最新版本 2\.0\.0-alpha\.134 发布于 2026/11/07（8 天前）；至今共发布 86 个版本，其中过去 12 个月发布了 86 个；首次发布于 2026/02/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。