# @benchsdk/client 中文文档

规范地址：https://npmcn.com/package/%40benchsdk/client/

版本：0\.5\.12
npm 元数据更新时间：2026-11-04T00:33:54.578Z
中文译文更新时间：2026-11-07T22:02:38.885Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40benchsdk/client
原文对照：https://npmcn.com/package/%40benchsdk/client/?lang=original
项目主页：https://www.computesdk.com/
源码仓库：https://github.com/computesdk/benchmarks

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

- 包体积（解压后）：19.1 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- 首次发布：2026-07-27T20:11:01.775Z
- 最新版本发布：2026-11-04T00:33:54.275Z
- 近 30 天下载量：5965（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

计算SDK基准管弦乐器的客户和工人助手

## 安装

```sh
npm install @benchsdk/client
```

也可以使用：`pnpm add @benchsdk/client`、`yarn add @benchsdk/client`、`bun add @benchsdk/client`

## README

# @ benchsdk/ 客户端

> **背相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.** `@benchsdk/client` 全部再出口 `@benchsdk/runner` 表面和保存遗产 `createBenchmarkClient().runWorker(options)` 拼写。 新项目应从 `@benchsdk/runner` 作者/操作助手或 `@benchsdk/api` 用于原始REST类型.

计算SDK基准管弦乐器的客户和工人助手.

此套件与平台拥有的基准/运行/参与者/工人API进行会谈. 它没有薄荷罐头跑步、工人、尝试、事件或任务标识。 工人要求平台分配的工作,在指定范围内执行任务指数,并发送 `task_results` 分批返回平台.

## 安装

```bash
npm install @benchsdk/client
```

> 高级基准作者`defineBenchmarkConfig` 编号 : `defineTask` 财务报告和审定财务报表 本地管弦乐手) [`@benchsdk/runner`](https://npmcn.com/package/%40benchsdk/benchsdk-runner)此包是 REST 传输 + 只有工人发动机.

## 认证

`createBenchmarkClient` 需要平台 API 键或 OAuth 令牌。 提供 `apiKey`编号 :`token` 直接或设置 `BENCHMARKS_PLATFORM_API_KEY` 或者说 `BENCHMARKS_PLATFORM_TOKEN` 在环境中.

## 运行一个工作者

```ts
import { createBenchmarkClient } from '@benchsdk/client';
import { compute } from 'computesdk';

const client = createBenchmarkClient({
  apiKey: process.env.BENCHMARKS_PLATFORM_API_KEY,
});

// `task` is a raw function; declare named steps imperatively via `step(...)`,
// so values flow between steps with closures and cleanup runs in a `finally`.
const { assignment, records } = await client.runWorker({
  benchmarkSlug: 'scale',
  runId: process.env.BENCHMARK_RUN_ID!,
  participantSlug: 'e2b',
  processKind: 'container',
  processKey: process.env.HOSTNAME,
  concurrency: 100,
  task: async ({ assignment, step }) => {
    const sandbox = await step('create', () =>
      compute.sandbox.create({ provider: assignment.provider ?? 'e2b' }),
    );
    try {
      await step('readiness', () => sandbox.runCommand('true'), { readiness: 'internal' });
      await step('exec.first-command', () => sandbox.runCommand('node -v'));
      // A `readiness: 'poll'` step reports active concurrency and waits until
      // the platform reports the participant's step is ready (a barrier).
      await step('pause', () => {}, { readiness: 'poll' });
      return { sandboxId: sandbox.id };
    } finally {
      await step('destroy', () => sandbox.destroy());
    }
  },
});
```

`client.runWorker(...)` 对参与者的下一个待定平台任务提出索赔。 如果没有工作,它会返回 `{ assignment: null, records: [] }`。 。 。 .

任务结果被分批冲入平台,默认为1000个记录. 设定 `batchSize` sDK验证每批5000个记录的平台限制。 工人还默认每隔30秒冲出部分批次 `flushIntervalMs`,在最后完成或关闭时总是冲出待决记录.

## 创建平台运行

```ts
import { createBenchmarkClient } from '@benchsdk/client';

const client = createBenchmarkClient({
  apiKey: process.env.BENCHMARKS_PLATFORM_API_KEY,
});

await client.upsertBenchmark('scale', {
  name: 'Scale',
  config: { timeoutMs: 120_000 },
});

const { run } = await client.createRun('scale', {
  name: '10k smoke',
  totalTasks: 10_000,
  workerCount: 20,
  participants: ['e2b', 'modal'],
  config: { timeoutMs: 120_000 },
});

await client.planWorkers('scale', run.id, 'e2b');
await client.planWorkers('scale', run.id, 'modal');

console.log(run.id);
```

工人必须事先计划好 `client.runWorker(...)` 可要求指派任务.

## API 密码

### 工人发动机

```ts
client.runWorker(options)
```

这个 `task` 函数接收 :

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `assignment` | `BenchmarkAssignment` | 该工人的平台拥有的任务 |
| `taskIndex` | `number` | 基准运行范围内的决定因素任务索引 |
| `step` | `(name, fn, options?) => Promise<R>` | 运行 `fn` 并记录其时间/结果 |

如果任务返回 JSON 对象, 它将作为任务结果存储 `data`。 。 。 .

`step(name, fn, options)` 支持通过 `options`数字 :

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `reportConcurrency` | `boolean?` | 在工人心跳中包含此步骤的主动数 。 默认为 `true` |
| `concurrency` | `number?` | 这个步骤的每个工人目标. 工人货币/分配指标的默认值 |
| `readiness` | `'poll' | 'internal'?` | 准备状态协调模式。 默认为 `'internal'`启用 `'poll'` 用于平台协调障碍步骤 |
| `readyPollIntervalMs` | `number?` | 等待时的投票间隔 。 默认为 `1000` |
| `readyTimeoutMs` | `number?` | 最大待机时间 |

### 低级客户端

```ts
client.updateBenchmark(benchmarkSlug, input)
client.updateRun(benchmarkSlug, runId, input)
client.updateParticipant(benchmarkSlug, runId, participantSlug, input)
client.planWorkers(benchmarkSlug, runId, participantSlug)
client.getWorker(benchmarkSlug, runId, workerId)
client.updateWorker(benchmarkSlug, runId, workerId, input)
client.claimWorker(benchmarkSlug, runId, participantSlug, { processKind, processKey })
client.sendTaskResults({ benchmarkSlug, runId, workerId, attemptId, sequenceNumber, isFinal, records })
client.uploadWorkerArtifact(benchmarkSlug, runId, workerId, {
  attemptId,
  kind: 'log',
  name: 'coordinator.log',
  contentType: 'text/plain; charset=utf-8',
  body: logText,
})
client.heartbeatWorker(benchmarkSlug, runId, workerId, {
  attemptId,
  currentStep: 'pause',
  concurrency: [{ step: 'pause', active: 100, target: 100 }],
})
client.getRunProgress(benchmarkSlug, runId)
client.getBenchmarkResults(benchmarkSlug, { limit })
client.getRunResults(benchmarkSlug, runId)
client.getRunTaskResults(benchmarkSlug, runId, { bucketSize, failureLimit })
client.getRunTimeline(benchmarkSlug, runId, { bucketMs })
client.getRunImports(benchmarkSlug, runId)
client.completeWorker(benchmarkSlug, runId, workerId, attemptId)
client.failWorker(benchmarkSlug, runId, workerId, attemptId, error)
client.runWorker(options)
```

不适合的习惯协调员 `runWorker`,使用最佳记者包装:

```ts
const reporter = await BenchmarkReporter.claim({
  benchmarkSlug: 'scale',
  runId,
  participantSlug: 'e2b',
  processKind: 'container',
  processKey: instanceId,
});

reporter?.setProgress({ done, inFlight, errors });
reporter?.recordResult(record);
await reporter?.waitForStepReady({ step: 'ready.barrier', timeoutMs: 15 * 60_000 });
await reporter?.uploadArtifact({
  kind: 'log',
  name: 'coordinator.log',
  contentType: 'text/plain; charset=utf-8',
  body: logText,
});
await reporter?.finish(false);
```

`BenchmarkReporter` 吞入平台遥测故障,用于索赔,心跳,结果冲洗,文物上传,并完成通话. 即使暂时没有报告,基准工作也可以继续进行.

对于 `runWorker`,使用时 `onFinish` 在最后任务结果被冲出之后,并在工人尝试完成或失败之前,上传一次工人级日志:

```ts
client.runWorker({
  benchmarkSlug: 'scale',
  runId,
  participantSlug: 'e2b',
  task,
  onFinish: async ({ uploadArtifact }) => {
    await uploadArtifact({
      kind: 'log',
      name: 'coordinator.log',
      contentType: 'text/plain; charset=utf-8',
      body: logText,
    });
  },
});
```

对于协调卫生文物,抽样系统衡量标准:

```ts
const metrics = createSystemMetricsCollector();
const samples = [await metrics.sample()];
metrics.stop();
```

`client.getRunProgress(...)` 返回运行摘要加每个参与者的工人、任务和货币进度 :

```ts
const progress = await client.getRunProgress('scale', runId);

console.log(progress.summary.status);
console.log(progress.summary.participants);

const participant = progress.participants.find((item) => item.slug === 'e2b');
console.log(participant?.status);
console.log(participant?.workers);
console.log(participant?.tasks.completionRatio);
console.log(participant?.concurrency.find((item) => item.step === 'pause')?.ready);
```

大多数工人应该使用 `client.runWorker(...)`。 。 。 .

## 任务结果形状

```json
{
  "taskIndex": 0,
  "status": "success",
  "startedAt": "2026-06-03T00:00:00.000Z",
  "completedAt": "2026-06-03T00:00:01.000Z",
  "latencyMs": 1000,
  "steps": [
    { "name": "create", "status": "success", "startedAt": "...", "completedAt": "...", "latencyMs": 700 },
    { "name": "exec.first-command", "status": "success", "startedAt": "...", "completedAt": "...", "latencyMs": 120 },
    { "name": "destroy", "status": "success", "startedAt": "...", "completedAt": "...", "latencyMs": 180 }
  ],
  "data": {
    "sandboxId": "..."
  }
}
```

## 常见问题

### @benchsdk/client 是什么？

计算SDK基准管弦乐器的客户和工人助手

### 如何安装 @benchsdk/client？

在项目目录运行 npm install @benchsdk/client，或使用 pnpm add / yarn add / bun add。

### @benchsdk/client 支持 TypeScript 吗？

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

### @benchsdk/client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @benchsdk/client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @benchsdk/client 可以商用吗？

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

### @benchsdk/client 的下载量有多少？

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

### @benchsdk/client 还在维护吗？

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