在 Transformers.js 中集成 Vercel AI SDK面向浏览器的声明式推理指南【免费下载链接】transformers.jsState-of-the-art Machine Learning for the web. Run Transformers directly in your browser, with no need for a server!项目地址: https://gitcode.com/GitHub_Trending/tr/transformers.js导读本指南讲解如何在 Transformers.jshuggingface/transformers基础上通过官方生态的browser-ai/transformers-js提供器将模型能力接入 Vercel AI SDK实现在浏览器端以及 Node.js 服务端以streamText、generateText、embed、transcribe、useChat等标准 AI SDK API 完成推理。读完本文你将掌握从安装配置、文本生成/嵌入/音频转录/视觉问答到 Web Worker 卸载、下载进度追踪、工具调用含人工审批、自定义ChatTransport与浏览器兼容回退的完整实战方案。关联文档packages/transformers/docs/source/integrations/vercel-ai-sdk.md。本文围绕该文档为核心骨架展开并辅以仓库内 next-ai-sdk 教程、WebGPU 指南、dtypes 量化指南 与源码佐证。为什么在 Vercel AI SDK 中使用 Transformers.jsVercel AI SDK 是构建 AI 应用的主流工具包它提供了一套统一的、声明式的模型调用接口。而browser-ai/transformers-js提供器构建在huggingface/transformers之上为 Transformers.js 赋予了标准的 AI SDK 接口层替你处理了以下繁琐的底层工作Web Worker 的设置将模型推理从主线程剥离避免阻塞 UI消息传递Worker 与主线程之间的通信协议封装进度追踪模型首次下载时的进度回调流式输出Token 级增量输出中断处理配合AbortSignal停止生成状态管理与useChat等 React Hook 的状态同步。最终效果是你可以在浏览器里用和任何其他 AI SDK 提供器完全一致的streamText、generateText、useChatAPI只是底层模型跑在用户本地设备浏览器或 Node.js上无需任何服务端推理基础设施。背景知识Transformers.js 本身通过pipeline等高层 API 提供开箱即用的推理能力其入口见 transformers.js。AI SDK 集成层只是把这一能力以标准接口暴露出来并不会改变模型本身的加载与执行机制。安装与版本对应关系安装browser-ai/transformers-js、Transformers.js 本体以及 AI SDK 相关包npm install browser-ai/transformers-js huggingface/transformers ai ai-sdk/react版本对应关系务必匹配否则 API 可能不兼容browser-ai/transformers-jsAI SDK说明v2.0.0v6.x当前稳定版本v1.0.0v5.x旧版本Legacy其中ai为核心运行时包ai-sdk/react提供 React 侧的useChatHook。文本生成流式文本生成streamText流式输出是聊天类应用的标配能力。使用streamText搭配transformersJS(modelId)即可创建模型实例import { streamText } from ai; import { transformersJS } from browser-ai/transformers-js; const result streamText({ model: transformersJS(HuggingFaceTB/SmolLM2-360M-Instruct), prompt: Invent a new holiday and describe its traditions., }); for await (const textPart of result.textStream) { console.log(textPart); }textStream是一个异步迭代器逐段产出文本增量。仓库的 pipeline 文档 也印证了text-generation类任务支持流式输出——通过TextStreamer以回调方式逐 token 返回二者思路一致只是 AI SDK 层将其标准化为ReadableStream语义。非流式文本生成generateText当不需要增量输出、只要最终结果时使用generateTextimport { generateText } from ai; import { transformersJS } from browser-ai/transformers-js; const result await generateText({ model: transformersJS(HuggingFaceTB/SmolLM2-360M-Instruct), prompt: Invent a new holiday and describe its traditions., }); console.log(result.text);文本嵌入Text Embeddings借助browser-ai/transformers-js的transformersJS.embedding()工厂方法可以把任意 embedding 模型例如Supabase/gte-small接入 AI SDK 的embed/embedManyimport { embed, embedMany } from ai; import { transformersJS } from browser-ai/transformers-js; // 单个嵌入 const { embedding } await embed({ model: transformersJS.embedding(Supabase/gte-small), value: Hello, world!, }); // 批量嵌入 const { embeddings } await embedMany({ model: transformersJS.embedding(Supabase/gte-small), values: [Hello, World, AI], });这对应着 Transformers.js 的feature-extractionpipeline见 pipelines.md 中的示例。浏览器端嵌入可以用于本地语义搜索、去重、聚类等场景且无需向服务器发送原始文本。音频转录Audio Transcriptionbrowser-ai/transformers-js通过transformersJS.transcription()暴露 Whisper 系列模型配合 AI SDK 的实验性transcribeAPIimport { experimental_transcribe as transcribe } from ai; import { transformersJS } from browser-ai/transformers-js; const transcript await transcribe({ model: transformersJS.transcription(Xenova/whisper-base), audio: audioFile, }); console.log(transcript.text); console.log(transcript.segments); // 带时间戳的片段segments包含带时间戳的分段结果便于做逐句对齐展示。底层对应 Transformers.js 的automatic-speech-recognitionpipelineXenova/whisper-base是该生态中经典的 ONNX 转写模型其模型实现与测试见 tests/models/whisper。视觉模型Vision Models多模态模型通过传入isVisionModel: true选项启用并在消息中以 OpenAI 兼容的content数组混合文本与图片import { streamText } from ai; import { transformersJS } from browser-ai/transformers-js; const result streamText({ model: transformersJS(HuggingFaceTB/SmolVLM-256M-Instruct, { isVisionModel: true, device: webgpu, }), messages: [ { role: user, content: [ { type: text, text: Describe this image }, { type: image, image: someImageBlobOrUrl }, ], }, ], }); for await (const chunk of result.textStream) { console.log(chunk); }要点isVisionModel: true告知提供器按多模态输入处理消息device: webgpu指定推理后端。仓库的 WebGPU 指南 说明得益于与 ONNX Runtime Web 的合作启用 WebGPU 只需在加载模型时设置device: webgpu这对SmolVLM这类视觉模型尤其重要——GPU 加速能显著提升图像编码与生成速度image字段接受 Blob 或 URL。Web Worker 卸载性能优化在浏览器主线程上运行大模型推理会阻塞 UI 渲染。推荐的做法是把推理放到 Web Worker 中。1. 创建worker.tsbrowser-ai/transformers-js提供了现成的TransformersJSWorkerHandler它封装了模型加载、推理、流式输出以及与主线程的通信import { TransformersJSWorkerHandler } from browser-ai/transformers-js; const handler new TransformersJSWorkerHandler(); self.onmessage (msg: MessageEvent) { handler.onmessage(msg); };2. 创建模型时传入 Workerimport { streamText } from ai; import { transformersJS } from browser-ai/transformers-js; const model transformersJS(HuggingFaceTB/SmolLM2-360M-Instruct, { device: webgpu, worker: new Worker(new URL(./worker.ts, import.meta.url), { type: module, }), }); const result streamText({ model, messages: [{ role: user, content: Hello! }], });new URL(./worker.ts, import.meta.url)是 Vite/Next.js 等打包器标准的 Worker 加载写法type: module使其以 ES Module 方式运行。该模式在 next-ai-sdk 教程 中也被完整采用教程还通过supportsWorker配置标志控制是否启用 Worker 加载。下载进度追踪Download Progress Tracking模型在首次使用时才会下载因此把下载进度暴露给用户能显著改善体验。browser-ai/transformers-js提供了availability()与createSessionWithProgress()两个方法import { streamText } from ai; import { transformersJS } from browser-ai/transformers-js; const model transformersJS(HuggingFaceTB/SmolLM2-360M-Instruct); const availability await model.availability(); if (availability unavailable) { console.log(Browser doesnt support Transformers.js); } else if (availability downloadable) { await model.createSessionWithProgress(({ progress }) { console.log(Download progress: ${Math.round(progress * 100)}%); }); } // 模型已就绪 const result streamText({ model, prompt: Hello! });availability可能返回的值语义如下unavailable当前浏览器不支持 Transformers.js 推理如缺少 WebGPU/WASM 能力downloadable需要先下载模型可通过回调上报progress01 之间的小数available模型已在本地缓存可直接推理。下载完成后模型权重会被缓存在浏览器默认使用 Cache API相关开关见 env.js 中的useBrowserCache/useFSCache/cacheDir等配置后续访问无需重复下载。工具调用Tool Calling将工具与模型能力结合可以让模型自主决策并调用你注册的函数。官方建议工具调用场景优先选用擅长多步推理的推理模型如 Qwen3这类模型在处理需要逐步推理的任务时表现更好。import { streamText, tool, stepCountIs } from ai; import { transformersJS } from browser-ai/transformers-js; import { z } from zod; const result await streamText({ model: transformersJS(onnx-community/Qwen3-0.6B-ONNX), messages: [{ role: user, content: Whats the weather in San Francisco? }], tools: { weather: tool({ description: Get the weather in a location, inputSchema: z.object({ location: z.string().describe(The location to get the weather for), }), execute: async ({ location }) ({ location, temperature: 72 Math.floor(Math.random() * 21) - 10, }), }), }, stopWhen: stepCountIs(5), });关键点每个工具用tool()定义description帮助模型理解何时调用inputSchema用 Zod 描述参数结构模型会据此生成 JSON 参数stopWhen: stepCountIs(5)限制最多 5 步工具调用循环防止无限循环工具调用还支持执行审批needsApproval模型发起调用后会暂停执行等待用户确认或拒绝后再运行适用于获取地理位置这类敏感操作。该机制在 next-ai-sdk 教程 的getLocation工具中有完整示例。useChat与自定义 Transport客户端推理服务端推理通常通过 HTTP 路由转发而纯客户端推理需要把模型调用直接接到useChat。为此AI SDK v6 提供了 自定义 transport 机制。第一步实现ChatTransportimport { ChatTransport, UIMessageChunk, streamText, convertToModelMessages, ChatRequestOptions, } from ai; import { TransformersJSLanguageModel, TransformersUIMessage, } from browser-ai/transformers-js; export class TransformersChatTransport implements ChatTransportTransformersUIMessage { constructor(private readonly model: TransformersJSLanguageModel) {} async sendMessages( options: { chatId: string; messages: TransformersUIMessage[]; abortSignal: AbortSignal | undefined; } { trigger: submit-message | submit-tool-result | regenerate-message; messageId: string | undefined; } ChatRequestOptions, ): PromiseReadableStreamUIMessageChunk { const prompt await convertToModelMessages(options.messages); const result streamText({ model: this.model, messages: prompt, abortSignal: options.abortSignal, }); return result.toUIMessageStream(); } async reconnectToStream(): PromiseReadableStreamUIMessageChunk | null { return null; // 客户端推理不支持流重连 } }第二步在组件中使用import { useChat } from ai-sdk/react; import { transformersJS, TransformersUIMessage } from browser-ai/transformers-js; const model transformersJS(HuggingFaceTB/SmolLM2-360M-Instruct, { device: webgpu, worker: new Worker(new URL(./worker.ts, import.meta.url), { type: module }), }); const { sendMessage, messages, stop } useChatTransformersUIMessage({ transport: new TransformersChatTransport(model), });实现细节说明convertToModelMessages()把 UI 消息转换为模型消息格式toUIMessageStream()把streamText的结果转换为useChat可消费的 UI 消息流abortSignal透传给streamText从而支持useChat的stop()中断reconnectToStream()返回null因为客户端推理没有服务端连接可供重连更完整的 transport 实现含下载进度作为自定义 data part 写入流、createUIMessageStream用法见 next-ai-sdk 教程 的chat-transport.ts章节。浏览器兼容回退Browser Compatibility Fallback并非所有设备都支持在浏览器内运行推理。利用doesBrowserSupportTransformersJS()做能力检测在不支持时回退到服务端路由例如通过 AI SDK 的DefaultChatTransport走/api/chat接口import { transformersJS, TransformersUIMessage, doesBrowserSupportTransformersJS, } from browser-ai/transformers-js; const { sendMessage, messages, stop } useChatTransformersUIMessage({ transport: doesBrowserSupportTransformersJS() ? new TransformersChatTransport(model) : new DefaultChatTransport({ api: /api/chat }), });这种客户端优先、服务端兜底的渐进增强策略可以让 WebGPU 不支持的旧浏览器用户依然获得完整功能。关于浏览器能力的前置判断根据仓库 WebGPU 指南 与 env.js 源码可以进一步细化判断维度WebGPU 支持情况约 70% 的浏览器支持截至 2024 年 10 月。Chrome/Edge 113 默认支持Firefox 需开启dom.webgpu.enabled标志Safari 需开启WebGPU特性标志Safari 26 默认启用env.js中通过navigator.gpu/navigator.ml的存在性检测IS_WEBGPU_AVAILABLE/IS_WEBNN_AVAILABLE并区分IS_BROWSER_ENV、IS_WEBWORKER_ENV等运行环境若availability()返回unavailable说明当前环境无法使用 Transformers.js应直接走服务端回退。量化与推理配置建议browser-ai/transformers-js的模型选项透传 Transformers.js 的加载参数其中最常用的是device与dtypedevice: webgpu使用 GPU 加速详见 WebGPU 指南dtype: q4f16/fp16等指定量化精度显著降低下载体积与内存占用。仓库的 dtypes 指南 说明常用选项包括全精度fp32、半精度fp16、8-bitq8、int8、uint8与 4-bitq4、bnb4、q4f16。在 next-ai-sdk 教程 的models.ts中可以看到实际项目配置示例Qwen3 0.6B 使用{ device: webgpu, dtype: q4f16 }Granite 4.0 350M 使用{ device: webgpu, dtype: fp16 }。若模型仓库同时提供多种 ONNX 量化文件还可以通过ModelRegistry.get_available_dtypes()动态探测可用精度自动挑选最小体积的量化版本。完整实战路径Next.js AI 聊天机器人官方提供了从零搭建一个支持工具调用含人工审批的浏览器端聊天机器人的完整教程Building a Next.js AI Chatbot。其核心步骤可作为上述 API 模式的落地范本创建项目npx create-next-applatest安装ai ai-sdk/react browser-ai/transformers-js huggingface/transformers zodNext.js 配置在next.config.ts中通过 webpack alias 将sharp$、onnxruntime-node$置为false排除服务端专用包确保浏览器 bundle 干净支持output: export静态导出创建 Workersrc/app/worker.ts中实例化TransformersJSWorkerHandler模型配置以ModelConfig列表管理多个模型模型 ID、device、dtype、supportsWorker标志定义工具用tool() Zod 定义getCurrentTime、randomNumber、getLocation后者设置needsApproval: true实现 Transport在sendMessages中先做availability()检查与createSessionWithProgress()进度上报再以createUIMessageStream包装streamText(...).toUIMessageStream()并配合stepCountIs(5)限制工具循环步数构建 UIuseChatTransformersUIMessage按消息 part 类型渲染文本、data-modelDownloadProgress下载进度条与tool-*审批按钮并用lastAssistantMessageIsCompleteWithApprovalResponses让审批后自动继续生成运行验证npm run dev首次发送消息时模型下载并缓存之后直接使用缓存。可尝试触发审批流的提示词如我在哪里。注意本仓库为只读资源以上路径用于自行搭建项目无需修改本仓库文件。小结通过browser-ai/transformers-jsTransformers.js 得以无缝融入 Vercel AI SDK 的统一编程模型文本生成流式/非流式、嵌入、音频转录、视觉问答、工具调用与 UI 状态管理都能在浏览器本地完成。结合 Web Worker 卸载、下载进度追踪、needsApproval人工审批与doesBrowserSupportTransformersJS()服务端回退你可以构建出性能与体验兼备的隐私友好型 AI 应用——用户的文本、图片与音频数据全程留在本机无需上传到任何服务器。进一步阅读Building a Next.js AI Chatbot完整分步教程 —— 从项目创建到工具审批的完整落地实现Running models on WebGPU ——device: webgpu的适用浏览器与加速原理Using quantized models (dtypes) —— 量化精度选择与get_available_dtypes探测Transformers.js 环境变量配置env.js 源码 —— 浏览器缓存、模型路径、日志等级等底层可调项transformers.js 入口导出 —— 了解模型、Pipeline 与工具函数的整体导出【免费下载链接】transformers.jsState-of-the-art Machine Learning for the web. Run Transformers directly in your browser, with no need for a server!项目地址: https://gitcode.com/GitHub_Trending/tr/transformers.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考