「本地模型」是 a4agent 自 0.3.0 起内置的推理控制台：把 llama.cpp 的 llama-server 封装为一键启动的 OpenAI 兼容 API 服务——装哪个引擎、选哪个模型、给什么参数，全程可视化操作。它与「配置方案与一键切换」组合，即可得到 Claude Code 完全离线方案：本地模型生成 OpenAI 兼容接口，切换工具把各端流量指到本机，全程不依赖任何云上 API。本文章介绍首次配置向导、模型库、服务运行、推理参数、局域网开放与一键接入配置方案的完整使用方式。
1. 功能概述
| 维度 | 说明 |
|---|---|
| 定位 | 本地大模型推理服务管理：引擎获取、模型库、服务启停、参数调优 |
| 引擎 | llama.cpp 官方预编译 llama-server（Vulkan / CUDA 12.4 / CUDA 13.3 / CPU 四种包，钉定固定版本、二进制可复现） |
| 模型 | 任意 .gguf 格式模型，多目录扫描与元数据解析 |
| 服务形态 | OpenAI 兼容 API（/v1/chat/completions），本机或局域网开放 |
| 与切换的关系 | 「接入配置方案」一键创建指向本地服务的配置方案，四端即插即用 |
| 引入版本 | 0.3.0（原独立 a4agent 项目能力完整合并） |
引擎/硬件/模型] B --> C[模型库
扫描 gguf] C --> D[启动服务
llama-server] D --> E[OpenAI 兼容 API
127.0.0.1 或局域网] E --> F[接入配置方案] F --> G[四端切换使用
Claude Code/Codex/dsh/ZCode] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style C fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style D fill:#ffecd6,stroke:#e67e22,stroke-width:2px style E fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style F fill:#fdebd0,stroke:#b7950b,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
2. 首次配置向导
首次进入「本地模型」页签会进入五步配置向导：获取引擎 → 检测硬件 → 选择模型目录 → 选择默认模型 → 服务端口，走完即可启动服务。
2.1 硬件检测与预设推荐
向导通过 nvidia-smi 与注册表双路枚举显卡，列出厂商、显存与驱动版本；再按显存档位推荐一套开箱即用的推理预设（上下文长度、KV 缓存量化、MTP 投机解码）。预设依据混合架构推理模型的显存特征调校——此类模型仅约四分之一层携带 KV 缓存，q4_0 量化下每千 token 约 5.6KB，上下文的显存代价远小于权重本身：
| 显存档位 | 上下文长度 | KV 缓存 | 说明 |
|---|---|---|---|
| CPU 兜底（无独显或 <2GB） | 8192 | q4_0 | 走 CPU 推理速度受限，建议搭配 9B 级模型 |
| 入门档（<6GB） | 8192 | q4_0 | 瓶颈是权重本身，仅够 9B 全量 offload，35B 勿尝试 |
| 主流档（6–12GB） | 32768 | q4_0 | 9B 全量 offload + 32k 绰绰有余；35B 需换 Q3 量化并降回 16k |
| 进阶档（12–16GB） | 32768 | q4_0 | 27B / 35B 小量化可跑 32k，9B 可手动上探 64k |
| 高端档（16–24GB） | 65536 | q4_0 | 35B 小量化全量 offload + 64k 有余量 |
| 旗舰档（24GB 以上） | 131072 | q8_0 | 128k 长上下文且 KV 可升 q8_0，上限可试原生 256k |
选择模型时页面还会给出显存溢出风险预警（见第 3 节）。
2.2 引擎自动获取
按显卡型号自动下载对应的 llama.cpp 官方预编译引擎包，无需手动编译：
| 引擎包 | 适用场景 |
|---|---|
| Vulkan | 各家显卡通用（NVIDIA / AMD / Intel），免装 CUDA 运行库 |
| CUDA 12.4 / CUDA 13.3 | NVIDIA 显卡专用，性能优于 Vulkan |
| CPU | 无独显或仅核显的兜底选择 |
引擎获取的三种方式：
- 自动下载：CUDA 引擎由主包与 cudart 运行库两个包组成，下载后自动解压合并、原子换入，下载中断可取消重试；
- 离线安装：网络不便时，指定一个含
llama-server.exe的目录即可完成安装； - 接管旧版：检测到旧版安装已下载过引擎时自动接管其引擎目录，无需重复下载。
引擎版本钉定固定提交，保证二进制可复现；引擎默认存放在数据目录的 engine\ 子目录下，位置详见数据目录与日志说明。
2.3 模型目录与默认模型
选择一个或多个模型目录后，向导扫描其中的 .gguf 文件并解析元数据，选定一个作为默认模型并确认服务端口（默认 8080）后完成配置。向导配置随时可在「推理设置」中调整。
3. 模型库
「本地模型」页的模型库负责把散落各处的 .gguf 模型纳入统一管理：
- 多目录扫描：可添加多个模型目录（桌面端调用系统原生文件夹选择对话框，浏览器调试模式退化为手动输入路径），自动扫描其中全部
.gguf文件； - 元数据解析：直接读取 GGUF 文件头，展示文件大小、量化级别、原生上下文长度、是否含 MTP 层（含 MTP 层的模型支持投机解码加速）；
- 设为默认模型：一键把某个模型设为服务启动时加载的默认模型；
- 多模态投影：可选指定
mmproj投影模型（浏览文件选择），用于多模态模型； - 显存风险预警：结合当前显卡显存与所选上下文 / KV 缓存参数估算占用，超过约 88% 给出提示、超过约 97% 给出强预警，避免启动后因显存溢出崩溃。
4. 服务运行
拉起 llama-server] B --> C{健康检查
最长 4 分钟} C -->|就绪| D[运行中
OpenAI 兼容 API 可用] C -->|失败| E[失败
日志明确报错] D --> F[手动停止] D -.->|进程崩溃| G[记录崩溃日志] E --> F style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style C fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style D fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style E fill:#fadbd8,stroke:#c0392b,stroke-width:2px style F fill:#fdebd0,stroke:#b7950b,stroke-width:2px style G fill:#fadbd8,stroke:#c0392b,stroke-width:2px
- 运行状态机：页面实时显示启动中 / 运行中 / 失败 / 已停止四种状态，并滚动展示引擎日志；
- 健康检查：启动后轮询服务就绪状态，最长等待 4 分钟，就绪即通知可用；
- 明确报错：端口被占用、引擎缺失、进程崩溃等情况均在日志中给出明确原因，不静默失败；
- 内存裁剪：运行就绪后按设定延迟（默认 90 秒）执行定时内存裁剪，回收闲置内存；
- API 鉴权：可为服务一键生成
sk-随机密钥开启鉴权，局域网开放时建议开启。
5. 推理参数
全部推理参数可视化调整，改完即存、下次启动生效：
| 参数 | 默认值 | 说明 |
|---|---|---|
| 上下文长度 | 32768 | 模型可处理的最大 token 数，受显存约束 |
| KV 缓存量化 | q4_0 | f16 / q8_0 / q4_0 三档，量化越低显存占用越小、精度略降 |
| Flash Attention | 开启 | 注意力计算加速，减少显存占用 |
| GPU 层数 | 99（全部） | 模型层数卸载到 GPU 的数量，99 表示全量 offload |
| 线程数 | 0（自动） | CPU 推理线程数 |
| 批处理大小 | 512 | 单批 token 数 |
| 并行数 | 1 | 同时处理的并发请求数 |
| MTP 投机解码步数 | 0（关闭） | 模型含 MTP 层时可开启，按步数加速生成；自动探测引擎新 spec 与旧 --mtp 两种写法 |
| API Key | 空 | 非空时启用 sk- 鉴权 |
| 附加参数 | 空 | 高级逃生舱：原样追加到 llama-server 命令行，应对未覆盖的参数 |
6. 局域网开放与接入
服务默认监听 127.0.0.1，仅本机可用；在推理设置中把监听地址切换为 0.0.0.0 即可对局域网开放，接入页会同步显示实际的局域网调用地址。
「接入」卡片把调用所需的信息一次性给全：
- Base URL：如
http://192.168.1.10:8080/v1； - Chat Completions 地址：
/v1/chat/completions完整地址； - 模型名：请求体
model字段应填的值； - 可复制示例：
curl命令与 openai Python SDK 代码各一份，复制即用。
对局域网开放时建议开启 API Key 鉴权，避免局域网内其他设备无限制调用。
7. 接入配置方案
「接入配置方案」按钮把本地服务与 a4agent 的核心切换能力打通：
- 点击「接入配置方案」，自动创建一条指向本地推理服务的配置方案（服务商指向本机地址、OpenAI 兼容类型）；
- 到「配置方案」页把该方案切换到目标工具（Claude Code / Codex / dsh / ZCode）；
- 四端即用上本地模型；想换回云上 API，切回其他配置方案即可，本地与云端无缝互切。
搭配与限制同普通 OpenAI 兼容服务商一致（如 Codex / dsh 目标只能搭配 OpenAI 兼容类型），见配置方案与一键切换第 3 节。
8. 接口一览
「本地模型」页签背后是 /api/v1/llama 接口簇，主要接口如下：
| 接口 | 方法 | 用途 |
|---|---|---|
/api/v1/llama/status |
GET | 服务运行状态 |
/api/v1/llama/start / stop |
POST | 启动 / 停止推理服务 |
/api/v1/llama/logs |
GET | 增量拉取引擎日志 |
/api/v1/llama/hardware |
GET | 硬件检测（显卡厂商 / 显存 / 驱动） |
/api/v1/llama/engine/packs |
GET | 可用引擎包清单 |
/api/v1/llama/engine/download / offline / cancel |
POST | 引擎自动下载 / 离线安装 / 取消 |
/api/v1/llama/engine/progress |
GET | 引擎下载进度 |
/api/v1/llama/models / models/scan |
GET / POST | 模型列表与重新扫描 |
/api/v1/llama/models/dirs / models/dirs/remove |
POST | 添加 / 移除模型目录 |
/api/v1/llama/models/default |
POST | 设为默认模型 |
/api/v1/llama/models/risk |
POST | 显存占用风险评估 |
/api/v1/llama/wizard/finish |
POST | 完成首次配置向导 |
/api/v1/llama/settings |
GET / POST | 读取 / 保存推理设置 |
/api/v1/llama/connect |
GET | 接入信息（Base URL / 模型名 / 示例） |
/api/v1/llama/integrate |
POST | 一键创建接入配置方案 |
9. 常见问题
问：没有 NVIDIA 显卡能用吗？
答：可以。向导会推荐 Vulkan 引擎包（NVIDIA / AMD / Intel 通用）或 CPU 兜底包；CPU 推理速度受限，建议搭配小参数量模型与 8k 上下文档位。
问：启动服务时报端口被占用怎么办？
答：日志会明确提示端口冲突。换一个服务端口（推理设置中修改，默认 8080）或结束占用该端口的进程后重新启动；修改端口后接入卡片中的 Base URL 会同步更新，已创建的接入配置方案需重新生成。
问：下载引擎太慢或网络受限怎么办？
答：支持离线安装——在能联网的机器上从 llama.cpp 发行版页下载对应预编译包，解压后在本机指定含 llama-server.exe 的目录即可；引擎版本与自动下载的保持一致即可。
问：模型启动就崩溃或报显存不足？
答：看模型库的风险预警列与引擎日志。常见处理：降低上下文长度、把 KV 缓存降到 q4_0、更换更小量化级别的模型文件；显存实在不足时减少 GPU 层数改为部分 offload（CPU 承担剩余层）。
问：MTP 投机解码是什么，怎么开？
答：MTP 是模型自带的投机解码加速层——模型库扫描时会标注模型是否含 MTP 层；含 MTP 层的模型在推理设置中把 MTP 步数调为大于 0 即可开启，a4agent 会自动适配引擎的新旧参数写法。
问：本地模型的数据放在哪里？
答：推理配置（llama_config.json）与引擎目录（engine\）都在运行时数据目录内（安装版为 %APPDATA%\a4agent\），与配置方案、备份数据同目录管理，详见数据目录与日志说明。
问：本地服务和云上 API 能同时给不同工具用吗？
答：可以。为本地服务与云上服务商各建一条配置方案，切换到哪个方案，对应工具就用哪个上游；多个工具也可以通过目标多选同时指向同一条方案。
举手提问