01七条论断
如果只读一页,读这里。每一条都能在源码里被证伪——这是本文唯一的写作标准。
耦合点是协议,不是框架
应用只依赖两件事:一个接受 multipart WAV 的 transcription 端点,一个说 OpenAI Chat Completions SSE 的对话端点。换掉 audio.cpp 或 llama.cpp,只要新引擎说这两句话,Swift 侧一行都不用改。反过来说,这也是它敢在上一版把整套 Python worker 整体删除的底气。
稳定性来自「把不可靠的东西挪到进程外」
模型推理是最可能崩的一段代码,也是内存占用最大的一段。它被放进两个独立进程:崩了只影响那一个引擎,UI 存活并展示失败原因;应用重启也不会去杀端口上归属不明的进程。代价是跨进程通信与状态同步,收益是崩溃半径被压到最小。
EngineWorker.swift:111 · MinutesApp.swift:62正确性由三个计数器守住:闸门、代次、序号
并发送识别会压垮引擎(闸门),在飞的旧结果会覆盖新分段(代次),识别完成顺序与音频顺序不一致会让转写串行(序号)。三个问题各配一个极小机制,加起来不到 80 行,但缺任何一个都会出现「文字乱序」「重复句」「丢句」这类难复现的诡异 bug。
MeetingSession.swift:7,117,306「就绪」不是布尔值,是一个待证明的身份
端口上有人应答 HTTP 200 不等于「我的模型加载好了」。健康检查同时校验运行时特征、模型路径(符号链接归一后逐字符比对)和加载状态;三者任一不符就判 incompatible 而不是 ready。这让「旧进程还没退干净」「端口被别的服务占了」从玄学变成一句明确报错。
断句问题被从声学搬到了文本
没有 VAD。音频按固定 1.5 秒节奏整段送识别,切段的条件是「识别文本以句末标点收尾且音频够长」,或「段长触顶 15 秒」。复杂声学环境下的能量阈值不可靠(噪声爬升漏检、切句点断词),而标点由模型给,稳定得多。
MeetingSession.swift:89-97,137供应链是代码的一部分,不是 README 的一句话
上游 commit、模型 revision、字节数、SHA256 全部锁进 dependencies.lock;构建脚本还会用 otool 检查产物没有偷偷链上 Python.framework、Torch、MLX、ffmpeg 或 Homebrew。镜像只影响传输,不影响最终校验。
「原生」不等于「全面更快」,文档自己也承认
迁移到 Metal 原生服务后,ASR 耗时降到约一半、内存 footprint 降 36–51%,LLM 总耗时降 8%——但纯生成速度从 85.30 掉到 80.76 token/s。这个倒退被写进了基准文档而不是藏起来,是这套工程里最值得学的一处诚实。
Benchmarks/README.md:原生版本小节02系统全景
一句话:一个 SwiftUI 应用进程,加两个由它拉起、只监听回环地址的原生推理进程。三者之间没有共享内存、没有私有 RPC、没有 Python。
EngineClient 是唯一发网络请求的组件——EngineSupervisor 只做进程与状态的聚合,不碰数据面。运行时契约
把「进程边界」当作架构里一等公民,代价与收益都要写清楚。下面这张表是两侧实际约定,不是设计意图的转述。
| 维度 | ASR 侧 | LLM 侧 |
|---|---|---|
| 可执行文件 | engine/bin/audiocpp_server | engine/bin/llama-server |
| 默认端口 | 8797(避开常被占用的 8787) | 8788 |
| 模型别名 | minutes-asr | minutes-llm |
| 启动参数 | 由应用生成 runtime/asr-<port>.json | 纯命令行参数,无配置文件 |
| 数据面 | multipart/form-data + PCM16 WAV | JSON + text/event-stream |
| 身份证明 | backend=metal + 模型 family=qwen3_asr + loaded + 路径一致 | build_info 非空 + model_path 一致 + 非 sleeping |
| 就绪判据 | HTTP 200 且模型已加载 | HTTP 200;503 且 message 含 loading 视为启动中 |
| 超时策略 | 单请求 600s,资源 3600s | 启动探测 1.5s,总等待 180s |
两个引擎都不接受「应用内嵌」。嵌入式调用能省掉 HTTP 与进程管理,但会让模型崩溃等于应用崩溃、模型内存常驻不可回收、也无法在应用重启时保留已加载的权重。当前形态的代价是每次识别多一次回环 HTTP(<1ms 量级),收益是崩溃隔离与可独立观测。对「一次会议要跑一两个小时」的场景,这个交换是划算的。
03进程契约:什么时候必须重启,凭什么算就绪
进程管理的难点不在「拉起来」,在「判断该不该拉」和「判断拉起来的到底是谁」。前者用启动签名,后者用三重身份校验。
启动签名:一个字符串取代一堆布尔标记
EngineWorker 没有为端口、模型、路径各存一个 didChange 标记,而是把它们拼成一个签名。每次 start() 先算当前签名,与正在运行的那个比对:一致且已 ready 就什么都不做;不一致就先把旧进程停掉。这让「改完端口点启动」这种操作不会出现两个进程抢同一个端口。
// EngineWorker.swift:89 — 任一变化都必须重启
private func launchSignature() -> String {
[
configuration.engineRoot,
configuration.modelPath(for: kind),
String(configuration.port(for: kind)),
kind == .llm ? String(configuration.llmContextSize) : "offline",
].joined(separator: "|")
}
签名还被用来做竞态护栏:所有状态跃迁函数(becomeReady / failIfStarting)都要求「当前签名等于当初传入的签名」才生效。用户在中途改了端口,那个还在跑的旧 Task 就无法把新会话误标成 failed。
三重身份校验:把「端口上有人」变成「端口上是我的人」
只查 GET /health 是否 200 是不够的——上一版遗留的 Python worker 也会返回 200。当前实现要求同时满足三个条件,任一不符即判 incompatible 并给出可读原因:
① 运行时特征
LLM 要求 /props 返回非空 build_info;ASR 要求 health.backend == "metal" 且有 version。旧 Python 服务没有这些字段。
② 模型路径一致
取服务自报的模型路径,与设置里的期望路径各自做 expandingTildeInPath → standardizedFileURL → resolvingSymlinksInPath 归一后逐字符比对。
③ 加载完成
LLM 要求 is_sleeping 为假;ASR 要求模型条目 configured 且 loaded 为真。否则返回 starting,继续等。
// EngineHealth.swift:11 — 返回三态而非布尔
static func validateLLM(health: [String: Any], props: [String: Any],
expectedModelPath: String) -> Status {
guard health["status"] as? String == "ok",
let build = props["build_info"] as? String, !build.isEmpty
else { return .incompatible("端口上的服务不是受支持的 llama.cpp") }
guard let modelPath = props["model_path"] as? String
else { return .incompatible("llama.cpp 未返回模型路径") }
guard pathsEqual(modelPath, expectedModelPath)
else { return .incompatible("加载的模型与当前设置不一致") }
if props["is_sleeping"] as? Bool == true { return .starting }
return .ready(detail: "llama.cpp \(build)")
}
端口被占用时,代码分得清三种情况
这是「本地服务」类应用最常见的支持工单来源。当前实现不猜,直接探测后分流:
| 探测结果 | 含义 | 动作 |
|---|---|---|
unavailable | 端口无人应答 | 自己拉起进程,等它健康(180s 上限) |
starting | 有服务在,但模型还在加载 | 不重复拉起,只轮询等它 ready,之后转为外部存活监测(每 5s) |
incompatible | 有服务在,但不是我要的那个 | 立即失败并提示「端口被占用:…。请停止旧服务或修改端口」 |
注意第二行的细节:外部启动的服务没有 Process 终止回调,所以 ready 之后要切到另一条代码路径继续盯它,否则用户手动 kill 了引擎,应用会一直以为它还活着。monitorExternalHealth 就是那条路径。
拉起子进程前,代码主动从环境里删掉 DYLD_LIBRARY_PATH 与 DYLD_FALLBACK_LIBRARY_PATH(EngineWorker.swift:142)。否则在 Xcode 里启动应用时,继承来的这两个变量会让 llama-server 加载到错误版本的动态库——表现是启动即崩溃,日志里看不出原因。
04数据流水线:从麦克风到可读纪要
一条主线,九个环节,没有任何环节把音频或文本送出本机。整条链上只有三处异步:音频回调、识别请求、SSE 流。
节奏参数:全部集中在 MeetingSession 顶部
| 参数 | 值 | 为什么是这个值 |
|---|---|---|
pollInterval | 1.5 s | 离线识别 25 s 音频耗 0.96 s,1.5 s 的节奏留有 1.5 倍余量;再密就是空转 |
minCloseSeconds | 5 s | 防止「嗯。」「好。」这类极短句被切成独立段,导致分段碎片化 |
maxSegmentSeconds | 15 s | 无标点(连续讲述)时的兜底切分,保证时间戳密度 |
bufferCapSeconds | 60 s | 覆盖引擎重启窗口;超出丢最旧,防止内存无界 |
TranscriptionGate.limit | 2 | 让「正在进行的识别」与「刚完成的识别」有重叠,又不至于排队雪崩 |
| 最短音频 | 0.5 s | samples < 8000 直接返回空文本,不触发模型推理 |
三个计数器:整条链的正确性支点
闸门 · TranscriptionGate
一个 actor 实现的计数信号量,但它提供两种取法,语义完全不同:
tryAcquire()——宁可丢,不可堵。用于 1.5 s 节奏的中间结果识别:拿不到名额就跳过这一轮,下一轮 1.5 s 后还有机会。acquire()——必须拿到。用于会议结束时的冲刷:最后一段音频丢了就永久丢了,值得等。
这个区分很关键。如果全用阻塞版,引擎变慢时请求会堆积,越堆越慢,最后超时丢一片;如果全用非阻塞版,收尾那段音频可能永远等不到名额。
代次 · interimGeneration
发出识别请求时记下当前代次,结果回来后比对:不等就整个丢弃。因为在此期间缓冲可能已经被切段(closeSegment 里 interimGeneration += 1)或冲刷(flushBuffer 同样 +1)。没有这一层,一个慢回来的识别结果会把已经落定的分段又写成 interim 文本,用户看到「刚说过的字又退回去」。
序号 · sequence + pendingSequences
识别是并发的(limit=2),完成顺序天然不等于音频顺序。落定时分配递增序号,先进 pendingSequences 字典,只有当 nextExpectedSequence 存在时才出队追加到 meeting.segments。一个晚到的 5 号会等在字典里,直到 0–4 都到齐。
代码注释写得很直白:能量阈值在复杂声学环境下不可靠(噪声爬升漏检、切句点断词)。VAD 的误判会直接变成「漏字」或「断词」,而这类错误用户无法自行修正。改用固定节奏 + 文本标点后,最坏情况只是分段粒度不理想,文本本身仍完整——把不可恢复的错误降级为可恢复的瑕疵,这是整条流水线里最值得抄的一个决策。
05分层与职责边界
22 个 Swift 文件、2,893 行。分层不是按「MVC」切的,而是按「谁依赖谁的隔离域」切的——读依赖方向比读目录名有用。
| 层 / 文件 | 行 | 职责 | 边界约束 |
|---|---|---|---|
| 入口 MinutesApp | 65 | 窗口、设置场景、启动与退出钩子 | 测试宿主下不启动模型(检测 XCTestCase 是否存在) |
| 表现层 · 913 行 | |||
| ContentView | 106 | 三栏骨架、工具栏、空状态 | 只读 supervisor 状态决定按钮可用性,不发起引擎操作 |
| SidebarView | 92 | 会议列表、删除确认 | 删除按钮常驻占位、只切透明度,避免布局跳动 |
| LiveMeetingView | 105 | 状态条、波形、暂停/继续/结束 | 只调 session 的方法,不直接碰 client |
| TranscriptView | 93 | 分段列表、interim 灰字、自动滚底 | 按 sequence 排序后再渲染,双保险 |
| MinutesView | 228 | 纪要四节、转写原文、重生成、标题编辑 | 长转写按行 LazyVStack;DateFormatter 静态缓存 |
| SettingsView | 183 | 模型路径、端口、Prompt、诊断日志 | 路径即时校验并给出可读错误 |
| EngineStatusControl | 106 | 工具栏状态灯 + 启停菜单 | 把两个 worker 的多态折叠成一个总体状态 |
| 领域与会话 · 713 行 | |||
| MeetingSession | 421 | 状态机、节奏识别、切段、纪要编排 | @MainActor;不 import SwiftUI,状态靠 @Observable 投影 |
| MinutesComposer | 145 | 提示词、分块、map-reduce、四节解析 | 纯函数集合,无副作用,可单独单测 |
| MeetingsStore | 63 | 会议列表加载、保存、删除 | 文件名只由会议 id 决定,反复保存不产生重复文件 |
| Models | 84 | Meeting / TranscriptSegment / MinutesDocument / 错误类型 | 全部 Codable + Sendable,无行为 |
| 引擎接入 · 891 行 | |||
| EngineWorker | 415 | 单进程生命周期、健康探测、日志泵、退避重启 | @unchecked Sendable + NSLock;健康探测跑在 detached Task |
| EngineConfiguration | 177 | 路径、端口、Prompt、配置迁移 | @unchecked Sendable(UserDefaults 本身线程安全) |
| EngineClient | 168 | WAV 上传、SSE 流式对话 | actor;全应用唯一发网络请求处 |
| EngineSupervisor | 66 | 两个 worker 的状态与日志聚合 | @MainActor @Observable;日志环形上限 2000 行 |
| EngineHealth | 65 | 把两种上游健康响应归一为三态 | 无状态纯函数,路径比较前做符号链接归一 |
| 传输与编码 · 194 行 | |||
| OpenAIStreamParser | 105 | 逐字节 SSE 状态机 | 值类型 struct;[DONE] 缺失即抛错,不保存半篇 |
| WAVEncoder | 50 | float32 → PCM16 WAV | 拒绝 NaN/Inf;超长直接抛错而不是静默截断 |
| ASRServerConfiguration | 39 | 按当前配置生成 audio.cpp 的 JSON | 每次启动重写;请求体上限 8 MiB |
| 采集与基础设施 · 117 行 | |||
| AudioCaptureService | 98 | 麦克风采集、重采样、RMS | 实时音频线程只做转换与 yield,不做任何 IO |
| Log | 19 | os.Logger 分四个 category | 无自定义日志框架,接系统 Console |
依赖方向
依赖是一条单向链,没有回边:Views → MeetingSession → EngineClient → HTTP,而 EngineSupervisor 与 MeetingSession 之间是平级注入而非包含。这点在代码里体现得很具体——MeetingSession 持有 engineSupervisor 的引用是为了读 states 和 baseURL,它并不命令 supervisor 去启动引擎;启停是用户在工具栏或设置里做的独立操作。
好处是「引擎没就绪」这个条件可以优雅降级:start() 检查不到 ASR ready 就设 errorMessage 返回,composeMinutes() 检查不到 LLM ready 就只保留转写原文并写一句提示。整条链路没有一处假设引擎一定可用。
06引擎生命周期与自愈
四个状态、五条转移。真正值得看的是两条边上的策略差:为什么一种退出要重试,另一种绝对不重试。
EngineWorker 的状态机。注意 starting → failed 与 ready → failed 落进同一个状态,但后续行为完全不同:前者不重试,后者退避重试。区分逻辑在 handleTermination 里。为什么「启动即退出」不重试
如果 starting 阶段进程就退出了,几乎一定是配置问题:模型文件不存在、端口被占、GGUF 与二进制不匹配。这类错误重试一万次也是同样的结果,只会把 CPU 吃满、把日志刷爆、且用户看不到真正原因。所以代码在这里直接返回,把日志留给用户看:
// EngineWorker.swift:243 — 两种退出,两种待遇
if case .ready = state {
state = .failed("\(kind.runtimeName) 意外退出,正在自动重启…")
} else if case .starting = state {
// 启动即退出通常是模型、端口或配置错误,先展示日志,不做崩溃循环
state = .failed("\(kind.runtimeName) 启动即退出,详见日志")
return
} else { return }
failureCount += 1
let backoffNanos = UInt64(3 * min(1 << min(failureCount, 4), 16)) * 1_000_000_000
| 连续失败次数 | 1 | 2 | 3 | 4 | ≥5 |
|---|---|---|---|---|---|
| 退避等待 | 6 s | 12 s | 24 s | 48 s | 48 s(封顶) |
封顶 48 秒而非无限增长,是因为本地推理进程的典型故障(显存不足、模型被外部删除)恢复后重试就能成功,长退避只会让用户以为「卡住了」。成功进入 ready 时 failureCount 归零,下次崩溃仍从 6 秒起步。
应用级启动编排
AppDelegate 做了一件不太显眼但很实用的事:启动 3 秒后,对仍处于 failed 的 worker 再试一次。
原因是上一个应用实例的模型进程可能还在退出过程中——用户按 Cmd+Q 后立刻重开,旧进程还占着 8797/8788,新实例的健康探测会判 incompatible(「端口被占用」)。等 3 秒后旧进程通常已释放端口,重试即成功。这比「无条件重试」克制,也比「让用户自己点重试」友好。
只重试 failed 的、不重试 ready 的,也不会打断正在正常加载的引擎。
07并发模型:五个隔离域,各管一件事
Swift 6 的严格并发检查会逼着人做选择。这个项目没有「一刀切全上 actor」,而是按「这段代码能不能阻塞」分成五类——这是全文技术含量最高的一节。
| 隔离域 | 承载者 | 为什么是它 |
|---|---|---|
| 主 actor | Views、MeetingSession、EngineSupervisor |
@Observable 的变更通知与 SwiftUI 渲染必须在主线程;状态机的相位推进也只在这里发生,天然串行 |
| 自定义 actor | EngineClient、TranscriptionGate |
保护 URLSession 的调用与信号量计数。两者都不做阻塞操作,纯 async/await,适合 actor |
| detached Task | 健康探测、退避重启、外部服务监测 | 健康探测内部用 DispatchSemaphore 同步等 HTTP 返回。如果继承 MainActor,就会把 UI 冻住 1.5 秒 |
NSLock |
EngineWorker 的进程句柄与状态、HealthResponseBox |
这些读操作需要同步返回(如 isStarting(signature) 在 guard 里用),改成 async 会污染整条调用链 |
| 实时音频线程 | AudioCaptureService.handleInput |
CoreAudio 回调线程,不能 await、不能分配锁。只做格式转换、算 RMS、continuation.yield |
关键一处:为什么 EngineWorker 不是 actor
直觉上「进程管理器」最像 actor。但它的健康探测是这样写的:
// EngineWorker.swift:372 — 同步等待,不能放进 actor
private func fetch(_ path: String) -> (data: Data?, response: HTTPURLResponse?) {
let semaphore = DispatchSemaphore(value: 0)
let result = HealthResponseBox()
URLSession.shared.dataTask(with: request) { data, response, _ in
result.store(data: data, response: response as? HTTPURLResponse)
semaphore.signal()
}.resume()
semaphore.wait() // ← 阻塞当前线程直到超时(1.5 s)
return result.load()
}
在 actor 里 semaphore.wait() 会独占该 actor 的执行器线程,而回调 store(...) 又要进同一个 actor——直接死锁。所以这里是 @unchecked Sendable + NSLock + 在 Task.detached 里跑的经典组合。代码里那句注释就是结论:健康探测内部有信号量等待,不能继承 MainActor。
这里用同步阻塞 HTTP 换取的是「状态判断的原子性」:探测结果、签名比对、状态跃迁在一个不可打断的片段里完成。如果改成 async,就会多出若干个 await 挂起点,每个挂起点都可能让用户改配置、让旧 Task 完成——那才是真正的竞态温床。代价是 1.5 秒的线程占用,但它在 detached 线程上,不影响 UI。
主线程为什么不会被网络请求堵住
MeetingSession 标了 @MainActor,整条流水线看起来都在主线程跑。实际上不会阻塞,因为:
pipelineTask虽然继承@MainActor隔离,但它在for await chunk in stream处挂起,把主线程交还出去;每块音频回来只做几十微秒的数组追加。client.transcribe(...)是跨 actor 调用,await期间主 actor 完全空闲,SwiftUI 正常渲染。- SSE 逐字节解析(
streamChat)跑在EngineClient的 Task 里,只有解析出的文本块才yield回主 actor 追加到composedText。
换句话说,主线程承担的是「状态变更」,不是「数据传输」。这是 @MainActor 用得对不对的分水岭:把状态放主线程是必须的,把等待放主线程才是错的。
日志的跨域投递
worker 的 stdout/stderr 由 readabilityHandler 在任意线程上泵出,要进 @MainActor 的 EngineSupervisor.logs。做法是 Task { @MainActor in ... },并在每行带上 Date() 时间戳——因为经过调度后到达顺序不保证严格等于产生顺序,靠时间戳而不是数组位置来表达真实次序。日志环形上限 2000 行,超出丢最旧,长时间挂机不会吃内存。
08数据模型与持久化
没有任何数据库。一场会议一个 JSON 文件,键名有序输出,可以直接 cat、可以 diff、可以手工修。
三层结构
Meeting 是根,包含元信息、分段数组、可选纪要和一份冗余的纯文本转写:
Meeting
├── id: UUID // 同时是文件名
├── title: String // 空则由 LLM 生成,失败回退「M月d日 HH:mm 会议」
├── createdAt: Date // ISO8601 编码
├── duration: TimeInterval
├── segments: [TranscriptSegment]
│ ├── start / end // 相对会议开始的秒数
│ ├── text
│ ├── language // 引擎自报,可能为 nil
│ └── sequence // 落定顺序,用于归位与排序
├── minutes: MinutesDocument?
│ ├── summary // 摘要正文
│ ├── decisions[] // 决议条目
│ ├── actionItems[] // 行动项条目
│ └── keywords[] // 关键词
└── transcriptText: String // 冗余:所有分段用 \n 拼起来
transcriptText 是刻意的冗余。它让「重新生成纪要」不必遍历分段重拼,也让旧版本数据(只有分段、没有该字段)能靠 segments.map(\.text).joined() 平滑兼容——MinutesView 里就是这个兜底写法。
文件名策略里的一次事故
fileURL(for:) 上面写着:文件名只由会议 id 决定:同一次会议反复保存只落一个文件,反复 save 不会产生带不同时间戳前缀的重复文件。 而在 MeetingSession.init 里还有另一段注释,记录了更严重的问题:
曾共用 store.draft 的副本,所有新会议 id 相同,后一个会把前一个在列表和磁盘上整体覆盖——「新建会议把上一个会议整没了」的元凶。
两处注释合起来说明一件事:标识符策略必须与持久化策略一起设计。id 复用会让「保存」变成「覆盖」,而这类 bug 在 UI 上表现为「数据莫名其妙消失」,极难归因。
写入的原子性
data.write(to:options: .atomic) + JSONEncoder.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]。三个选项各有明确目的:
- atomic:先写临时文件再替换,进程在写入中途被杀不会留下半截 JSON(否则下次启动解码失败,整场会议丢失)
- prettyPrinted + sortedKeys:让人读、让 diff 稳定。同一份数据两次保存产生完全相同的字节,git 里不会出现假变更
- withoutEscapingSlashes:路径和 URL 里的
/不被转义成\/,可读性
加载侧是「宽松解析」:compactMap { try? decoder.decode(...) },单个文件损坏只会少一场会议,不会导致列表整体加载失败。这是本地文件存储的正确姿势——一份坏数据不该拖垮全部。
配置迁移
EngineConfiguration 维护 engineConfigurationVersion(当前为 2)。迁移逻辑只处理一件具体的事:把两个旧硬编码默认路径(MLX 的 HF 缓存目录、旧 qwenasr-studio 的模型目录)一次性改写成新的 GGUF 默认路径,自定义路径原样保留。
这里有个细节值得注意:testEmptyDefaultsDoNotFreezeEnvironmentDrivenModelRoot 这个测试在断言——空配置时不要往 UserDefaults 里写值。因为一旦写了,后续 MINUTES_MODELS_ROOT 环境变量就再也不会生效(getter 优先返回已存的值)。「默认值不应该被固化成显式配置」,这是配置系统里最容易踩的一脚。
09供应链:把「可复现」写成脚本
从「git clone 一下」到「一条命令得到字节级可验证的引擎」,中间隔着一份锁文件、两个脚本和一道 otool 门禁。
锁文件:所有不确定性收敛到一处
Engine/dependencies.lock 是个 19 行的 Bash 片段,被两个脚本 source 进去。它同时锁住了源码版本与模型版本:
| 锁定项 | 值 | 作用 |
|---|---|---|
| audio.cpp commit | 6f71a3b87105b974… | ASR 服务源码 |
| llama.cpp commit | 513ad7ae0770cdd7… | LLM 服务源码 |
| ASR 模型 revision | 7a103b33f0412053… | Qwen3-ASR-1.7B Q8_0 |
| ASR 字节数 / SHA256 | 2,473,017,600 / 3bc2462e… | 完整性校验 |
| LLM 模型 revision | e87f176479d0855a… | Qwen3.5-4B Q4_K_M |
| LLM 字节数 / SHA256 | 2,740,937,888 / 00fe7986… | 完整性校验 |
关键在于镜像只影响传输路径,不影响验收标准。下载脚本列了三个来源(ModelScope 镜像 → hf-mirror → Hugging Face 官方),逐个尝试;无论从哪个来源拿到,最终都必须通过锁文件里的字节数与 SHA256。这解决了国内网络环境下的真实痛点,又没有牺牲可验证性。
构建脚本的四道门
① 工具存在性
逐个检查 git cmake clang++ xcrun curl install otool codesign tar,以及 metal 编译器。缺任何一个都在第 0 秒失败,而不是编译到一半。
② 源码获取三路
git fetch --depth 1 优先;失败则下载同提交的 tarball;再失败则用已经验证过的本地归档。每路都写 .minutes-source-commit 印记。
③ 二进制卫生
otool -L 扫产物,出现 Python.framework、Torch、MLX、ffmpeg、/opt/homebrew 即报错退出。确保「零 Python」不是口号。
④ 原子安装
先 install -m 755 到 .name.installing,再 mv 覆盖,最后 ad-hoc codesign。应用运行中升级不会读到半个可执行文件。
构建配置本身也是「够用就好」的取向:关掉 tests、examples、UI、CURL、OpenSSL,只留 server;BUILD_SHARED_LIBS=OFF 生成静态链接,避免 dyld 找库问题;GGML_METAL_EMBED_LIBRARY=ON 把 metallib 嵌进二进制,省掉运行时定位资源目录的麻烦。
下载脚本:把「断点续传」做对
没有用 huggingface-cli,也没有 pip。只用 curl、shasum、stat、xargs,代价是要自己处理分块。几个细节说明作者踩过坑:
- 每块用
--range start-end,并校验 HTTP 状态必须为 206——服务器若不支持 Range 会返回 200 和整个文件,不校验就会拼出 4 倍大小的垃圾 - 先写
.download临时文件,长度正确才mv。失败的块不会污染已完成块 - 分块文件名零填充序号(
.chunk.00007),cat target.chunk.*的展开顺序即字节顺序——不需要额外排序 .chunk-layout记录「总字节数:块大小」,块大小变了就清掉旧块重下,避免新旧布局混拼- 某来源失败时保留已完成块,换下一个来源只补缺的块
拼装后做一次全文件 SHA256,不符则清理全部分块并报错。宁可让用户重下 2.5 GB,也不让一个损坏的 GGUF 进入推理路径——后者会导致难查的乱码输出。
两个脚本开头都检查 id -u,发现是 root 立刻退出并说明原因:引擎装在当前用户的 ~/Library/Application Support/Minutes,用 sudo 跑会改为查 root 的目录,结果是应用找不到文件。这条提示同时出现在 README 里,属于「一定会有人踩」的坑。
10验证体系:三层,从纯逻辑到真实推理
6 个单元测试文件、359 行,一个 XCTest 宿主之外的冒烟程序。三层各自负责一种失败模式,谁都不越界。
| 层 | 手段 | 守住什么 |
|---|---|---|
| 纯逻辑单测 | WAVEncoderTests、OpenAIStreamParserTests、MinutesComposer 解析 | 字节级正确性:WAV 头 44 字节、−32767 的位模式、UTF-8 跨字节不破、CRLF 与多行 data |
| 契约单测 | EngineClientTests(URLProtocol 打桩)、EngineHealthTests、EngineConfigurationTests | 请求形状(multipart 头、model=minutes-llm、stream=true)、身份校验拒绝旧服务、配置迁移不冻结默认值 |
| 真实闭环 | scripts/verify_native.sh + Benchmarks/NativeWorkerSmoke | 真进程、真模型、真音频:两个 worker 就绪、ASR 关键词命中、LLM 四节格式、map-reduce 产出摘要 |
为什么闭环验证要绕开 XCTest
verify_native.sh 用 swiftc 直接把 9 个源文件和一个 main.swift 编成一个独立可执行文件,不经过 XCTest 宿主。理由写在脚本注释和 README 里:XCTest 宿主下环境变量常常传不进去,导致依赖 MINUTES_SMOKE_ASR 的断言静默跳过——测试显示「全部通过」,实际什么也没验。
这是一类容易被忽视的假绿:XCTSkip 和「条件不满足就 return」都会让 CI 显示绿灯,但覆盖面为零。绕开宿主是最彻底的修法。
三道断言都是内容级的,不是「有没有返回」级的:
- ASR:识别结果必须包含「虚拟电厂」——防止引擎「成功返回了但输出是空的/乱码」
- LLM:输出必须同时包含
## 摘要与## 行动项,且不得包含<think>——后者验证--reasoning off真的生效了 - map-reduce:把一个 700 行重复段落(远超 12000 字符)喂进去,必须产出非空 summary
EngineWorkerTests 要验证「启动即退出应立刻 failed,而不是等 180 秒超时」。它把 /usr/bin/false 复制成假的 audiocpp_server——一个必定以非零码退出的可执行文件——然后断言 5 秒内进入 failed。用系统自带二进制构造失败场景,不需要 mock 框架,也不需要真的模型。
11性能基线:一次诚实的迁移复盘
从「PyTorch/MPS + MLX」换到「audio.cpp + llama.cpp 原生 Metal」,六个指标里五个变好、一个变差。这个变差被写进了文档,而不是从表里删掉。
| 指标 | 旧版 | 原生 | 变化 | 判读 |
|---|---|---|---|---|
| ASR 11.4 s 音频 | 1.061 s(RTF 0.093) | 0.545 s(RTF 0.048) | −49% | 明显改善 |
| ASR 25 s 音频 | 1.909 s(RTF 0.076) | 0.957 s(RTF 0.038) | −50% | 长音频优势稳定 |
| LLM 首 token(TTFT) | 0.366 s | 0.024 s | −93% | 含 prompt cache 命中,不能直接比 |
| LLM 总耗时 | 2.996 s | 2.755 s | −8% | 小幅改善 |
| LLM 生成速度 | 85.30 tok/s | 80.76 tok/s | −5% | 退步 |
| ASR footprint | 6,245 MB | 3,065 MB | −51% | 显著改善 |
| LLM footprint | 3,543 MB | 1,284 MB | −64% | 显著改善 |
| ASR RSS | 约 1.02 GiB | 约 3.09 GiB | +202% | 口径相反,需并列看 |
| LLM RSS | 约 3.37 GiB | 约 3.87 GiB | +15% | 同上 |
为什么不能只报一个内存数字
文档里同时保留 ps RSS 与 phys_footprint,并明确写出「两种口径均保留,避免把 mmap/统一内存差异误写成单一的内存结论」。这是很专业的克制:
llama.cpp用mmap映射 GGUF,RSS 会把映射页也算进去,因此看起来更大;而phys_footprint更接近系统实际承压- 「原生内存降低 51%」和「原生 RSS 上升 203%」两句同时为真。只引用一半,就是选择性陈述
量化带来的质量差异,也被写下来了
同一个 25 秒样本,旧版开头识别为「数据合在一起…总出力…」,新版为「时聚合在一起…总处理…」,新版还多出「核电状态」。文档的结论是:
主体内容一致,但个别词错误说明 Q8 不能视为与 FP16 完全等价,后续仍应使用带人工校对文本的会议集评估 CER。
同时它也明确写了「当前样本没有人工校对参考文本,因此本表不虚构 CER/WER」。在一个很容易吹指标的领域里,这两句比任何数字都更能说明工程素养。
方法学
为了可复现,基准测试本身是代码:Benchmarks/NativeWorkerSmoke/main.swift 在真实进程上跑,TTFT 用服务器返回的 prompt_ms、生成速度用服务器 token 计数(不拿字符数换算 token)。每个样本预热 1 次、测 5 次取中位数并给出范围。RSS 是采样值不是峰值监控,文档也如实标注了这一点。
12边界与技术债
这一节按「多久会开始咬人」排序,而不是按好修程度排。第一条是读代码时发现的真实缺陷,建议优先实机复现。
| # | 问题 | 位置 | 表现 | 严重度 |
|---|---|---|---|---|
| 1 | 暂停/继续的时间基准不一致 | MeetingSession.swift:99,203,243 |
恢复后长时间不再出字;分段时间戳回退到 00:00 附近 | 高 |
| 2 | 分块不拆超长单行 | MinutesComposer.swift:43 |
单行超过 12000 字符时块预算失效,可能撑爆上下文 | 中 |
| 3 | 写盘失败被静默吞掉 | MeetingsStore.swift:49 |
磁盘满或权限异常时会议未落盘,UI 无任何提示 | 中 |
| 4 | 长会议 map 阶段串行 | EngineWorker.swift:131 |
--parallel 1,两小时会议要跑 N 次串行压缩 |
中 |
| 5 | 无 CI | 仓库根 | 6 个测试文件靠本机 Xcode 手跑,回归全凭自觉 | 中 |
| 6 | 旧路径常量含开发者绝对路径 | EngineConfiguration.swift:53 |
迁移逻辑只在作者本机命中;开源仓库暴露用户名 | 低 |
| 7 | 默认端口写死 | EngineConfiguration.swift:17 |
8797/8788 被占需手动改,改完要重启对应 worker | 低 |
| 8 | 沙箱未启用 | project.pbxproj |
CODE_SIGN_ENTITLEMENTS 为空;无法上架 App Store |
设计选择 |
第一条展开:为什么暂停会打断识别
这不是风格问题,是一条能推出具体症状的路径。三个事实串起来:
pause()只是取消采集任务并停止引擎,既不清空buffer,也不冲刷它;resume()走start(),音频 offset 的基准被重新设为startTime = Date(),即从 0 重新计;appendToBuffer只在buffer.isEmpty时才更新bufferStart。
于是恢复后的第一块音频会让 bufferStart 保持暂停前的旧值(例如 1234.5 秒),而 bufferEnd 变成 0.28 秒,bufferLength 直接成为负数。轮询条件是 bufferLength - lastPollAt >= 1.5,负值永远不满足,识别就此静默停止,直到 offset 重新长过暂停前的累计时长。
// MeetingSession.swift:99 — 只有 buffer 为空才重置起点
private func appendToBuffer(_ chunk: CapturedChunk, offset: TimeInterval) {
if buffer.isEmpty { bufferStart = offset } // ← 恢复后 buffer 仍非空,这里不执行
buffer.append(contentsOf: chunk.samples)
bufferEnd = offset + Double(chunk.samples.count) / 16000.0
var bufferLength = bufferEnd - bufferStart // ← 0.28 - 1234.5 < 0
if bufferLength - lastPollAt >= pollInterval { ... } // ← 永不成立
}
复现:开一场会议,说 2–3 分钟让 bufferStart 累积到较大值,点暂停,10 秒后点继续,然后持续说话——正常情况下应每 1.5 秒更新一次灰色 interim 文本,实际会长时间没有任何新字。
修法:pause() 里把缓冲一并处理掉(要么 await flushBuffer() 落定,要么直接清空并重置 bufferStart/lastPollAt)。后者更简单,代价是最多丢 1.5 秒音频;前者更完整,但 pause 目前是同步方法,需要改成 async 或起一个 Task。
说明:以上由静态代码路径推断,未做运行时复现。同一根因还会让恢复后的分段时间戳从 00:00 重新开始,与顶部的会议计时脱节。
第二条展开:分块函数的隐含前提
makeBlocks 按行累加,块间不拆行——这个设计的理由是「保证每块语义完整」,本身是对的。但它隐含假设「单行不会超过预算」。转写文本是 ASR 输出,正常情况下每段几十字,不会触发;但如果将来接入「粘贴一份完整会议记录」或「导入字幕文件」,一行一万多字的情况立刻会让 current 单块超预算,进而在 32768 上下文里挤掉输出空间。
修法很轻:在 line.count > maxChars 时把该行按字符切开,或直接把 maxChars 作为硬上限做二次切分。
这些是边界,不是缺陷
- ASR 是 1.5 秒轮询,不是服务端增量流式。README 自己写明了这一点。用户感知是「说完一句话,半秒到一秒后上屏」,不是逐字浮现。
- 没有说话人分离、没有词级时间戳。片段时间戳由 Swift 采集时钟生成,精度是「段」而不是「词」。要做得靠引入 diarization 模型,那是另一个量级的工程量。
- LLM 单请求槽、上下文 32768。这是为了在 4B 模型上控制内存与首 token 延迟。长会议靠 map-reduce 绕开,而不是靠更大的窗口。
- TTS 已移除。随旧 Python worker 一起删掉了,主流程不再有朗读能力。这是有意识的减法。
13结论与文件索引
三条判断
第一,这套架构的价值在于「把不确定性关进笼子」。模型会崩、端口会被占、识别结果会乱序、用户会在会议中途改配置——每一件都被一个具体机制接住了:进程隔离、三重身份校验、序号归位、启动签名。没有一处用「正常情况下不会发生」来搪塞。
第二,它的复杂度花在了正确的地方。2,893 行里,接近 900 行在引擎接入与进程管理,只有 913 行在界面。对一个「本地推理应用」来说这个比例是对的——难的不是画界面,是让一个会崩溃的模型在用户机器上表现得像一个稳定功能。
第三,它最值得学习的是文档纪律。README 写「当前边界」,基准文档写「这一项退步了」,代码注释写「这里曾经有个 bug 导致新建会议把上一个整没了」。这些不是装饰,它们让下一个人(或下一次的自己)不必重新踩一遍。
优先级建议:先修暂停/继续的时间基准(用户可感知的功能缺陷),再补 CI(防止回归),然后考虑下载脚本的断点续传可观测性(目前分块进度只在 stdout)。至于换更大模型、加说话人分离、开沙箱上架——这些都是产品决策,不是架构债。
文件索引
| 想改什么 | 看这里 | 行数 |
|---|---|---|
| 采集参数、重采样 | Minutes/Audio/AudioCaptureService.swift | 98 |
| 识别节奏、切段规则、分段归位 | Minutes/Meeting/MeetingSession.swift | 421 |
| 纪要提示词、分块、四节解析 | Minutes/Meeting/MinutesComposer.swift | 145 |
| 会话列表与 JSON 读写 | Minutes/Meeting/MeetingsStore.swift | 63 |
| 进程拉起、健康探测、退避重启 | Minutes/Engine/EngineWorker.swift | 415 |
| 身份校验规则 | Minutes/Engine/EngineHealth.swift | 65 |
| HTTP 请求形状 | Minutes/Engine/EngineClient.swift | 168 |
| SSE 逐字节解析 | Minutes/Engine/OpenAIStreamParser.swift | 105 |
| WAV 头与 PCM16 | Minutes/Engine/WAVEncoder.swift | 50 |
| 端口、模型路径、Prompt、迁移 | Minutes/Engine/EngineConfiguration.swift | 177 |
| audio.cpp 的 JSON 配置 | Minutes/Engine/ASRServerConfiguration.swift | 39 |
| 数据模型与错误类型 | Minutes/Core/Models.swift | 84 |
| 原生引擎构建 | scripts/bootstrap.sh | 134 |
| 模型下载与校验 | scripts/download_models.sh | 145 |
| 真进程闭环验证 | scripts/verify_native.sh + Benchmarks/NativeWorkerSmoke/main.swift | 28 + 79 |
| 版本与校验和锁定 | Engine/dependencies.lock | 19 |