@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原始人.

安装

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

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

使用量

基本设置

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( 仍然支持 ):

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

代理指令

使用 instructions 属性 :

// 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 一致性模式
• 在所有相互作用中提供稳定的代理行为

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

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

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%的可靠性 :

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 类型, 因此新的工作级别或摘要模式不需要修改适配器) :

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 自动保存对话历史 :

// 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 - 生产准备持续储存
• 记忆 - 开发/试验

提供者元数据如何工作:

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数字 :

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, (...) (中文(简体) )
• 失败的是 ImageModelErrors; 高尔夫球队; retryable 429 / 5xx 为真
• 见 图像模型指南

除错日志

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

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 关卡)
• 存在上下文错误

日志输出示例 :

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}

环境配置 :

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

# 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

程序控制 :

对于运行时的动态控制 :

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 日志不影响数据库、 快取等)

见 链接日志指南 关于特定组成部分的伐木的更详细资料.

缓存计量和成本优化

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

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 自动处理

当缓存帮助最多时 :

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

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

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

多个适配器

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

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:

// 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 折旧) (中文(简体) ).

选择指南范本

特征

• ✅ 基于步骤的工具调用 - 多个工具作为打出的项目在一个响应中调用
• ✅ 事件流 - 适当的事件分类学(不只是信号流)
• ✅ 结构化产出 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

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,好消息是: 不需要更改代码!

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

// 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 文档
• 迁移到响应 API 指南
• 为什么我们建立反应API
• 结构化产出指南