# @crvouga/mockingbird-service-openai 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-openai/

版本：1\.11\.0
npm 元数据更新时间：2026-11-11T02:24:49.275Z
中文译文更新时间：2026-11-11T02:15:16.303Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-openai
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-openai/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/openai#readme
源码仓库：https://github.com/crvouga/mockingbird

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

- 包体积（解压后）：4.5 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-10-05T09:27:31.850Z
- 最新版本发布：2026-11-11T02:24:48.938Z
- 近 30 天下载量：17314（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

本地的脚本OpenAI模拟器:聊天/工具循环,SSE,嵌入,模型,文件以及没有计费推论的上传.

## 安装

```sh
npm install @crvouga/mockingbird-service-openai
```

也可以使用：`pnpm add @crvouga/mockingbird-service-openai`、`yarn add @crvouga/mockingbird-service-openai`、`bun add @crvouga/mockingbird-service-openai`

## README

# @crvouga/mockingbird-service-openai (英语)

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

A 类 **阴道**,可移植,完全本地 OpenAI 模拟器用于聊天补全,函数工具循环, 聊天SSE流,嵌入,模型,文件并进行上传. 未修改过的验证 **开源软件国际化之简体中文组**, (中文(简体) ), **@ai-sdk/openai 4.0.83 (英语)** 财务报告和审定财务报表 **(一) 7.0.127 (中文(简体) )** 过节点HTTP. 它不进行推断,也不要求供应商账户或开具API密钥.

## 安装

```sh
bun add @crvouga/mockingbird-service-openai
```

## 使用量

这些例子使用官方 `openai@7.27.0` SDK(英语:SDK).

```ts
import OpenAI from "openai"
import { createRuntime, DEFAULT_TOKEN } from "@crvouga/mockingbird-service-openai"

// Test setup: the emulator, scripted with the reply the test expects.
const emulator = createRuntime({
  scripts: [{
    kind: "chat",
    message: { role: "assistant", content: "Fixture answer" },
    usage: { prompt_tokens: 12, completion_tokens: 3, cached_tokens: 8 },
  }],
})

// The app's own OpenAI client. Only its fetch changes: requests reach the
// emulator in this process instead of api.openai.com.
const openai = new OpenAI({
  apiKey: DEFAULT_TOKEN,
  fetch: (url: RequestInfo | URL, init?: RequestInit) => emulator.fetch(new Request(url, init)),
})
const completion = await openai.chat.completions.create({
  model: "fixture-chat",
  messages: [{ role: "user", content: "Fixture question" }],
})
console.log(completion.choices[0]?.message.content) // "Fixture answer"
console.log(completion.usage?.total_tokens) // 15
```

对于Vercel AI SDK,也安装 `@ai-sdk/openai@4.0.83` 财务报告和审定财务报表 `ai@7.0.127`,并点 供应商 `baseURL` 在一个听服务器. 使用明确的 `.chat()` 提供商:提供商的默认模式使用Resolution API.

```ts
import { createOpenAI } from "@ai-sdk/openai"
import { generateText } from "ai"
import { createServer } from "@crvouga/mockingbird-service-openai/server"
import { DEFAULT_TOKEN } from "@crvouga/mockingbird-service-openai"

const server = await createServer({
  scripts: [{ kind: "chat", message: { role: "assistant", content: "Fixture answer" } }],
})
try {
  const provider = createOpenAI({ baseURL: `${server.url}/v1`, apiKey: DEFAULT_TOKEN })
  console.log((await generateText({ model: provider.chat("fixture-chat"), prompt: "Fixture", maxRetries: 0 })).text)
} finally {
  await server.close()
}
```

`openai` 还接受 `baseURL: server.url + "/v1"` 和钉子 `apiKey`。 。 。 . CLI是: 校对: `mockingbird-openai serve --port 8813`。 。 。 . `createServer()` 默认为麻黄口.

## 路线和坚持行为

| 终点 | 行为 |
| --- | --- |
| `POST /v1/chat/completions` | 脚本助手 JSON 或 Chat SSE; 工具、 完成原因和精确使用 |
| `GET /v1/chat/completions` | 仅存储完成,模型过滤器, `after`, (中文(简体) ), `limit`, (中文(简体) ), `order` |
| `GET` 编号 : `DELETE /v1/chat/completions/{completion_id}` | 检索/删除a `store: true` 完成 |
| `POST /v1/embeddings` | 精确的脚本向量、字符串或符号输入、浮标/基准64编码和尺寸 |
| `GET /v1/models` 编号 : `GET /v1/models/{model}` | 配置合成模型固定装置 |
| `POST` 编号 : `GET /v1/files` | 多段文件创建; 以目的、 顺序、 后面和限制方式列出元数据 |
| `GET` 编号 : `DELETE /v1/files/{file_id}` | 元数据读取和删除 |
| `GET /v1/files/{file_id}/content` | 精确的二进制字节 |
| `POST /v1/uploads` | 创建一个未完成的上传, 在一个小时后过期 |
| `POST /v1/uploads/{upload_id}/parts` | 多块 `data`,未公布的待公布部分 |
| `POST /v1/uploads/{upload_id}/complete` | 已订购 `part_ids`; 准确宣布的字节数和可选的 MD5 检查 |
| `POST /v1/uploads/{upload_id}/cancel` | 取消待定的上传 |

`DEFAULT_TOKEN` 实值 `fixture-openai-token`· ; `tokens: [{ token, models?: string[] }]` 配置 合成无记名证书和可选型号访问. 无效/ 丢失的证书返回 401, 403,未知型号/资源 404,畸形请求400 `{ error: { message, type, param, code } }` 财务报告和审定财务报表 `x-request-id`。默认模式是 `fixture-chat` 财务报告和审定财务报表 `fixture-embedding` (三维. `models` 接受 `{ id, kind: "chat" | "embedding", dimensions?, created?, owned_by? }`. 没有模型名称意味着真正的推论或供应商的可用性.

脚本选择会消耗第一个匹配其类型和可选的未消费脚本 `match: { model?, lastRole?, contentIncludes?, toolCallId? }`。未匹配的脚本仍然排队. `ChatScript` 已经 `kind: "chat"`, (中文(简体) ), `message: { role: "assistant", content: string | null, tool_calls?, refusal? }`选项 `finish_reason`, (中文(简体) ), `usage`, (中文(简体) ), `chunk_size` 财务报告和审定财务报表 `stream_delay_ms`。 。 。 . 函数调用 `{ id?, type: "function", function: { name, arguments: string } }`· ; 参数必须是有效的 JSON **字符串**. 遗失的身份证一次生成,并持续存在。 助理 以工具/反驳方式保留无效内容;a `role: "tool"` 答复必须提及先前 助理呼叫身份证 完成原因为: `stop`, (中文(简体) ), `tool_calls`, (中文(简体) ), `length`, (中文(简体) ), `content_filter`。 。 。 . `EmbeddingScript` 已经 `kind: "embedding"`, (中文(简体) ), `vectors: number[][]`,可选匹配和使用.

准确的用法是 `{ prompt_tokens, completion_tokens?, cached_tokens? }` (非负整数, 缓存时间最多). 聊天答覆包括全部符和 `prompt_tokens_details.cached_tokens`。 。 。 . 没有脚本, 本地默认为 `Fixture response`; 嵌入使用决定散列 向量计. 默认符号估计数 UTF-8 字节除以 4, 四舍五入, 最小值 一个 这些缺省是合成政策;供应使用/媒介用于精确的消费者测试. 它们没有大致的语义推论,或声称是等同的.

SSE 发射 `chat.completion.chunk` JSON 有索引内容/工具参数三角洲, 最终 结束原因,和 `[DONE]`。 。 。 . `stream_options.include_usage: true` 添加最后的空选择 使用块; 较早的块带有无效使用. `chunk_size` 计数 Unicode 字符; `stream_delay_ms` 延迟为取消测试提供框架。 中止/取消 流并清除其待决的计时器; 开始完成仍然是已创建的资源.

仅 `store: true` 完成部分可通过供应商阅读。 聊天命令默认为 上升的创作时间。 它的本地页面界限是默认的 20, 最多 100 个 。 文件命令本地默认降级 创建时间,限制/最大为一万;呼叫者可以明确设定订单. 稳定插入顺序换行 创建时的联系. `after` 是最后一个资源 ID; 所有页面曝光 `first_id`, (中文(简体) ), `last_id`, (中文(简体) ), `has_more`。重复 `prompt_cache_key`,信头或请求的ID不复制创建: 有文件记载的"查特"合同并不能保证"一能"的突变. 只上传完成 接受等待上传; 完成/取消/过期上传拒绝进一步的突变.

使用多部分机构的文件 `purpose` 财务报告和审定财务报表 `file`。所支持的目的有: `assistants`, (中文(简体) ), `batch`, (中文(简体) ), `fine-tune`, (中文(简体) ), `vision`, (中文(简体) ), `user_data`; 上传阶段使用前四. 批次文件于 三十日来. 可选 `expires_after[anchor]=created_at` 财务报告和审定财务报表 `expires_after[seconds]` 接受 3,600–2,592,000秒(英语: 分阶段上传完成后在调用器部分创建文件 命令,验证字节数/检查和,并永远不公布部分数据. `maxFileBytes` 默认 至 20 MiB并限制文件/上载/部件; 这不是生产配额.

所有记录都使用 SQLite Collections 和 IdSequence; 生命周期时间戳/过期使用共享 时钟. 每个命名空间接收构建器 `scripts`, (中文(简体) ), `models`, (中文(简体) ), `files` 固定; 重置还原 他们。 文件接受 `{ id?, filename, purpose, bytes: string | number[], expires_at? }`。 。 。 . 使用 `x-mockingbird-namespace`, (中文(简体) ), `/__admin/ns/{namespace}/v1/...`,或共享证书登记 为SDKs。 时间线分会/检查点重用共享运行时间并保持状态隔离.

## 控制、失败和隐私

`DEFAULT_ADMIN_KEY` 实值 `fixture-openai-admin`。管理数据路径需要 `x-mockingbird-admin-key`; 配置一个非空 `adminKey` 用来替换它。 习惯 `adminPrefix` 移动所有控件和命名空间路径载体。 共享时钟,错误,重置,日记, 状态、证书、指标和时间线路线仍然可用.

| 控制权 | 目的 |
| --- | --- |
| `POST /__admin/scripts` | 严格验证和排队一个恰克/嵌入脚本 |
| `GET /__admin/scripts` | 身份证、类型和消费状态 |
| `POST /__admin/raw-faults` | 明显未加工 `{ body: string, status?, content_type?, model? }`; 允许错误的供应商数据 |
| `GET /__admin/request-metadata` | 模型、计数/作用、字节长度、散列和反应/标记标识 |
| `POST /__admin/request-assertions` | `{ fingerprints: string[] }`,比较订购的 SHA-256 请求散列 |
| `GET /__admin/stream-metadata` | 打开/ 关闭/ 放弃流状态和块数 |
| `GET /__admin/upload-metadata` | 上传元数据 |

普通脚本拒绝未知字段,在原子上反应形状不正确. 原始错误控制 是唯一的逃生舱门. `fingerprint(body)` 计算确切的 JSON 序列化 SHA-256 散列 - 财产命令事项。 没有保留任何收到的提示/工具结果 . 脚本、答复、文件/部分字节和原始断层体是用 SQLite 加密的 AES-GCM 私有运行时键和逻辑命名空间绑定 。 一般状态快照显示密码文本和 元数据, 绝不是正文或密钥 。 供应商资源读取解密请求的产出 . 共享请求日记/日志只包含元数据;API密钥从未被登录.

预设起火一次: `rate_limited` (429,"重试后"和"后"), `server_error` (500个), `service_unavailable` (503个), `network_reset`, (中文(简体) ), `invalid_json`, (中文(简体) ), `malformed_stream`, (中文(简体) ), `content_refusal`, (中文(简体) ), `slow_response` (发送前50分). 可读错误/ 滴入不消耗脚本 . 报道的原始客户端只重复了网络错误,429和5xx. 官方 OpenAI SDK 另加 408/409 由自己的政策重审;配置 `maxRetries` 当他们坚持尝试的时候。 运输 latency使用壁时间,而资源寿命周期则使用模拟器时钟.

## API 密码

根导出 `OpenAIAPI`, (中文(简体) ), `createRuntime`, (中文(简体) ), `document`, (中文(简体) ), `supportedOperationIds`, (中文(简体) ), `DEFAULT_MODELS`, (中文(简体) ), `DEFAULT_TOKEN`, (中文(简体) ), `DEFAULT_ADMIN_KEY`, (中文(简体) ), `OPENAI_NAMESPACE`, (中文(简体) ), `OPENAI_PRESETS`, (中文(简体) ), `fingerprint`, (中文(简体) ), `validateScript`, (中文(简体) ), `createVaultKey`, (中文(简体) ), `vendorError`,并导出固定/标记/选项/运行时间类型. API 曝光 `fetch`, (中文(简体) ), `reset`, (中文(简体) ), `ensureSeeded`, (中文(简体) ), `queue`, (中文(简体) ), `queueRaw`, (中文(简体) ), `seedFile`, (中文(简体) ), `state`, (中文(简体) ), `app`, (中文(简体) ), `sqlite`节点 `./server` 出口 `createServer`, (中文(简体) ), `DEFAULT_PORT`, (中文(简体) ), `serveTarget` 和服务器类型. 可选 `vaultKey` 是召客提供的私人关键材料, 从未在状态中坚持.

## 甲骨文和核查

合同正式签订后 [聊天创建](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create), (中文(简体) ), [函数调用](https://developers.openai.com/api/docs/guides/function-calling), (中文(简体) ), [存储的聊天列表](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/list), (中文(简体) ), [嵌入](https://developers.openai.com/api/reference/resources/embeddings/methods/create), (中文(简体) ), [模型](https://developers.openai.com/api/reference/resources/models/methods/list), (中文(简体) ), [文件](https://developers.openai.com/api/reference/resources/files/methods/create), (中文(简体) ), [文件列表](https://developers.openai.com/api/reference/resources/files/methods/list), (中文(简体) ), [上传](https://developers.openai.com/api/reference/resources/uploads/methods/create), (中文(简体) ), [完成](https://developers.openai.com/api/reference/resources/uploads/methods/complete),以及 [错误](https://developers.openai.com/api/docs/guides/error-codes)。 。 。 .

`bun test` 在节点HTTP上验证未修改的 SDK, 报告的非流工具循环精确 重试计数、SSE/破坏处理、精确字节和舞台原子学、命名空间/重置/时间线, 每个预设程序 每一个启动的JSON操作, 和故意的分歧。 多段/二进制作业已进行验收测试. `bun run parity` 出口2:存储器政策禁止开出账单推断. 没有现场OpenAI结果 索赔; 正式文件和当地SDK执行是证据.

## 故意不模拟

反应 API、实时/音频/图像/批量/精细调整 API、内置主机工具、多式联运 内容解释、真实推论/开具、帐单、生产配额、, 生产不透明的ID/cursor编码和无文件的要求ID分解。 这个包 从来没有打电话给OpenAI。 加密的持久性是私有运行时态,而不是生产密钥金库.

## 常见问题

### @crvouga/mockingbird-service-openai 是什么？

本地的脚本OpenAI模拟器:聊天/工具循环,SSE,嵌入,模型,文件以及没有计费推论的上传\.

### 如何安装 @crvouga/mockingbird-service-openai？

在项目目录运行 npm install @crvouga/mockingbird-service-openai，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-openai，可以用 npx mockingbird-openai 直接运行。

### @crvouga/mockingbird-service-openai 支持 TypeScript 吗？

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

### @crvouga/mockingbird-service-openai 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @crvouga/mockingbird-service-openai 可以商用吗？

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

### @crvouga/mockingbird-service-openai 的下载量有多少？

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

### @crvouga/mockingbird-service-openai 还在维护吗？

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