# @azure/ai-speech-transcription 中文文档

规范地址：https://npmcn.com/package/%40azure/ai-speech-transcription/

版本：1\.0\.0
npm 元数据更新时间：2026-05-15T19:14:12.343Z
中文译文更新时间：2026-11-07T15:27:06.382Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azure/ai-speech-transcription
原文对照：https://npmcn.com/package/%40azure/ai-speech-transcription/?lang=original
项目主页：https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/README.md
源码仓库：https://github.com/Azure/azure-sdk-for-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：318 kB，140 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：6 个
- 首次发布：2026-03-15T18:57:46.153Z
- 最新版本发布：2026-05-15T19:14:12.163Z
- 近 30 天下载量：8520（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

生成用于 TranslactionClient 的 SDK .

## 安装

```sh
npm install @azure/ai-speech-transcription
```

也可以使用：`pnpm add @azure/ai-speech-transcription`、`yarn add @azure/ai-speech-transcription`、`bun add @azure/ai-speech-transcription`

## README

# 用于 JavaScript 的 Azure AI Speech Transscript 客户端库

Azure AI Speech Transcription客户端库为Azure的语音对文本的转写服务提供了方便的取用,使您能够高精度地将音频转换为文本.

使用客户端库 :

-   将音频文件转换为文本
-   支持多种语言和语言
-   启用扬声器对号以识别不同的扬声器
-   应用污名过滤
-   使用自定义语音模式
-   处理本地文件和远程 URL
-   使用增强模式进行LLM驱动的转录和翻译

密钥链接 :

-   [源代码](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/src)
-   [软件包( NPM)](https://www.npmjs.com/package/@azure/ai-speech-transcription)
-   [API 参考文件](https://learn.microsoft.com/javascript/api/@azure/ai-speech-transcription?view=azure-node-latest)
-   [产品文档](https://learn.microsoft.com/azure/ai-services/speech-service/overview)

## 开始

### 目前得到支持的环境

-   [节点.js的LTS版本](https://github.com/nodejs/release#release-schedule)
-   最新版本有"萨法里","克罗姆","边缘"和"火狐"等.

看我们的 [支助政策](https://github.com/Azure/azure-sdk-for-js/blob/main/SUPPORT.md) 更多细节.

### 先决条件

-   一个 [Azure 订阅](https://azure.microsoft.com/free/)。 。 。 .
-   一个 [Azure AI 语音资源](https://learn.microsoft.com/azure/ai-services/speech-service/overview#try-the-speech-service-for-free) 或一个 [Azure AI 创始资源](https://learn.microsoft.com/azure/ai-foundry/)。 。 。 .

### 安装 `@azure/ai-speech-transcription` 软件包

为 JavaScript 安装 Azure AI Speech Transcript 客户端库 `npm`数字 :

```bash
npm install @azure/ai-speech-transcription
```

### 创建和认证 a `TranscriptionClient`

要创建访问 Azure Translaction API 的客户端对象, 您需要 `endpoint` 您的 Azure 转录资源和 a `credential`。 。 。 . 您可以在 [Azure 门户](https://portal.azure.com/)。 。 。 .

#### 选项1: API 密钥认证

您可以在 [Azure 门户](https://portal.azure.com/)。 。 。 .

```ts
import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
```

#### 备选案文2:Entra ID认证(建议生产)

对于生产设想,建议使用EntraID认证,并配有管理下的身份或服务负责人. 安装 `@azure/identity` 软件包 :

```bash
npm install @azure/identity
```

您还需要指定合适的角色(例如“认知服务用户”)为您管理的身份或服务负责人。 更多信息见 [Azure AI 服务认证](https://learn.microsoft.com/azure/ai-services/authentication)。 。 。 .

使用节点和类似节点的环境,可以使用 `DefaultAzureCredential` 类来认证客户端.

```ts
import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { DefaultAzureCredential } from "@azure/identity";

const client = new TranscriptionClient("<endpoint>", new DefaultAzureCredential());
```

对于浏览器环境,请使用 `InteractiveBrowserCredential` 从 `@azure/identity` 要认证的软件包.

```ts
import { InteractiveBrowserCredential } from "@azure/identity";
import { TranscriptionClient } from "@azure/ai-speech-transcription";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const client = new TranscriptionClient("<endpoint>", credential);
```

### 服务 API 版本

客户端库默认针对最新的服务API版本. 您可以在即时切换客户端时选择特定支持的 API 版本 :

```ts
import { TranscriptionClient, KnownServiceApiVersions } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"), {
  serviceVersion: KnownServiceApiVersions.V20251015,
});
```

### Java 脚本套装

要在浏览器中使用此客户端库,首先需要使用捆绑器. 关于如何做到这一点的详情,请参见我们 [捆绑文件](https://aka.ms/AzureSDKBundling)。 。 。 .

## 关键概念

### 译名

`TranscriptionClient` 是使用 Azure AI Speech Transscription 客户端库开发者的主要界面. 它提供两个超载 `transcribe` 方法——用于音频二进制数据和音频 URL.

### 音频格式

该服务支持各种音频格式,包括WAV,MP3,OGG,FLAC等. 音频必须是:

-   时间短于2小时
-   体积小于250 MB

### 转写选项

您可以自定义以下选项:

-   **职业过滤**: 控制在抄本中如何处理亵渎行为(`"None"`, (中文(简体) ), `"Masked"`, (中文(简体) ), `"Removed"`, (中文(简体) ), `"Tags"`(中文(简体) )
-   **扬声器斜化**:用多语种音频识别不同的发言者(最多36名发言者)
-   **词组列表**: 提供特定域的短语来提高准确性
-   **语言检测**: 自动检测口语,或指定已知语言
-   **增强模式**:通过LLM驱动的处理、翻译和快速定制,提高文本的质量

## 实例

-   [转写本地音频文件](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-transcribe-a-local-audio-file)
-   [从 URL 转换音频](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-transcribe-audio-from-a-url)
-   [访问单个转写单词](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-access-individual-transcribed-words)
-   [确定扬声器的分号](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-identify-speakers-with-diarization)
-   [过滤污名](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-filter-profanity)
-   [用自定义短语提高准确性](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-improve-accuracy-with-custom-phrases)
-   [用一种已知语言转写](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-transcribe-with-a-known-language)
-   [使用最精确的增强模式](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-use-enhanced-mode-for-highest-accuracy)
-   [用增强模式翻译](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-translate-with-enhanced-mode)
-   [组合多个选项](https://npmcn.com/package/%40azure/ai-speech-transcription/#readme-combine-multiple-options)

### 转写本地音频文件

最基本的操作是从您的本地文件系统中转录一个音频文件:

```ts
import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile);
console.log(`Duration: ${result.durationInMs}ms`);
console.log("Transcription:", result.combinedPhrases[0]?.text);
```

### 从 URL 转换音频

您可以直接从可公开访问的 URL 中转录音频, 而不首先下载文件 :

```ts
import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const result = await client.transcribe("https://example.com/audio/sample.wav", {
  locales: ["en-US"],
});
console.log("Transcription:", result.combinedPhrases[0]?.text);
```

### 访问单个转写单词

获取词层细节,包括时间戳、信心分数和个人单词:

```ts
import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile);
for (const phrase of result.phrases) {
  console.log(`Phrase: ${phrase.text}`);
  console.log(`  Offset: ${phrase.offsetInMs}ms | Duration: ${phrase.durationInMs}ms`);
  console.log(`  Confidence: ${phrase.confidence.toFixed(2)}`);
  // Access individual words in the phrase
  for (const word of phrase.words ?? []) {
    console.log(`    Word: '${word.text}' | Offset: ${word.offsetInMs}ms`);
  }
}
```

### 确定扬声器的分号

在多语种对话中

```ts
import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/conversation.wav");
const result = await client.transcribe(audioFile, {
  diarizationOptions: {
    maxSpeakers: 4, // Expect up to 4 speakers in the conversation
  },
});
for (const phrase of result.phrases) {
  console.log(`Speaker ${phrase.speaker}: ${phrase.text}`);
}
```

> **说明**:确定发言者的总数永远不会超过 `maxSpeakers`。如果实际音频中包含的扬声器比指定的多,则服务将合并它们。 如果您不确定准确的计数, 请设置一个合理的上行 .

### 过滤污名

使用不同的过滤模式控制在复制中如何出现淫秽:

```ts
import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile, {
  profanityFilterMode: KnownProfanityFilterModes.Masked, // Default - profanity replaced with asterisks
});
console.log("Transcription:", result.combinedPhrases[0]?.text);
```

可用模式 :

-   `"None"`:没有过滤——污名作为口语出现
-   `"Masked"`: 纯度被星号所取代(例如, `f***`(中文(简体) )
-   `"Removed"`: 纯度完全从文本中删除
-   `"Tags"`:用XML标签包裹的纯度(如, `<profanity>word</profanity>`(中文(简体) )

### 用自定义短语提高准确性

添加自定义短语来帮助服务正确识别特定域名、名称和缩写:

```ts
import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile, {
  phraseList: {
    phrases: ["Contoso", "Jessie", "Rehaan"],
  },
});
console.log("Transcription:", result.combinedPhrases[0]?.text);
```

### 用一种已知语言转写

当您知道音频的语言时, 指定一个单一的语域会提高准确度并减少延迟 :

```ts
import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/english-audio.mp3");
const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
});
console.log("Transcription:", result.combinedPhrases[0]?.text);
```

关于语言识别,当您不确定语言时,请指定多个候选语言,服务会自动检测语言:

```ts
import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.mp3");
const result = await client.transcribe(audioFile, {
  locales: ["en-US", "es-ES"],
});
for (const phrase of result.phrases) {
  console.log(`[${phrase.locale}] ${phrase.text}`);
}
```

### 使用最精确的增强模式

增强模式使用 LLM 驱动的处理来进行最高精度的转录:

```ts
import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile, {
  // Enhanced mode: LLM-powered speech recognition with prompt customization
  enhancedMode: {
    task: "transcribe",
    prompt: ["Output must be in lexical format."],
  },
  // Existing Fast Transcription options work alongside enhanced mode
  diarizationOptions: {
    maxSpeakers: 2,
  },
  profanityFilterMode: KnownProfanityFilterModes.Masked,
  activeChannels: [0, 1],
});
for (const phrase of result.phrases) {
  console.log(`[Speaker ${phrase.speaker}] ${phrase.text}`);
}
```

### 用增强模式翻译

增强模式还支持将语音翻译为目标语言:

```ts
import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/chinese-audio.wav");
const result = await client.transcribe(audioFile, {
  enhancedMode: {
    task: "translate",
    targetLanguage: "ko", // Translate to Korean
  },
  profanityFilterMode: KnownProfanityFilterModes.Masked,
});
console.log("Translated to Korean:", result.combinedPhrases[0]?.text);
```

### 组合多个选项

可以结合多个转录功能,用于复杂的情景:

```ts
import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/meeting.wav");
const result = await client.transcribe(audioFile, {
  // Enable speaker diarization
  diarizationOptions: {
    maxSpeakers: 5,
  },
  // Mask profanity
  profanityFilterMode: KnownProfanityFilterModes.Masked,
  // Add custom phrases
  phraseList: {
    phrases: ["action items", "Q4", "KPIs"],
  },
});
console.log("Full Transcript:");
console.log(result.combinedPhrases[0]?.text);
for (const phrase of result.phrases) {
  console.log(`Speaker ${phrase.speaker}: ${phrase.text}`);
}
```

## 解决问题

### 共同问题

-   **认证失败**: 验证您的 API 密钥或 Entra ID 证书正确, 且您的 Speech 资源已激活 .
-   **不支持的音频格式**:确保您的音频使用支持格式(WAV,MP3,OGG,FLAC等). 该服务自动处理格式检测.
-   **慢速抄录**:对于大文件,确保您的网络连接稳定.
-   **准确性差**:尝试指定正确的地块,为特定域名添加自定义短语,或者使用增强模式.

### 日志

允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 `AZURE_LOG_LEVEL` 环境变量改为 `info`。或者,可以在运行时拨打 `setLogLevel` 输入 `@azure/logger`数字 :

```ts
import { setLogLevel } from "@azure/logger";

setLogLevel("info");
```

关于如何启用日志的更详细指示,您可以查看 [@ azure/ logger 包文件](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger)。 。 。 .

## 今后的步骤

探索更多样本,以更多地了解先进特征:

-   [基本译名](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/samples-dev/basicTranscription.ts) - 创建客户和基本记录
-   [转写选项](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/samples-dev/transcriptionOptions.ts) - 合并多种抄录功能
-   [从 URL 转写](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/samples-dev/transcriptionFromUrl.ts) - 从远程 URL 转写
-   [增强模式](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/samples-dev/enhancedMode.ts) - LLM功率记录和翻译
-   [职业过滤](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/samples-dev/profanityFiltering.ts) - 所有亵渎过滤模式
-   [扬声器分割](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/samples-dev/speakerDiarization.ts) - 议长身份鉴定
-   [词组列表](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/samples-dev/phraseList.ts) - 自定义词汇
-   [用语言进行转写](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/samples-dev/transcriptionWithLocale.ts) - 语言规格和检测
-   [多语种译名](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/transcription/ai-speech-transcription/samples-dev/multilingualTranscription.ts) - 多语种内容(审查)

## 捐款

如果您想为图书馆捐钱 请读一下 [贡献指南](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) 学习如何构建和测试密码.

## 相关项目

-   [微软 Azure SDK 用于 JavaScript](https://github.com/Azure/azure-sdk-for-js)

## 常见问题

### @azure/ai-speech-transcription 是什么？

生成用于 TranslactionClient 的 SDK \.

### 如何安装 @azure/ai-speech-transcription？

在项目目录运行 npm install @azure/ai-speech-transcription，或使用 pnpm add / yarn add / bun add。

### @azure/ai-speech-transcription 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azure/ai-speech-transcription 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @azure/ai-speech-transcription 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azure/ai-speech-transcription 可以商用吗？

@azure/ai-speech-transcription 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @azure/ai-speech-transcription 的下载量有多少？

根据 npm 官方下载统计，@azure/ai-speech-transcription 在 2026/10/08 – 2026/11/06 这 30 天内被下载 8,520 次，日均约 284 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @azure/ai-speech-transcription 还在维护吗？

最新版本 1\.0\.0 发布于 2026/05/16（5 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/03/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。