架构决策记录
ADR 0044: Mac 节点的引擎以宿主机进程运行,镜像是 darwin 环境包
本文目录
日期:2026-10-14 · 状态:已接受
依据:Apple Silicon 推理调研、Mac 节点计划(含真机 spike 记录)。
背景
Apple silicon Mac 的 GPU 只有 macOS 宿主机上的进程能经 Metal 使用。macOS 上所有 Linux 容器(Docker Desktop、OrbStack、apple/container)都跑在虚拟机里,虚拟机里没有 Metal;唯一能用 GPU 的路径(Podman + krunkit,Vulkan 转 MoltenVK)在 M2 Max 上把 llama.cpp 的解码速度减半。agent 现有的三个运行时(docker、nerdctl、runveil)都以 Linux 镜像为单位:runveil 的执行核心是 Linux ptrace 上的 PRoot,镜像里是 Linux ELF。
决策
- 新运行时
host(internal/agent/runtime/hostproc):引擎是 agent 用户的普通进程组,在 macOS 上优先于 Docker Desktop 被选中(--driver host可强制)。进程托管(pid、退出码、组停止、日志)与 runveil 共用runtime/procgroup。 - 镜像是环境包:darwin/arm64 的 OCI 镜像,内容是一个可搬迁的根(python-build-standalone、装进其 site-packages 的引擎、
/bin下的入口),由build/host-envs在 Linux 上交叉构建,按gpuworks-runner:metal<最低 macOS>-<引擎><版本>-rN发布(CLAUDE.md「内置镜像命名」)。拉取、离线导入、镜像源与目录沿用现有机制(runveil 的原生拉取,按 OS/架构选 manifest)。 - 按容器语义翻译路径:每个 manifest 解包一次,供它的所有实例共享;解包时把包内的绝对符号链接与 venv 的
pyvenv.cfg重定根;启动时把 argv、环境变量、PATH、工作目录里的挂载目标(/model)换成宿主机源路径,包内路径换成解包位置。服务端照旧下发容器形状的启动参数,不知道节点是否有容器。 - 实例隔离:每个实例独立的
HOME、短路径TMPDIR(/tmp/gpuworks-host-<uid>/…,Unix socket 路径不超过 macOS 的 104 字节)、按环境包共享的缓存;不继承 agent 的PATH、DYLD_*与 Python 变量;运行期间持有caffeinate -i防空闲睡眠。引擎只绑 127.0.0.1,网关经 hub 隧道访问。 - 厂商
apple、框架metal:GPU 报 1 张统一内存卡,显存为 Metal 允许 GPU 常驻的工作集(iogpu.wired_limit_mb,未设时内存 ≤32 GiB 取 2/3,以上取 3/4);平台不修改该值。driver 版本即 macOS 版本,镜像兼容性按最低 macOS 判断。 - 平台功能按厂商声明(
accelerator.Supports):Apple 节点不提供引擎休眠(vllm-metal 的/sleep返回 200 但不释放内存)、多机与 KV 磁盘层,调度器按需要的功能过滤节点。 - 按内存共享卡(
accelerator.SharedByMemory):一台 Mac 同时跑多个实例;每个实例按准入时的份额记账(vLLM/SGLang 取gpu_memory_utilization × 工作集与启动需求中较大者,callable 取启动需求),份额记在实例期望状态的memory_claim_bytes里。
取舍
- 宿主机进程 vs 容器:放弃容器的隔离(文件系统、网络、cgroup),换来不损失 GPU 性能;隔离靠实例目录、环境变量清理与只绑回环。个人电脑上用户自己的进程与引擎共享内存,平台无法替用户约束。
- 自建环境包 vs 依赖用户安装(brew、官方脚本):多一条构建线、每个包数百 MB,换来版本钉死、M1–M5 同一个包、国内镜像源可用、运行时不联网。
- 路径翻译 vs 让服务端为 Mac 生成宿主机路径:翻译集中在 agent 的一个包里,服务端、模板与预览不分叉;代价是翻译只覆盖整 token、
--flag=value、KEY=value、冒号路径表和脚本里以单词出现的挂载目标。 - 份额持久化:新增
memory_claim_bytes一个事实,而不是每次快照按估算重算——重算既随模板与估算漂移,也违反逐实例全量计算的规模约束。
后果
- vLLM 沿用
vllm引擎与参数字典(vllm-metal 接受vllm serve的命令行),macOS 上 gloo 的回环网卡由 quirk 改为lo0。不支持的能力在 Mac 节点上由调度器给出带厂商名的拒绝原因。 - mlx-vlm、mlx-audio 等按请求选模型的服务走 callable 模板,包内适配层(
gpuworks_adapters)把实例钉在--model上,因为网关会把请求的model改成部署服务名。 - 新的 darwin 平台差异(安装用 launchd、
sysinfo走 sysctl、终端的 pty 与进程回收走 darwin ioctl 和kern.proc)都在 agent 侧;实例终端进入的是实例的环境(环境包的 PATH、实例的 HOME 与工作目录),不是容器;server 的 darwin 构建与 agent 同机即"单机一体",安装流程与 Linux 节点一致。
这篇文档有帮助吗?