README.md

5.8 实时识别：边说边出字，名单放在哪一步

这份代码回答两个问题。第一，实时语音识别的延迟花在哪：开口后多久出第一个字，说完后多久拿到最终文字。第二，人名这类上下文，放进识别模型（识别时给 terms），还是放进后面的纠错模型（识别完再交给一个大模型改），哪种做法写对的人名多、代价是多等多久。

有两个脚本：

• run.py：拿模块 2 的示例录音（每条都有脚本原文作标准答案）做对比实验。每条录音按真实语速推给 AI Builder Space 的实时接口，比较五种做法：识别时不给名单；识别时给 terms；识别后交给纠错模型；识别时给 terms 再交给纠错模型；以及作为参考的“说完后整段上传识别”。每种做法数人名写对了几处，再记两个延迟。
• live.py：给你自己用的小工具。对着麦克风说话，文字边说边打印出来；说完按回车，拿到最终文字。也可以用 --file 推一段录音。

需要什么设备

只用 API，任何电脑都行。live.py 用麦克风时需要一个能录音的输入设备。

安装与运行

cd 5_8_realtime
uv venv && source .venv/bin/activate      # 没有 uv 就用 python3 -m venv .venv
uv pip install -r requirements.txt
export AI_BUILDER_TOKEN=sk_你的key

python run.py --lang zh       # 中文示例录音，约 6 分钟，花费约 0.2 美元
python run.py --lang en       # 英文示例录音
python live.py                # 对着麦克风说话，说完按回车
python live.py --terms names.txt          # 识别时带名单，每行一个词

第一次运行 run.py 会自动下载模块 2 的 38 条示例录音（约 13 MB），只用其中提到人名的 23 条。录音是按真实语速推的，模拟一个人正在说话，所以跑得和录音一样长。

实时接口有两个模型：默认的 gpt-live-transcribe，和 --model gpt-realtime。

该看到什么

我们的样例输出在 sample_output/（2026-10-23，Mac Studio 上调用 AI Builder Space，中英文各跑两遍）。23 条录音里一共有 31 处人名、20 处术语：

实时识别开口后约 1.1–1.2 秒出第一段字，之后边说边出。说完到拿到最终文字不到 1 秒，比说完再整段上传快。

几个值得注意的地方：

• 名单放进识别这一步，几乎不增加延迟。 人名从 3 处升到 22–27 处，说完后拿到最终文字的时间没有变化。
• 放进纠错这一步，要多等一次大模型调用，中位数 1.5–1.8 秒。英文里它不如识别时给 terms（20–21 vs 26–27），中文里两者差不多。
• 两种错误不一样，所以两步都做最好。 识别时没有名单，“祁骁”被听成“取消”“其消息”，这些是通顺的真词，纠错模型看不出它们是人名，就留着没改；识别时给了 terms，声音还在，就能写对。反过来，“蔺思远”有几次在识别时给了 terms 还是写错，纠错模型照名单改了回来。两步都做，中文到 29–30 处，英文到 27–28 处。
• 另一个模型的取舍。 用 --model gpt-realtime 跑中文一遍：识别时给 terms 写对 28/31，比默认模型多；但它在说话过程中不出字，第一段文字要等说完、提交以后才来（中位数 12.2 秒，基本就是录音时长）。边说边出字和最终准确率，要按你的场景取舍。

换成你自己的数据

run.py 需要两样东西：一个录音目录（每条一个 <id>.wav），和一个标准答案文件，格式照 memos_zh.json：

{"people": {"人名": "角色说明"}, "terms": ["术语1", "术语2"],
 "memos": [{"id": "001", "text": "这条录音实际说了什么（逐字）"}]}

然后 python run.py --audio 我的录音目录 --memos 我的答案.json。名单（识别时的 terms 和纠错时的名单）用的就是 people 和 terms 两栏。只有提到 people 里人名的录音会参与比较。

录音要是 24 kHz、单声道、16 位的 WAV。手机录的 m4a 之类先转一下：

ffmpeg -i 录音.m4a -ar 24000 -ac 1 -sample_fmt s16 录音.wav

计分规则：某个词在标准答案里出现 n 次，转写里出现 k 次，就算写对 min(n, k) 处。中文忽略大小写和空格按字面匹配，英文按整词匹配，和模块 2 的计分一致。

live.py 的麦克风路径我们在 Mac 上通过一个虚拟音频设备验证过（把录音放进虚拟设备，再从它录进来），没有用真人现场说话测过。