Qwen2.5-Omni-3B-Audio-CoreAI + CoreAIKit实战:掌握describeAudio等3个核心API即可开发音频对话App
Qwen2.5-Omni-3B-Audio-CoreAI + CoreAIKit实战:掌握describeAudio等3个核心API即可开发音频对话App
Qwen2.5-Omni-3B-Audio-CoreAI 是 Qwen2.5-Omni-3B(Thinker)转成的 Apple Core AI 模型包(.aimodel / .aimodelc),专为 iOS 27 / macOS 27 的端侧音频理解设计:它不是语音转写器,而是"听声描述"——告诉 App 它听到了什么声音(事件、质感、情绪、音乐)。配合 CoreAIKit,只需掌握 describeAudio 等 3 个核心 API,就能开发出完全离线的音频对话 App,无需服务器、无需上传音频。
一、先搞清楚:这个模型能做什么、不能做什么
✅ 能:描述声音内容(事件、质感、情绪、音乐),例如 "I hear a loud hissing sound."、"…a continuous sine wave sound." ❌ 不能:逐字转写语音内容(它不是 Transcriber)
理解这个定位很重要:音频对话 App 在这里的含义是"用户对一段声音提问,模型用文字回答",整条链路(音频编码 + 语言解码)都在设备本地跑在 GPU 或 Neural Engine 上。
项目结构一览:
| 路径 | 内容 | 大小 |
|---|---|---|
| gpu-pipelined/qwen2_5_omni_3b_thinker_int8lin_n750_s1/ | 文本解码器(int8lin 量化,S=1),用于 macOS | 3.9 GB |
| gpu-pipelined/qwen2_5_omni_3b_audio_encoder_fp16_k15/qwen2_5_omni_3b_audio_encoder_fp16_k15.aimodel/ | Whisper 风格音频编码器(fp16,K=15 ≈ 30 秒音频),双平台通用 | 1.2 GB |
| ios/qwen2_5_omni_3b_thinker_n750_ios/ | 文本解码器 AOT 版本(.aimodelc,面向 iPhone 17 Pro / h18p) |
4.5 GB |
💡 为什么 iPhone 用 AOT 版本?因为 3.9 GB 的图在端侧 JIT 编译时容易被系统 jetsam 杀掉;AOT 预编译权重以 mmap 干净页方式加载,12 GB 内存的设备加载后仍留有约 5.9 GB 余量。
技术细节见项目说明 README.md,模型框架信息见 config.json。
二、快速上手:安装 CoreAIKit 的完整步骤
🛠️ 三步集成清单(以 CoreAIKit 0.7.3 为准):
- SPM 引入:在 Xcode 中通过 Swift Package Manager 添加 CoreAIKit 包(精确版本 0.7.3),引用 product CoreAIKit
- 权限配置:只有录麦克风时才需在 Info.plist 中加
NSMicrophoneUsageDescription;macOS 端无需任何 Entitlements - 首次运行下载:首次使用会自动下载模型(Mac 上约 5,485 MB),之后走本地缓存(Application Support),下载进度可通过
downloadProgress回调展示
⚠️ 性能提醒:务必用 Release 模式测量性能,Debug 模式下逐 token 的宿主侧开销会让它慢约 3 倍。
三、3 个核心 API:从零写出你的音频理解功能
API 1:CoreAI.describeAudio —— 一行代码完成任务
这是 CoreAIKit 提供的任务算子(task op),不需要手动管理 session、不需要搬运模型,首次使用自动下载:
let scene = try await CoreAI.describeAudio(audioURL)
传一个音频文件 URL,scene 就是模型对这段声音的完整描述。适合想最快看到效果的场景。
API 2:KitAudioModel + attach —— 加载模型并喂入音频片段
需要自己掌控流程(比如用实时麦克风)时:
import CoreAIKit
import FoundationModels
let audio = try await KitAudioModel(catalog: "qwen2.5-omni-3b-audio")
try await audio.attach(samples: AudioFile.pcm16kMono(audioURL))
注意两点:
- 音频需为 16 kHz 单声道 PCM;任意格式可先解码到 16 kHz mono,时长 ≤ 约 30 秒(编码器 K=15 的设计上限)
- 每个 session 只能 attach 一段音频,要分析不同音频就 attach 新片段
- 想录实时麦克风?用 kit 自带的
MicRecorder,它输出 16 kHz 单声道[Float],替换attach的参数即可
API 3:LanguageModelSession.respond —— 向模型提问
let session = LanguageModelSession(model: audio)
let reply = try await session.respond(to: "What do you hear?")
// reply.content: 模型"听到"了什么,全程端侧描述
至此三行核心代码齐活:加载 → 喂音频 → 提问。GUI、CLI、一行式算子背后驱动的都是同一套 KitAudioModel(catalog:) + LanguageModelSession,区别只是封装层级。
四、原理速览:模型内部是怎么"听"的?
用 README.md 的说法,两个模型组成一个 coreai-pipelined GPU 引擎流水线:
- 音频编码器(fp16):16 kHz log-mel 前端采用 Whisper-large-v3 参数(Accelerate/vDSP 实现),与 HF 特征提取器逐位一致(cos 相似度 1.0),把音频切成声学特征
- 文本解码器(int8lin):音频嵌入存放在一个静态输入缓冲区
audio_embeds [750,2048]中,提示词里的<|AUDIO|>占位符携带vocab + slot扩展 id 由计算图收集;TMRoPE 对音频+文本退化为一维位置,因此位置是引擎原生的,无需额外 rope-shift 输入
解码器 int8lin 量化通过 top-1 精确对比 fp32 HF oracle 的校验门,编码器重写后与 eager 的 cos 相似度为 1.0(GPU 0.99999);iPhone 贪心解码与 Mac 输出内容一致。
五、上手实战:用 AudioChat 跑通第一个 Demo
🎬 最省事的验证方式:
git clone https://gitcode.com/hf_mirrors/mlboydaisuke/Qwen2.5-Omni-3B-Audio-CoreAI
clone 本项目后可先浏览 README.md 了解完整运行流程与设备覆盖情况。官方验证过的设备包括 iPhone 17 Pro(A19 Pro)和 M4 Max。
对应的 AudioChat 示例 App 支持 GUI + CLI 双模式,一个 App 覆盖目录里所有音频理解模型。macOS 无头模式示例:
swift run -c release audiochat-cli --model qwen2.5-omni-3b-audio --audio sample.wav --prompt "What do you hear?"
六、常见问题 FAQ
Q:音频最长能传多长? A:约 30 秒(编码器 K=15 的设计上限),超长的先切段。
Q:模型占多少空间? A:解码器 + 编码器合计约 5.5 GB(Mac),iPhone AOT 解码器约 4.5 GB。首次运行自动下载并缓存。
Q:Debug 模式跑得很慢正常吗? A:正常,Debug 比 Release 慢约 3 倍,性能测试请用 Release。
Q:iPhone 上会不会被系统杀掉?
A:本项目已用 AOT(.aimodelc)解码器规避端侧 JIT jetsam 问题,12 GB 设备加载后仍留约 5.9 GB 内存余量(需 increased-memory-limit entitlement)。
Q:License 是什么? A:Apache-2.0(继承 Qwen2.5-Omni-3B),社区转换版本,与 Alibaba、Apple 无官方关联。
七、总结:一张图记住你的 App 架构
麦克风 / 音频文件
↓ 解码为 16kHz mono PCM(≤30s)
MicRecorder / AudioFile.pcm16kMono
↓ attach(samples:)
KitAudioModel(catalog:) ← 端侧下载 + 缓存
↓
LanguageModelSession.respond(to:)
↓
reply.content ← 模型"听到了什么"的完整描述
掌握 describeAudio、KitAudioModel + attach、LanguageModelSession.respond 这 3 个 API,你就已经具备开发端侧音频对话 App 的全部核心能力。剩下的只是 UI 和权限的功课——音频数据全程不出设备,这正是端侧 Core AI 的魅力所在。🎧