# 实时语音识别（阿里云 NLS 版）—— 实现与协议

> **整理时间**：2026-09-23 ｜ **依据**：**实测**（`harness/tools/probe-nls-realtime.mjs`
> 打真实网关逐帧看过载荷）+ 阿里云官方文档要点
> **性质**：现行实现的契约记录。**替换的是旧的厂商 SDK**（`asr-realtime.md` 记录的那套），
> 切换完成后那份文档只作为"旧实现"的历史参考。

## 1. 为什么换、换成了什么

旧的实时语音识别走厂商 metamaker 的中转（`/common/asr_hub?...&engine=aliyun_dashscope`，
`asr-realtime.md` 有完整记录）。2026-09-23 用户要求**换成阿里云 NLS 直连**。

前端这一侧的关键差别：**前端不再持有任何云凭据**。NLS 的 token 要用 AccessKeySecret
签名换取，而 secret 不能进前端产物 —— 所以由服务端换好 token 再下发：

```
浏览器  ──GET /nls-token/──▶  服务端（dev：vite 中间件，见 harness/tools/nls-token.mjs）
                                │  用 AK/SK 签 CreateToken
                                ▼
                            阿里云 nls-meta  ← 返回 token（24h）
浏览器  ◀── { token, expireAt, appkey } ──┘
浏览器  ──wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1?token=…──▶ NLS 网关
```

| 件 | 在哪 |
|---|---|
| 前端取 token（带缓存） | [`src/network/api/nls-token.ts`](../../../src/network/api/nls-token.ts) |
| 协议层（**纯函数**，可被 harness 测） | [`src/three-libs/asr/nls-protocol.ts`](../../../src/three-libs/asr/nls-protocol.ts) |
| 采集与连接（**对外契约与旧 SDK 一致**） | [`src/three-libs/asr/nls.ts`](../../../src/three-libs/asr/nls.ts) |
| 服务端换 token（dev） | `vite.config.ts` 的 `/nls-token/` + [`harness/tools/nls-token.mjs`](../../tools/nls-token.mjs) |
| 验证脚本 | [`harness/tools/verify-nls-realtime.mjs`](../../tools/verify-nls-realtime.mjs)（30 项，含真实识别） |
| 探针（读原始帧用） | [`harness/tools/probe-nls-realtime.mjs`](../../tools/probe-nls-realtime.mjs) |

## 2. 连接与指令

```
wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1?token=<token>
```

客户端发**文本帧**（JSON 指令）与**二进制帧**（音频）：

| 指令 | 关键字段 |
|---|---|
| `StartTranscription` | `header`：`appkey` / `message_id` / `task_id` / `namespace=SpeechTranscriber` / `task=start` / `name`；`payload`：`format=pcm`、`sample_rate=16000`、`enable_intermediate_result=true`、`enable_punctuation_prediction=true`、`enable_voice_detection=true`、`max_sentence_silence`（200~2000，默认用 800） |
| `StopTranscription` | 同 header（`task=stop`、**同一个 task_id**） |

🚨 **两条实测踩出来的硬约束**（都在 `nls-protocol.ts` 里注释了）：

1. **每一条指令都要带 `appkey`** —— 只有 start 带时，stop 会回
   `TaskFailed 40000002 Gateway:MESSAGE_INVALID:Missing message appkey!`
2. **`task_id` 不能是空串** —— 否则回
   `TaskFailed 40000002 Gateway:MESSAGE_INVALID:Invalid task id ''!`
   （所以 `buildStartTranscription` 不传就自己生成，调用方把返回帧里的 task_id 复用到 stop）

## 3. 下行事件与"文本怎么拼"

| 网关事件 | 含义 | 前端产出 |
|---|---|---|
| `TranscriptionStarted` | 开始识别 | `openSocket()` 的 await 在这里 resolve |
| `SentenceBegin` | 一句开始（VAD） | 不产出（状态不变） |
| `TranscriptionResultChanged` | **中间结果** | `transform` 事件 `type=mid`，`transformText` = 已定稿全文 + 本句中间结果 |
| `SentenceEnd` | **一句定稿** | `transform` 事件 `type=fin`，把**整句**追加进全文 |
| `TranscriptionCompleted` | 收尾完成 | `transform()` 的 await 在这里 resolve |
| `TaskFailed` | 出错 | emit `error` + 拒绝 `openSocket()`/`transform()` |

⚠️ **拼接规则（关键）**：中间结果**会被后续结果覆盖**（实测："青浦区高新" → "青浦区高新技术企" →
… 是同一句的逐步增长），所以 **`SentenceEnd` 的整句才是能拼进全文的部分**，
中间结果只用来实时显示。这条已写成断言（`verify-nls-realtime.mjs` 的【1】）。

## 4. 音频

- **16k / 16bit / 单声道 / 小端 PCM**，二进制帧推给网关
- 采集：`getUserMedia` → `MediaStreamAudioSourceNode` → `ScriptProcessorNode`
  （与旧实现同一套；`audioContext` / `source` 仍然暴露给外面画波形，PC 那边在用）
- 重采样：**按 `audioContext.sampleRate` 实际值算**（`encodePcm16kMono(input, fromRate)`）——
  旧实现写死 44100，设备是 48000 时会送出"慢约 8.8% 的 16k"（见旧文档 §9.1），新实现不再沿用
- 节奏：每 **100ms** 推一帧（3200 字节 = 1600 采样）。缓存的音频先攒着，连上后按这个节奏推；
  收尾时把余下的按同样节奏发完再发 `StopTranscription`

## 4.5 延迟：实测数字与「追赶」策略（用户 2026-09-23 报「出字延迟高」）

**先量化，再改**（`probe-nls-realtime.mjs` 会打印「感知延迟 = 麦克风已说多少 − 网关处理到第几毫秒」）：

| 现象 | 实测 |
|---|---|
| 网关**中间结果节奏** | 恒 **~480ms** 一次（`max_sentence_silence` 调 300/800 都不变；开 `enable_semantic_sentence_detection` 也不变）→ **这是引擎固有的**，前端改不了 |
| 网关**首个**中间结果 | 音频开始后约 **480~720ms** |
| 定稿 `SentenceEnd` | 说话停下后 ≈ `max_sentence_silence` + 处理时间（阈值 300 比 800 **早到约 300ms**） |
| **客户端落后**（按 1× 实时推时） | 握手期间攒下的积压**永远排不掉** → 感知延迟**永久 ~1.4s** |

**根因**：连上网关之前（取 token + WS 握手，通常 0.2~1s）麦克风已经开始采集，这段音频先攒着；
如果之后只按 **1× 实时** 排空，积压就一直是那么多 ⇒ 整体恒定慢半拍。
（切过来之前那套厂商 SDK 是按 **2×** 排空的，所以它能追上 —— 这是我这次切换引入的一处退化。）

**改法**：排空策略改成「**平时按实时、积压时最多 4× 追**」
（`NLS_FLUSH_TICK_MS=50`、`NLS_MAX_FRAMES_PER_TICK=2`，见 `nls-protocol.ts`）。
A/B 实测（模拟 1s 握手积压、同一段语音）：

| 排空策略 | 感知延迟（稳定期） | 定稿时 |
|---|---|---|
| 1× 实时 | **1377~1434ms**（且不收敛） | 2087ms |
| **4× 追赶**（现在） | **145~183ms** | 683ms |

另外两处同方向的调整：**停止时的余量按 ~5× 发**（用户此刻正等最后一段文字，不该再按实时节奏等）、
断句阈值默认 **500ms**（网关默认 800，取中：说得快的人不被切断，说一句停一下的人更快看到定稿）。
这三条都有断言守着（`verify-nls-realtime.mjs` 的【2】）。

> 剩下的 ~150ms 是客户端+链路，~480ms 的更新节奏是引擎的 —— 想再快只能换引擎/参数，
> **不要再往客户端"提前发送"上想办法**（文档要求按实时速率发；4× 是追赶积压的上限，不是常态）。

## 5. 对外契约（**与旧 SDK 一致，所以两个壳组件不用改**）

```ts
const asr = new NlsAsr(appKey?, CONSTANTS?);   // appKey 现在是兜底：真正用端点下发的 appkey
await asr.openMicroPhone();                    // 失败抛 Error（NotAllowedError → "权限被拒绝"）
asr.addEventListener('transform', (e) => { inputText.value = e.transformText; });
asr.startRecord();                             // 必须在 openSocket() 之前
await asr.openSocket();                        // 取 token → 连网关 → 等 TranscriptionStarted
const { text } = await asr.transform();        // 停采集 → 发完余量 → StopTranscription → 定稿全文
asr.close();
asr.clear();                                   // 之后实例作废（壳组件置 null）
```

事件负载与旧实现同形：`{ type: 'mid' | 'fin', current, transformText, command }`
（旧实现还有 `breath`，NLS 版没有对应概念 —— 壳组件本来就不区分 `type`，只取 `transformText`）。

## 6. 怎么验证

```bash
npx esbuild harness/tools/_entry-nls.ts --bundle --format=esm \
  --outfile=harness/tools/_nls.mjs --alias:@=./src --define:import.meta.env='{}'
node harness/tools/verify-nls-realtime.mjs
```

- 【1】【2】纯协议与编码（不需要凭据）
- 【3】**真实识别**：用 Windows 自带 TTS 造一段中文语音（`Microsoft Huihui Desktop`），
  按 100ms 推流给真实网关，断言"识别期间有中间结果 + 定稿文本包含关键内容"。
  产物音频落在 `harness/tools/fixtures/_*`（gitignore）。
  没有凭据 / 不是 Windows 时这一段**明确跳过**，不会假装通过。

排查协议问题用探针（它把上下行每一帧原样打出来）：

```bash
node harness/tools/probe-nls-realtime.mjs                          # 只握手
node harness/tools/probe-nls-realtime.mjs --say="青浦区高新技术企业奖励是多少钱"
```

## 7. 现状与未决

- ✅ 协议层、类、token 通路都已实现并**打真实网关验证通过**（39/39，含真实识别）
- ✅ **两个壳组件已切过来**（2026-09-23）：`BusinessAssistantPC.vue` / `BusinessAssistantMobile.vue`
  改为 `import ASR from '@/three-libs/asr/nls'`，并把构造函数里的硬编码 appKey 去掉
  （appkey 由端点下发）。契约一致，所以除了 import 与那一处构造参数，**其余一行没改**
  —— 有源码级断言守着（`verify-nls-realtime.mjs` 的【4】）
- ⏳ **需要用户在浏览器实测一次**：点麦克风说一句 → 输入框应边说边出字；再点一次停止 →
  文本保留。桌面端还应看到波形在动（波形走的是 `audioContext`/`source`，契约没变）
- ⏳ **生产要由后端/网关提供 `/nls-token/`**（技术债 #10），否则线上拿不到 token
- 📌 旧实现（`asr/index.ts`）**保留**：切回它只改 import，且它承载着"厂商中转"那条退路
  （旧实现依赖的 `VITE_ASR` / `VITE_XF_ASR` 仍在四份 env 里）