argmaxinc/argmax-oss-swift · 上手攻略

• 仓库：argmaxinc/argmax-oss-swift
• 链接：https://github.com/argmaxinc/argmax-oss-swift
• 分类：ai（端侧语音 AI / Apple Silicon）
• 作者：spark
• 更新：2026-07-15

是什么

argmax-oss-swift 是 Argmax 公司开源的 Apple Silicon 上的端侧语音 AI Swift SDK 套件。一个 Swift Package 里打包了三个产品：

• WhisperKit — 用 OpenAI Whisper 做离线 语音转文字（ASR），模型跑在 Core ML 上。
• TTSKit — 用 Qwen3-TTS 做离线 文字转语音（TTS），支持 9 种声音、10 种语言，real-time streaming。
• SpeakerKit — 用 Pyannote v4 做 说话人日志（speaker diarization），和 WhisperKit 拼装可拿到"哪段是谁说的话"。

三者共享 ArgmaxOSS umbrella product，可以一并引入，也可以按需取单一 product。配套还带一个 argmax-cli 命令行工具（含本地 server，API 兼容 OpenAI /v1/audio/transcriptions），方便快速测试。

底层逻辑：所有模型跑在用户设备上，所有音频都不过云——这对隐私敏感场景（医疗、法律、采访、机密会议）非常关键。

解决什么问题

1. iOS / macOS 上要"离线语音 AI"：三方 Whisper 实现要么依赖 Python / PyTorch，要么走云；WhisperKit 是少数能在 iPhone / Mac 上用 Core ML 跑的官方级实现。
2. 不愿维护多套 SDK：录音 App、笔记 App、会议 App 同时需要 ASR + TTS + diarization 时，三个独立 SDK 意味着三套模型加载、两套音频管线。
3. 不想从零集成 OpenAI / Deepgram 客户端：开源里再写一个本地 OpenAI Audio API 兼容 server 是个不小工作；Argmax 已经发了。
4. 要做 demo / 原型 / 内部工具：CLI + 一个 OpenAI SDK 兼容端口，5 行代码就能和现有 OpenAI 音频代码共存。

快速安装

当前版本（仓库 README 给出的 SPM 上界）：from: "0.9.0"（Swift Package） 要求： - macOS 14+（SpeakerKit 可到 macOS 13+） - iOS 18+（TTSKit 要求） - Xcode 16+ - Swift 5.9 / 5.10

方式一：Swift Package Manager

Xcode 里

1. File > Add Package Dependencies…
2. 输入 https://github.com/argmaxinc/argmax-oss-swift
3. 选择版本范围（比如 Up to next major: 0.9.0）
4. 选 product：ArgmaxOSS（全部），或者按需选 WhisperKit / TTSKit / SpeakerKit

Package.swift 里

// Package.swift
dependencies: [
    .package(url: "https://github.com/argmaxinc/argmax-oss-swift.git", from: "0.9.0"),
],

targets: [
    .target(
        name: "YourApp",
        dependencies: [
            // 一揽子
            .product(name: "ArgmaxOSS", package: "argmax-oss-swift"),

            // 或者按需：
            // .product(name: "WhisperKit", package: "argmax-oss-swift"),
            // .product(name: "TTSKit",    package: "argmax-oss-swift"),
            // .product(name: "SpeakerKit", package: "argmax-oss-swift"),
        ]
    )
]

方式二：Homebrew（CLI）

brew install whisperkit-cli
# 或 brew install argmax-cli   —— 取决于 tap 名字

核心用法

1. WhisperKit：转写一个本地音频文件

import WhisperKit

Task {
    let pipe = try? await WhisperKit()
    let result = try? await pipe!.transcribe(audioPath: "path/to/audio.{wav,mp3,m4a,flac}")
    print(result?.text)
}

模型会自动按设备下载推荐模型；想强制指定：

let pipe = try? await WhisperKit(
    WhisperKitConfig(model: "large-v3-v20240930_626MB")
)

支持 glob：model: "large-v3*"（注意：搜索必须匹配唯一一个模型，否则抛错）。

模型选型速查：

模型列表见 https://huggingface.co/argmaxinc/whisperkit-coreml

2. WhisperKit 微调版：自托管 HuggingFace 模型

let config = WhisperKitConfig(
    model: "your-finetuned",
    modelRepo: "yourname/your-finetuned-repo"
)
let pipe = try? await WhisperKit(config)

转换工具在姊妹仓库 whisperkittools，可以把任意 Whisper 微调版本转成 Core ML 并上传。

3. CLI + 本地 Server（OpenAI API 兼容）

git clone https://github.com/argmaxinc/argmax-oss-swift.git
cd argmax-oss-swift
make setup                                       # 配置环境
make download-model MODEL=large-v3-v20240930_626MB    # 装 git-lfs

# 直接转写
swift run argmax-cli transcribe \
  --model-path "Models/whisperkit-coreml/openai_whisper-large-v3-v20240930_626MB" \
  --audio-path audio.m4a

# 麦克风实时转写
swift run argmax-cli transcribe \
  --model-path "Models/whisperkit-coreml/openai_whisper-large-v3-v20240930_626MB" \
  --stream

启动 OpenAI 兼容本地 server：

make build-local-server
BUILD_ALL=1 swift run argmax-cli serve --host 0.0.0.0 --port 8080 --model tiny

之后你的 OpenAI SDK 代码可以无缝切过来：

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8080/v1")
result = client.audio.transcriptions.create(
    file=open("audio.wav", "rb"),
    model="tiny",
)
print(result.text)

支持 POST /v1/audio/transcriptions、POST /v1/audio/translations、SSE 流式输出、language、prompt、response_format（json / verbose_json，不支持 plain / srt / vtt）、temperature、timestamp_granularities[]（word / segment）。

4. TTSKit：生成语音

import TTSKit

Task {
    let tts = try await TTSKit()
    let result = try await tts.generate(text: "Hello from TTSKit!")
    print("Generated \(result.audioDuration)s at \(result.sampleRate)Hz")
}

9 个内置 voice：ryan, aiden, onoAnna, sohee, eric, dylan, serena, vivian, uncleFu。 10 种语言：english, chinese, japanese, korean, german, french, russian, portuguese, spanish, italian。

let result = try await tts.generate(
    text: "こんにちは世界",
    speaker: .onoAnna,
    language: .japanese
)

两个模型大小：.qwen3TTS_0_6b（~1GB，全平台，含 iOS）和 .qwen3TTS_1_7b（~2.2GB，仅 macOS，支持 style instruction）。

let tts = try await TTSKit(TTSKitConfig(model: .qwen3TTS_1_7b))

var opts = GenerationOptions()
opts.instruction = "Speak slowly and warmly, like a storyteller."
let r = try await tts.generate(text: "Once upon a time...", speaker: .ryan, options: opts)

实时流式播：

try await tts.play(text: "Long passage...", playbackStrategy: .auto)
// 其他策略：.stream / .buffered(seconds:) / .generateFirst

Decoder 模式：

保存音频：

try await AudioOutput.saveAudio(
    result.audio,
    toFolder: outputDir,
    filename: "output",
    format: .m4a   // 或 .wav
)

5. SpeakerKit：说话人聚类

import SpeakerKit
import WhisperKit

let speakerKit = try await SpeakerKit()
let whisperKit = try await WhisperKit()

let audioArray = try AudioProcessor.loadAudioAsFloatArray(fromPath: "meeting.wav")

let transcription = try await whisperKit.transcribe(audioArray: audioArray)
let diarization   = try await speakerKit.diarize(audioArray: audioArray)

// 把说话人和文字拼一起
let speakerSegments = diarization.addSpeakerInfo(to: transcription)
for group in speakerSegments {
    for seg in group {
        print("\(seg.speaker): \(seg.text)")
    }
}

匹配策略：.subsegment（默认，按 word gap 切分子段）或 .segment（整段给一个人）。

控制说话人数量：

let opts = PyannoteDiarizationOptions(
    numberOfSpeakers: 2,        // 不传则自动推断
    clusterDistanceThreshold: 0.6,
    useExclusiveReconciliation: false
)
let result = try await speakerKit.diarize(audioArray: audioArray, options: opts)

输出 RTTM：

let rttm = SpeakerKit.generateRTTM(from: diarization, fileName: "meeting")

6. CLI：TTS & Diarize 命令

# TTS：实时播放或保存
swift run argmax-cli tts --text "Hello from the command line" --play
swift run argmax-cli tts --text "Save to file" --output-path output.wav

# 多语言 + 自定义声音 + 风格指令（仅 1.7B）
swift run argmax-cli tts --text "日本語テスト" --speaker ono-anna --language japanese
swift run argmax-cli tts --text-file article.txt --model 1.7b --instruction "Read cheerfully"

# Speaker 日志
swift run argmax-cli diarize --audio-path meeting.wav --verbose
swift run argmax-cli diarize --audio-path meeting.wav --rttm-path output.rttm

典型适用场景

• 隐私优先的 iOS / macOS 录音笔记 App：本地转写 + 说话人分割，文件永远不出设备。
• 会议记录 / 访谈整理：WhisperKit 抽文字，SpeakerKit 分配"采访者 / 受访者"，导出 SRT / VTT 给后期剪辑。
• 车载 / 离线智能助手：Apple Silicon on-device，反应延迟 100-300ms，无网也能用。
• 替代云 API 的本地 TTS 工具：批量生成短视频 / 教学 / 客服语音库，避免云厂商计费与并发限速。
• OpenAI Whisper / TTS 用户的私有部署：用 Argmax 的本地 server 跑 OpenAI SDK 代码；数据不出网，月费归零。

坑与注意

1. 平台版本门槛：TTSKit 要 iOS 18+/macOS 15+；WhisperKit CLI 在 macOS 跑得动，iOS 上只能 SDK 嵌入。
2. 模型体积：Large v3 Turbo 要 ~626 MB 空间；TTSKit 1.7B 模型 ~2.2 GB（仅 macOS，且 0.6B ~1 GB 在 iOS 上才能跑）。首次加载会自动下载，要预留磁盘和流量。
3. --model-path 必须指向真实已下载目录：make download-model MODEL=... 只下单一模型；想全量就 make download-models。
4. 不要忘了 git-lfs：HuggingFace 上的 Core ML 模型在 LFS 上，clone 之前要确保 git lfs install 过。
5. OpenAI 兼容 server 的限制：只支持 json / verbose_json，不支持 text / srt / vtt；模型必须先在 server 端 --model 指定。
6. 模型选择 = 内存：iPhone 跑 Large v3 Turbo 时单次推理峰值内存 600-800 MB，需要在 Info.plist 加 NSHighResolutionCapable 和合适的 background task 预算。
7. AudioProcessor 输入：loadAudioAsFloatArray 要求 WAV 单声道浮点；多声道 / 压缩格式要在 Swift 里自己转 PCM。
8. decoder 模式锁定：.latencyOptimized 和 .throughputOptimized 在模型加载时就固定；中途切换要重新 load 模型。
9. argmax-cli serve 默认端口 50060（README 提到的本地数字），--port 可改；不要在公网开。

与同类对比

核心差异：在 Apple 硬件上想要一站式、低延迟、完全离线的语音 AI，这套 SDK 是 2026 年的"工具栏"——同类需要自己把 whisper.cpp + Piper + pyannote 串起来，还要写一遍 OpenAI 兼容层。

一句话推荐结论

做 macOS / iOS 上的语音 AI，优先 Argmax 套件：ASR + TTS + Diarization 一站搞定，端侧、无云费、Core ML 加速；CI 里把它当 OpenAI Audio API 的私有替代品也完美。

来源

• 仓库 README：https://github.com/argmaxinc/argmax-oss-swift
• WhisperKit 模型表：https://huggingface.co/argmaxinc/whisperkit-coreml
• TTSKit 模型表：https://huggingface.co/argmaxinc/ttskit-coreml
• SpeakerKit 模型表：https://huggingface.co/argmaxinc/speakerkit-coreml
• 工具链仓库（whisperkittools）：https://github.com/argmaxinc/whisperkittools
• 官方博客（SpeakerKit 架构 / Argmax Pro Local Server）：https://argmaxinc.com/blog

不确定处

• README 标注的 from: "0.9.0" 是文档截稿时的 SPM 版本上限；实际最新版本（含 patch）以 SwiftPM 解析时返回值为准。
• 0.6B / 1.7B 模型在 iPhone 14 / 15 / 16 系列的"实时率"（RTF）数字 README 未给硬数字，需要按 TTSKitExample 实测。
• argmax-cli 的 Homebrew tap 与 cask 名字（whisperkit-cli 还是 argmax-cli）未在 README 锁定，建议 brew search 后再装。
• SpeakerKit 在 iPhone 上的 diarization 效果（多人会议）官方未给出对低功耗模式（Low Power Mode）的兼容性数据，建议先用小样例试跑。