离线与本地推理模式

Ante 通过原生管理的 llama.cpp 引擎运行本地 GGUF 模型。无需 API 密钥，无需注册账号：指定模型文件，完整的智能体闭环即可在自有硬件上流畅运转。模型加载到本地磁盘后，推理过程完全无需任何网络连接。

若需完全断开网络环境运行，请同时设置 ANTE_TELEMETRY=off。这会独立于本地推理禁用应用程序指标与日志上报；参见遥测机制。

信息

离线模式目前处于活跃开发中。

工作原理

当您选择离线模式时，Ante 会自动：

检查 llama.cpp 运行时，并提供安装或升级服务：拉取与当前硬件架构（Apple Silicon Metal；Linux CUDA、Vulkan 或 CPU）严格匹配且经过校验和验证的官方固定版本
扫描并发现系统中的 GGUF 模型文件
检测本地端口上已在运行的 llama 服务端
根据模型文件大小与上下文窗口自动预估内存/显存需求
为您启动并全程监管推理服务端

若希望使用自定义的 llama.cpp 构建版本、指定专属启动参数或接入已启动的服务，请参见自定义引擎。

环境准备

启动 Ante 并打开离线模式 — 正常启动 Ante 并在 TUI 中使用离线模式选择器：
```
ante

# 在 TUI 中执行
/offline-mode
```
安装 llama.cpp — 若尚未安装，Ante 会提示自动安装至 ~/.ante/llama.cpp。当 Ante 新版本更新了固定引擎版本时，也会提示一键升级。在非交互环境下可直接运行 ante offline install：它会安装固定版本，替换不匹配的版本，并在已是最新时直接退出。
选择模型 — 支持三种来源：
- 推荐验证模型 — 从 Hugging Face 直接下载官方验证推荐的模型
- 本地模型 — 自动发现系统磁盘中已有的 GGUF 文件
- 运行中的服务 — 直接接入已在本地端口或可达端点上运行的 llama 服务
或直接传入模型路径 — 跳过 TUI 一步到位加载 GGUF 文件：
```
ante --offline-model /path/to/model.gguf "your prompt here"
```
Ante 会拉起 llama-server，等待就绪，随后运行会话。适用于脚本自动化或 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-server，等待就绪，执行会话，并在结束后自动关闭服务端。

无头模式绝不会提示安装引擎。在尚未安装引擎的机器上，运行会快速失败并提示先执行 ante offline install —— 便于预置到脚本和 CI 镜像中。

服务模式（WebSocket 服务器）

在运行 ante serve 时，可以加载一次模型并供所有接入客户端共享：

ante serve --ws 127.0.0.1:9000 --offline-model ~/.ante/models/Qwen3.5-9B-Q4_K_M.gguf

llama-server 会在接受连接前启动，每个 WebSocket 客户端均复用同一个运行中的服务端。服务端会在收到 Ctrl+C 或 SIGTERM 时优雅关闭。

加载进度展示

在下载模型或将其加载到内存中时，Ante 会在 TUI 中实时展示进度条并显示状态信息：

下载阶段 — 进度追踪已接收字节数与总文件大小
元数据 — 正在从 GGUF 文件中读取模型元数据
张量加载 — 正在将权重加载至 RAM/VRAM
GPU 卸载 — 正在将网络层传输至 GPU（若可用）

无头模式下相同的进度会通过日志输出呈现。

模型自动扫描发现

Ante 会自动扫描以下目录中的 GGUF 模型文件：

目录	说明
`~/.ante/models`	默认模型存储目录（可配置）
`~/.cache/llama.cpp`	llama.cpp 缓存目录
`~/.cache/huggingface/hub`	Hugging Face 缓存目录
`~/.llama/models`	常见的 llama 模型目录

模型专属偏好设置

按模型配置的参数，会自动保存在离线配置文件中：

设置项	说明
`context_window`	上下文窗口大小（最小 32K Token）
`thinking`	启用/禁用思维链推理
`temperature`	采样温度（未设置时使用模型默认值）
`extra_args`	额外的 llama-server 启动参数，追加到启动命令后 —— 参见自定义引擎

视觉多模态模型

若模型文件同级目录下存在多模态投影文件（mmproj-*.gguf），Ante 会在启动时自动挂载，模型将在对话中支持接收图片。

内存显存考量

Ante 根据模型文件大小、KV 缓存（随上下文窗口伸缩）及分片数量综合估算内存占用。

提示

对于大模型，可调小上下文窗口以降低内存占用。最低为 32K Token。

本地服务管理

快捷键	功能
`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 服务的起始端口号	`8080`
`last_model`	上次使用的模型（自动保存）	—
`model_preferences`	各模型的专属偏好设置（见上文）	—
`llama_cpp`	引擎安装详情、二进制路径及服务端默认配置 —— 参见自定义引擎	由 Ante 管理

环境变量

环境变量	说明
`ANTE_OFFLINE_CONTEXT`	覆盖默认上下文窗口上限（Token 数）。当需要大于 32K 默认值的上下文且硬件具备足够 RAM 时非常有用。示例：`ANTE_OFFLINE_CONTEXT=65536 ante --offline-model ...`

工作原理​

环境准备​

脚本自动化与服务端使用​

无头模式（单会话）​

服务模式（WebSocket 服务器）​

加载进度展示​

模型自动扫描发现​

模型专属偏好设置​

视觉多模态模型​

内存显存考量​

本地服务管理​

配置参考​

环境变量​