Bitfab 类型脚本 SDK
Bitfab 客户端用于基于提供者的 API 呼叫.
Monorepo 设置
此软件包属于 pnpm 工作空间 单相机。 工作空间结构分别涉及:
- 根号
package.json: 只包含共享的依赖性( Biome, TypeScript, Vitest, Knip) - 软件包
package.json: 包含此软件包特有的运行时间依赖性 - 您可以从根目录中运行测试和验证 :
pnpm test或者说pnpm validate - 不需要手动更新跨套件共享的 dev 工具版本
安装依赖关系
总是从中安装依赖性 根目录数字 :
# From the root directory
pnpm install
更新 pnpm
要在单曲中更新 pnpm :
# From the root directory
pnpm pnpm:update
此自动更新 pnpm 并同步版本 package.json 和CI/CD工作流程.
运行中的命令
您可以从此目录或从根运行命令 :
# 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 |
运行单个工具 :
# 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
安装
基本安装
npm install @bitfab/sdk
# or
pnpm add @bitfab/sdk
# or
yarn add @bitfab/sdk
自动子树变换适配器包括在下面
@bitfab/sdk/transform/*;不需要第二个软件包.
与 OpenAI 代理 SDK 追踪
如果您想要使用 OpenAI 代理 SDK 跟踪集成 :
npm install @bitfab/sdk @openai/agents
# or
pnpm add @bitfab/sdk @openai/agents
这个 @openai/agents 软件包是一个可选的对等依赖性 - SDK 工作正常,除非您需要跟踪功能.
地方发展
cd bitfab-typescript-sdk
pnpm build
将地方发展联系起来:
# In this directory
pnpm link --global
# In your app directory
pnpm link --global bitfab
要切换到 npm 版本 :
pnpm unlink bitfab
pnpm add bitfab
使用量
基本使用(当地执行)
默认情况下, SDK 执行 BAML 函数 本地客户端 通过从服务器取出 BAML 提示并用自己的 API 键运行它:
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数字 :
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",
});
用类型脚本通用
您可以指定类型安全的返回类型 :
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
处理错误
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 (英语)(中文(简体) ) |
timeout | 没有 | 请求超时以毫秒计( 默认为 1200) |
envVars | 没有 | LLM 提供者 API 密钥的环境变量( 例如 ), { OPENAI_API_KEY: "..." }) (中文(简体) ). 要求在当地执行. |
executeLocally | 没有 | 是否在客户端上执行本地 BAML( 默认: true) 。 设定为假以使用服务器的 API 密钥在服务器上执行 . |
执行模式
本地执行( 默认)
何时 executeLocally: true (默认), SDK:
- 从 Bitfab 服务器获取 BAML 函数定义
- 在本地执行 BAML 使用
@boundaryml/baml运行时间 - 使用您的 LLM 提供者 API 密钥( 通过
envVars(中文(简体) ) - 直接返回结果
福利:
- 全面控制 API 密钥和成本
- 空闲度较低( 没有服务器往返执行)
- 隐私:您的数据不会通过 Bitfab 服务器
所需经费:
- 您必须通过 LLM 提供者 API 密钥提供
envVars - BAML 运行时间运行在您的环境中( Node.js,带多填充等的浏览器)
服务器系统执行
何时 executeLocally: false这个SDK:
- 向 Bitfab 服务器发送函数名称和输入
- 服务器使用自己的 API 密钥执行 BAML
- 返回结果给您
福利:
- 不需要管理 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完全没有
测试
提供测试脚本以验证本地和服务器侧执行:
# 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?"
测试脚本会:
- 用您的 API 密钥测试本地执行
- 测试服务器侧执行
- 比较结果和业绩
出版
pnpm build
npm publish --access public