# @browserstack/ai-sdk 中文文档

规范地址：https://npmcn.com/package/%40browserstack/ai-sdk/

版本：1\.0\.0-beta\.22
npm 元数据更新时间：2026-10-06T11:28:45.075Z
中文译文更新时间：2026-11-08T16:29:26.180Z
软件包许可：SEE LICENSE IN LICENSE\.md

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

原始 npm 页面：https://www.npmjs.com/package/%40browserstack/ai-sdk
原文对照：https://npmcn.com/package/%40browserstack/ai-sdk/?lang=original
项目主页：https://evals.browserstack.com/docs/

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

- 包体积（解压后）：21.7 MB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- 首次发布：2026-04-22T08:39:27.655Z
- 最新版本发布：2026-10-06T11:28:44.875Z
- 近 30 天下载量：12834（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

浏览器Stack AI SDK for Node.js — LLM 的可观察性、可评价性和可追踪性

## 安装

```sh
npm install @browserstack/ai-sdk
```

也可以使用：`pnpm add @browserstack/ai-sdk`、`yarn add @browserstack/ai-sdk`、`bun add @browserstack/ai-sdk`

## README

# @ 浏览器tack/ai- sdk

一个TypeScript/NodeJS SDK,用于AI应用的可观察性,测试性,以及评价性.

> **需要节点.js QQ 18.**

## 安装

```bash
npm install @browserstack/ai-sdk@beta
```

## 快速启动

```typescript
import { AISDK } from '@browserstack/ai-sdk';

// Initialize the client
const client = new AISDK({
  publicKey: 'your-public-key',
  secretKey: 'your-secret-key',
});

// Create a trace
const trace = client.trace({
  name: 'user_login_flow',
  metadata: {
    testSuite: 'authentication_tests',
    testFile: 'auth.test.js',
  },
  tags: ['auth', 'critical'],
});

// Create spans
const loginSpan = trace.span({
  name: 'navigate_to_login',
  input: { url: '/login' }
});

loginSpan.end({
  output: { pageLoaded: true, loadTime: 250 }
});

// Create events
trace.event({
  name: 'assertion_check',
  metadata: {
    assertion: 'Login button should be visible',
    passed: true,
    expected: 'button visible',
    actual: 'button visible'
  }
});

// Cleanup
await client.flushAsync();
await client.shutdownAsync();
```

## 自动仪器

自动跟踪 LLM 调用而不修改代码 :

```bash
node --require @browserstack/ai-sdk/instrument app.js
```

## 配置

客户端可以使用环境变量或构建器选项进行配置:

### 环境变量

```bash
AISDK_PUBLIC_KEY=your_public_key
AISDK_SECRET_KEY=your_secret_key
```

### 内存和后压

SDK在你的通话和成功发送之间 持有追踪数据. 当摄取缓慢或失败时,所持有的数据以字节预算为界—— 一旦预算达到 SDK 留下最古老的痕迹而不是增长 直到过程被杀死.

| 变量 | 默认 | 它控制着什么 |
| --- | --- | --- |
| `AISDK_MAX_HELD_BYTES` | `104857600` (100甲基溴) | 整个队列和飞行请求中的总估计字节. **需要换个记忆天花板时 换一个把手.** |
| `AISDK_MAX_QUEUE_SIZE` | `1000` | 交货前持有的物品。 独立封顶——以捆绑者为准先取胜. |
| `AISDK_MAX_SOCKETS` | `30` | 连接池大小 . |
| `AISDK_BATCH_SIZE` | `15` | 每项请求的项目. |
| `AISDK_BATCH_TIMEOUT_MS` | `5000` | 最长时间的部分批次等待 才被发送. |
| `AISDK_MAX_RETRIES` | `3` | 尝试失败后进行报复,所以 **总尝试4次**。 。 。 . |
| `AISDK_REQUEST_TIMEOUT_MS` | `30000` | 请求超时. `0` 完全禁用它 . |

**放大你的容器.** `AISDK_MAX_HELD_BYTES` 限制 SDK 的 _跟踪有效载荷 字节_,而不是过程。 期望真正的RSS大约 **1.8x 预算** a 包括: 持续失败负载测试针对100 MB 默认值的平分为~180 MB. 在您申请的足迹上至少2x的预算.

一半的预算用于飞行请求 一半用于排队 所以 短暂的减速被吸收而不是放出: 排队的项目仍然可以交付 当终点恢复时,飞行中点被固定,直到返回 结束.

**设置普通字节数 .** 后缀没有解析—— `AISDK_MAX_HELD_BYTES=100MB` 读作 **100 字节**,而不是100兆字节,以及 `1e6` 读作1。 以下数值 64 KB 被拒绝使用 `[CONFIG_REJECTED]` 线条并使用默认值.

### 扩展属性限制

OpenTeleometry 默认为每段128个属性, 一个请求的广告 许多工具(或长的代理循环)可以接近. SDK提高这个上限 改为 `10000` 默认情况下——对无限制生产者的后援,而不是 负载后卫.

| 变量 | 它控制着什么 |
| --- | --- |
| `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` | 设定为数字, 使用您自己的跨度属性计数限制, 而不是 SDK 的默认值 . |
| `OTEL_ATTRIBUTE_COUNT_LIMIT` | 相同的覆被; OpenTeleometry 的通称(非 span- specific)变量, 当上面的一个未设置时读取 . |

### 读取日志

四行默认打印, 无 `AISDK_DEBUG`因为他们的意思是追踪 数据正在被丢弃。 每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分 `suppressed=N` 为了它所代表的事件.

| 线条 | 含义 | 怎么办 |
| --- | --- | --- |
| `[BUDGET_SHED]` | 字节预算已经达到;最古老的痕迹已经消失. | 摄取不相续. 首先检查终点健康——增加预算只会拖延. |
| `[QUEUE_OVERFLOW]` | 物品上限已经达到. | 提升 `AISDK_MAX_QUEUE_SIZE`,或者检查终点健康. |
| `[INFLIGHT_CAP]` | 由于飞行中的字节在天花板上,所以调度暂停. | 正常后压. 持续的外观意味着摄入量退化. |
| `[DROP]` | 有一批货物在用完复试后被丢弃. | 交货从未确认。 数据可能已经到达服务器 `X-Batch-Id` 让摄取去除再试的批量——所以把这当作未经证实的,而不是某些损失. |

其他一切,包括按要求进行的诊断 `AISDK_DEBUG=true`。 。 。 .

### 构造选项

```typescript
const client = new AISDK({
  publicKey: 'your_public_key',
  secretKey: 'your_secret_key',
  environment: 'production',
  flushAt: 20,
  flushInterval: 10000,
});
```

## 常见问题

### @browserstack/ai-sdk 是什么？

浏览器Stack AI SDK for Node\.js — LLM 的可观察性、可评价性和可追踪性

### 如何安装 @browserstack/ai-sdk？

在项目目录运行 npm install @browserstack/ai-sdk，或使用 pnpm add / yarn add / bun add。

### @browserstack/ai-sdk 支持 TypeScript 吗？

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

### @browserstack/ai-sdk 支持 ESM 还是 CommonJS？

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

### @browserstack/ai-sdk 需要什么版本的 Node\.js？

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

### @browserstack/ai-sdk 可以商用吗？

@browserstack/ai-sdk 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @browserstack/ai-sdk 的下载量有多少？

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

### @browserstack/ai-sdk 还在维护吗？

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