@ raintrust/ 语言
TypeScript 绑定 Lingua - LLMs 的通用消息格式.
安装
pnpm add @braintrust/lingua
# or
npm install @braintrust/lingua
# or
yarn add @braintrust/lingua
此自动安装 @braintrust/lingua-wasm 作为依赖(你不需要单独安装).
如果您只需要类型脚本而不需要转换或验证功能,则安装只类型包:
pnpm add -D @braintrust/lingua-types
import type { Message, UniversalRequest } from "@braintrust/lingua-types";
使用量
该软件包为Node.js和浏览器环境提供了单独的切入点:
@braintrust/lingua或者说@braintrust/lingua/node- 带本地WASM的节点(自动初始化)@braintrust/lingua/browser- 有网络目标WASM的浏览器(需要明确初始化)
节点.js
在Node.js中, WASM 模块自动加载 - 只是导入和使用:
import {
type Message,
linguaToChatCompletionsMessages,
chatCompletionsMessagesToLingua,
} from "@braintrust/lingua";
// Create messages in Lingua format
const messages: Message[] = [
{ role: "user", content: "Hello, how are you?" },
];
// Convert to OpenAI format
const openaiMessages = linguaToChatCompletionsMessages(messages);
// Convert OpenAI response back to Lingua
const linguaMessages = chatCompletionsMessagesToLingua([response.choices[0].message]);
浏览器
浏览器构建需要在使用前明确初始化:
import init, {
linguaToChatCompletionsMessages,
type Message,
} from "@braintrust/lingua/browser";
// Initialize with WASM URL (must be called before using any functions)
await init("/wasm/lingua.wasm");
// Now you can use Lingua functions
const messages: Message[] = [{ role: "user", content: "Hello!" }];
const openaiMessages = linguaToChatCompletionsMessages(messages);
初始化选项 :
// Option 1: URL string (fetches the WASM file)
await init("/wasm/lingua.wasm");
// Option 2: ArrayBuffer/Uint8Array (useful for testing or custom loading)
const wasmBuffer = await fetch("/wasm/lingua.wasm").then((r) => r.arrayBuffer());
await init(wasmBuffer);
重要时间轴: 必须 提供一个 WASM 源
init()。如果调用时没有参数,函数会出错.
下一个.js
对于 Next.js 应用程序,您需要:
- 将 WASM 文件复制到您的公共目录 构建时
- 将 WASM 软件包排除在网页包处理之外
- 在客户端初始化
步骤1:配置 next.config.mjs
import CopyWebpackPlugin from "copy-webpack-plugin";
/** @type {import('next').NextConfig} */
const nextConfig = {
webpack: (config, { isServer }) => {
// Copy WASM file to public directory
config.plugins.push(
new CopyWebpackPlugin({
patterns: [
{
from: "node_modules/@braintrust/lingua-wasm/web/lingua_bg.wasm",
to: "../public/wasm/lingua.wasm",
},
],
})
);
// Exclude lingua-wasm from webpack's WASM processing
config.module.rules.push({
test: /\.wasm$/,
exclude: [/[\\/]lingua-wasm[\\/]/],
type: "webassembly/async",
});
return config;
},
// Mark the WASM package as external for server-side
serverExternalPackages: ["@braintrust/lingua-wasm"],
};
export default nextConfig;
步骤2: 创建客户端包装
// lib/lingua.tsx
"use client";
import * as linguaModule from "@braintrust/lingua/browser";
import { useEffect } from "react";
const WASM_URL = "/wasm/lingua.wasm";
let ready: Promise<void> | null = null;
export async function initLingua(): Promise<void> {
if (!ready) {
ready = linguaModule.init(WASM_URL).catch((error) => {
console.error("[Lingua] Initialization failed:", error);
ready = null;
throw error;
});
}
return ready;
}
// Optional: React provider to initialize on app load
export function LinguaProvider({ children }: { children: React.ReactNode }) {
useEffect(() => {
initLingua();
}, []);
return <>{children}</>;
}
// Re-export everything from the browser module
export * from "@braintrust/lingua/browser";
第3步:在组件中使用
"use client";
import { initLingua, linguaToChatCompletionsMessages } from "@/lib/lingua";
async function convertMessages() {
await initLingua(); // Ensures WASM is loaded
const messages = [{ role: "user" as const, content: "Hello!" }];
return linguaToChatCompletionsMessages(messages);
}
软件包架构
TypeScript 包由运行时间需求分割 :
@braintrust/lingua # TypeScript wrapper (this package)
└── @braintrust/lingua-wasm # Raw WASM bindings (auto-installed dependency)
├── nodejs/ # Node.js WASM build
└── web/ # Browser WASM build
@braintrust/lingua-types # Type-only package with no WASM dependency
@braintrust/lingua- 从下列来源进口的纯类型脚本:@braintrust/lingua-wasm@braintrust/lingua-wasm- 原始内容wasm-pack输出, 用于清洁捆绑的单独软件包@braintrust/lingua-types- 仅供消费者使用的包式类型脚本申报
这种分离确保了webpack/bundlers可以正确处理WASM文件而无需复杂的配置.
发展
这个包裹是Lingua monorepo的一部分. TypeScript类型是使用ts-rs从 Rust 源代码自动生成的.
大楼
# Build TypeScript types, WASM, and wrapper packages from the repo root
make typescript
生成类型
从 Rust 重新生成类型脚本 :
pnpm generate
运行测试
pnpm test
项目结构
bindings/
├── lingua-wasm/ # @braintrust/lingua-wasm package
│ ├── nodejs/ # wasm-pack --target nodejs output
│ ├── web/ # wasm-pack --target web output
│ └── package.json
├── typescript-types/ # @braintrust/lingua-types package
│ ├── src/
│ └── dist/
└── typescript/ # @braintrust/lingua package (this directory)
├── src/
│ ├── generated/ # Auto-generated types from Rust
│ ├── index.ts # Node.js entry point
│ ├── index.browser.ts # Browser entry point
│ └── wasm-runtime.ts # WASM initialization logic
├── dist/
│ ├── index.mjs # Compiled Node.js module
│ ├── index.browser.mjs # Compiled browser module
│ └── *.d.mts # Type definitions
├── tests/
└── package.json
API 参考
转换函数
// OpenAI Chat Completions ↔ Lingua
linguaToChatCompletionsMessages(messages: Message[]): ChatCompletionMessageParam[]
chatCompletionsMessagesToLingua(messages: ChatCompletionMessage[]): Message[]
// Anthropic ↔ Lingua
linguaToAnthropicMessages(messages: Message[]): MessageParam[]
anthropicMessagesToLingua(messages: AnthropicMessage[]): Message[]
// Validation
validateChatCompletionsRequest(request: unknown): ValidationResult
validateChatCompletionsResponse(response: unknown): ValidationResult
validateAnthropicRequest(request: unknown): ValidationResult
validateAnthropicResponse(response: unknown): ValidationResult
类型
interface Message {
role: "user" | "assistant" | "system" | "tool";
content: string | ContentPart[];
id?: string | null;
}
类型兼容性
生成的类型被设计为与流行的LLM SDK相兼容:
- OpenAI SDK (英语:
openai(中文(简体) ) - 人类SDK(
@anthropic-ai/sdk(中文(简体) )
许可证
麻省理工学院