demo.py
demo.py
"""
实验 9-4 配套 demo:端到端语音思考 vs 级联流水线(真实跑通两条路并对照)。
书中实验 9-4 的核心是端到端语音思考模型 Step-Audio R1(直接「听→想→说」)。
Step-Audio R1 需多卡 GPU 部署、无公开 endpoint,本 demo 因此用 OpenAI 的
speech-to-speech 模型 `gpt-audio` 作为**真实可跑的端到端代表**(音频进、单模型、
音频出,无独立 ASR/LLM/TTS 三段),与**级联基线**(whisper-1 → gpt-5.6-luna → tts-1)
同题对照,两条路的延迟都是真实测得、两段输出音频都用 ffprobe 校验。
流程:
1. 用 TTS 合成一段「用户提问」的语音(一道需要多步推理的数学题,Spoken-MQA 风格),
作为两条管道共同的输入;
2. 端到端:一次 gpt-audio 调用,音频进 → 语音答案 + 转写出(单模型融合);
3. 级联:whisper-1 转写 → gpt-5.6-luna 思考 → tts-1 合成回答语音(三段串行);
4. 打印两条路的真实延迟对照,并用 ffprobe 确认两段输出音频真实生成;
5. 给出端到端 vs 级联的范式对照(延迟、副语言信息损失),并引用书中表 9-1。
"""
from __future__ import annotations
import argparse
import json
import os
import shutil
import subprocess
import sys
from pathlib import Path
from dotenv import load_dotenv
from openai import OpenAI
from speech_model import (
CascadedSpeechModel,
EndToEndSpeechModel,
PipelineResult,
synthesize_question_audio,
)
HERE = Path(__file__).parent
AUDIO_DIR = HERE / "audio"
# 一道需要多步推理的口述数学题(Spoken-MQA 风格:先听懂,再多步计算)
USER_QUESTION = (
"小明有 12 块钱,他买了 3 支铅笔,每支 2 块钱,"
"然后又用剩下的钱买了尽可能多的、每块 1 块 5 的橡皮,"
"请问他最后还剩多少钱?"
)
# 一句「答案取决于怎么说」的话:字面是顺从/无所谓,真实情绪要靠语气、语速、语调
# 才能判断(是真的没意见,还是无奈、赌气)。这类副语言(Paralinguistic)任务正是
# 端到端相对级联的分水岭——见 chapter9.md「文本代理思考」与 MGRD。
PARALINGUISTIC_QUESTION = "行吧,那就这样吧,我没什么意见。"
# 两类任务,对应书中两条对照轴:
# math —— 语义任务:级联与端到端准确率相当(书 9.3「自级联」一节),主看延迟。
# paralinguistic—— 副语言任务:答案取决于「怎么说」。级联在 ASR 处把语音压成纯文本,
# LLM 只能凭字面猜情绪(书中「文本代理思考」);端到端直接听声学特征。
TASKS: dict[str, dict] = {
"math": {
"question": USER_QUESTION,
"e2e_prompt": (
"你是一个中文语音助手。请先在内部完成必要的推理,再用简洁、口语化、"
"适合朗读的中文说出结论,控制在三句话以内。"
),
"cascade_prompt": (
"你是一个语音助手。请先进行必要的推理,再给出简洁、口语化、"
"适合朗读的中文回答。回答控制在三句话以内。"
),
"axis": (
"语义(Spoken-MQA 风格):答案只取决于「说了什么」。级联与端到端准确率相当,"
"本任务主要对照【延迟】维度。"
),
},
"paralinguistic": {
"question": PARALINGUISTIC_QUESTION,
"e2e_prompt": (
"你是一个中文语音助手。请先判断说话人的情绪、语速和语调(尽量依据声学特征"
"本身,而非仅凭字面意思),说出你听到的语气,再据此给出体贴、口语化、"
"适合朗读的中文回应,三句以内。"
),
"cascade_prompt": (
"你是一个中文语音助手。请先判断说话人的情绪、语速和语调,说出你听到的语气,"
"再据此给出体贴、口语化、适合朗读的中文回应,三句以内。"
),
"axis": (
"副语言(Paralinguistic):答案取决于「怎么说」。级联的 LLM 只拿得到 ASR 纯"
"文本,任何情绪判断都是「文本代理思考」(凭字面猜);端到端直接听声学特征。"
"本任务对照【信息损失】维度。注意:默认输入由 TTS 合成、情感偏平,差异被削弱;"
"用 --audio-input 喂一段真实带情绪的录音,对照会明显得多。"
),
},
}
def hr(char: str = "-", n: int = 68) -> str:
return char * n
def ffprobe_info(audio_path: str) -> dict:
"""用 ffprobe 读取音频真实信息(时长、格式、码率),确认文件已生成。"""
if not shutil.which("ffprobe"):
return {"error": "未安装 ffprobe,跳过音频校验(brew install ffmpeg)"}
try:
out = subprocess.run(
[
"ffprobe", "-v", "error",
"-show_entries", "format=duration,format_name,bit_rate,size",
"-of", "json", audio_path,
],
capture_output=True, text=True, check=True,
)
fmt = json.loads(out.stdout).get("format", {})
return {
"格式": fmt.get("format_name"),
"时长(秒)": round(float(fmt.get("duration", 0)), 2),
"码率(bps)": fmt.get("bit_rate"),
"文件大小(字节)": fmt.get("size"),
}
except Exception as e: # noqa: BLE001
return {"error": f"ffprobe 失败:{e}"}
def print_e2e_result(result: PipelineResult, backend: str) -> None:
s = result.stages[0]
print(hr("="))
print(f"范式一:端到端语音思考(后端={backend},模型={s.model})")
print(hr("="))
print("形态:音频进 → 单模型「听→想→说」→ 音频出(一次调用,无独立 ASR/LLM/TTS 段)")
print(f"\n[单阶段] {s.name} | 延迟={s.latency_s:.2f}s")
if s.text is not None:
print(f" 语音答案转写(模型顺带产出,非中间文本阶段):{s.text}")
print(f" 语音答案:{s.audio_path}")
print(f" ffprobe 校验:{ffprobe_info(s.audio_path)}")
print(f"\n端到端总延迟(单模型一次前向):{result.total_latency_s:.2f}s")
def print_cascade_result(result: PipelineResult) -> None:
print("\n" + hr("="))
print(f"范式二(对照基线):级联流水线 ASR → LLM → TTS")
print(hr("="))
for i, s in enumerate(result.stages, 1):
print(f"\n[阶段 {i}] {s.name} | 模型={s.model} | 延迟={s.latency_s:.2f}s")
if s.text is not None:
print(f" 文本:{s.text}")
if s.audio_path is not None:
print(f" 音频:{s.audio_path}")
print(f" ffprobe 校验:{ffprobe_info(s.audio_path)}")
print(f"\n级联总延迟(各阶段串行相加):{result.total_latency_s:.2f}s")
def print_comparison(e2e: PipelineResult, e2e_backend: str, cas: PipelineResult,
task: str) -> None:
"""打印端到端 vs 级联的真实对照(实测延迟)+ 范式概念差异 + 书中表 9-1(引用)。"""
stages = {s.name: s for s in cas.stages}
asr = stages["ASR 语音识别"]
llm = stages["LLM 思考"]
tts = stages["TTS 语音合成"]
print("\n" + hr("="))
print("端到端 vs 级联:真实对照")
print(hr("="))
print(f"\n【任务】{task}:{TASKS[task]['axis']}")
print("\n【1】实测总延迟(本次运行,随网络与负载波动)")
print(f" 端到端({e2e_backend},单模型一次调用):{e2e.total_latency_s:.2f}s")
print(f" 级联 ASR({asr.latency_s:.2f}s) + LLM({llm.latency_s:.2f}s) "
f"+ TTS({tts.latency_s:.2f}s) = {cas.total_latency_s:.2f}s(三段串行累加)")
delta = cas.total_latency_s - e2e.total_latency_s
faster = "端到端更快" if delta > 0 else "级联更快"
print(f" 差值:{abs(delta):.2f}s({faster})。注意端到端是「一次前向出整段音频」,"
"真流式端到端还能「边想边说」把首字延迟进一步压低;级联的三段则天然串行累加。")
print("\n【2】信息损失(副语言 / 语气)——范式差异,非本次延迟数字")
print(" 级联在 ASR 处把语音压成纯文本,说话人的情绪、语速、语调、重音、停顿,")
print(" 以及背景环境声/音乐在交接时几乎全部丢失——LLM 只看到「说了什么」,")
print(" 看不到「怎么说的」。本次输入语音在 ASR 处被抹平为纯文本:")
print(f" ASR 文本 → 「{asr.text}」")
print(" 端到端模型在隐空间(Latent Space)中直接传递这些副语言信息,能感知")
print(" 情绪/语速/语调,并据此生成有表现力、韵律匹配的回复。")
print(" 两条路对同一段音频的回答(可直观对比是否「听到了怎么说」):")
print(f" 级联(只凭 ASR 文本,文本代理思考)→ 「{llm.text}」")
print(f" 端到端(直接听声学特征) → 「{e2e.stages[0].text}」")
print("\n【3】书中表 9-1:Step-Audio R1 不同语音思考配置(引自 Step-Audio R1 论文,"
"非本 demo 产出)")
print(" 配置 Spoken-MQA URO-Bench")
print(" 不思考直接回答(基线) 70.6% 77.4")
print(" MPS Speak-First(零延迟) 92.8% 82.5")
print(" MPS Think-First(~80 tok 延迟) 93.9% 84.8")
print(" 完整 TBS(无延迟约束) 93.0% —")
print(" 出处:Step-Audio R1 论文(书中表 9-1 转引)。这些是论文报告的评测分数,")
print(" 不是本 demo 跑出来的——本 demo 只产出上面【1】的真实延迟与两段真实音频。")
print(" 要点:Speak-First 几乎不损推理精度(92.8% ≈ TBS 93.0%),因为 CoT")
print(" 开头往往只是复述问题;这正是端到端「边想边说」能低延迟又不失准的原因。")
print("\n【4】取舍小结")
print(" 级联:模块清晰、每段可独立调优、可解释性好;但延迟串行累加、副语言损失大。")
print(" 端到端:延迟更低、保留非文字信息、韵律自然;代价是训练数据需求大、")
print(" 可解释性差。二者在 2026 年的生产系统中长期并存。")
def parse_args() -> argparse.Namespace:
p = argparse.ArgumentParser(
prog="demo.py",
description="实验 9-4:端到端语音思考 vs 级联流水线。合成(或读取)一段「用户"
"提问」语音,同题跑通端到端(gpt-audio,可切 Step-Audio R1)与级联"
"(whisper-1 → gpt-5.6-luna → tts-1),打印真实延迟与信息损失对照。",
epilog="示例:\n"
" python demo.py # 默认:数学题,端到端+级联对照\n"
" python demo.py --task paralinguistic # 副语言任务:凸显端到端优势\n"
" python demo.py --audio-input my_voice.wav # 用真实录音作输入(更能体现语气差异)\n"
" python demo.py --e2e-model gpt-audio --voice nova --output-dir out\n"
" python demo.py --step-audio-endpoint http://localhost:8000/v1/audio/chat",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
p.add_argument("--task", choices=sorted(TASKS), default="math",
help="任务类型:math=口述数学题(语义任务,主看延迟);"
"paralinguistic=副语言任务(答案取决于「怎么说」,凸显端到端"
"对级联的优势)。默认 math。")
p.add_argument("--question", default=None,
help="自定义口述提问文本,覆盖 --task 的默认题目。与 --audio-input 互斥。")
p.add_argument("--audio-input", metavar="FILE", default=None,
help="直接用一段已有的音频文件(.wav/.mp3)作为输入,跳过 TTS 合成"
"提问;适合喂真实带情绪的录音。与 --question 互斥。")
p.add_argument("--e2e-model", default=None,
help="端到端 speech-to-speech 模型名(默认取环境变量 E2E_MODEL,"
"再默认 gpt-audio)。")
p.add_argument("--step-audio-endpoint", default=None,
help="自部署的 Step-Audio R1 服务地址;给定后端到端一路改走它"
"(覆盖环境变量 STEP_AUDIO_ENDPOINT)。")
p.add_argument("--voice", default="alloy",
help="回答语音音色(端到端与级联 TTS 共用,默认 alloy)。")
p.add_argument("--output-dir", metavar="DIR", default=None,
help="音频输出目录(默认为脚本同级的 audio/)。")
p.add_argument("--skip-cascade", action="store_true",
help="只跑端到端,不跑级联对照基线。")
args = p.parse_args()
if args.question and args.audio_input:
p.error("--question 与 --audio-input 互斥,请二选一。")
return args
def _map_openrouter_model(model: str) -> str:
"""把常见模型名映射为 OpenRouter 的 provider/model 形式。"""
if "/" in model:
return model
if model.startswith("gpt-"):
return "openai/" + model
if model.startswith("claude-"):
return "anthropic/claude-opus-4.8"
return "openai/gpt-5.6-luna"
def _resolve_llm_client(openai_client: OpenAI):
"""为级联的纯文本 LLM 思考选路:优先 OpenRouter,否则回落到 OpenAI 直连。
返回 (client, model, route_label)。ASR/TTS/端到端音频仍固定用 openai_client。
"""
model = os.getenv("LLM_MODEL") or os.getenv("OPENAI_MODEL") or "gpt-5.6-luna"
if os.getenv("OPENROUTER_API_KEY"):
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.getenv("OPENROUTER_API_KEY"),
timeout=120.0,
max_retries=3,
)
return client, _map_openrouter_model(model), "OpenRouter"
return openai_client, model, "OpenAI 直连"
def main() -> int:
args = parse_args()
task = args.task
task_cfg = TASKS[task]
question = args.question or task_cfg["question"]
load_dotenv(HERE / ".env")
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
print("错误:未配置 OPENAI_API_KEY。端到端 gpt-audio 与级联的 ASR(whisper)/TTS(tts-1) "
"都是音频端点,只有 OpenAI 直连才有——OpenRouter 无音频端点,故本实验必须提供"
" OpenAI 直连 Key。请复制 env.example 为 .env 并填入。", file=sys.stderr)
return 1
# 音频客户端:端到端 gpt-audio、级联的 whisper/tts 都必须走 OpenAI 直连。
# timeout + 自动重试:单次网络/SSL 抖动不至于让整条流水线崩溃
client = OpenAI(api_key=api_key, timeout=120.0, max_retries=3)
# 级联中间的纯文本 LLM 思考:优先走 OpenRouter(绕开 gpt-5.6* 直连的组织实名认证),
# 没有 OPENROUTER_API_KEY 时回落到上面的 OpenAI 直连客户端。
llm_client, llm_model, llm_route = _resolve_llm_client(client)
out_dir = Path(args.output_dir) if args.output_dir else AUDIO_DIR
out_dir.mkdir(parents=True, exist_ok=True)
e2e_audio = str(out_dir / "answer_end_to_end.wav")
cascade_audio = str(out_dir / "answer_cascade.mp3")
# -- 步骤 1:准备「用户提问」语音(两条管道共同输入) ----------------------
print(hr("="))
print(f"步骤 1:准备一段「用户提问」语音(任务={task},作为两条管道共同的输入)")
print(hr("="))
if args.audio_input:
question_audio = args.audio_input
if not Path(question_audio).is_file():
print(f"错误:--audio-input 指定的音频文件不存在:{question_audio}",
file=sys.stderr)
return 1
print(f"使用已有输入音频(跳过 TTS 合成):{question_audio}")
print("提问文本:(未知,来自音频文件,将由级联的 ASR 转写还原)")
else:
question_audio = str(out_dir / "user_question.mp3")
print(f"提问文本:{question}")
synthesize_question_audio(client, question, question_audio)
print(f"已用 TTS 合成输入音频:{question_audio}")
print(f"ffprobe 校验:{ffprobe_info(question_audio)}")
# -- 步骤 2:端到端语音思考(真实跑通) -----------------------------------
print("\n" + hr("="))
print("步骤 2:端到端语音思考(音频进 → 单模型 → 音频出)")
print(hr("="))
e2e_model = EndToEndSpeechModel(
client,
model=args.e2e_model,
voice=args.voice,
system_prompt=task_cfg["e2e_prompt"],
endpoint=args.step_audio_endpoint,
)
backend = e2e_model.backend
if backend == "step-audio-r1":
print(f"检测到 STEP_AUDIO_ENDPOINT={e2e_model.endpoint},走真实 Step-Audio R1。")
else:
print(f"未配置 STEP_AUDIO_ENDPOINT,用 OpenAI speech-to-speech 模型 "
f"{e2e_model.model} 作为端到端代表(真正的音频→单模型→音频)。")
print("如需换成书中的 Step-Audio R1,自部署后把地址写入 STEP_AUDIO_ENDPOINT 即可。\n")
try:
e2e_result = e2e_model.run(question_audio, e2e_audio)
except Exception as e: # noqa: BLE001
print(f"错误:端到端调用失败:{e}", file=sys.stderr)
return 2
print_e2e_result(e2e_result, backend)
# -- 步骤 3:级联流水线(对照基线) ---------------------------------------
cascade_result = None
if not args.skip_cascade:
print(f"\n级联 LLM 思考路由:{llm_route}(模型 {llm_model});"
f"ASR/TTS 仍走 OpenAI 直连。")
cascaded = CascadedSpeechModel(
client,
llm_model=llm_model,
tts_voice=args.voice,
system_prompt=task_cfg["cascade_prompt"],
llm_client=llm_client,
)
cascade_result = cascaded.run(question_audio, cascade_audio)
print_cascade_result(cascade_result)
# -- 步骤 4:真实延迟对照 + 范式差异 + 表 9-1(引用) ---------------------
if cascade_result is not None:
print_comparison(e2e_result, backend, cascade_result, task)
print("\n完成。可试听:")
print(f" ffplay {e2e_audio} # 端到端语音答案")
if cascade_result is not None:
print(f" ffplay {cascade_audio} # 级联语音答案")
return 0
if __name__ == "__main__":
raise SystemExit(main())