> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 语音识别（ASR）

> 使用在 Qualcomm NPU 上运行的设备端 ASR 模型将音频转录为文本。

ASR 服务使用完全在 Qualcomm NPU 上运行的设备端模型将音频转录为文本。它同时支持基于文件的批量转录和通过 WebSocket 的实时流式转录。

## 前提条件

确保 Audio Analytics 容器已部署并正在运行。有关设置说明，请参阅[运行 Audio Analytics 容器](/zh/ai-workflows/audio-analytics-overview)。

## 音频格式要求

| 属性     | 要求                                               |
| ------ | ------------------------------------------------ |
| 格式     | 仅限 WAV                                           |
| 采样率    | 需要 16 kHz。如果您的音频采样率不同，请在创建请求中通过 `parameters` 声明。 |
| 声道     | 单声道（自动转换）                                        |
| 最大文件大小 | 25 MB                                            |

## 可用模型

查询模型端点以获取可用 ASR 模型列表：

```bash theme={null}
curl http://localhost:8085/audio-analytics/v1/api/transcriptions/models
```

**响应：**

```json theme={null}
[
  {
    "name": "whisper-small-quantized",
    "display_name": "Whisper Small (Quantized)",
    "description": "OpenAI whisper-small-quantized model for general transcription"
  }
]
```

在转录请求中使用此响应中的 `name` 值。

## 端点

| 方法     | 端点                       | 描述           |
| ------ | ------------------------ | ------------ |
| `GET`  | `/transcriptions/models` | 列出可用的 ASR 模型 |
| `POST` | `/transcriptions/create` | 转录文件或启动流式会话  |
| `POST` | `/transcriptions/close`  | 关闭活跃的流式会话    |
| `POST` | `/transcriptions/flush`  | 强制立即处理缓冲的音频  |

## 文件转录

上传 WAV 文件并在单个响应中接收完整转录结果：

```bash theme={null}
curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/create \
  -F "file=@recording.wav" \
  -F "model=whisper-small-quantized" \
  -F "language=en" \
  -F "stream=false"
```

**响应：**

```json theme={null}
{
  "text": "The transcribed text from your audio file.",
  "language": "en",
  "language_name": "English",
  "type": "transcript.text.done"
}
```

将 `language` 设置为模型支持的语言代码，或省略该参数以进行自动检测。

## 带流式结果的文件转录

上传完整的 WAV 文件，并在文件处理过程中通过 WebSocket 接收转录结果：

```bash theme={null}
curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/create \
  -F "file=@recording.wav" \
  -F "model=whisper-small-quantized" \
  -F "language=en" \
  -F "stream=true"
```

服务器确认上传并开始处理。连接到 WebSocket 以接收结果。

**WebSocket 结果：**

```json theme={null}
{ "state": "connection_established" }
{ "type": "transcript.text.done", "text": "The transcribed text.", "language": "en", "language_name": "English", "state": "transcription" }
```

## 实时音频流

实时发送原始音频数据块，并在说话的同时接收转录结果。

### 第 1 步 - 创建会话

如果您的音频不是 16 kHz 单声道 PCM，请通过 `parameters` 声明音频格式：

```bash theme={null}
curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/create \
  -H "Content-Type: application/json" \
  -d '{
    "model": "whisper-small-quantized",
    "language": "en",
    "stream": true,
    "vad": 1200,
    "parameters": [
      {"key": "sampling_rate", "value": "44100"},
      {"key": "channels", "value": "1"},
      {"key": "format", "value": "pcm_s16le"}
    ]
  }'
```

**响应：**

```json theme={null}
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "asr_initialized",
  "text": "Successfully started Transcription Engine. Please connect to the WebSocket to send audio data & receive transcription output.",
  "language": "en",
  "type": "transcript.event"
}
```

`vad` 参数设置检测到语音结束前的静音等待时长（毫秒）。省略该参数可禁用 VAD，并通过 `/transcriptions/flush` 或 `/transcriptions/close` 手动管理语句结束。

### 第 2 步 - 连接 WebSocket 并发送音频

连接到 `ws://localhost:8085/stream`。服务器在连接后、任何转录消息到达之前会先发送 `connection_established` 消息：

```json theme={null}
{ "state": "connection_established" }
```

通过 WebSocket 以 8192 字节的数据块发送音频：

```javascript theme={null}
const ws = new WebSocket('ws://localhost:8085/stream');

ws.send(JSON.stringify({
  "message_type": "transcriptions_session_audio",
  "message_source": "audio_analytics_api",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "input_audio",
  "data": "<BASE64_ENCODED_PCM>"
}));
```

### 第 3 步 - 接收结果

服务器针对每个语句发出如下序列：

```json theme={null}
{ "type": "transcript.event", "state": "speech_start", "session_id": "..." }
{ "type": "transcript.text.delta", "text": "Partial text...", "language": "en", "session_id": "..." }
{ "type": "transcript.event", "state": "speech_end", "session_id": "..." }
{ "type": "transcript.text.done", "text": "Complete utterance text.", "language": "en", "state": "transcription", "session_id": "..." }
```

在 `transcript.text.done` 之后，引擎会重置并监听下一条语句。会话保持打开状态，直到您调用 `/transcriptions/close`。

### 第 4 步 - 关闭会话

```bash theme={null}
curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/close \
  -H "Content-Type: application/json" \
  -d '{"session_id": "550e8400-e29b-41d4-a716-446655440000"}'
```

**响应：**

```json theme={null}
{
  "text": "",
  "language": null,
  "type": "asr_closed",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "asr_closed"
}
```

<Note>同一时间只能有一个活跃的 ASR 会话。在已有活跃会话时启动第二个会话会返回 HTTP `409 Conflict`。请先关闭现有会话。</Note>

## 语音活动检测（VAD）

VAD 控制服务器在流式会话期间如何检测语句的结束。当检测到静音持续达到配置的时长时，服务器会针对当前语句发出 `speech_end`，随后发出 `transcript.text.done`。会话保持打开并为下一条语句重置——VAD 不会关闭会话。

| 参数    | 描述                                                                                                                                |
| ----- | --------------------------------------------------------------------------------------------------------------------------------- |
| `vad` | 触发 `speech_end` 之前的静音等待时长（毫秒）。例如，`1200` = 1.2 秒静音触发语句结束。省略可禁用 VAD，并通过 `/transcriptions/flush` 或 `/transcriptions/close` 手动管理语句结束。 |

<Note>如果在容器配置中 `SESSION_TIMEOUT_S`（默认：30 秒）设置的时长内未收到音频，无论 VAD 状态如何，会话都会自动关闭。</Note>

## 冲刷缓冲的音频

在不关闭会话的情况下强制立即转录缓冲的音频：

```bash theme={null}
curl -X POST http://localhost:8085/audio-analytics/v1/api/transcriptions/flush \
  -H "Content-Type: application/json" \
  -d '{"session_id": "550e8400-e29b-41d4-a716-446655440000"}'
```

## Python 示例

```python theme={null}
import requests

def transcribe_file(audio_file, language=None):
    url = "http://localhost:8085/audio-analytics/v1/api/transcriptions/create"
    data = {
        "model": "whisper-small-quantized",
        "stream": "false"
    }
    if language:
        data["language"] = language
    with open(audio_file, "rb") as f:
        response = requests.post(url, files={"file": f}, data=data, timeout=60)
    response.raise_for_status()
    return response.json()["text"]

print(transcribe_file("sample.wav"))
```

## 故障排除

**转录质量差：** 请使用 16 kHz 单声道 WAV 文件，并确保音频清晰、背景噪音最小。

## 后续步骤

<CardGroup cols={2}>
  <Card title="文本转语音" icon="volume-high" href="/zh/ai-workflows/tts-container">
    在设备端将文本合成为语音
  </Card>

  <Card title="语言翻译" icon="language" href="/zh/ai-workflows/language-translation">
    在设备端进行跨语言文本翻译
  </Card>
</CardGroup>