解决 omlx 模型下载缓慢：配置 HuggingFace 镜像全指南
国内使用 omlx 下载大模型遇到 416 Range Not Satisfiable 错误？本文提供 3 种配置 HuggingFace 镜像端点的方法，彻底解决网络报错与连接中断问题。
在使用 omlx 运行大模型时，许多国内用户常会遇到 416 Range Not Satisfiable 错误或下载进度长时间停滞。这通常是因为默认的 HuggingFace 服务器在海外，跨境网络波动导致连接中断。
自 v0.2.7 版本起，作者已正式增加了对镜像站点的支持。以下是三种针对不同场景的优化方法：
方法一：通过管理界面设置（推荐，最简单）
如果您喜欢可视化操作，可以直接在浏览器中配置：
- 打开 omlx 管理面板。
- 进入 "模型" (Models) > "下载器" (Downloader) 选项卡。
- 点击标题旁边的 ⚙️ 齿轮图标。
- 在输入框中填入镜像地址：
https://hf-mirror.com。 - 点击保存即可。
方法二：使用环境变量（开发者常用）
如果您是在终端启动服务，或者希望全局生效，可以设置环境变量。
- Linux / macOS:
export OMLX_HF_ENDPOINT=https://hf-mirror.com - Windows (PowerShell):
$env:OMLX_HF_ENDPOINT="https://hf-mirror.com"
方法三：启动时指定 CLI 标志
您也可以在每次启动 omlx 服务时，通过命令行参数直接指定镜像端点：
omlx serve --hf-endpoint https://hf-mirror.com
为什么会出现 416 错误？
根据 Issue #141 中的讨论，这种错误通常发生在断点续传失败时。由于防火墙或网络限速，请求的字节范围（Range Request）被服务器拒绝。切换到 hf-mirror.com 后，由于服务器在国内或 CDN 覆盖更广，这类连接重置问题将得到显著改善。
针对 macOS 用户的特别提示
如果您使用的是 omlx macOS 客户端，可以点击： 设置 (Settings) → 高级 (Advanced) → HuggingFace Mirror Endpoint 进行一键修改。
小贴士： 如果后续需要恢复默认下载路径，只需将设置中的 URL 字段清空并保存，系统会自动切换回官方的
huggingface.co。