# @bitfab/sdk 中文文档

规范地址：https://npmcn.com/package/%40bitfab/sdk/

版本：0\.76\.6
npm 元数据更新时间：2026-11-06T05:46:21.740Z
中文译文更新时间：2026-11-08T04:15:44.722Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bitfab/sdk
原文对照：https://npmcn.com/package/%40bitfab/sdk/?lang=original
项目主页：https://github.com/Project-White-Rabbit/ai-assistant/tree/main/bitfab-typescript-sdk#readme
源码仓库：https://github.com/Project-White-Rabbit/ai-assistant

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

- 包体积（解压后）：5.2 MB，152 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.15\.0
- 运行依赖：14 个
- peer 依赖：ai \>=5\.0\.0，langchain \>=1\.0\.0 \<2\.0\.0，deepagents \>=1\.0\.0 \<2\.0\.0，@openai/agents \>=0\.3\.0 \<1\.0\.0，@langchain/core \>=0\.3\.0 \<2\.0\.0，@boundaryml/baml \>=0\.220\.0，@langchain/langgraph \>=0\.2\.0 \<2\.0\.0
- 首次发布：2026-05-20T21:19:04.701Z
- 最新版本发布：2026-11-06T05:46:21.540Z
- 近 30 天下载量：15117（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：252（近 12 个月 252 个）

## 中文简介

本地 BAML 执行的基于提供者的 API 调用 Bitfab 客户端

## 安装

```sh
npm install @bitfab/sdk
```

也可以使用：`pnpm add @bitfab/sdk`、`yarn add @bitfab/sdk`、`bun add @bitfab/sdk`

## README

# Bitfab 类型脚本 SDK

Bitfab 客户端用于基于提供者的 API 呼叫.

## Monorepo 设置

此软件包属于 **pnpm 工作空间** 单相机。 工作空间结构分别涉及:

-   **根号 `package.json`**: 只包含共享的依赖性( Biome, TypeScript, Vitest, Knip)
-   **软件包 `package.json`**: 包含此软件包特有的运行时间依赖性
-   您可以从根目录中运行测试和验证 : `pnpm test` 或者说 `pnpm validate`
-   不需要手动更新跨套件共享的 dev 工具版本

### 安装依赖关系

总是从中安装依赖性 **根目录**数字 :

```bash
# From the root directory
pnpm install
```

### 更新 pnpm

要在单曲中更新 pnpm :

```bash
# From the root directory
pnpm pnpm:update
```

此自动更新 pnpm 并同步版本 `package.json` 和CI/CD工作流程.

### 运行中的命令

您可以从此目录或从根运行命令 :

```bash
# From this directory
pnpm test
pnpm build
pnpm validate

# From the root directory (runs across all packages)
pnpm test          # Run all tests
pnpm validate      # Run lint + tsc + test
```

### 可用的开发工具

这一一揽子计划包括下列共享发展工具:

| 工具 | 目的 | 命令 |
| --- | --- | --- |
| **维特** | 覆盖的单位测试 | `pnpm test` |
| **生物体** | 快速闪烁格式化( F) | `pnpm lint` |
| **类型脚本** | 类型检查 | `pnpm tsc` |
| **克尼普语Name** | 查找未使用的依赖/导出 | `pnpm knip` |

**运行单个工具 :**

```bash
# Run tests with coverage
pnpm test

# Lint and format code
pnpm lint

# Type check without building
pnpm tsc

# Find unused dependencies
pnpm knip

# Run all validation checks
pnpm validate
```

## 安装

### 基本安装

```bash
npm install @bitfab/sdk
# or
pnpm add @bitfab/sdk
# or
yarn add @bitfab/sdk
```

自动子树变换适配器包括在下面 `@bitfab/sdk/transform/*`;不需要第二个软件包.

### 与 OpenAI 代理 SDK 追踪

如果您想要使用 OpenAI 代理 SDK 跟踪集成 :

```bash
npm install @bitfab/sdk @openai/agents
# or
pnpm add @bitfab/sdk @openai/agents
```

这个 `@openai/agents` 软件包是一个可选的对等依赖性 - SDK 工作正常,除非您需要跟踪功能.

## 地方发展

```bash
cd bitfab-typescript-sdk
pnpm build
```

将地方发展联系起来:

```bash
# In this directory
pnpm link --global

# In your app directory
pnpm link --global bitfab
```

要切换到 npm 版本 :

```bash
pnpm unlink bitfab
pnpm add bitfab
```

## 使用量

### 基本使用(当地执行)

默认情况下, SDK 执行 BAML 函数 **本地客户端** 通过从服务器取出 BAML 提示并用自己的 API 键运行它:

```typescript
import { Bitfab } from "bitfab";

const client = new Bitfab({
  apiKey: "bf_your_api_key_here", // Required: Your Bitfab API key
  serviceUrl: "https://bitfab.ai", // Optional
  envVars: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY, // Your LLM provider API keys
  },
  executeLocally: true, // Default: true
});

const result = await client.call("method_name", {
  arg1: "value1",
  arg2: "value2",
});
```

### 服务器系统执行

如果您喜欢在服务器上执行 BAML( 使用服务器的 API 密钥), 设置 `executeLocally: false`数字 :

```typescript
const client = new Bitfab({
  apiKey: "bf_your_api_key_here",
  executeLocally: false, // Execute on server instead of locally
});

const result = await client.call("method_name", {
  arg1: "value1",
  arg2: "value2",
});
```

### 用类型脚本通用

您可以指定类型安全的返回类型 :

```typescript
interface MyResponse {
  answer: string;
  confidence: number;
}

const result = await client.call<MyResponse>("analyze", {
  text: "Hello world",
});

console.log(result.answer); // TypeScript knows this is a string
```

### 处理错误

```typescript
import { Bitfab, BitfabError } from "bitfab";

const client = new Bitfab({
  apiKey: "bf_your_api_key_here",
  serviceUrl: "https://your-bitfab-instance.com",
});

try {
  const result = await client.call("method_name", { input: "value" });
} catch (error) {
  if (error instanceof BitfabError) {
    console.error("Bitfab error:", error.message);
    if (error.url) {
      console.error("Configure at:", error.url);
    }
  }
}
```

## 配置

| 选项 | 需求 | 说明 |
| --- | --- | --- |
| `apiKey` | 对 | 您的 Bitfab API 密钥( 从您的 Bitfab 仪表板生成) |
| `serviceUrl` | 没有 | Bitfab API 的基础 URL( 默认 ): [https://bitfab.ai (英语)](https://bitfab.ai/)(中文(简体) ) |
| `timeout` | 没有 | 请求超时以毫秒计( 默认为 1200) |
| `envVars` | 没有 | LLM 提供者 API 密钥的环境变量( 例如 ), `{ OPENAI_API_KEY: "..." }`) (中文(简体) ). 要求在当地执行. |
| `executeLocally` | 没有 | 是否在客户端上执行本地 BAML( 默认: true) 。 设定为假以使用服务器的 API 密钥在服务器上执行 . |

## 执行模式

### 本地执行( 默认)

何时 `executeLocally: true` (默认), SDK:

1.  从 Bitfab 服务器获取 BAML 函数定义
2.  在本地执行 BAML 使用 `@boundaryml/baml` 运行时间
3.  使用您的 LLM 提供者 API 密钥( 通过 `envVars`(中文(简体) )
4.  直接返回结果

**福利:**

-   全面控制 API 密钥和成本
-   空闲度较低( 没有服务器往返执行)
-   隐私:您的数据不会通过 Bitfab 服务器

**所需经费:**

-   您必须通过 LLM 提供者 API 密钥提供 `envVars`
-   BAML 运行时间运行在您的环境中( Node.js,带多填充等的浏览器)

### 服务器系统执行

何时 `executeLocally: false`这个SDK:

1.  向 Bitfab 服务器发送函数名称和输入
2.  服务器使用自己的 API 密钥执行 BAML
3.  返回结果给您

**福利:**

-   不需要管理 LLM 提供者 API 密钥
-   较简单的设置
-   任何环境中的工作

**所需经费:**

-   Bitfab 服务器必须配置必要的 API 密钥

## 环境变量

-   `BITFAB_API_KEY`: 当 `apiKey` 被省略或解析为空,在初始使用时读取
-   `BITFAB_CAPTURE_ENABLED`: 未通过客户端的抓取开关 `captureEnabled`。 。 。 . `1`, (中文(简体) ), `true`,或 `yes` 俘虏; `0`, (中文(简体) ), `false`,或 `no` 没有。 未知的捕获,和 `captureEnabled` 在代码中总是获胜
-   `OPENAI_API_KEY`, (中文(简体) ), `ANTHROPIC_API_KEY`等: LLM 提供者 API 密钥( 本地执行需要)
-   `BITFAB_OTEL_MAX_REQUEST_BYTES`: 出口请求大小目标(正整数至 `3000000`(中文(简体) )
-   `BITFAB_OTEL_EXPORT_CONCURRENCY`: 每个出口窗口同时提出的直接请求(`1`\- 说吧`64`默认值 `32`(中文(简体) )
-   `BITFAB_COMMIT_SHA`: 记录为 `commit_ref.sha` 在每一个根痕量上, 对于一个没有部署平台的构建变量或 git 检查出值的容器
-   `BITFAB_DISABLE_COMMIT_REF`: 设置为不发送 `commit_ref` 完全没有

## 测试

提供测试脚本以验证本地和服务器侧执行:

```bash
# Set up environment variables
export BITFAB_API_KEY="bf_your_api_key"
export OPENAI_API_KEY="your_openai_key"

# Run the test script
pnpm tsx test-local-execution.ts [function-name] [query]

# Example
pnpm tsx test-local-execution.ts extract-entities "What is the capital of France?"
```

测试脚本会:

1.  用您的 API 密钥测试本地执行
2.  测试服务器侧执行
3.  比较结果和业绩

## 出版

```bash
pnpm build
npm publish --access public
```

## 常见问题

### @bitfab/sdk 是什么？

本地 BAML 执行的基于提供者的 API 调用 Bitfab 客户端

### 如何安装 @bitfab/sdk？

在项目目录运行 npm install @bitfab/sdk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bitfab-seed、bitfab-replay，可以用 npx bitfab-seed 直接运行。

### @bitfab/sdk 支持 TypeScript 吗？

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

### @bitfab/sdk 支持 ESM 还是 CommonJS？

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

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

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

### @bitfab/sdk 可以商用吗？

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

### @bitfab/sdk 的下载量有多少？

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

### @bitfab/sdk 还在维护吗？

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