# @dbx-tools/model 中文文档

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

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

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

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

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

- 包体积（解压后）：2.5 MB，87 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：12 个
- 首次发布：2026-06-22T07:16:27.500Z
- 最新版本发布：2026-11-10T19:19:04.052Z
- 近 30 天下载量：10806（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：404（近 12 个月 404 个）

## 中文简介

工作空间感知数据砖模型

## 安装

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

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

## README

# @dbx-工具/型号

解析一个松散的模型请求, 例如 `"claude sonnet"` 或者说 `"chat-fast"` 改为 混凝土 Databricks Model 正在工作空间中服务端点。 客户名单 `/serving-endpoints`,缓存并丰富 目录,将终点按能力分类,模糊匹配名称和倒数 回到一个小的静态地层 当活的目录没有.

## 快开始

```ts
import { createModelClient } from "@dbx-tools/model";

const models = await createModelClient();
const selected = await models.resolveModel({ explicit: "sonnet" });
console.log(selected.modelId);
```

默认情况下,非精确路径会请求工作空间服务端点, 如 `databricks-gpt-5-6-sol`。通过匹配选择路径 `system.ai.*` AI 网关服务:

```ts
const models = await createModelClient({ preferSystemModels: true });
const route = await models.route({ explicit: "gpt-5-6-sol", protocol: "responses" });
// route.modelId === "system.ai.gpt-5-6-sol"
```

准确的终点 ID 或 准确 `system.ai.*` 名字总是赢,不管这个 优先选择.

浏览器安全请求/结果分类和终点分类类型 [@dbx-工具/共享型号](https://npmcn.com/package/shared/model)。 。 。 .

软件包 :

-   通过 SDK 列出 Databricks 模型服务端点并使其正常化 变成一个稳定的简易形状,包含 TypeScript 拥有的家族和推理努力 元数据.
-   将端点分类为聊天思维、聊天平衡、聊天快和 采用基础模型 API 分数和家庭heuristics的嵌入类.
-   决定松散的用户输入, 如 `"sonnet"` 或者说 `"chat fast"` 给水泥 端点为 id.
-   支持类天花板,这样呼叫者可以要求一个能力波段,而不需要 不小心升级到更大的模型.
-   支助 `requiresTools` 过滤此调用者只选择 端点被验证为完整的函数调用和结果回放回路.
-   支持结构化输出过滤和质量、速度或成本优化; 速度敏感选择在比较前倾向于非合理终点 现场剖面速度得分.
-   每个工作空间主机通过 AppKit 缓存工具丰富目录, 并重新列出一次在解决错误上,所以新部署的模型仍然解决.
-   构建调用者的每个请求认证标题引用 URL 和 薄荷 发布自己的 OpenAI 形状的 HTTP 请求 .
-   提供由建筑生成的退休,反应,图像输入,应用patch, 网络搜索、推理、工具调用、结构化输出、温度支持、, 延缓性、人偏好评级、ITPM、OTPM、QPH和象征性价格元数据 通过缓存的进程中的搜索。 Databricks 文档以 (原始内容存档于2018-10-21). model.dev和modelparams.dev快照. 将延迟元数据使用标准化 麻省理工学院有执照 `vicaroai/tokens-per-second` 数据砖和 这些目录没有提供每个模型的延迟领域。 评分使用每张CC BY 4.0 利马纳 `latest` parquet配置通过Hugging Face发布. Token 价格只来自 Databricks 定价页面, 承诺的回扣 保持刷新和运行时间 启动离线安全.
-   为本地工具和已退化的工作空间提供一个小的静态后退地板 访问.

## 使用 AppKit 模式服务

当您已经知道端点时, 使用本地 AppKit 模式服务插件 别名 它给你认证的引用/流道, OBO 执行、生成端点类型、请求- 机构过滤和前端 钩子.

当困难部分选择了 结束点 :

-   解析人类的松散输入,例如 `"sonnet"` 或者说 `"fast"` 对抗现场 工作空间目录.
-   组端点进入能力类 `chat-thinking`, (中文(简体) ), `chat-balanced`, (中文(简体) ), `chat-fast`,以及 `embedding`。 。 。 .
-   强制设置等级天花板,使呼叫者可以降解为更小的型号,而不使用 升级到更大的一个.
-   从已缓存,浓缩的端点列表中构建模型拾取器并调试路径.
-   在编目时保持本地代理商和CLI使用静态回落 无法访问 .

## 路线请求

```ts
import { createModelClient } from "@dbx-tools/model";

const models = await createModelClient({
  auth: { profile: "DEFAULT" },
  cacheTtlMs: 60_000,
});

const selected = await models.resolveModel({ explicit: "gpt" });
const route = await models.route({
  explicit: selected.modelId,
  protocol: "responses",
});

const response = await fetch(route.url, {
  method: "POST",
  headers: { ...route.headers, "content-type": "application/json" },
  body: JSON.stringify({ model: route.modelId, input: "Hello" }),
});
```

`createModelClient()` 是节点客户端使用的可移植的认证背面. 它列出并规范端点,缓存一个 每个主机的目录,工作空间ID,和主机,刷新一次 未匹配的模糊请求, 解决路径, 返回完整认证 头条, 曝光配置文件, 并返回软件包生成的元数据 。 内容 便携式 `@dbx-tools/model/python` 切入点不包括 AppKit 目录 包装同时重用同样的纯正的排名和政策执行.

## 选择一个模式

```ts
import { createWorkspaceClient } from "@databricks/appkit";
import { resolve } from "@dbx-tools/model";

const client = createWorkspaceClient();
const host = String(await client.config.getHost());

const selected = await resolve.selectModel(client, host, {
  explicit: "claude sonnet",
});

console.log(selected.modelId, selected.source);
```

`selectModel()` 是代理和CLI的高级助手。 它读取现场 目录,当有明确字符串时应用模糊匹配,然后 返回单个 `modelId` 加上一个源标签 解释为什么那个终点获胜. 设定 `liveOnly: true` 对于必须选择 排名最高的可用终点,不得跌入 当目录不匹配时, 离线静态 id . 没有明确的ID或类,自动选择更倾向于排名最高的 活生生的GPT家庭成员,再倒回排名最高的活聊模式.

这个 `source` 标签用于日志和调试 UI 。 它明确区分 匹配基于类选择、环境默认和倒置结果, 因此,操作者可以判断请求是否使用了预期的示范政策.

## 构建一个取模器

```ts
import { resolve } from "@dbx-tools/model";

const ranked = await resolve.searchModels(client, host, {
  search: "opus",
  modelClass: "chat-thinking",
  requiresTools: true,
  limit: 5,
});
```

使用 `searchModels()` 用于 UI 拾取器和调试路径。 它返回排序模型 使用相同的模糊阈值,并 类天花板逻辑为 `selectModel()`分类,模糊的分数, 家庭转换顺序和变体偏好在此直接执行 软件包,不需要本地绑定.

当呼叫者需要特定的运行时间形状时,在排序前先过滤. 譬如说, 选择最好的 1 024 维嵌入端点 :

```ts
const [embedding] = await resolve.searchModels(client, host, {
  modelClass: "embedding",
  dimension: 1024,
  limit: 1,
});
```

搜索过滤器 : 使用 `name` 确切的终点, `search` 用于模糊 名称和标签匹配, `modelClass` 班级意识排名, `task` 用于 确切的任务, `dimension` 或者说 `minDimension`编号 :`maxDimension` 用于嵌入 形状, `reasoningEffort` 用于支持的推理水平,以及 `requiresTools` 用于完整的工具调用支持.

## 与持有的目录有关的工作

当您已经有结束点摘要时, 请使用纯解析器函数 `resolve` 财务报告和审定财务报表 `modelCatalog` 没有另一个工作空间呼叫 :

```ts
import { modelCatalog, resolve } from "@dbx-tools/model";

const endpoints = await modelCatalog.listServingEndpoints(client, host);
const ranked = resolve.lookupModels(endpoints, { search: "sonnet", limit: 3 });
const picked = resolve.resolveModel(endpoints, {
  explicit: "claude sonnet",
  modelClass: "chat-balanced",
  requiresTools: true,
});
```

阶级充当天花板. `chat-balanced` 可能会回到 `chat-fast`不过 不升级为 `chat-thinking`。嵌入的终点只考虑 当请求的类是 `embedding`。 。 。 .

## 列表和缓存服务端点

```ts
import { modelCatalog } from "@dbx-tools/model";

const endpoints = await modelCatalog.listServingEndpoints(client, host, {
  ttlMs: 5 * 60_000,
});

const raw = await modelCatalog.listServingEndpointsUncached(client);
await modelCatalog.clearServingEndpointsCache(host);
```

`listServingEndpoints()` 使用共享内存- 第一模式项目缓存, 丰富 带有分类和嵌入维度的终点,并通过 工作空间主机和信任的证书身份。 如果刷新失败, 可以返回 磁盘上最后的已知好值. `listServingEndpointsUncached()` 实值 用于仅需要 SDK 响应而不需要缓存的脚本 依赖性.

## 模糊解析端点名称

```ts
const matches = serving.searchServingEndpoints("claude sonnet", endpoints, {
  threshold: 0.35,
});

const endpointName = serving.resolveModelId("sonnet", endpoints);
```

模糊匹配是服务器的故意关切,因为它取决于直播 工作空间目录并可能重新列出误差。 在需要调用时禁用 确切的终点标识.

## 决心反对可能过时的目录

```ts
const resolved = await resolve.rankModelIdLive((force) => loadCatalogue(force), "opus");
```

`rankModelIdLive()` 符合你已经持有的目录 在错过时, 重新装入一次 `force` 在放弃之前,所以一个模型 部署在您的缓存之后 温取还解而未复出. 你提供装货机,所以卡通 保单留在你的: `listServingEndpoints` 及其共享项目缓存, 一个平原 字段,或测试双倍. `rankModelId()` 是纯正的形态结束 一张相片 与 `serving.resolveModelId`,它打破相等的比分 按类别,然后版本,所以 `"opus"` 首选 `opus-5` 结束 `opus-4-7`。 。 。 .

## 直接调用终点

```ts
import { invoke } from "@dbx-tools/model";

const response = await fetch(invoke.invocationsUrl(host, endpointId), {
  method: "POST",
  headers: { ...(await invoke.authHeaders(client)), "content-type": "application/json" },
  body: JSON.stringify({ messages }),
});
```

使用 `invoke` 当您需要针对服务终点发布您自己的请求时 带有OpenAI形状的车体,例如来自代理车体,通过路由,或 流媒体客户端,而不是 SDK 键入 `servingEndpoints.query`。薄荷 `authHeaders()` 每个请求: SDK 当其接近时刷新下个符号 过期,所以你从来没有跟踪 一生自己.

此 repo 会谈的每个服务路径都是常数, 并有匹配的 URL 构建器 : `INVOCATIONS_SUFFIX` 编号 : `invocationsUrl()`, (中文(简体) ), `RESPONSES_PATH` 编号 : `responsesUrl()`, (中文(简体) ), `OPEN_RESPONSES_PATH` 编号 : `openResponsesUrl()`,以及 `CHAT_COMPLETIONS_PATH` 编号 : `chatCompletionsUrl()`。导入一个而不是写入一个 `/serving-endpoints/...` 消费者的字面意思:模型可以接受的路径是 a 模型的财产(见 `isResponsesOnly()` 财务报告和审定财务报表 `responsesUpstreamUrl()`, (中文(简体) ), 所以一个包中的硬码字符串在路由时会悄悄地相去甚远 变化. `isResponsesOnly()` 涵盖 Codex 和 GBT 5.4+ 端点, 拒绝 包含工具的聊天补全,同时将GPT-OSS保留在其支持的聊天路径上. TypeScript 助手应用此策略, 所以每个节点消费者共享一个版本 不装入本地库的阈值.

## 读取已公布的模型元数据

```ts
import { metadata } from "@dbx-tools/model";

const capabilities = metadata.modelCapabilitiesFor("databricks-gpt-5-4");
const latencyScore = metadata.modelLatencyScoreFor("databricks-gpt-6-luna");
const rating = metadata.modelRatingFor("databricks-gpt-6-sol");
const limits = metadata.modelRateLimitsFor("gpt-5.4");
const prices = metadata.modelTokenPricesFor("system.ai.gpt-5-4");
const estimate = metadata.estimateModelTokenPrice(
  "databricks-gpt-5-4",
  { inputTokens: 1_000_000, outputTokens: 500_000 },
  { condition: "short-context", usdPerDbu: 0.07 },
);
const status = metadata.modelStatusFor("system.ai.gemini-2-5-pro");

latencyScore?.score;
latencyScore?.measurements.outputTokensPerSecond;
rating?.score;
rating?.rankings.text_style_control?.lowerBound;
```

包船承诺根据Databricks文件制作快照 公共示范目录 `bun run --filter '@dbx-tools/model' metadata`。 。 。 . 运行时调用正常端点、显示、基础模型和提供者 身份被记录在记忆片和地图中 他们不获取文档或 基准. `modelMetadataFor()` 返回状态、能力、正常化 随机元数据、Arena评分、公布的限值和Databricks DBU率 百万个输入、输出、缓存读取和缓存写出一个字符串的符号 或者说 `ServingEndpointSummary`。 。 。 .

`latencyScore.score` 是基准的中位数 正常反应时间以毫秒计,因此较低值更快. `latencyScore.measurements` 将中位数时间保留到第一个符号,中位数输出 吞吐量、成功运行计数、正常完成长度和测量 时间. `rating.score` 是一个0-100 平均百分位 在整个模型的可用 LMArena 配置, 因此, 更高的值即使在源大小上更好 不同之处. `rating.rankings` 保留每个来源的分数, 下和上信任度 界限、级别、公布日期、优先票数和差额或代理人 观察和会话算数.

当 Arena 列出多重推理- 努力时 变体,每个配置保持其最高分的总行. 更喜欢看 精确的模型匹配,否则继承自该模型中最新的测量模型 同样的家庭和变体。 消费者可以直接排序或应用根分数 他们自己的自信,新鲜度, 和覆盖政策 对于嵌入的价值观. 用适用的 Databricks SKU 价格乘以代号费率计算得出 货币成本.

原生的网络搜索能力始于所记录的模型集. 再见 在同一个托管的基金会-模型家庭中的版本通过 `versionTuple`. GPT-OSS 模型从不继承本地网络搜索. 自定义和 外部端点名称也不继承,因为这些名称中的位数不是 作为模型版本处理.

模型网关可以覆盖已发现的路由和模型 目录。 使用该网关覆盖来禁用工作空间时的网络搜索 路由并不支持元数据否则会做广告的能力.

## 使用静态倒置

```ts
import { classes, fallback } from "@dbx-tools/model";
import { model } from "@dbx-tools/shared-model";

const cls = classes.parseModelClass("chat-fast") ?? model.ModelClass.ChatFast;
const modelId = fallback.modelForClass(cls);
```

倒计时地板让代理和当地脚本在 工作空间不能列出终点。 优先生产活性目录分辨率 政策决定。 仅在无活性解析度时使用后退 .

## 模块

-   `resolve` - 高级别 `selectModel`,类型脚本排序搜索,以及 目录持有的解析器函数.
-   `serving` - 数据砖服务端点列表、缓存管理、模糊 搜索,以及端点标识解析.
-   `invoke` - 服务路径常数、URL构建和每个请求认证 hTTP上呼叫端点的信头 .
-   `metadata` - 建筑产生的退休、能力、耐久性、评级, 速率限制,以及带有缓存的正态外观的象征性价格快照.
-   `modelClient` - 便携式认证意识发现、选择、路由、, 剖面图和元数据外观.
-   `classes` - 模范级的解析、订货和最高级的帮手.
-   `policy` - 家庭、服务程序、工具、推理政策.
-   `fallback` - 静态回落型号,每类.

AppKit- Mastra 集成通过 [@dbx-tools/appkit-mastra (英语)](https://npmcn.com/package/%40dbx-tools/appkit-mastra)。 。 。 .

## 常见问题

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

工作空间感知数据砖模型

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

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

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

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

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

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

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

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

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

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

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

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