测试

Mizuoto 的测试分三层：

• 核心的测试不需要 GPU，也不需要模型：dummy 引擎在测试自己的进程里，端到端地支撑起规划、任务、运行时服务、流式、取消和错误。
• 引擎的测试在 CPU 上用权重随机的小模型运行每个引擎和训练器，包括在模拟设备上部分加载、流式加载的运行，同样在 CI 里跑。
• 真实模型：契约套件让已安装的模型走完整条链路，对照工具把原生引擎与参照实现逐采样比较。开发者改动引擎时手动运行它们。

python scripts/dev.py check 运行 CI 跑的全部：lint、typecheck-py、test-py、test-web、typegen-check。

布局复制锚点链接

tests/
  conftest.py            make_services、services 和 wav_file 夹具
  test_architecture.py   分层规则、全局状态规则、注意力入口、轻量导入、单一发行包
  core/                  每个服务一个文件：jobs、engines、models、tts、voices、presets、training、projects、
                         remote、settings、runtime_service、compute、protocol（帧、任务、任务 worker 事件）、
                         audio/text/process、db/errors/events，以及 CPU 调优和 compute.fast 的开关
  api/                   test_api.py（通过 TestClient 测整个 API）、test_embed.py（MizuotoServer）
  cli/                   test_cli.py（命令树 EXPECTED_TREE 与各条命令）
  runtime/               运行时的各部分：上下文、ops、加载（test_runtime.py），设备（test_device.py），
                         显存单元、部分加载与管理器（test_memory.py），注意力调度与后端（test_accel*.py），
                         mizuoto.nn 与参考实现逐比特一致（test_nn_exact.py），DSP 夹具（test_dsp.py），
                         compute.compile（test_compile.py），随机数生成器跳转（test_rng_jump.py）
  text/                  mizuoto.text 的分词器，用一个很小的词表
  engines_native/        每个引擎和训练器在小型随机模型上运行（test_<id>_tiny.py、test_<id>_train_tiny.py）；
                         streaming.py（模拟设备上的流式加载检查）、training_memory.py（训练显存工具的检查）
  engines/               test_contract.py：针对真实模型的契约套件（默认排除）
  fixtures/dsp/          由 scripts/parity/dsp_fixtures.py 生成的 DSP 夹具
packages/native/<pkg>/tests/
                         需要接受许可的引擎自己的测试，与其许可证覆盖的代码放在一起：小模型测试
                         （test_fishspeech_tiny.py、test_fishspeech_train_tiny.py、test_indextts_tiny.py）和
                         test_<id>_package.py（它的版本与 Mizuoto 范围、清单对照、引擎规则）

pyproject.toml 定义了四个标记，默认全部排除（addopts = "-m 'not live and not engine and not weights and not e2e'"）：

所以 python -m pytest（或 python scripts/dev.py test-py）运行的是核心的测试和小模型测试。需要 torch 或某个可选包的测试，在没有它时会跳过（pytest.importorskip）。

dummy 引擎复制锚点链接

mizuoto/engines/dummy/ 是一个没有模型的完整引擎：引擎（engine.py）和训练器（train.py），清单是 mizuoto/core/engines/manifests/dummy.toml。它只导入 numpy，不需要 torch，并像所有引擎一样在测试的进程里运行。

• 它把每个字符变成一小段音调，音高取决于音色（预设、描述、参考音频的 SHA-256 或权重的哈希），所以不同音色听起来不同；随机数从 ctx.rng 抽取，所以同一个种子得到同样的音频。
• 它声明了全部能力：预设说话人、克隆、设计、风格与情感、流式输出与流式文本输入、音色转换、语音编辑、批处理、权重、transcribe 操作（所以 ASR 路径也能测）、训练。
• 引擎选项可以让它故意出错：delay_ms、chunk_ms 和 load_delay_ms 让它变慢；fail = error | oom | crash | exception 和 fail_at_segment 让它在指定位置失败、内存不足、报告崩溃（worker_failed）或抛出未处理的异常。

正是靠它，在下一次检查时停下的取消、内存不足变成 compute_unavailable、超时、卸载、空闲回收和流式音频块，都能在没有 GPU 的 CI 机器上几秒内测完。dummy 引擎也是用户试用 Mizuoto 的方式，smoke_wheels.py 也用它。

夹具复制锚点链接

tests/conftest.py：

@pytest.fixture
def make_services(tmp_path: Path):
    from mizuoto.core.context import build_services
    built = []

    def make(start_background: bool = False, **kwargs):
        env = kwargs.pop("env", {})
        s = build_services(data_dir=tmp_path / "data", environ=dict(env), start_background=start_background, **kwargs)
        built.append(s)
        return s

    yield make
    for s in built:
        s.close()

• 每个测试一个临时数据目录、一个空的环境（environ={}：开发者自己的 MIZUOTO_* 变量不会混进来）。
• services 是 make_services() 的简写；wav_file 是一段 2 秒、22.05 kHz 的立体声 WAV。
• 需要调度器和空闲回收的测试传 start_background=True。API 测试就是这样：create_app(make_services(start_background=True), bound_host="127.0.0.1", serve_ui=False)，然后用 TestClient。
• 下载测试把 services.models.http_transport 换成 httpx.MockTransport。
• 远程测试（tests/core/test_remote.py）在本机启动一个 AgentServer，由主机通过 TCP 驱动它的 dummy 引擎。

小型随机模型复制锚点链接

tests/engines_native/ 为每个引擎搭一个与引擎结构相同、只有几个小层、权重随机的模型，按引擎期望的样子写进临时目录（配置、字节级词表、safetensors），然后驱动真实的代码：用 Runtime(DeviceService(), ModelManager(...)) 调 Engine.load，配一个 RequestContext，测音色提示、解码、批处理、可重复的种子和取消。test_<id>_train_tiny.py 用几段音频跑完引擎训练器的每个阶段。它们不需要下载，所以 CI 每次推送都用 CPU 版 torch 运行。需要接受许可的引擎的测试放在各自的包里，即 packages/native/<pkg>/tests/；pyproject.toml 的 testpaths 列出了这些目录，所以 python -m pytest 会连同其余测试一起运行它们，没装对应的包时跳过。它们用到 tests/engines_native 的辅助模块（streaming.py、accel_checks.py），所以要在仓库根目录运行；在包目录里运行也可以，根目录 pyproject.toml 的 pythonpath 会把根目录加进 sys.path。

这里还守着几条跨引擎的规则：

• 注意力。 每个调用点传入的 mask_info 都与它的稠密掩码对照检查。MIZUOTO_TEST_ACCEL=count python -m pytest tests/engines_native packages/native 让每次注意力调用都经过一个策略：它统计调用点，并按调用点自己的参照方式计算；如果某个调用点从没以这种方式被调用到（例如有代码绕过 compute.attention 直接调用 SDPA），测试结束时就会失败。每个 conftest 列出本目录的调用点（SITES_TESTED）；检查本身在 tests/engines_native/accel_checks.py。
• 训练显存工具。 training_memory.py 的 check_checkpointing 把训练器的阶段在全新的工作目录里跑两遍，一遍原样，一遍每个块都做梯度检查点，比较每个指标和每个写出的权重文件：必须完全相同。保持结果的其他工具（如把优化器状态放在内存里）用同样的方式检查。

模拟设备上的流式加载复制锚点链接

显存管理改变的是权重放在哪里，不是计算什么，所以部分加载和流式加载的结果必须与整体加载完全相同。tests/engines_native/streaming.py 让 CPU 扮演一个给定大小的设备（DeviceService(simulate=…, strict=True)）：

• check_streamed 在三种设备大小下（每个单元都流式加载、一半、全部常驻）运行小型引擎，与普通 CPU 上的结果逐采样比较。
• 严格模式下，不在设备上的组件以 meta 张量存放，被流式加载的单元的权重只在该单元运行时存在。所以一个引擎在某个阶段用了没有为这个阶段放置（ctx.use）的组件，或者在单元的 forward 之外读了它的权重，就会在这里失败。
• check_oom_retry 让阶段里的某一层第一次调用时内存不足：阶段以更多权重流式加载的方式重新运行，结果必须与未受干扰时完全相同。

显存管理本身见显存管理。

真实引擎的契约套件复制锚点链接

tests/engines/test_contract.py 对每个可用引擎的每个已安装目录模型，走完整的链路（规划 → 任务 → 运行时 → 引擎）：

python scripts/dev.py test-engines                 # 所有已安装的模型
python scripts/dev.py test-engines qwen3tts f5tts -- -x -k cancel
MIZUOTO_TEST_DEVICE=cpu python scripts/dev.py test-engines cosyvoice

test-engines 设置 MIZUOTO_CONTRACT=1 和 MIZUOTO_TEST_ENGINES（指定的引擎），以 -m engine -v 运行 tests/engines。套件使用 MIZUOTO_TEST_DATA_DIR（默认是平常的数据目录）里的模型，但在临时数据目录里运行，不往真实目录写任何东西，设备是 MIZUOTO_TEST_DEVICE（默认 auto）。MIZUOTO_TEST_SETTINGS 以 JSON 追加设置：{"compute": {"vram_limit_mb": 4096}} 让每个模型部分加载，在大卡上模拟一块 4 GB 的 GPU。

要克隆的参考音频来自 MIZUOTO_TEST_REFERENCE（加上 MIZUOTO_TEST_REFERENCE_TEXT），没有时由已安装的预设或设计模型说一段。需要接受许可的引擎只有在设了 MIZUOTO_TEST_ACCEPT_LICENCES=1（并装了它们的包）时才参加，许可只在临时目录里接受。

在 CPU 上，每个引擎的全部目录模型都通过契约套件。在 RTX 3090 上（2026-10-19），每个已安装的模型（含需要接受许可的引擎）都通过了上面四项新测试：0.9–6 秒的请求在 0.1–2.3 秒后送出首段音频，取消在 0.05–0.6 秒内完成，卸载后设备上最多留下 8 MB。整套跑完需要几个小时（模型越大越慢），所以改动某个引擎时只跑它。

与参照实现对照复制锚点链接

scripts/parity/ 把原生引擎与它们的参照实现逐采样比较（它的 README 有完整说明）。参照是 Mizuoto 0.1 的引擎 worker（git 标签 v1-engine-workers，各引擎在自己原来的环境里运行上游代码）；0.1 没有的 VoxCPM，参照是上游自己的包，经 stack.py --impl upstream 套进同一条链路。代码在仓库里；数据放在仓库之外的工作区 MIZUOTO_PARITY_DIR（默认 ~/code_workspace/experiment/kodama-refactor），其中有：

• reference/：位于标签 v1-engine-workers 的 git 工作树，即原生引擎与之比对的 0.1 代码；
• reference-host/ 和 native-env/：分别驱动参照实现和原生实现的 Python 环境（原生一侧用参照环境相同的 torch 2.8.0，差异因此只来自代码而不是内核）；CosyVoice 另有一套 torch 2.8 上的参照环境和数据目录；
• corpus/（参考音频及其转写）、fixtures/（每次运行写出的音频和行为）、reports/（比较报告）。

W=~/code_workspace/experiment/kodama-refactor
CUDA_VISIBLE_DEVICES= $W/reference-host/bin/python scripts/parity/stack.py run scripts/parity/cases/qwen3tts.jsonl --impl reference
CUDA_VISIBLE_DEVICES= $W/native-env/bin/python scripts/parity/stack.py run scripts/parity/cases/qwen3tts.jsonl --impl native
$W/native-env/bin/python scripts/parity/compare.py qwen3tts --a reference --b native --report $W/reports/qwen3tts-T3.md

先自洽，再对照。 参照实现先与自己的重复运行比较（--name reference-repeat）：自己都不能复现的用例无法用来评判原生实现。cases/<engine>.jsonl 每行一个用例，字段见 README。

结果：在 CPU 上以 fp32 运行时，每个引擎都与参照完全相同（VoxCPM 在 bf16 下也是），只有 CosyVoice 在两边各自生成音色提示时例外：CAM++ 的说话人嵌入与 onnxruntime 相差约 1e-6，HiFT 的正弦源把这个差异沿句子积累放大；给定同一个音色提示时，CosyVoice 也逐采样相同。每个训练器在 CPU 上与上游带同样种子的运行给出逐字节相同的损失、学习率和权重。

行为一致性的层级与容差复制锚点链接

“相同”分层判断。低层级逐比特检查，高层级判断整条链路：

• 为什么 T3 只在 CPU 上以 fp32 判断。 任何一点 logits 差异都会翻转一次多项式抽样（或一个束），之后的一切随之分叉。在 GPU 上降精度运行时，连上游自己都不能与自己逐比特一致（例如批量和单条的贪心解码），所以 GPU 上的一致性由 T1 的模块级误差加 T4 的统计指标判断。
• 音频之外的行为也是对照的一部分，在两种实现上都经过契约套件检查：实际生效的参数和警告、音色模式的判定（fit）、流式的粒度与块数、取消的行为、对无效输入的错误码（参考音频太长、不支持的语言、缺少转写）、输出采样率、分段的拼接。
• 加速与提速遵守同样的层级：会改变比特的加速（例如编译）至少保持在该引擎的 T1/T3 容差之内，并记录实测误差；默认路径上的提速必须逐比特不变。
• T0 的 DSP 夹具只在生成它们的那类机器上完全相同：带 AVX2、不带 AVX-512 的 x86-64 Linux，且 torch 版本相同。在别处，内核的舍入不同（numpy 的 AVX-512 exp 和 log、Windows CRT 的 libm、Arm 上 torch 的 FFT 和 soxr 的 SIMD、另一个 torch 版本），所以 tests/runtime/test_dsp.py 在那里检查输出在这种舍入之内一致：float32 最大绝对误差 ≤ 1e-4 × max(1, ‖ref‖∞)，float64 ≤ 1e-12 × max(1, ‖ref‖∞)。CI 的 macOS、Windows 和 AVX-512 机器上实测最大为 4e-5。

T4 结果复制锚点链接

scripts/parity/quality.py 运行这一层（命令见 scripts/parity/README.md）。语料（scripts/parity/corpus/t4.json）共 17 组，每组是一个模型和一种音色模式：三个音色（克隆用语料中的两段英文片段和一段中文片段；三个预置说话人；三个设计音色）朗读 20 段文本（10 段英文、10 段中文，不含数字），种子为 1–3，每组每侧 180 个片段。原生实现用本仓库运行；参照实现对 0.1 已有的引擎用 0.1，对 VoxCPM 用上游的包，各自在自己的一块 RTX 3090 上以生产精度运行。评判工具：通过 Mizuoto 的 ASR 运行的 Whisper large-v3-turbo（英文按词、中文按字计算，繁体字用 OpenCC 的表转为简体）、CAM++（CosyVoice 的）、UTMOS22 strong（SpeechMOS）、BS.1770 响度和 YIN F0。

第一次完整运行后做了三处改进，上面的层级规则已经包含它们：

• 失败计数，而不是平均。 失控的片段（采样模型停不下来，或一直生成静音）错误率没有上限：Qwen3-TTS 的一个 965 % 的片段把均值从 1.3 % 拉到 6.7 %。错误率高于 50 % 的片段在每侧单独计数，用 Fisher 精确检验比较；其他指标只用没有失败的片段。
• 超出阈值还需要差异显著。 在 180 个采样片段上，最差片段和 0.05 的 UTMOS 余量都会随机波动：只有配对检验（按音色和文本，种子取平均）给出 p < 0.05 时，该组才不通过。
• 用定向重跑判断个别离群值。 语料中发现的两个失控片段（Qwen3-TTS 的英文说话人读中文，以及 IndexTTS 1.5 读到一半变成静音）都在两侧用该音色和语言、10 个种子重跑：参照实现失败得一样多（各 100 个中 3 和 3；2 和 3）。两者都是上游自身的行为。

测量于 2026-10-18（参照 → 原生；失败片段数为参照 / 原生）：

每组的每个音色，响度和 F0 都在参照的四分位距之内。容差之内唯一的系统性差异是 IndexTTS 1.5 的 UTMOS，低 0.03（p 0.025，主要来自第二个英文音色）；同样种子下，它的 GPU 输出本来就与 0.1 不同（2.3 dB，见性能中的 G0）；原因后来已经查明并修正（见 IndexTTS）。Fish Speech S2 Pro 在 GPU 上没有参照（0.1 的克隆在 GPU 上失败）：仅原生的结果为错误率 1.23 %，没有失败片段，相似度 0.723，UTMOS 4.07。改变音频的可选项用同样的方法评判：在每个可选项改变的组上，用该可选项（--setting，请求选项则用 --option）运行原生实现，与默认的原生运行对照。全部通过（默认 → 可选项）：

未安装 flash-attn 时，compute.attention=fast 处处都是 SDPA，所以音频相同。安装后，F5-TTS 没有可交给 FlashAttention 的带填充的半精度调用。GPT-SoVITS v4 的 DiT 对引导时大小为 2 的批量只给出一行键长度，flash-attn 因此拒绝（seqlens_k must have shape (batch_size)），直到后端把长度扩展到查询的批大小；现在这 704 次调用都由它计算。

第一次可选项运行暴露了评测工具的一个错误：请求和对照用例把引擎选项写在 options 下，而请求模型没有这个字段，pydantic 会直接忽略它，所以 packed_guidance 和六个 T3 用例（GPT-SoVITS 的 cut5、批量和串行用例，VoxCPM 的续写和重试用例）实际上都用默认值运行。现在它们改用 engine_options；在 CPU 上重跑后，这六个用例在应用了各自选项的情况下与 0.1 和上游逐采样相同。

Web UI 测试复制锚点链接

mizuoto/webui/src/**/*.test.ts 用 vitest 运行；python scripts/dev.py test-web 先运行 bun run test，再运行 bun run typecheck（vue-tsc）。除了组件和 store 的单元测试，还有几个守护整个界面的规则测试：imports.test.ts、tokens.test.ts、layout.test.ts、ui/layers.test.ts 和 i18n/i18n.test.ts（两种语言的键相同）；见 Web UI。

python scripts/dev.py typegen-check 重新生成 schema.d.ts 并与提交的版本比较；API 改了而类型没有重新生成时失败。

文档站（site/）有自己的 vitest 测试；src/lib/i18n-content.test.ts 要求每个中文 <slug>.mdx 都有对应的 <slug>.en.mdx，且两个侧栏的页面顺序相同。

CI复制锚点链接

.github/workflows/ci.yml 在每次推送到分支和每个拉取请求时运行，使用 torch 的 CPU 构建（https://download.pytorch.org/whl/cpu）。Mizuoto 和两个需要接受许可的包各自发布，所以各自检查，一次改动只运行它所改内容的检查。依赖用 uv 安装（astral-sh/setup-uv，UV_SYSTEM_PYTHON=1：装进 setup-python 提供的 Python，不建虚拟环境；缓存关闭，因为解包后的 torch wheel 会挤占 10 GB 的缓存上限）。

第一个作业 scope 读取改动的文件（推送的来自 compare API，拉取请求的来自它的文件列表），由 python scripts/ci.py scope 映射为检查：

新分支、手动触发、被 compare API 截断的列表（300 个文件）或读取失败时检查全部；tests/test_ci.py 覆盖这套映射。

同一分支较新的运行会取消较旧的运行。推送到 main 且改动了某个版本文件时会启动发布工作流，它把 ci.yml 作为自己的检查，检查这次推送改动的内容；CI 自己对这次推送的运行会跳过所有作业（scope 看到了版本文件），所以检查只跑一次。标签只启动发布工作流，它的检查是全部。把文档站推送到 GitHub Pages 由 site.yml 负责，不在 CI 里（见发布）。

python scripts/dev.py check 在本地运行全部内容（只在你的平台和 Python 上，装上需要接受许可的包，基于你检出的 Mizuoto）。契约套件和对照工具需要模型（对照还需要参照实现的环境），权重有几十 GB，所以不进 CI；发布工作流有自己的 wheel 冒烟测试（见发布）。