@buildingai/ai-sdk

基于 Vercel AI SDK 6.x 的统一 AI SDK，提供项目内统一的 Provider 注册、能力分发和常用工具封装。

特性

统一文本、Embedding、图像、语音、转写、重排序、内容审核能力

基于 getProvider() / getProviderFor*() 统一切换 Provider

重新导出 ai 包的核心 API，减少业务层直接依赖底层 Provider SDK

提供 getReasoningOptions()、MCP 工具封装、usage 估算工具

支持运行时查询当前内置 Provider 列表

安装

快速开始

基础文本生成

import { generateText, getProvider } from "@buildingai/ai-sdk";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const result = await generateText({
    ...provider("gpt-4o"),
    prompt: "Hello, how are you?",
});

console.log(result.text);

流式文本生成

import { getProvider, streamText } from "@buildingai/ai-sdk";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const result = streamText({
    ...provider("gpt-4o"),
    messages: [{ role: "user", content: "Tell me a story about a robot." }],
});

for await (const chunk of result.textStream) {
    process.stdout.write(chunk);
}

结构化输出

推荐优先使用 generateText + Output.object(...)，而不是手动解析 JSON。

import { generateText, getProvider, Output } from "@buildingai/ai-sdk";
import { z } from "zod";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const result = await generateText({
    ...provider("gpt-4o"),
    output: Output.object({
        schema: z.object({
            name: z.string(),
            age: z.number(),
            email: z.string().email(),
        }),
    }),
    prompt: "Generate a random user profile.",
});

console.log(result.output);

Provider 用法

使用 `getProvider()`（推荐）

import { embed, generateText, getProvider } from "@buildingai/ai-sdk";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const text = await generateText({
    ...provider("gpt-4o"),
    prompt: "Hello!",
});

const embedding = await embed({
    ...provider("text-embedding-3-small"),
    value: "Hello!",
});

使用专门函数

当你明确知道要用哪种能力时，推荐使用 getProviderFor*()，类型更准确。

import {
    embed,
    experimental_generateSpeech as generateSpeech,
    generateText,
    getProviderForEmbedding,
    getProviderForSpeech,
    getProviderForText,
} from "@buildingai/ai-sdk";

const textProvider = getProviderForText("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const text = await generateText({
    ...textProvider("gpt-4o"),
    prompt: "Hello!",
});

const embeddingProvider = getProviderForEmbedding("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const embedding = await embed({
    ...embeddingProvider("text-embedding-3-small"),
    value: "Hello!",
});

const speechProvider = getProviderForSpeech("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const speech = await generateSpeech({
    ...speechProvider("tts-1"),
    text: "Hello, world!",
    voice: "alloy",
});

能力检测

import {
    experimental_generateSpeech as generateSpeech,
    getProvider,
} from "@buildingai/ai-sdk";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

if (provider.supports("speech")) {
    const speech = await generateSpeech({
        ...provider.speech("tts-1"),
        text: "Hello!",
    });

    console.log(speech.audio.format);
}

console.log(provider.capabilities.getAll());

获取当前内置 Provider 列表

如果你想知道“当前版本到底支持哪些厂商”，请以运行时注册表为准：

import { listProviders } from "@buildingai/ai-sdk";

console.table(listProviders());

当前内置 Provider 的注册来源是：

packages/@buildingai/ai-sdk/src/registry/provider-registry.ts

当前内置 Providers

以下列表按当前代码注册表整理：

Provider	标识符	说明
OpenAI	`openai`	OpenAI GPT 系列模型
DeepSeek	`deepseek`	DeepSeek 深度求索
智谱 AI	`zhipuai`	智谱 AI GLM 系列模型
月之暗面	`moonshot`	月之暗面 Kimi
硅基流动	`siliconflow`	硅基流动
通义千问	`tongyi`	阿里云通义千问
火山引擎	`volcengine`	火山引擎豆包
腾讯混元	`hunyuan`	腾讯混元
百度文心	`wenxin`	百度文心一言
讯飞星火	`spark`	讯飞星火大模型
Ollama	`ollama`	Ollama 本地模型
MiniMax	`minimax`	MiniMax M2 系列模型
Anthropic	`anthropic`	Anthropic Claude 系列模型
Google	`google`	Google Gemini 系列模型
Cohere	`cohere`	Cohere 系列模型
Gitee AI	`gitee_ai`	Gitee AI 魔力方舟
xAI	`x`	xAI Grok 系列模型
OpenRouter	`openrouter`	OpenRouter 统一接入 300+ 模型
Azure	`azure`	Azure AI 服务
自定义	`custom`	自定义 OpenAI 兼容 API

扩展能力

语音合成（TTS）

注意：当前 ai 6.x 中的语音合成导出名为 experimental_generateSpeech。

import {
    experimental_generateSpeech as generateSpeech,
    getProvider,
} from "@buildingai/ai-sdk";
import { writeFile } from "node:fs/promises";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const result = await generateSpeech({
    ...provider.speech("tts-1"),
    text: "Hello, world!",
    voice: "alloy",
    speed: 1,
    outputFormat: "mp3",
});

await writeFile("output.mp3", result.audio.uint8Array);

语音识别（STT）

注意：当前 ai 6.x 中的语音转写导出名为 experimental_transcribe。

import {
    experimental_transcribe as transcribe,
    getProvider,
} from "@buildingai/ai-sdk";
import { readFile } from "node:fs/promises";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const audio = await readFile("audio.mp3");

const result = await transcribe({
    ...provider.transcription("whisper-1"),
    audio,
    providerOptions: {
        openai: {
            language: "zh",
            response_format: "json",
        },
    },
});

console.log(result.text);

图像生成

import { generateImage, getProvider } from "@buildingai/ai-sdk";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const result = await generateImage({
    ...provider.image("dall-e-3"),
    prompt: "A beautiful sunset over mountains",
    size: "1024x1024",
    providerOptions: {
        openai: {
            quality: "hd",
        },
    },
});

console.log(result.images[0]);

内容审核

当前包提供了 moderation model 能力，但没有额外封装一个顶层 moderate() 辅助函数。推荐直接调用 moderation model 的 doModerate()：

import { getProvider } from "@buildingai/ai-sdk";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const moderationModel = provider.moderation("text-moderation-latest").model;
const result = await moderationModel.doModerate({
    input: "Some text to check",
});

console.log(result.results[0].flagged);

文档重排序

import { getProvider, rerankV3 } from "@buildingai/ai-sdk";

const provider = getProvider("zhipuai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const result = await rerankV3({
    ...provider.rerank("rerank-1"),
    query: "AI technology trends",
    documents: [
        "Machine learning is a subset of AI",
        "Deep learning uses neural networks",
        "Natural language processing enables text understanding",
    ],
    topN: 2,
});

result.ranking.forEach((item) => {
    console.log(`Index: ${item.originalIndex}, Score: ${item.score}`);
});

错误处理

import {
    generateText,
    getProvider,
    isAPIError,
    isProviderCapabilityError,
    isRateLimitError,
} from "@buildingai/ai-sdk";

try {
    const provider = getProvider("openai", {
        apiKey: process.env.OPENAI_API_KEY,
    });

    const result = await generateText({
        ...provider("gpt-4o"),
        prompt: "Hello!",
    });

    console.log(result.text);
} catch (error) {
    if (isProviderCapabilityError(error)) {
        console.error(`Provider doesn't support: ${error.capability}`);
    } else if (isRateLimitError(error)) {
        console.error(`Rate limited, retry after: ${error.retryAfter}ms`);
    } else if (isAPIError(error)) {
        console.error(`API error: ${error.statusCode} - ${error.message}`);
    } else {
        throw error;
    }
}

Tool 调用

推荐使用 inputSchema，这也是当前项目内实际使用的写法。

import { generateText, getProvider, tool } from "@buildingai/ai-sdk";
import { z } from "zod";

const provider = getProvider("openai", {
    apiKey: process.env.OPENAI_API_KEY,
});

const result = await generateText({
    ...provider("gpt-4o"),
    prompt: "What is the weather in Tokyo?",
    tools: {
        getWeather: tool({
            description: "Get weather for a location",
            inputSchema: z.object({
                location: z.string().describe("City name"),
            }),
            execute: async ({ location }) => {
                return { location, temperature: 22, condition: "sunny" };
            },
        }),
    },
    maxSteps: 5,
});

console.log(result.text);

API 参考

核心导出

导出	说明
`generateText`	文本生成
`streamText`	流式文本生成
`Output`	结构化输出定义工具
`embed`	文本向量化
`embedMany`	批量向量化
`generateImage`	图像生成
`rerank`	AI SDK 原生重排序
`rerankV3`	`rerank` 的兼容别名
`tool`	定义工具
`ToolLoopAgent`	多步工具调用 Agent

兼容导出

以下 API 仍然会随着 ai 包一起被重新导出，但新代码通常更推荐使用上面的主路径：

导出	说明
`generateObject`	兼容导出，优先考虑 `generateText + Output.object(...)`
`streamObject`	流式结构化输出
`experimental_generateSpeech`	语音合成
`experimental_transcribe`	语音转写

Provider 相关导出

导出	说明
`getProvider`	获取通用 Provider
`getProviderForText`	获取文本模型 Provider
`getProviderForEmbedding`	获取 Embedding Provider
`getProviderForSpeech`	获取语音合成 Provider
`getProviderForTranscription`	获取语音转写 Provider
`getProviderForImage`	获取图像模型 Provider
`getProviderForModeration`	获取内容审核 Provider
`getProviderForRerank`	获取重排序 Provider
`listProviders`	列出当前内置 Provider
`getReasoningOptions`	根据 Provider 生成 reasoning 参数

License

MIT

AI SDK 开发文档

@buildingai/ai-sdk#

特性#

安装#

快速开始#

基础文本生成#

流式文本生成#

结构化输出#

Provider 用法#

使用 getProvider()（推荐）#

使用专门函数#

能力检测#

获取当前内置 Provider 列表#

当前内置 Providers#

扩展能力#

语音合成（TTS）#

语音识别（STT）#

图像生成#

内容审核#

文档重排序#

错误处理#

Tool 调用#

API 参考#

核心导出#

兼容导出#

Provider 相关导出#

License#