下载与管理本地模型
本地模型在你的电脑上完成推理，无需将本次推理输入发送给云端模型服务。挑选模型时，请优先根据实际要完成的任务以及当前电脑的硬件与磁盘空间做决定，不必盲目追求大参数量或榜单热度。若还不熟悉参数规模与量化格式的区别，可先阅读看懂本地模型的参数量与格式。
1. 认识“已安装”模型列表
打开左侧导航栏的本地模型。在已安装列表中，你可以查看每个模型的当前状态、复制模型名称（如 local/...），并进入调用测试；只有通过实际测试并满足准入条件的模型，才能开启代理供外部工具调用。
上图为原生 App 的本地模型列表。图中显示的 Apple 模型是由 macOS 系统自带并管理的系统模型，当前状态为“需要重新测试”。由于它不占用 OmniProxy 的模型权重目录，界面显示的 0 KB 仅代表不额外占用应用存储，不代表普通本地模型只有这么大。该条目仅在受支持的 Mac 设备上出现，OmniProxy 无法下载、移动或删除它。
2. 从模型目录下载模型
- 点击“已安装”列表下方的加号（+），打开模型目录。
- 按任务类型（如对话、翻译、图像或语音）筛选候选模型，仔细阅读页面的设备适用性提示与当前可执行状态。
- 核对具体的模型工件（Artifact）、文件大小与许可证要求——同一模型家族的不同量化版本属于不同文件，请按需选择。
- 下载前确认“默认下载位置”剩余空间充足；若保存在外置移动硬盘或 NAS，请确认设备已连接且已授予目录访问权限。
- 在下载确认框中核对实际文件清单，点击开始下载。
- 等待文件下载与完整性校验全部结束后，返回已安装列表执行调用测试。
注意：在模型目录里能看到某个名字，不代表你当前的电脑硬件一定能跑得动它；OmniProxy 支持某一种文件格式（如 GGUF），也不代表市面上所有该格式的模型文件都能直接加载。
模型目录暂时不可用时怎么办？
上图为原生 App 的真实故障状态截图。当远程模型目录加载失败时，界面尚未拉取到可选列表，此时请勿反复盲点下载。请先检查网络连接后点击重试；若网络暂时无法恢复，可点击取消，这不会删除或影响你本机已安装且可用的模型。
3. 测试模型并加入代理
模型文件就绪后，必须先通过真实调用测试，才能加入网关代理：
- 在已安装列表中，点击目标模型行的调用测试图标。
- 选择该模型支持的能力与调用方案，填入最小测试输入（例如文本对话先发一句简短提问）。
- 点击运行，检查实际返回的文本、图片或音频结果——任何报错、空响应或格式异常都不算测试通过。
- 如果你打开的是接口调试窗口：保存 Header 或 JSON 仅用于方便下次调试，手工标记测试结果也不能替代真实的模型加载与能力验证；看到 HTTP 状态正常后，仍需核对返回正文。
- 加入代理：点击加入代理时，系统会强制检查当前安装的静态校验、实际加载与能力验证结果（未通过会退回验证步骤，不会因为保存过调试 JSON 就允许强行加入）。其中，Apple 系统模型的准入按钮直接位于模型行；自定义接口调试的加入代理按钮位于调试窗口内。
- 确认启用：加入成功后，模型行会显示启用/停用代理的开关，请确认其处于启用状态。外部工具若直接填写该模型的复制名称（
local/...），无需先配置映射即可调用；若希望固定使用chat名称，请前往用固定名称映射模型。最后从外部工具发一条请求，在监控台确认实际执行模型。
| 模型行显示的状态 | 接下来该做什么 |
|---|---|
| 下载中 / 文件未校验 | 等待下载校验完成，或按任务行提供的恢复/重试操作处理。 |
| 已安装 | 点击进入调用测试（不能仅凭磁盘上有文件就认定模型可用）。 |
| 需要重新测试 | 模型或调用方案已更新，请重新运行一次当前调用方案的测试。 |
| 已测试（未加入代理） | 点击模型行或调试窗口中的准入按钮将其加入代理，再检查网关模型列表。 |
| 设备不支持 | 当前硬件或系统不满足运行条件，请更换其他受支持的模型工件，不要强行加载。 |
4. 管理多个模型存储位置
前往左侧设置 → 模型存储，可以管理两类不同的模型目录（详细说明见系统设置、模型存储与日志）：
- 迁移 OmniProxy 管理的存储（默认下载位置）：本地模型列表里没有单独的“移动某个模型”按钮。如需把受管模型库及后续新下载统一搬到移动硬盘或 NAS，请先连接外置存储，在设置中点击“默认下载位置”旁的更改位置，选择并授权新目录。阅读容量与迁移影响后确认开始迁移，务必等待验证和切换全部完成后再开始新下载，切勿刚选完目录就直接拔盘，也不要在访达（Finder）里手动剪切搬移文件。
- 原地挂载其他工具的模型（更多模型文件夹）：如果你想直接复用电脑上其他软件已下载的模型文件，展开更多模型文件夹并添加对应目录。OmniProxy 会在原路径识别文件，不会把它们复制一份。添加后请回到本地模型页面查看识别结果与可用状态，同样必须完成调用测试后才能用于代理（挂载目录不会替你安装其他软件专有的运行引擎）。
存储目录异常处理：
- 授权失效：前往设置 → 模型存储重新选择原目录并授予访问权限。
- 目录在线但未识别出模型：核对文件是否完整、具体工件格式是否受当前引擎支持，不要通过反复重复添加同一个目录来尝试触发识别。
- 默认下载位置离线：先恢复外置磁盘连接，或按正式迁移流程切换到新目录；网关不会在你未确认的情况下擅自换盘写入。
- 区分操作边界：“移除目录登记”、“迁移受管存储”与“删除模型文件”是完全不同的操作，执行前请仔细阅读弹窗确认范围。
5. 删除、更新与 Apple 系统模型说明
- 安全删除：删除下载任务或模型文件前，请先停止正在进行的推理任务，并前往模型映射解除相关绑定。对于通过“更多模型文件夹”挂载的外部目录，请勿将其中的其他软件原文件当作 OmniProxy 缓存随意清理。
- 更新后重测：当模型文件或底层调用方案更新后，此前的测试记录会失效，请按提示重新执行调用测试。
- 关于 Apple 系统模型：它由 macOS 系统托管，不支持在 OmniProxy 内下载、迁移或删除；其可用性取决于当前 Mac 硬件、macOS 版本、系统设置与语言支持。当某项任务或语言不受 Apple 系统模型支持时，系统会明确报错，不会因为你选了它就偷偷在后台替换成云端付费模型。此外，它也会作为候选引擎出现在对话模型代译列表中。
6. 本地模型成功调用示例
在受支持的 Mac 上，当 Apple 系统模型准备就绪后，打开该行的调用测试，输入以下英文指令并运行：
Reply with a short English greeting.如下图所示，模型实际返回 Hello!，状态为 HTTP 200，同时界面展示了首 Token 延迟与生成速率。确认输出无误后点击加入代理，成功后按钮会变为关闭代理（本示例直接调用系统托管模型，不涉及下载第三方权重文件）。
上图为原生 App 中 Apple 系统模型调用测试成功的真实界面截图。