企业官网建设流程全解析

• 语音
• 音频
• AI 应用

本指南以仓库根目录 BENCHMARKS.md 为骨架，深入结合 Makefile、fastlane/Fastfile 与 Tests/WhisperKitTests/RegressionTests.swift 源码，完整还原从环境准备、设备检测、模型配置、批量跑分到结果上传的端到端流程。读完本文，你将掌握 WhisperKit 官方性能评测管线的全部操作细节，并理解 TPS 吞吐、内存占用、WER 准确率等关键指标在代码中是如何被采集与度量的。

一、Benchmark 评测体系概述

argmax-oss-swift（On-device Speech AI for Apple Silicon）在BENCHMARKS.md中定义了一套可复现的 WhisperKit 端侧性能评测方案：通过 Xcode 测试框架（XCTest）+ Fastlane 自动化，在指定设备（iPhone / iPad / Mac）上批量加载不同 Whisper 模型，对固定测试语料执行转写，并采集延迟、内存、系统状态等数据，最终输出为标准 JSON 结果文件。

整套评测由三层协作完成：

评测结果按设备保存为 JSON，可统一上传至公开评测数据集（HuggingFace 上的 whisperkit-evals-dataset 数据集），用于跨设备、跨模型、跨版本的横向对比与回归跟踪。

二、源码获取与本地环境搭建

2.1 获取源码

评测脚本与测试代码位于本仓库内，运行测试套件前需先克隆：

git clone https://gitcode.com/GitHub_Trending/wh/argmax-oss-swift.git

2.2 一键初始化依赖

仓库通过 Makefile 的setup目标完成环境自检与依赖安装：

make setup

从 Makefile 的setup实现可以看到，它会逐一校验以下工具，缺失时通过 Homebrew 自动安装：

• pip3/python3
• Homebrew（缺失时直接报错退出，提示先安装）
• huggingface-cli（后续上传评测结果必需）
• git-lfs（拉取大体积 CoreML 模型必需）
• trash（清理旧的 .xcresult 产物）
• fastlane（评测自动化核心）
• xcbeautify（美化 xcodebuild 日志）

setup 结束后还会调用generate-xcconfigs：从 Xcode 的开发者账号中读取 Team ID，写入Examples/WhisperAX/Debug.xcconfig与Examples/TTS/TTSKitExample/Debug.xcconfig。若未登录 Xcode / 未选择开发者团队，此步会提示错误。

更详细的协作环境说明可参阅 CONTRIBUTING.md。

2.3 模型下载（可选前置）

若需要在本地直接验证评测（而非仅跑自动化），可按需先拉取模型。仓库提供argmaxinc/whisperkit-coreml模型仓库的封装：

make download-models # 下载全部模型 make download-model MODEL=base # 仅下载指定规格（如 base）

download-model内部通过git lfs pull --include="openai_whisper-$(MODEL)/*"按目录精确拉取，避免一次性下载全部模型占用磁盘。

三、Xcode 环境变量注入

评测的核心是WhisperAX示例工程中的回归测试，被测模型通过环境变量传递给 Xcode（由 Fastlane 注入）：

1. 打开示例工程：

xed Examples/WhisperAX

2. 在 Xcode 顶部选中WhisperAX，点击底部Edit Scheme。

3. 在Environment Variables面板中，确认存在名为MODEL_NAME、值为$(MODEL_NAME)的条目。

这条$(MODEL_NAME)变量由 fastlane/Fastfile 的run_benchmark通过xcargs "MODEL_NAME=#{model}"注入，并在 Tests/WhisperKitTests/RegressionTests.swift 的testEnvConfigurations()中被读取：

if let modelSizeEnv = ProcessInfo.processInfo.environment["MODEL_NAME"], !modelSizeEnv.isEmpty { modelsToTest = [modelSizeEnv] ... }

即：测试运行时以MODEL_NAME为准确定被测模型；同时支持可选的MODEL_REPO环境变量指定模型仓库（Fastlane 会以MODEL_REPO=argmaxinc/whisperkit-coreml注入）。

四、测试设备准备

[!IMPORTANT] 在物理设备上运行测试需要有效的开发者账号（Apple Developer Account）。

运行前需要完成以下前置动作：

1. 将所有外部设备通过数据线连接并配对到你的 Mac；
2. 在开发者账号中注册这些设备；
3. 确保设备已开启 Developer Mode（开发者模式）；
4. 若连接后设备列表无显示，按Command + Shift + 2打开设备列表窗口跟踪连接进度。

Fastlane 侧通过xcrun devicectl list devices（见 fastlane/Fastfile 的available_devices）枚举所有已连接的真机，并自动把当前 Mac（通过system_profiler SPHardwareDataType与sw_vers读取芯片型号、机型与系统版本）作为名为My Mac的评测目标一并纳入——这正是该评测体系能同时覆盖 iPhone / iPad / Apple Silicon Mac 的原因。

五、数据集配置

测试语料定义在 Tests/WhisperKitTests/RegressionTests.swift 顶部的全局数组datasets中，默认预填了当前可用的数据集：

var datasets = ["librispeech-10mins", "earnings22-10mins"]

• full 模式使用上述两个数据集；
• debug 模式（testModelPerformanceWithDebugConfig）仅使用debugDataset = ["earnings22-10mins"]，以加快排错速度。

数据集本身托管在测试数据仓库中，运行时会由downloadTestData(forDataset:)通过 Hub API 按"\(dataset)/*"通配符增量下载音频（.mp3）与参考转写元数据（.json）到临时目录。每个数据集对应一份含参考文本的元数据 JSON，用于后续 WER（词错误率）计算。

六、模型矩阵配置

被测模型定义在 fastlane/Fastfile 的BENCHMARK_CONFIGS常量中。找到BENCHMARK_CONFIGS，修改对应 benchmark 下的models数组即可定制测试矩阵。

6.1 full 配置（完整评测）

full: { test_identifier: 'WhisperAXTests/RegressionTests/testModelPerformance', name: 'full', models: [ 'openai_whisper-tiny', 'openai_whisper-tiny.en', 'openai_whisper-base', 'openai_whisper-base.en', 'openai_whisper-small', 'openai_whisper-small.en', 'openai_whisper-large-v2', 'openai_whisper-large-v2_949MB', 'openai_whisper-large-v2_turbo', 'openai_whisper-large-v2_turbo_955MB', 'openai_whisper-large-v3', 'openai_whisper-large-v3_947MB', 'openai_whisper-large-v3_turbo', 'openai_whisper-large-v3_turbo_954MB', 'distil-whisper_distil-large-v3', 'distil-whisper_distil-large-v3_594MB', 'distil-whisper_distil-large-v3_turbo', 'distil-whisper_distil-large-v3_turbo_600MB', 'openai_whisper-large-v3-v20240930', 'openai_whisper-large-v3-v20240930_turbo', 'openai_whisper-large-v3-v20240930_626MB', 'openai_whisper-large-v3-v20240930_turbo_632MB' ], repo: 'argmaxinc/whisperkit-coreml' }

full 矩阵共 22 个模型条目，覆盖 tiny / base / small / large-v2 / large-v3 / large-v3-turbo / distil-whisper 蒸馏版以及带量化体积后缀（如_949MB、_955MB）的变体。完整测试在testModelPerformance中执行，其默认模型列表来自WhisperKit.recommendedModels().supported（见 Sources/WhisperKit/Core/WhisperKit.swift），即按当前设备硬件自动推荐的受支持模型集。

6.2 debug 配置（快速排错）

debug: { test_identifier: 'WhisperAXTests/RegressionTests/testModelPerformanceWithDebugConfig', name: 'debug', models: ['tiny', 'crash_test', 'unknown_model', 'small.en'], repo: 'argmaxinc/whisperkit-coreml' }

debug 矩阵刻意包含三个特殊条目用于验证管线健壮性：

• tiny：正常执行的最小模型；
• crash_test：在testEnvConfigurations()中命中后直接触发fatalError("Crash test triggered")，用于验证失败路径与日志采集；
• unknown_model：非法模型名，用于验证异常处理分支。

两个配置共用WhisperAXTests/RegressionTests内的测试标识符，并通过config[:debug]切换。

6.3 设备-模型支持矩阵

模型并非在所有设备上均可运行。Examples/WhisperAX/WhisperAXTests/WhisperKitTests/Resources/config-v03.json 与 config-v04.json 按芯片（A12/A13/S9/S10、A14、A15/A16/A17 Pro/A18、M1、M2/M3/M4 等）声明了每类设备的supported模型列表与default模型，并附带model_checksums校验和。测试运行前会检查WhisperKit.recommendedModels().disabled，若模型被标记为当前设备不可用，则直接抛出modelsUnavailable跳过该条目。

七、运行基准测试

评测命令由 Makefile 封装，底层委托给 Fastlane。

7.1 列出已连接设备

运行前先确认设备连接状态，避免后续批量跑分因设备掉线而失败：

make list-devices

输出为 Ruby 风格的设备字典数组，每个条目形如：

{ :name=>"My Mac", :type=>"Apple M2 Pro", :platform=>"macOS", :os_version=>"15.0.1", :product=>"Mac14,12", :id=>"XXXXXXXX-1234-5678-9012-XXXXXXXXXXXX", :state=>"connected" }

该输出来自 fastlane/Fastfile 的available_devices：真机信息由xcrun devicectl list devices解析（过滤掉状态为unavailable的条目），Mac 信息则由system_profiler+sw_vers拼接。务必确认:state为connected后再继续。

7.2 执行评测

完成上述配置后即可运行。评测存在full与debug两种配置：

先用 debug 快速排错：

make benchmark-devices DEBUG=true

确认无误后运行 full 完整评测：

make benchmark-devices

可选：限定目标设备

两种模式下均可通过DEVICES指定设备列表（逗号分隔的设备名，名称取自make list-devices的:name字段）：

make benchmark-devices DEVICES="iPhone 15 Pro Max,My Mac"

Makefile 中对应逻辑为：

DEVICES ?= DEBUG ?= false benchmark-devices: generate-whisperax-xcconfig @if [ -n "$(DEVICES)" ]; then \ fastlane benchmark devices:"$(DEVICES)" debug:$(DEBUG); \ else \ fastlane benchmark debug:$(DEBUG); \ fi

可见benchmark-devices先依赖generate-whisperax-xcconfig（保证 Team ID 就绪），再将参数透传给fastlane benchmarklane；fastlane benchmark内部按debug开关选择:debug或:full配置，并对设备名做逗号切分与匹配（benchmark_specific_devices中若找不到匹配设备会直接user_error!终止）。

7.3 背后发生了什么

从 fastlane/Fastfile 的run_benchmark可以看到每次跑分的完整链路：

1. 按 commit hash 与时间戳生成输出目录benchmark_data/{COMMIT_TIMESTAMP}_{COMMIT_HASH}/；
2. 对models数组中每个模型依次执行scan（等价于 xcodebuild test）：
   • 目标工程：Examples/WhisperAX/WhisperAX.xcodeproj，scheme：WhisperAX；
   • 仅运行only_testing指定的回归测试标识符；
   • 注入MODEL_NAME、MODEL_REPO并附加-allowProvisioningUpdates、-allowProvisioningDeviceRegistration（自动处理真机签名注册）；
   • result_bundle输出 .xcresult 包，每个模型独立打包为WhisperAX_{hash}_{config}.xcresult；
3. 单个模型失败不会中断整体流程（fail_build: false+ rescue 记录错误后继续下一个模型）；
4. 每个设备生成一份合并摘要 JSON。

八、结果解析与指标说明

8.1 产物位置

运行完成后，结果位于：

• fastlane/benchmark_data/：完整原始产物，包括每台设备的.xcresult（含日志与附件）及各设备/模型的 JSON；
• fastlane/upload_folder/benchmark_data/：仅包含fastlane/benchmark_data中可直接用于分析的 JSON 结果（由 fastlane/Fastfile 的prepare_upload在每次运行后同步刷新，旧内容会被清理）。

8.2 JSON 数据模型

单条评测记录对应 Tests/WhisperKitTests/RegressionTestUtils.swift 中的RegressionStats：

struct RegressionStats: JSONCodable { let testInfo: TestInfo // 设备、音频文件、数据集、模型、模型大小MB、日期、耗时、timings、prediction/reference、wer、diff let memoryStats: MemoryStats // 内存测量（min/max/average、pre/post transcribe 内存） let latencyStats: LatencyStats // 延迟测量（Tokens/Sec） let staticAttributes: StaticAttributes // OS 版本、低电量模式、encoder/decoder compute、解码选项 let systemMeasurements: SystemMeasurements // 系统内存、磁盘空间、电池电量、热状态、时间序列 }

各设备还会生成一份{device}_summary_{timestamp}.json的合并摘要（TestReport），包含设备模型、OS 类型/版本、测试过的模型、failureInfo与附件索引。

8.3 关键指标采集原理

• 转写吞吐（Tokens/Sec）：TranscriptionTestState在转写回调中累计 token 数，按时间差实时计算 TPS；每累计 100 个 token 打一次min/max/average测量点。Tests/WhisperKitTests/RegressionTests.swift 中设有tpsThreshold = 4.0的断言——若 TPS 低于 4 且非 0，测试将失败并提示"潜在 CPU 回退"（说明模型未跑在神经网络引擎等加速单元上）。

• 内存：AppMemoryChecker通过task_info读取phys_footprint；SystemMemoryCheckerAdvanced通过host_statistics64读取系统级可用/活跃/有线/交换内存。测试在转写前后分别记录preTranscribeMemory与postTranscribeMemory。

• 系统状态采样：测试期间启动 1 秒周期的 DispatchSource 定时器，持续记录系统内存、磁盘剩余空间、电池电量（UIDevice.current.batteryLevel/ macOS 的 IOKit 电源信息）与热状态（ProcessInfo.processInfo.thermalState），这些时间序列数据最终进入SystemMeasurements，用于判断性能波动是否受降频、发热或磁盘压力影响。

• 准确率（WER）：参考文本与预测文本经 Tests/WhisperKitTests/Evaluate/WERUtils.swift 计算词错误率——先做英文文本归一化，再按词编码为字符、用 Levenshtein 编辑距离得到替换/删除/插入次数，最终 WER = (S + D + I) / (H + S + D)。归一化与否会显著影响结果（测试断言中未归一化的 WER 约为归一化值的 2 倍以上），因此在跨版本对比时务必保持同一套归一化口径。

8.4 模型初始化防护

评测对模型加载也做了三重保护（createWithMemoryCheck，见 Tests/WhisperKitTests/RegressionTests.swift）：

• 后台监控可用内存，剩余不足 0.1 GB 时判定 OOM 并取消初始化；
• 5 分钟超时保护（timedOut）；
• 初始化异常统一转换为WhisperError.modelsUnavailable并记入failureInfo。

九、结果上传

官方会定期在多种设备上运行本套评测，并将结果上传至公开评测数据集（HuggingFace 的whisperkit-evals-dataset），供基准对比空间引用。如果你也希望把本地结果贡献回去，可执行：

make upload-benchmark-results

其内部调用 fastlane/Fastfile 的upload_resultslane：先校验fastlane/upload_folder存在，再以时间戳生成分支名benchmark_results_{timestamp}，最终执行：

huggingface-cli upload argmaxinc/whisperkit-evals-dataset 'fastlane/upload_folder' --repo-type dataset --create-pr

即以创建 Pull Request的方式上传，而非直接写入主分支——这样既能贡献数据，又保留了数据集维护者的审核权。注意此步依赖make setup阶段安装的huggingface-cli与有效的 HuggingFace 登录态（huggingface-cli whoami可通过 Makefile 的setup-huggingface-cli完成登录，支持HF_TOKEN环境变量）。

十、故障排查（Troubleshooting）

Benchmarks.md 提供了三级排错策略，实测优先级如下：

1. 直接在 Xcode 中运行测试：

   xed Examples/WhisperAX

   在测试导航器中运行RegressionTests/testModelPerformanceWithDebugConfig。

   • 若成功，可排除设备或模型本身的问题；
   • 若失败，Xcode 会给出更详细的报错信息（签名、模型加载、内存等）。
2. 收敛到单台设备：先make list-devices确认设备名，再指定单设备运行，便于聚焦日志：

   make benchmark-devices DEVICES="My Mac"

3. 联系社区：若仍无法解决，可在仓库创建 issue（附上完整日志与设备信息），或到官方 Discord 求助。

此外，根据 fastlane/Fastfile 的实现，还有几个容易踩的坑值得注意：

• 设备名必须与list-devices输出完全一致（区分大小写、含空格写法），否则benchmark_specific_devices会直接报No matching devices found；
• 物理设备必须已开启开发者模式并完成配对注册，否则devicectl无法列出；
• 旧 .xcresult 冲突：run_benchmarks会按device[:product]通配清理旧产物，若手工遗留同名 .xcresult 需确保trash可用；
• Xcode 版本兼容：extract_xcresult_attachments会根据xcodebuild -version自动为 Xcode 16+ 追加--legacy参数，旧版 Xcode 无需此参数。

十一、从 Benchmark 到开发闭环

这套评测体系的价值不止于发布基准数据，它同时是仓库内建的回归保护：full配置的 22 个模型 × 2 个数据集在每台目标设备上全量跑通，意味着任何对 Sources/WhisperKit 核心（AudioEncoder、TextDecoder、TokenSampler 等）的改动，都能通过 TPS 阈值断言、WER 精确断言（如testLargeWER中 WER 需等于 0.1852080123266564 ± 0.001）和内存断言（testInMemoryAndDiskUsage要求模型内存占用 < 1000 MB、磁盘占用 < 5000 MB）快速暴露退化。将make benchmark-devices纳入 CI，即可获得面向真实硬件的持续性能监控——这正是端侧 AI 应用迭代中不可或缺的一环。

• 语音
• 音频
• AI 应用