# @dbx-tools/appkit-model-gateway 中文文档

规范地址：https://npmcn.com/package/%40dbx-tools/appkit-model-gateway/

版本：0\.9\.206
npm 元数据更新时间：2026-11-10T19:19:17.176Z
中文译文更新时间：2026-11-11T17:50:06.034Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40dbx-tools/appkit-model-gateway
原文对照：https://npmcn.com/package/%40dbx-tools/appkit-model-gateway/?lang=original
项目主页：https://github.com/reggie-db/dbx-tools#readme
源码仓库：https://github.com/reggie-db/dbx-tools

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

- 包体积（解压后）：695 kB，51 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2026-10-05T22:24:19.155Z
- 最新版本发布：2026-11-10T19:19:16.857Z
- 近 30 天下载量：8184（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：97（近 12 个月 97 个）

## 中文简介

Databricks OpenAI、Anthropic、Codex和AI Gateway API的 AppKit 模型网关

## 安装

```sh
npm install @dbx-tools/appkit-model-gateway
```

也可以使用：`pnpm add @dbx-tools/appkit-model-gateway`、`yarn add @dbx-tools/appkit-model-gateway`、`bun add @dbx-tools/appkit-model-gateway`

## README

# @dbx-tools/appkit-模范出道道

通过 OpenAI 响应、 OpenAI 聊天在 Databricks 工作空间中曝光模型 完成, Anthropic Messages, 嵌入, 以及 Codex 兼容 API. 这个 网关发现工作空间目录并选择兼容的数据砖 每个请求的路径.

## 选择嵌入式、前景式或服务模式

当模型路由属于已存在的应用程序时注册 AppKit 插件 . 运行 `dbx model-gateway` 用于本地工具所使用的前景回路端点. 使用 `dbx model-gateway service install` 当当地终点必须继续下去时 终点站关闭后.

## 注册 AppKit 插件

```ts
import { createApp, server } from "@databricks/appkit";
import { modelGateway } from "@dbx-tools/appkit-model-gateway";

await createApp({
  plugins: [modelGateway(), server()],
});
```

AppKit 挂载插件路由 `/api/model-gateway/v1/*`编辑 [@dbx-tools/cli (英语)](https://npmcn.com/package/cli/dbx-tools) 提供前景服务器构建, 当前用户服务管理,以及标准根兼容路径.

## 连接客户端

当一个工具期望 OpenAI 兼容的基础 URL 时使用独立的 CLI :

```sh
dbx model-gateway \
  --profile PRIMARY-PROFILE \
  --profile FALLBACK-PROFILE \
  --listen tcp://127.0.0.1:4000
```

简介按申报顺序进行。 模型发现和路由使用 第一个简介。 当一个推断请求收到 HTTP 429 时, 网关重试 相同的上游模型,通过下一个配置图,其工作空间是可用的. 冷却器由工作空间和模型 ID 共享,所以两个配置相同 工作空间不会绕过相同的限制。 报告重试间隔后 过期, 请求自动返回第一个配置 .

`Retry-After` 优先于 JSON `retry_after` 数值。 数据砖时 报告每个分钟的工作空间符号限制,但没有两个值,即网关 使用60秒冷却;其他429个响应使用15秒.

系统模型的首选路线是非准确的答复请求,包括: 代码交通,通过 `system.ai.*` AI 网关服务而非工作空间 服务端点。 Codex型号的弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出后弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹出弹 确切的终点 编号或 `system.ai.*` 名字总是赢.

配置客户端为 [http://127.0.0.1:4000/v1 (中文(简体) )](http://127.0.0.1:4000/v1)。用于嵌入式应用程序 路径,使用应用程序来源加 `/api/model-gateway/v1`。 。 。 .

网关支持:

-   OpenAI 回复和聊天补全.
-   Anthropic Messages. (原始内容存档于2018-09-27).
-   OpenAI-相容嵌入.
-   Codex模型发现和响应流量.

## 使用智能路由器

选择虚拟 `smart-router` 模式来自任何支持的聊天协议 :

```json
{
  "model": "smart-router",
  "input": "Refactor the authorization layer across the repository"
}
```

回来之前 `GET /v1/models`网关让人想起 `task_v3` 向数据砖请求能力 `/ai-gateway/routing/v1/routes:select`。虚拟模式仅在 该请求在有效身份和生活上取得成功 `system.ai.*` 候选人。 阳性探测器共用5分钟,同时探测器 组合为一个请求。 时立即返回 Stale 值 `@dbx-tools/cache` `refreshAfterWrite` 连接一个访问触发背景 刷新点 一个明确的推断请求跳过这个合成的飞行前,因为 它的真正路由选择已经是可用性检查.

推断一下,网关从Resolution输入中提取了捆绑的任务上下文, 聊天补全或Anthropic消息,纯文本,或通用JSON对象. 这个 不包括证书、工具计划和工具参数。 OpenAI 形状的请求 使用该 `codex` 智能路由器控制策略; Anthropic 信件使用 `claude`。 。 。 . 选中的路由必须匹配一个可兼容协议的在线 模特们 没有本地的分级或倒置选择器 .

一样 `smart-router` id 与 Resignation, Chat Professions, Anthropic 一起工作 信息 和 Codex 兼容的响应流量 。 嵌入需要一个 明确型号。 明确的具体模型和模范类标题继续 赢了.

智能路由器选择被固定在逻辑用户转弯时. 默认存储 使用 AppKit 软件 `CacheManager`,因此配置的 Lakebase/PostgreSQL 持久性是 复用过应用复制品. 供应 `smartRouterStore` 要使用另一个存储 执行进展情况 `get`编号 :`set` 合同,包括SQLite支持 适配器. 仅存储所选模型和有界限的路由元数据; 提示 答复则不然.

这个状态是TTL路由针,不是对话历史. 网关没有 读取 Mastra `PostgresStore`: 支持的聊天请求已携带便携式 与马斯特拉连接会排除其他聊天客户. AppKit 缓存持久性也比网关拥有的文件或第二个更可取 过期的表格,因为它已经处理进程局部再利用,项目范围 磁盘倒置,并配置了Lakebase/PostgreSQL存储. 消费者还是可以 当部署需要另一个后端时, 注入不同的存储 .

反应信头显示 选定的混凝土模型,返回路线模型, 带、缓存源和任何 `task_v3` 任务等级、服务等级或剖析器 状态不重写上游反应机构的模型身份.

通过通过 JSON 或文本文件来选择不启动服务器的模型,或者 `-` 用于标准输入 :

```sh
dbx model-gateway --profile PROFILE --select-model-from request.json
```

## 发现模式

```ts
import { createModelGatewayClient } from "@dbx-tools/shared-model-gateway";

const client = createModelGatewayClient({ baseUrl: "http://127.0.0.1:4000/" });
const models = await client.listModels({ search: "sonnet" });
```

使用 `{ codex: true }` 当一个 Codex 客户端需要它的本地目录形状时.

## 请求兼容性

当选定模式支持时, 请求保留在本地流路径上 客户协议 。 当协议不同时,网关会翻译请求和 通过 Vercel AI SDK 消息进行响应,同时保留文本,功能工具, 推理、使用、结束原因、流出和取消。 嵌入使用一个 直接 Databricks 嵌入路由而不翻译.

该网关拒绝它无法保存的状态响应选项,包括 `previous_response_id`, (中文(简体) ), `store: true`,以及 `background: true`。 。 。 .

明确 `temperature: null` 省略。 对于已发布 Databricks 模型 模型.dev 元数据,不支持的温度被省略和支持的值 被夹在 Databricks 上 `0..2` 范围。 未知的自定义端点保持有限制 数值温度不变.

见 [请求参数翻译](https://npmcn.com/docs/model-gateway.md#understand-request-parameter-translation) 温度和推理流.

网页搜索和自定义工具请求仅在发现时使用直接路径 模型广告 所需的能力。 OpenAI 模型列表 `capabilities.web_search` 和代码 `supports_search_tool` 使用同样的 发现值.

## 配置代码

`GET /v1/models` 当请求带有时, 包括编码元数据 `Originator` 包含 `codex` (对大小写不敏感),或非空白 `client_version` 查询参数。 Codex sults 更喜欢完全合格的 Databricks 软件 模式服务名称.

添加 `metadata=true` 或 Codex 请求包含 每个模型上的可选 dbx 工具元数据对象。 其耐久性和评级领域 每个都暴露出一个可分级的根分数加上嵌入式的测量或源排名. 默认响应会省略字段, 因此已有的 OpenAI 和 Codex 客户端会保留 他们的当前有效载荷形状.

Codex将提供者模型与其捆绑的目录合并. 网关保留a 单独提供商的优先范围如此捆绑的建议保持不变, 然后将智能路由器放在Databricks模型列表之前. 特定代码模型 命令将 GPT 模型放在更古老的版本之前, 以及更新的家族版本 . Databricks GPT 标签包括 `Databricks` 前缀使其保持区分 在 Codex 应用其紧凑的标签格式后从捆绑的GBT 模型中取出.

指向编码提供者 :

```text
http://127.0.0.1:4000/v1
```

使用 `wire_api = "responses"` 财务报告和审定财务报表 `supports_websockets = false`。 。 。 .

## 配置示范政策

`model` 财务报告和审定财务报表 `modelClass` 设置默认选择. `preferSystemModels` 选择 `system.ai.*` AI网关服务为不准确的合格请求服务. 准确 服务终点或 `system.ai.*` 名称仍然胜利.

智能路由器默认为 `smartRouter: "auto"` 并只在 能力探测器成功 设定 `smartRouter: "true"` 进行模型发现 当路由器不可用时失败,或者 `smartRouter: "false"` 来禁用它. 配置 `smartRouterTimeoutMs`, (中文(简体) ), `smartRouterContextTokenBudget`, (中文(简体) ), `smartRouterProbeTtlMs`, (中文(简体) ), `smartRouterProbeRefreshIntervalMs`,以及 `smartRouterRouteTtlSeconds` 调奏 运输、上下文、请求驱动的探测器过期、背景探测器刷新以及 转动行为。 失败的真实选择立即失效 阳性探测器.

使用 `overrides` 当工作空间元数据必须针对特定模型进行更正时. 例如, 禁用所选网关路由的已公告的能力 无法使用 :

```ts
import { modelGateway } from "@dbx-tools/appkit-model-gateway";

modelGateway({
  overrides: [
    {
      model: "databricks-gpt-example",
      capabilities: { webSearch: false },
    },
  ],
});
```

重叠会影响出行道和OpenAI和Codex模型目录.

## 软件包 API

-   `modelGateway()` 注册 AppKit 插件.
-   `gateway` 处理协议中性网关请求.
-   `registry` 发现并解决工作空间模型.
-   `router` 从模型能力中选择一个相容的路径.
-   `smartRouter` 构建任务背景、探测可用性和呼叫 `task_v3`。 。 。 .
-   `transport` 向 Databricks 模型 API 发送请求 .

## 常见问题

### @dbx-tools/appkit-model-gateway 是什么？

Databricks OpenAI、Anthropic、Codex和AI Gateway API的 AppKit 模型网关

### 如何安装 @dbx-tools/appkit-model-gateway？

在项目目录运行 npm install @dbx-tools/appkit-model-gateway，或使用 pnpm add / yarn add / bun add。

### @dbx-tools/appkit-model-gateway 支持 TypeScript 吗？

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

### @dbx-tools/appkit-model-gateway 支持 ESM 还是 CommonJS？

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

### @dbx-tools/appkit-model-gateway 可以商用吗？

@dbx-tools/appkit-model-gateway 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dbx-tools/appkit-model-gateway 的下载量有多少？

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

### @dbx-tools/appkit-model-gateway 还在维护吗？

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