# @alvin0/ai-agent-sdk-provider-openai 中文文档 规范地址：https://npmcn.com/package/%40alvin0/ai-agent-sdk-provider-openai/ 版本：0\.1\.16 npm 元数据更新时间：2026-11-06T06:35:37.015Z 中文译文更新时间：2026-11-07T07:46:36.678Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40alvin0/ai-agent-sdk-provider-openai 原文对照：https://npmcn.com/package/%40alvin0/ai-agent-sdk-provider-openai/?lang=original 项目主页：https://github.com/alvin0/ai-agent-sdk/tree/main/packages/provider-openai#readme 源码仓库：https://github.com/alvin0/ai-agent-sdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：165 kB，11 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：4 个 - peer 依赖：@alvin0/ai-agent-sdk-core ^0\.1\.16 - 首次发布：2026-09-09T16:37:12.511Z - 最新版本发布：2026-11-06T06:35:36.632Z - 近 30 天下载量：2006（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：17（近 12 个月 17 个） ## 中文简介 AI- agent- sdk 通用 OpenAI 适配器和提供者插件 ## 安装 ```sh npm install @alvin0/ai-agent-sdk-provider-openai ``` 也可以使用：`pnpm add @alvin0/ai-agent-sdk-provider-openai`、`yarn add @alvin0/ai-agent-sdk-provider-openai`、`bun add @alvin0/ai-agent-sdk-provider-openai` ## README # @alvin0/ai-agent-sdk- professor-openai (英语) 运行时间 : **通用** (Edge/Worker,浏览器,Deno,Bun,和节点). 兼容网关可以配置 `baseUrl`, (中文(简体) ), `models`, (中文(简体) ), `fetch`,以及 `headers` (一个字符串记录或同步函数返回每个操作一个). 生成使用响应;嵌入使用OpenAI嵌入协议. 项目实例和现场生成/决定测试的使用 `gpt-6-luna` 作为 最小 OpenAI 模型 。 明确选择它或较新的模型;不要返回到 请求失败时的旧模型 。 嵌入模型选择是分开的. 嵌入式适配器/插件也支持自定义头. 标题为不区分大小写。 A 类 `headers` 条目覆盖 SDK 否则,将发出该名称(`accept`, (中文(简体) ), `content-type`, (中文(简体) ), `user-agent`, (中文(简体) ), 协议头)——只有连接级别名称 `fetch` 本身禁止 (单位:千美元)`host`, (中文(简体) ), `content-length`,.)或证书形状的名称(必须经过) `apiKey`编号 :`auth` 相反,它可以被修改成日志) 被拒绝. 供应证书 `apiKey`复制静态记录; 准备的嵌入式呼叫在所有批次中保持相同的头像快照. 需要信任的本地 HTTP 网关 `allowInsecureHttp: true`。 。 。 . ```sh pnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-provider-openai ``` 通用OpenAI适配器和交易提供器插件. 证书被注入;此包从不读取环境变量或文件. ```ts import { ModelRegistry } from '@alvin0/ai-agent-sdk-core' import { openAiPlugin } from '@alvin0/ai-agent-sdk-provider-openai' const registry = new ModelRegistry() registry.install(openAiPlugin({ apiKey: apiKeyFromSecretStore })) // injected string or CredentialSource ``` 使用 `openAiAdapter()` 用于人工路由注册。 API都是通用的,而且 需要明确 `apiKey`; 环境取景器属于节点包装器. 两个都接受 `models: [{ id, contextWindow, maxTokens }]` 加提供者一级 `defaultContextWindow` 财务报告和审定财务报表 `defaultMaxTokens` 堕倒. 一个目录模型的 `maxTokens` 是其SDK输出上限,除非 `models[].defaultMaxTokens` 设置,它默认的产出预算。 提供者的后退预算不是硬上限. 将操作环境保持在任何扩展文本价格阈值以下。 见 [提供者模式限制指南](https://npmcn.com/package/web-documents/en/09-providers/index.md) 举例来说 和优先规则。 这些声明不会增加服务器侧限制. 组成: `runtime.providers`寿命周期: `inert-runtime-owned-registration`· ; 运行时间激活并删除捕获的提供者注册. ## 连接相容的终点 这个软件包讲的是整个OpenAI API家族,而不仅仅是 `api.openai.com`二、导 言 电线得到支持—— `api: 'responses'` (违约)和 `api: 'chat-completions'` 因为大多数第三方的OpenAI兼容端点(DeepSeek, Groq, Congree,), Quen/DashScope, vLLM, Ollama, LM Studio, 许多网关) 只执行 `/chat/completions`中的插件实例 `id`, (中文(简体) ), `baseUrl`, (中文(简体) ), `displayName` (因此错误地命名了真正的销售商,而不是"OpenAI"),和 `api`数字 : ```ts import { envCredential } from '@alvin0/ai-agent-sdk-auth-node' openAiPlugin({ id: 'deepseek', displayName: 'DeepSeek', baseUrl: 'https://api.deepseek.com', api: 'chat-completions', apiKey: envCredential('DEEPSEEK_API_KEY'), compat: { reasoningFormat: 'deepseek' }, // effort → thinking + reasoning_effort }) ``` `compat` 一次曝光 Chat 补全线节点 : `reasoningFormat` (单位:千美元)`'openai'` 默认 - `reasoning_effort` 逐字记录——或 `'deepseek'`,或 `false` 绝不然, `maxTokensField` (单位:千美元)`'max_tokens'` 默认,或 `'max_completion_tokens'`,或 `false`, (中文(简体) ), `systemRole`, (中文(简体) ), `structuredOutputs`, (中文(简体) ), `tools`, (中文(简体) ), `parallelToolCalls`, (中文(简体) ), `streamUsage`, (中文(简体) ), `stop`, (中文(简体) ), `seed`, (中文(简体) ), `promptCacheKey`。未设置的旋钮保留协议的自有功能 保守的默认. ## 快速缓存 设定 `promptCaching: true` 生成一个稳定的 `prompt_cache_key` 每个适配器 实例或通过 `promptCacheKey` 当应用程序已经拥有一个稳定 语句键。 同样的密钥用于答复和聊天补全,包括 a 混合的每个模型路线。 将一个适配器/插件实例保留在一个缓存中 身份; 不要在不相关的租户之间共享自动生成的密钥. 兼容网关由机会处理:如果网关返回400 具体名称 `prompt_cache_key`适配器重试一次 没有球场 并记住 下级的余生. 与请求无关的错误永远不会被吞噬. 一个端点挂起在协议本身路径以外的地方( an Azure) OpenAI 部署, 重写路径的网关) 可以覆盖 `path` 财务报告和审定财务报表 添加 `query` (绝不是秘密——属于 `auth`编号 :`apiKey`: ```ts openAiPlugin({ id: 'azure-gpt', baseUrl: 'https://my-res.openai.azure.com/openai/deployments/gpt-6-luna', path: '/chat/completions', api: 'chat-completions', query: { 'api-version': '2026-06-01' }, apiKey: envCredential('AZURE_KEY'), }) ``` ## 默认配置优先 `contextWindow`, (中文(简体) ), `maxTokens`,以及 `inputModalities` 从明确 代理/调用配置用于模型声明、路由默认、运行时间默认 和SDK退缩政策。 探员 `contextWindow` 财务报告和审定财务报表 `inputModalities` 覆盖 已实施,并一直通过每个呼叫模式开关有效。 继承 努力和 `maxTokens` 切换模型时被丢弃; 清晰的每个调用 `maxTokens` 以优先为准。 省略的方式声明表示未知, 不只写文字。 宣布经核实的定制路线限制,而不是处理 作为供应商技术上限的回落预算. ## 土著决定 API 将同伴运行时间安装为直接依赖 : ```sh pnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-decision-adapter @alvin0/ai-agent-sdk-provider-openai ``` 使用 `/decisions` 附带决定运行时间的切入点 : ```ts import { createDecisionRuntime, choiceQuestion, scoreQuestion, booleanQuestion } from '@alvin0/ai-agent-sdk-decision-adapter' import { openAiDecisionPlugin } from '@alvin0/ai-agent-sdk-provider-openai/decisions' const runtime = createDecisionRuntime({ providers: [openAiDecisionPlugin({ apiKey: process.env.OPENAI_API_KEY!, // baseUrl: 'https://api.openai.com/v1', // API root, including /v1 })] }) try { const result = await runtime.decisionModel({ provider: 'openai', model: 'gpt-6-luna' }).evaluate({ state: { message: 'Please refund my order today.' }, questions: { route: choiceQuestion('Choose the department.', { billing: 'Payments and refunds', support: 'Technical issues' }), urgency: scoreQuestion('How urgent is this?', ['Routine', 'Urgent']), refund: booleanQuestion('Does the customer request a refund?'), }, }) console.log(result.answers, result.usage) } finally { await runtime.close() } ``` `openAiDecisionAdapter` 还直接与 `DecisionRequest`API 密钥可能 是字符串还是SDK证书来源 自定义路由、 API 根、 页眉、 重试 政策, `safetyIdentifier`、截止日期和请求/答复字节限制为 相会相会. 适配器执行一次 HTTP 尝试; 决定运行时间为 重试. 在做出错误决定后,它永远不会回到回复. 字符串状态和指令仍为文本;结构化的 JSON 描述为 序列化为文本。 此条目当前接受 SDK 文本/ JSON `DecisionInput`,而不是本地图像信息。 选择选项使用他们的 SDK 将密钥记录为有线值。 分数标签是零基索引,带有SDK 级别描述保留为线性描述. SDK 布尔问题映射 原生上游; `value` 使用0.5的概率阈值 `probabilityTrue` 保留提供者概率。 使用裁决证据门 当你的应用需要更大的信心. 答案保留提供者概率来源。 用过的地图已缓存和未保存 输入到不连接的 SDK 桶中,零输出符仍然是权威的. 本地拒绝投出不可重试 `ModelError` 有代码 `OPENAI_DECISION_REFUSED`它不产生任何捏造的答案。 尝试会计 即使在拒绝或无效答复阻碍结果的情况下仍保留所报告的使用. 当前本地模式目录包含 `gpt-6-luna`. 仍保留明确的识别模式 可配置给消费者和兼容网关;服务器决定 可用性。 本地决定需要一个 OpenAI API 密钥 。 代码用途 `CODEX_GUARDIAN_DECISIONS_API_KEY` (或 `OPENAI_API_KEY`独立为这个电话 的 ChatGPT OAuth 响应证书; 仅 OAuth 登录不配置 作出决定。 见 [决定指南](https://developers.openai.com/api/docs/guides/decisions) 财务报告和审定财务报表 [代码启动源](https://github.com/openai/codex/blob/main/codex-rs/ext/guardian-v2/src/async_scorer/startup.rs)。 。 。 . ## 常见问题 ### @alvin0/ai-agent-sdk-provider-openai 是什么？ AI- agent- sdk 通用 OpenAI 适配器和提供者插件 ### 如何安装 @alvin0/ai-agent-sdk-provider-openai？ 在项目目录运行 npm install @alvin0/ai-agent-sdk-provider-openai，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@alvin0/ai-agent-sdk-core（^0\.1\.16）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @alvin0/ai-agent-sdk-provider-openai 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @alvin0/ai-agent-sdk-provider-openai 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @alvin0/ai-agent-sdk-provider-openai 可以商用吗？ @alvin0/ai-agent-sdk-provider-openai 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @alvin0/ai-agent-sdk-provider-openai 的下载量有多少？ 根据 npm 官方下载统计，@alvin0/ai-agent-sdk-provider-openai 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,006 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @alvin0/ai-agent-sdk-provider-openai 还在维护吗？ 最新版本 0\.1\.16 发布于 2026/11/06（1 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/09/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。