进阶 docs.antigma.ai 2026-10-08 09:54:38 · 6 阅读
第20章 离线模式
Offline Mode
Ante 通过本地托管的 llama.cpp 引擎运行本地 GGUF 模型。无需 API 密钥，无需账户：只需将 Ante 指向模型文件，完整的智能体循环即可在本地硬件上运行。一旦模型存储在磁盘上，推理过程完全不需要网络连接。
若要实现完全离线的运行环境，请同时设置 `ANTE_TELEMETRY=off`。此操作会独立于本地推理，单独禁用应用指标和日志导出功能；详情请参阅遥测配置。
info：离线模式正处于积极开发阶段，体验可能不够完美，且迭代速度较快。
工作原理
选择离线模式后，Ante 将执行以下操作：
* 检查 llama.cpp 并提示安装或升级：这是经过校验和验证、与硬件匹配的内网官方构建版本。macOS 使用 Metal；Linux 会选择最强的兼容 CPU/Vulkan 功能层级，优先匹配 NVIDIA 计算能力并加载对应的 CUDA 构建，若固定版本没有兼容的 CUDA 构件，则回退至 Vulkan。
* 发现系统中的 GGUF 模型。
* 检测本地端口上已运行的 llama 服务器。
* 根据模型大小和上下文窗口估算内存需求。
* 通过 `llama serve` 启动并监管一个共享的 llama.cpp 路由器；切换托管模型时，将加载或卸载工作线程而无需重启该进程。
如果你倾向于使用自己构建的 llama.cpp、额外的服务器标志或自行启动的服务器，请参阅自定义引擎。
设置
启动 Ante 并进入离线模式——正常启动 Ante，并在 TUI 中使用离线模式选择器：
`ante
# 在 TUI 中
/offline-mode
` 安装 llama.cpp——如果未安装，Ante 会提示自动安装到 `~/.ante/llama.cpp`。当新版本的 Ante 中固定版本发生变更时，Ante 会提示升级。若要在不通过 TUI 的情况下执行相同操作，请运行 `ante offline install`：它将安装固定版本的构建，替换不匹配的构建，如果在当前已最新则不执行任何操作。 选择模型——从以下选项中选择： * 已验证模型——从 Hugging Face 下载的精选模型。 * 本地模型——系统中已有的 GGUF 文件（自动发现）。 * 运行中的服务器——连接本地端口或可达端点上已运行的 llama 服务器。 或者直接传递模型路径——跳过 TUI，一步加载 GGUF 文件： `ante --offline-model /path/to/model.gguf "你的提示词在此"
` Ante 会启动 llama.cpp 路由、加载模型、等待就绪后再运行会话。适用于脚本或 CI 场景。 模型加载后会以 local 提供商的身份注册到目录中，因此你也可以用 /providers 切换到它，或用 --provider local 指定。该条目只在服务器注册期间存在：服务器停止后，local 就会从目录中移除。如果启动时选中的是已保存的 local 但没有服务器在运行，会话会收到一条提示（运行 /offline-mode 即可启动或接入一个服务器）；无界面运行则会快速失败并给出同样的提示。参见混合使用本地与前沿模型。 脚本化与服务器用法 无界面（单次会话） 传入 --offline-model 即可针对本地 GGUF 文件运行一次性提示，无需 TUI： ante --offline-model ~/.ante/models/Qwen3.5-9B-Q4_K_M.gguf "Explain this code" Ante 会启动 llama serve 路由、加载模型、等待就绪、运行会话，然后自动关闭路由。 无界面运行不会提示安装引擎。在尚未安装引擎的机器上，运行会快速失败，并提示你先执行 ante offline install——适合固化到脚本和 CI 镜像中。 Serve 模式（WebSocket 服务器） 运行 ante serve 时，可以只加载一次模型，供所有连接的客户端共享： ante serve --ws 127.0.0.1:9000 --offline-model ~/.ante/models/Qwen3.5-9B-Q4_K_M.gguf llama serve 路由器会在 Ante 接受连接前启动并加载模型，所有 WebSocket 客户端均使用同一个运行中的进程。按下 Ctrl+C 或发送 SIGTERM 信号时，路由器会正常关闭。 加载进度 在模型下载或加载到内存期间，Ante 会在 TUI 中显示带有状态信息的实时进度条： 下载阶段——进度条根据已接收字节数与文件总大小的比值显示进度 元数据——正在从 GGUF 文件中读取模型元数据 张量加载——权重正在被加载到 RAM/VRAM 中 GPU 卸载——正在将层传输到 GPU（如可用） 在 headless 模式下，相同的进度会通过日志输出报告。 模型发现 Ante 会自动扫描以下目录中的 GGUF 模型文件： 目录说明~/.ante/models默认模型目录（可配置）~/.cache/llama.cppllama.cpp 缓存~/.cache/huggingface/hubHugging Face 缓存~/.llama/models常见的 llama 模型目录 模型偏好设置 针对每个模型的具体设置，会自动保存在离线配置文件中： 设置说明context_window上下文窗口大小（最小 32K tokens）thinking启用/禁用思维链（chain-of-thought）temperature采样温度（未设置则使用模型默认值）extra_args额外的 llama.cpp 模型选项，将被转换为共享路由器的每模型预设——详见 Custom Engines 视觉模型 如果多模态投影器文件（mmproj-*.gguf）位于模型文件旁边，Ante 会在启动时自动加载该文件，使模型能够处理聊天中的图像。 内存考量 Ante 根据模型文件大小、KV cache（随上下文窗口扩大而增加）以及分片数量来估算内存使用量。 提示对于大型模型，建议减小上下文窗口以降低内存占用。最小值为 32K tokens。 服务器管理 快捷操作Ctrl+E停止当前连接的服务器Ctrl+G切换推理日志面板Ctrl+K / Ctrl+J日志面板打开时，向上/向下滚动日志 当服务器运行时退出 Ante，系统会提示： s — 停止服务器并退出 k — 保持服务器运行并退出（打印 PID） Esc — 取消并留在 Ante 配置参考 所有离线模式的配置都存储在 ~/.ante/offline-config.json 中： {
"version": "1.0.0",
"model_directory": "~/.ante/models",
"port": 8080,
"last_model": "model-name",
"model_preferences": {
"model-id": {
"model_id": "model-id",
"context_window": 32768,
"thinking_enabled": true,
"temperature": 0.7,
"extra_args": "--threads 12"
（代码块内容，跳过） 字段 / 说明 / 默认值 model_directory / 本地 GGUF 模型的查找路径 / ~/.ante/models port / 托管的 llama.cpp 路由器或附加服务器的启动端口 / 8080 last_model / 最近使用的模型（自动保存） / — model_preferences / 每个模型的具体设置（见上文） / — llama_cpp / 引擎安装详情、二进制文件路径及服务器默认配置，详见“自定义引擎” / 由 Ante 管理 每个模型的偏好设置在资源发现阶段读取。修改 offline-config.json 后，请关闭并重新打开 /offline-mode 以加载新值。 环境变量 变量 / 说明 ANTE_OFFLINE_CONTEXT / 覆盖默认的上下文窗口上限（以 token 为单位）。在需要超过 32K 默认上下文且硬件内存充足时很有用。示例：ANTE_OFFLINE_CONTEXT=65536 ante --offline-model ...
# 在 TUI 中
/offline-mode
` 安装 llama.cpp——如果未安装，Ante 会提示自动安装到 `~/.ante/llama.cpp`。当新版本的 Ante 中固定版本发生变更时，Ante 会提示升级。若要在不通过 TUI 的情况下执行相同操作，请运行 `ante offline install`：它将安装固定版本的构建，替换不匹配的构建，如果在当前已最新则不执行任何操作。 选择模型——从以下选项中选择： * 已验证模型——从 Hugging Face 下载的精选模型。 * 本地模型——系统中已有的 GGUF 文件（自动发现）。 * 运行中的服务器——连接本地端口或可达端点上已运行的 llama 服务器。 或者直接传递模型路径——跳过 TUI，一步加载 GGUF 文件： `ante --offline-model /path/to/model.gguf "你的提示词在此"
` Ante 会启动 llama.cpp 路由、加载模型、等待就绪后再运行会话。适用于脚本或 CI 场景。 模型加载后会以 local 提供商的身份注册到目录中，因此你也可以用 /providers 切换到它，或用 --provider local 指定。该条目只在服务器注册期间存在：服务器停止后，local 就会从目录中移除。如果启动时选中的是已保存的 local 但没有服务器在运行，会话会收到一条提示（运行 /offline-mode 即可启动或接入一个服务器）；无界面运行则会快速失败并给出同样的提示。参见混合使用本地与前沿模型。 脚本化与服务器用法 无界面（单次会话） 传入 --offline-model 即可针对本地 GGUF 文件运行一次性提示，无需 TUI： ante --offline-model ~/.ante/models/Qwen3.5-9B-Q4_K_M.gguf "Explain this code" Ante 会启动 llama serve 路由、加载模型、等待就绪、运行会话，然后自动关闭路由。 无界面运行不会提示安装引擎。在尚未安装引擎的机器上，运行会快速失败，并提示你先执行 ante offline install——适合固化到脚本和 CI 镜像中。 Serve 模式（WebSocket 服务器） 运行 ante serve 时，可以只加载一次模型，供所有连接的客户端共享： ante serve --ws 127.0.0.1:9000 --offline-model ~/.ante/models/Qwen3.5-9B-Q4_K_M.gguf llama serve 路由器会在 Ante 接受连接前启动并加载模型，所有 WebSocket 客户端均使用同一个运行中的进程。按下 Ctrl+C 或发送 SIGTERM 信号时，路由器会正常关闭。 加载进度 在模型下载或加载到内存期间，Ante 会在 TUI 中显示带有状态信息的实时进度条： 下载阶段——进度条根据已接收字节数与文件总大小的比值显示进度 元数据——正在从 GGUF 文件中读取模型元数据 张量加载——权重正在被加载到 RAM/VRAM 中 GPU 卸载——正在将层传输到 GPU（如可用） 在 headless 模式下，相同的进度会通过日志输出报告。 模型发现 Ante 会自动扫描以下目录中的 GGUF 模型文件： 目录说明~/.ante/models默认模型目录（可配置）~/.cache/llama.cppllama.cpp 缓存~/.cache/huggingface/hubHugging Face 缓存~/.llama/models常见的 llama 模型目录 模型偏好设置 针对每个模型的具体设置，会自动保存在离线配置文件中： 设置说明context_window上下文窗口大小（最小 32K tokens）thinking启用/禁用思维链（chain-of-thought）temperature采样温度（未设置则使用模型默认值）extra_args额外的 llama.cpp 模型选项，将被转换为共享路由器的每模型预设——详见 Custom Engines 视觉模型 如果多模态投影器文件（mmproj-*.gguf）位于模型文件旁边，Ante 会在启动时自动加载该文件，使模型能够处理聊天中的图像。 内存考量 Ante 根据模型文件大小、KV cache（随上下文窗口扩大而增加）以及分片数量来估算内存使用量。 提示对于大型模型，建议减小上下文窗口以降低内存占用。最小值为 32K tokens。 服务器管理 快捷操作Ctrl+E停止当前连接的服务器Ctrl+G切换推理日志面板Ctrl+K / Ctrl+J日志面板打开时，向上/向下滚动日志 当服务器运行时退出 Ante，系统会提示： s — 停止服务器并退出 k — 保持服务器运行并退出（打印 PID） Esc — 取消并留在 Ante 配置参考 所有离线模式的配置都存储在 ~/.ante/offline-config.json 中： {
"version": "1.0.0",
"model_directory": "~/.ante/models",
"port": 8080,
"last_model": "model-name",
"model_preferences": {
"model-id": {
"model_id": "model-id",
"context_window": 32768,
"thinking_enabled": true,
"temperature": 0.7,
"extra_args": "--threads 12"
（代码块内容，跳过） 字段 / 说明 / 默认值 model_directory / 本地 GGUF 模型的查找路径 / ~/.ante/models port / 托管的 llama.cpp 路由器或附加服务器的启动端口 / 8080 last_model / 最近使用的模型（自动保存） / — model_preferences / 每个模型的具体设置（见上文） / — llama_cpp / 引擎安装详情、二进制文件路径及服务器默认配置，详见“自定义引擎” / 由 Ante 管理 每个模型的偏好设置在资源发现阶段读取。修改 offline-config.json 后，请关闭并重新打开 /offline-mode 以加载新值。 环境变量 变量 / 说明 ANTE_OFFLINE_CONTEXT / 覆盖默认的上下文窗口上限（以 token 为单位）。在需要超过 32K 默认上下文且硬件内存充足时很有用。示例：ANTE_OFFLINE_CONTEXT=65536 ante --offline-model ...
