Braintust 节点 API 库

这个库提供了从服务器侧的TypeScript或JavaScript获取Braintrust REST API的方便访问.

REST API 文档可见于 www.braintustdata.com (中文(简体) )。此库的全部 API 可以在 日记。 。 。 .

它的产生与 无污。 。 。 .

安装

npm install @braintrust/api

使用量

此库的全部 API 可在 日记。 。 。 .

import Braintrust from '@braintrust/api';

const client = new Braintrust({
  apiKey: process.env['BRAINTRUST_API_KEY'], // This is the default and can be omitted
});

async function main() {
  const project = await client.projects.create({ name: 'foobar' });

  console.log(project.id);
}

main();

请求响应类型( A)

这个库包括所有请求参数和响应字段的TypeScript定义. 你可以这样导入和使用它们:

import Braintrust from '@braintrust/api';

const client = new Braintrust({
  apiKey: process.env['BRAINTRUST_API_KEY'], // This is the default and can be omitted
});

async function main() {
  const params: Braintrust.ProjectCreateParams = { name: 'foobar' };
  const project: Braintrust.Project = await client.projects.create(params);
}

main();

每种方法的文件、请求参数和响应字段都以道克字符串形式提供,并将出现在大多数现代编辑中.

处理错误

当库无法连接到API时, 或者如果API返回一个非成功状态代码(即4xx或5xx回复), 子类 APIError 将扔出 :

async function main() {
  const project = await client.projects.create({ name: 'foobar' }).catch(async (err) => {
    if (err instanceof Braintrust.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });
}

main();

错误代码如下:

检索

某些出错默认会自动重试2次,并有短暂的指数后退. 连接出错(例如由于网络连接问题) 408 请求超时, 409 相冲突, 429 限制费率,和 QQ500 内部出错都会默认重审.

你可以用这个 maxRetries 选项以配置或禁用此选项:

// Configure the default for all requests:
const client = new Braintrust({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await client.projects.create({ name: 'foobar' }, {
  maxRetries: 5,
});

超时

默认1分钟后请求暂停 。 您可以用一个 timeout 选项 :

// Configure the default for all requests:
const client = new Braintrust({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.projects.create({ name: 'foobar' }, {
  timeout: 5 * 1000,
});

超时,一个 APIConnectionTimeoutError 被抛出.

请注意,哪些时间是 默认重审两次。 。 。 .

自动涂鸦

Braintrust API中的列表方法被标注. 你用得着 for await … of 在所有页面中通过项目排列的语法 :

async function fetchAllProjects(params) {
  const allProjects = [];
  // Automatically fetches more pages as needed.
  for await (const project of client.projects.list()) {
    allProjects.push(project);
  }
  return allProjects;
}

或者,您可以一次请求一页:

let page = await client.projects.list();
for (const project of page.objects) {
  console.log(project);
}

// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
  page = page.getNextPage();
  // ...
}

高级使用

获取原始响应数据(例如信头)

那个"行" Response 返回时间 fetch() 可通过 .asResponse() 方法 APIPromise 键入所有方法返回.

你也可以使用这个 .withResponse() 获取原始数据的方法 Response 与解析数据一起.

const client = new Braintrust();

const response = await client.projects.create({ name: 'foobar' }).asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // access the underlying Response object

const { data: project, response: raw } = await client.projects.create({ name: 'foobar' }).withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(project.id);

提出自定义/无文件记录的请求

此库的打入是为了方便地访问有文献记载的API. 如果您需要访问无证 端点,参数,或响应属性,库仍然可以被使用.

无记录的终点

要向无记录的端点提出请求, 您可以使用 client.get, (中文(简体) ), client.post,以及其他HTTP动词. 在提出这些请求时,将尊重客户端的选项,例如复试.

await client.post('/some/path', {
  body: { some_prop: 'foo' },
  query: { some_query_arg: 'bar' },
});

无文件请求段落

要使用无证参数提出请求, 您可以使用 // @ts-expect-error 关于无证件者 参数。 此库不会在运行时验证请求是否与类型相匹配, 所以任何额外的值 发送将按.

client.foo.create({
  foo: 'my_param',
  bar: 12,
  // @ts-expect-error baz is not yet public
  baz: 'undocumented option',
});

申请与 GET 动词,任何额外的参数都会在查询中,所有其他请求都会发送 身体里有额外的参数.

如果你想明确发送一个额外的参数,你可以这样做与 query, (中文(简体) ), body,以及 headers 请求 选项.

无文件回复属性

要访问无证响应属性, 您可以访问响应对象 // @ts-expect-error 打开 ,或者将响应对象投放到必要的类型。 像请求的段落,我们不 验证或从 API 的响应中脱去额外的属性.

自定义获取客户端

默认情况下,此库使用 node-fetch 在节点,并期望一个全局 fetch 函数在其他环境中.

如果您更愿意使用符合全球网络标准的网络标准 fetch 即使在节点环境中也能函数, (例如,如果您正在以 --experimental-fetch 组合填充的下一个JS undici, (中文(简体) ), 在您第一次导入前添加以下导入 from "Braintrust"数字 :

// Tell TypeScript and the package to use the global web fetch instead of node-fetch.
// Note, despite the name, this does not add any polyfills, but expects them to be provided if needed.
import '@braintrust/api/shims/web';
import Braintrust from '@braintrust/api';

倒转时加 import "@braintrust/api/shims/node" (它的确导入多填充). 如果您获取错误的类型脚本类型, 此功能也会有所帮助 Response (单位:千美元)更多细节) (中文(简体) ).

日志和中间软件

您也可以提供习惯 fetch 函数当即决客户端时, 可用于检查或修改 Request 或者说 Response 每次请求之前/之后:

import { fetch } from 'undici'; // as one example
import Braintrust from '@braintrust/api';

const client = new Braintrust({
  fetch: async (url: RequestInfo, init?: RequestInit): Promise<Response> => {
    console.log('About to make a request', url, init);
    const response = await fetch(url, init);
    console.log('Got response', response);
    return response;
  },
});

请注意,如果 DEBUG=true 环境变量,此库将自动记录所有请求和响应 . 这样做只是为了调试目的,今后可能会不通知而改变.

配置 HTTP( S) 代理( 例如, 代理)

默认情况下,这个库会对所有 http/https 请求使用一个稳定的代理来再利用 TCP 连接,消除了许多 TCP & TLS 握手并刮去大多数请求的大约100ms.

如果您想要禁用或自定义此行为, 例如在代理后使用 API, 您可以通过 httpAgent 用于所有请求(无论是http还是https),例如:

import http from 'http';
import { HttpsProxyAgent } from 'https-proxy-agent';

// Configure the default for all requests:
const client = new Braintrust({
  httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
});

// Override per-request:
await client.projects.create(
  { name: 'foobar' },
  {
    httpAgent: new http.Agent({ keepAlive: false }),
  },
);

语义版本

这套套件一般沿用 交换器 虽然某些向后兼容的修改可以作为小版本发布:

1. 仅影响静态类型的变化,而不突破运行时的行为.
2. 图书馆内部的改动,技术上是公开的,但并非打算或记录外部使用的. (请打开一个 GitHub 问题,让我们知道 如果你依赖这样的内部)。 。 。 .
3. 我们预计不会在实践中影响到绝大多数用户的变化.

我们认真对待倒向相容性,并努力地确保你能够依靠平稳的升级经验.

我们很期待你的反馈,请打开 问题 包括问题、错误或建议.

所需资源

TypeScript QQ 4.5被支持.

支持以下运行时间:

注意React Industrial此时不支持.

如果您对其它运行时间环境感兴趣, 请在 GitHub 上打开或投票 .