本地模型部署避坑：HF_HOME 缓存指向 + macOS fd 上限 256

本地部署大模型，真正的坑常不在模型本身，而在两处系统默认值：① 模型权重缓存目录指向错了------HF_HOME 指向外接盘一份 163 MB 下载中断的半成品，本机 2.9 GB 完整包不看，model.bin 于是 Unable to open file；② macOS 默认每进程文件描述符软上限只有 256 ，本地 AI 栈跑着跑着 Too many open files，服务连不上。两个坑我都实打实翻过车。

1. 坑一：模型权重缓存指向错了（HF_HOME / 外接盘）

路线 B（CPU 上的 faster-whisper-large-v3）第一次执行直接崩：RuntimeError: Unable to open file 'model.bin'。第一反应别急着"重新下载"，先问程序到底在哪个目录找文件。

两份缓存，程序只看其中一份：

缓存位置	大小	状态
本机默认 `~/.cache/huggingface/hub`	2.9 GB	完整，`model.bin` 在
`HF_HOME` 指向的外接盘缓存	163 MB	残骸，只剩 `*.incomplete`

根因：环境变量 HF_HOME 被设成外接盘那份下载中断的半成品。修法是指向完整那份，不必重下：

bash 复制代码

HF_HOME="$HOME/.cache/huggingface" HF_HUB_OFFLINE=1 \
  python transcribe.py 录音.wav --lang zh

验证：把 HF_HOME 改回外接盘，同样报错稳定复现 ⇒ 根因就是 cache 指向，不是模型坏了。

2. 坑二：文件描述符上限太低（macOS 默认 256）

本地 AI 栈（Ollama + Open WebUI + ChromaDB）跑着跑着，WebUI 回答里冒出 Ollama: Cannot connect to host localhost:11434 ssl:default [Too many open files]；首页 / 返回 500，但 /health 仍 200；ChromaDB 做 embedding 也可能报 Too many open files。

30 秒诊断：launchctl limit maxfiles 输出 maxfiles 256 unlimited------软限制 256 就是元凶。根因是 macOS 默认每进程软 fd 上限只有 256，AI 栈加载海量 C 扩展 + SQLite WAL + 权重 + 向量库，运行中轻松破 256。这不是内存泄漏，是上限太低。

修复三板斧（缺一都复发）：① plist 加 SoftResourceLimits → NumberOfFiles 65536 ；② 启动脚本加 ulimit -n 65536；③ launchctl kickstart -k 重启进程。监控加固：看门狗每轮记 fd，超 80%（52428 ）自动 kickstart，并同时探 / 和 /health。

bash 复制代码

# plist 片段（~/Library/LaunchAgents/ 下对应服务）
<key>SoftResourceLimits</key>
<dict><key>NumberOfFiles</key><integer>65536</integer></dict>
# 启动脚本顶部
ulimit -n 65536 2>/dev/null || true
# 重启（不要 load/bootstrap）
launchctl kickstart -k "gui/$(id -u)/com.yourname.ollama"

实测环境：macOS 26 Tahoe（Apple Silicon）。常见误诊：以为是网络 / 端口 / 模型损坏（重装重下无用）、只重启不加 limit（复发）、只改 launchctl limit maxfiles（当前 shell 生效，launchd 子进程不继承，白改）。

3. 复现清单

文件	行数	作用
`macos-local-ai-fd-exhaustion-fix SKILL.md`	109	fd 修复三板斧全集（plist `SoftResourceLimits` / `ulimit` / `launchctl kickstart` / 看门狗 52428）
缓存指向坑	---	来源 A6 本地语音转写实测：`HF_HOME` 指向外接盘 163MB 半成品 vs 本机 2.9GB 完整
涉及组件	---	Ollama / Open WebUI / ChromaDB；报错落点 `localhost:11434` 与 `Too many open files`