在人工智能浪潮席卷全球的今天，语音转文字（Automatic Speech Recognition, ASR）技术已成为许多应用的核心功能，从会议纪要、语音输入到媒体内容分析，无处不见其身影。本文将通过一个具体的 Node.js 代码示例，向您展示如何调用 SiliconFlow 的高性能音频转写 API，将本地音频文件快速、准确地转换为文字。
我们将深入分析一段用于实现该功能的 JavaScript 代码，不仅解释其工作原理，还将探讨其中涉及的关键技术和最佳实践。
概述
本文的核心目标是利用 Node.js 环境，向 SiliconFlow 的音频转写接口发送一个 POST 请求。这个请求会将一个本地的 MP3 音频文件上传，并获取服务端模型转写后的文本结果。我们将要分析的代码中处理文件读取、数据封装和 API 请求的全过程。
技术栈
要完整理解并运行本示例，您需要熟悉以下几个核心技术：
-
Node.js: 一个基于 Chrome V8 引擎的 JavaScript 运行时，让我们可以在服务器端执行 JavaScript 代码。示例中使用了其内置的 fs/promises 模块进行异步文件操作，以及原生的 fetch API 来发送网络请求。
-
Fetch API: 一个现代的、基于 Promise 的网络请求接口，现已在 Node.js v18 及以上版本中作为全局可用功能，无需安装额外依赖。
-
FormData: 一个用于构建 multipart/form-data 请求体的 Web API，同样在 Node.js 环境中原生支持。这对于上传文件至关重要。
-
SiliconFlow 音频转写 API: 一个提供高性能语音识别服务的云端接口。本次示例中使用的 FunAudioLLM/SenseVoiceSmall 模型。
拓展详解
在深入代码之前，我们先来探讨几个关键的技术点。
为什么是 Buffer 和 Blob？
在 Node.js 中处理文件时，我们首先接触到的是文件路径。然而，网络请求（特别是文件上传）并不能直接发送一个路径字符串，而是需要发送文件的二进制内容。
-
fs.readFile 与 Buffer: fs/promises.readFile(filePath) 是一个异步函数，它会读取指定路径的全部文件内容，并将其加载到内存中。如果不指定编码，返回的数据就是一个 Buffer 对象。Buffer 是 Node.js 用来高效处理二进制数据的专用对象。
-
Blob 的角色: Blob（Binary Large Object）是一个通用的、表示文件类对象的 Web API。fetch API 在设计上与浏览器环境保持一致，它原生支持 Blob 对象。通过 new Blob([fileBuffer], { type: "audio/mpeg" })，我们将 Node.js 的 Buffer 封装成一个 Blob 实例，并指定其 MIME 类型。
FormData 与 multipart/form-data
当你的 HTTP 请求需要同时发送文本字段（如模型名称）和文件（如音频数据）时，multipart/form-data 便是标准的数据格式。FormData 对象正是为此而生。
-
自动生成请求体: FormData 接口简化了构建这种复杂请求体的过程。你只需通过 .append() 方法添加键值对即可。
-
关键的 boundary: multipart/form-data 请求通过一个特殊的 "boundary" 字符串来分隔不同的数据部分。
-
为何不能手动设置 Content-Type: 这是一个非常重要的实践！当你将 FormData 对象作为 fetch 请求的 body 时，fetch 会自动为你生成正确的 Content-Type 头部，其中包含了独一无二的 boundary 字符串。 如果你手动设置 Content-Type: 'multipart/form-data'，fetch 将无法附加这个必需的 boundary，从而导致服务端无法解析请求体，请求最终失败。
文件名的重要性
在 form.append("file", fileBlob, path.basename(filePath)); 这行代码中，第三个参数 path.basename(filePath) 提供了文件名。这个参数虽然可选，但在实际应用中至关重要。它会被包含在 Content-Disposition 头部中发送给服务器。服务器可以依据这个文件名来识别文件类型、进行存储或进行其他处理。
代码分析
import fs from "fs/promises"; // 使用 promises 版本的 fs
import path from "path";
// API 配置信息
const url = "https://api.siliconflow.cn/v1/audio/transcriptions";
const apiKey = "sk-**************"; // 建议从 .env 文件读取
const filePath = "./converted.mp3";
代码首先导入了 Node.js 内置的 fs/promises 和 path 模块，并定义了 API 的 URL、密钥和本地文件路径。在生产环境中，强烈建议将 apiKey 等敏感信息存储在环境变量或 .env 文件中，而不是硬编码在代码里。我这里是硅基流动提供的免费api，需要的同学可以使用我的邀请码注册：IX1HEqHs
// --- 开始修改 ---
// 1. 异步读取文件内容到一个 Buffer 中
const fileBuffer = await fs.readFile(filePath);
// 2. 从 Buffer 创建一个 Blob 对象
const fileBlob = new Blob([fileBuffer], { type: "audio/mpeg" });
// 3. 构建 FormData
const form = new FormData();
form.append("model", "FunAudioLLM/SenseVoiceSmall");
// 4. 将 Blob 添加到 form 中，并提供第三个参数作为文件名
form.append("file", fileBlob, path.basename(filePath));
// --- 修改结束 ---
这是整个流程的核心部分：
-
fs.readFile(filePath): 异步读取 converted.mp3 文件的二进制内容，并存入 fileBuffer。
-
new Blob(...): 将 fileBuffer 封装成 Blob 对象，并明确其 MIME 类型为 audio/mpeg。
-
new FormData(): 创建一个空的 FormData 实例。
-
form.append(...):
-
添加 model 字段，值为 "FunAudioLLM/SenseVoiceSmall"，指定转写所用的模型。
-
添加 file 字段，值为我们创建的 fileBlob。同时，使用 path.basename(filePath) 提取并提供了原始文件名 "converted.mp3"。
-
const options = {
method: "POST",
headers: {
Authorization: "Bearer " + apiKey,
// 注意：使用 FormData 时，不要手动设置 Content-Type。
// fetch 会自动为你生成正确的 `multipart/form-data` 类型和 boundary。
},
body: form,
};
这里定义了 fetch 请求的配置对象。
-
method: "POST"，因为我们要上传数据。
-
headers: 只设置了 Authorization 头部用于身份验证。注释中明确强调了不要手动设置 Content-Type，这是遵循最佳实践的关键。
-
body: 直接将构建好的 form 对象作为请求体。
try {
console.log("正在发送请求到服务器...");
const response = await fetch(url, options);
// 检查响应状态码，更稳健的错误处理
if (!response.ok) {
const errorText = await response.text();
throw new Error(`请求失败，状态码: ${response.status}, 响应: ${errorText}`);
}
const data = await response.json();
console.log("转写结果：", data);
} catch (error) {
console.error("请求出错：", error);
}
最后，代码使用 try...catch 块来执行异步请求并处理可能出现的错误。
-
await fetch(url, options): 发送请求并等待服务器响应。
-
!response.ok: 这是一个稳健的错误检查。response.ok 会在 HTTP 状态码为 200-299 时为 true。如果请求失败（如4xx或5xx错误），代码会读取响应体中的错误文本并抛出一个包含详细信息的错误，这对于调试非常有帮助。
-
await response.json(): 如果请求成功，将响应体解析为 JSON 格式。
-
console.log/error: 在控制台打印成功的结果或捕获到的错误。
总结
本文通过分析一段具体的 Node.js 代码，详细阐述了如何调用 SiliconFlow 的音频转写 API。我们不仅理解了代码的执行流程，还深入探讨了 Buffer、Blob 和 FormData 在文件上传中的作用，并强调了在使用 fetch 和 FormData 时一个至关重要的注意事项——让浏览器或 Node.js 自动处理 Content-Type 头部。
扫一扫
320
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
