# NInfer v0.1.4 部署清单（Windows · RTX 5070 Ti Laptop 12GB）

> 目标机器：**Windows x64 + RTX 5070 Ti Laptop 12GB + 32GB RAM**。
> 依据：该仓库 `README.md` / `docs/INSTALL.md` / `docs/OFFLINE_BUNDLE.md` / `docs/DEPLOYMENT_AGENT_GUIDE.md` / `docs/MODELS.md` / `docs/TROUBLESHOOTING.md`（v0.1.4，2026-10-21 抓取）。
> ⚠️ 当前的 Linux 服务器（GTX 1060 6GB / 15GiB RAM / Pascal）**不适用**，原因见文末「本机不适用的依据」。

---

## 0. 先选路线

| | 路线 A：夸克整合包（推荐） | 路线 B：GitHub 源码 |
|---|---|---|
| 适合 | 只想把 27B Agent 跑起来 | 要改代码、换模型、只开 API |
| 要下的东西 | 1 个网盘 ZIP（引擎 + 两个 `.ninfer` 模型 + 便携 Node + dsh + 依赖） | 源码 ZIP/git + 自备 `.ninfer` 模型 + 在线下载引擎（约 0.8 GiB） |
| 首次是否需联网 | 否（仅驱动/Edge 是系统前置） | 是 |
| 首次磁盘 | 下载 + 解压约 55 GB | 模型 10.06 GiB + 转换时同时占两份 + 依赖缓存 |

两个模型**只加载一个**，不要同时加载。

---

## 1. 前置检查（10 分钟，全部只读）

接电、开混合显卡模式、关掉其他吃独显的程序后，在 **PowerShell（不要用 cmd 双击）** 里跑：

```powershell
node --version                                   # 路线 B 需 >= 24；路线 A 用包内便携 Node
nvidia-smi --query-gpu=name,memory.total,memory.used,memory.free,driver_version --format=csv
Get-NetTCPConnection -State Listen -LocalPort 1234,1236,3080 -ErrorAction SilentlyContinue |
    Select-Object LocalAddress,LocalPort,OwningProcess
Get-PSDrive -PSProvider FileSystem | Select-Object Name,@{n='FreeGB';e={[math]::Round($_.Free/1GB,1)}}
```

逐条确认：

- [ ] GPU 是 **Laptop** 版 5070 Ti，显存 **12 GB**（桌面同名卡不是同一硬件，别照搬）
- [ ] NVIDIA 驱动支持 **CUDA 13**（维护者环境 617.14；预编译包**不需要**装完整 CUDA Toolkit）
- [ ] 内存 **32 GB**（7 GiB Host KV + 模型映射 + 索引 + dsh/浏览器 + 系统）
- [ ] 系统已装 **Microsoft Edge**（浏览器工具靠它，不会自带）
- [ ] 目标盘 **NTFS/exFAT**（不能 FAT32），至少 55 GB 空余，路径尽量短（如 `D:\AI\infer-v014`）
- [ ] 1234 / 1236 / 3080 三个端口空闲（被占先确认归属，**不要 taskkill /IM node.exe**）

---

## 2. 路线 A：夸克整合包（离线，推荐）

### A1. 下载与解压
1. 从夸克完整下载 ZIP（**别在压缩包里直接运行**）。
2. 解压到短路径，例如 `D:\AI\infer-v014`。解压后目录里应有 `00-install-vc-runtime.cmd` … `08-pool-small.cmd`、`offline-bundle.json`、`SHA256SUMS`。

### A2. 装 VC++ 运行库
双击 **`00-install-vc-runtime.cmd`**，走完包内 Microsoft 签名安装器；提示要重启就先重启。

### A3. 显存三件事（**顺序别乱**）
1. **开混合显卡模式**：厂商控制中心 / BIOS 里的 Hybrid / Optimus，让桌面和浏览器走核显，独显只留给推理。无核显机型跳过。
2. **只对引擎关掉 CUDA 系统内存回退**：
   `NVIDIA 控制面板 → 管理 3D 设置 → 程序设置 → 添加 → 浏览` 选本包 `runtime\engine\ninfer-serve.exe`
   → 找到 **`CUDA - Sysmem Fallback Policy`（CUDA - 系统内存回退策略）** → 选 **Prefer No Sysmem Fallback**
   → 应用。**只改这个程序的设置，全局设置别动。**
3. 关掉游戏、视频处理、别的模型实例等后台独显负载。

> **不要顺手关掉 `HostKVMiB = 7168`。** 那是 KVMem 主动放在 RAM 里的历史 KV，跟驱动「显存不够偷偷塞内存」完全是两回事。关驱动的回退 ≠ 关 Host KV。
> 这项设置不增加物理显存：真不够时会直接 CUDA 分配失败，那时按 A6 逐档缩。

### A4. 跑离线安装（不启动模型）
双击 **`01-setup-huihui.cmd`**（日常用 Huihui abliterated Swift-1.5 版）或 **`01-setup-gsq.cmd`**（原版 GSQ-RCO）。
它会：核对 35,053 个文件的哈希（首次读两个约 10 GiB 模型，**可能几分钟不动，不是卡死**）→ 检测引擎依赖 → 生成本包独立的 dsh 配置。**此步不加载模型。**

### A5. 启动
双击 **`02-start.cmd`**：等权重加载 + CUDA Graph 捕获完成（首次较久）→ 自动打开带登录凭据的本机 Agent 网页。
- 登录 URL **只在本机日志**（`runtime\logs\dsh.stdout.log`），别贴出去。
- 关掉用 **`03-stop.cmd`**（按 PID/启动时间/路径核对归属，只停本目录启动的进程）。会话和权重保留，但 **RAM/GPU 里的 KV 不会跨进程保留**。
- 想要完整校验随时跑 **`04-verify.cmd`**（不发模型请求）。

### A6. 显存确实不够时的收缩顺序
1. 先查真实占用（`nvidia-smi` + 任务管理器「专用 GPU 内存」），确认不是另一个模型在跑。
2. **`07-kv-rk4v4.cmd`** 切回 RK4V4 再启动（同一 exe 支持两种格式，显存更省，但输出可能变）。
3. 还不行再 **`08-pool-small.cmd`**：DeviceKV 34560 / Retrieve 1536（sink 12288 / recent 19456 不变）。
4. 恢复默认用 **`08-pool-default.cmd`**（36864 / 3840）。
所有切换都**先 `03-stop` 再切，切完再 `02-start`**。缩检索窗口会损失长文召回，自己重验。

---

## 3. 路线 B：GitHub 源码 / 只要 API

```powershell
git clone https://github.com/CSUNX233/qwen3.8-27b-ninfer-5070tilaptop-kvmem-local-agent.git
cd qwen3.8-27b-ninfer-5070tilaptop-kvmem-local-agent
powershell -NoProfile -ExecutionPolicy Bypass -File .\setup.ps1 -ModelPath "D:\Models\qwen3.8-27b-gsq-rco-iq3-xxs.ninfer"
.\start.cmd
```

- 模型必须是 **v3 `.ninfer`（`text,mtp`）**，GGUF 不能直接当参数。自己做就用 `docs/MODELS.md` 的 Python 3.11 + CPU torch 转换流程，产物约 **10,796,660,224 B（≈10.06 GiB）**；转换时 GGUF 原件和产物同时占盘。
- 只当 API：安装加 `-SkipDsh`，启动 `powershell -NoProfile -ExecutionPolicy Bypass -File .\start.ps1 -EngineOnly`。
- 安装器校验 `config/downloads.json` 的 SHA-256（引擎来自本项目 Release，cuBLAS 来自 NVIDIA，FFmpeg 是 BtbN 固定 LGPL shared 构建）。**别跳过校验、别上网找 DLL 补**。
- 升级：`03-stop` → 备份 `config/local.json` → `git pull --ff-only` → 重跑同一条 `setup.ps1`（约 0.8 GiB 新引擎）。**别把旧 `downloads.json` 覆盖到新版本**，只 `git pull` 不会换 exe。

---

## 4. 默认参数与开关（`config/local.json`）

| 项 | 默认 | 含义 |
|---|---|---|
| `EnginePort` / `GuardPort` / `WebPort` | 1234 / 1236 / 3080 | 引擎 / 严格缓存守卫 / dsh 网页 |
| `MaxContext` | 262144 | **逻辑**容量（输入+输出+开销共占） |
| `DeviceKV` | 36864 | GPU KV 页池（≠ 逻辑上下文上限） |
| `HostKVMiB` | 7168 | RAM 历史 KV 预算 |
| `SinkTokens` / `RecentTokens` / `RetrieveTokens` | 12288 / 19456 / 3840 | 头部 / 近期 / 检索窗口 |
| `KVDType` | `nvfp4` | 可改 `rk4v4`；缺字段按 NVFP4 |
| `ReasoningEffort` | `xhigh` | 建议保持 |
| `AnswerPenaltyScope` | `answer` | `carry-over` 可关独立回答计数 |
| `ToolGroundedExecution` | `true` | 分步执行规则开关 |

一键脚本对照：`05-use-huihui` / `05-use-gsq` 换模型（**换完新开会话**）、`06-answer-counts` / `06-carry-over-counts`、`07-kv-nvfp4` / `07-kv-rk4v4`、`08-pool-default` / `08-pool-small`。

**先按 `36864 / 3840` 建立基线再逐档加。** 维护者的 `39168 / 6144` 是单机进阶档（NVFP4 启动 CUDA 余量约 64 MiB），不是安装默认值，也不保证你的卡能起。

---

## 5. 分层验收（调用链：dsh 3080 → 守卫 1236 → 引擎 1234 → GPU/Host KV）

```powershell
$c = Get-Content .\config\local.json -Raw | ConvertFrom-Json
$e = 'http://127.0.0.1:' + $c.EnginePort
Invoke-RestMethod ($e + '/health'); Invoke-RestMethod ($e + '/v1/models'); Invoke-RestMethod ($e + '/v1/load')
python .\benchmarks\run.py --mode smoke --url $e --model $c.ModelId --label deploy-engine
python .\benchmarks\run.py --mode smoke --url ('http://127.0.0.1:' + $c.GuardPort) --model $c.ModelId --label deploy-guard
```

逐层打勾，哪层红就定位哪层：

- [ ] **L1 引擎**：`/health` 200、`/v1/models` 有 `ModelId`、`/v1/load` 正常
- [ ] **L2 引擎推理**：engine smoke 通过（数学 / 工具调用 / 工具结果）
- [ ] **L3 守卫**：guard smoke 通过（仅引擎模式跳过）
- [ ] **L4 网页 Agent**：选 `ninfer-local` + xhigh，在临时目录完成「读文件 → 写最小实现 → 跑测试 → 更新待办 → 正常结束」
- [ ] **L5 工具**：搜索一个公开网页；浏览器 `browser_open` → 快照 → 一次动作（工具名形如 `mcp__browser__browser_open`）
- [ ] **L6 长任务**：冷长输入 → 完全重复请求（看缓存命中）→ 长输出后工具续接 + 召回正确性

> smoke 夹具显式用 temp 0 / seed 1234 / reasoning none，**只影响测试请求**，别拿它改日常设置。网页 200 只证明服务活着，**不能证明模型生成或工具链通过**。

---

## 6. 排障速查

| 现象 | 先看什么 |
|---|---|
| 双击没反应 | 在 PowerShell 手动跑 `start.ps1` 保留报错；查 `runtime\logs`、Node、VC++、模型/引擎路径、端口；加载 + Graph 捕获期间应该等 |
| CUDA OOM / 突然很慢 | 真实占用、是否跑了两份模型、浏览器是否在独显、Sysmem Fallback 是否对**正确的 exe** 设了、RAM 压力 |
| `Device KV page pool exhausted` | 是引擎页预算/恢复路径问题，**不是** "RAM 不够"；核对 exe 哈希、恢复完整默认预算，留输入/输出长度、工具顺序、`/v1/load` 和错误日志 |
| 上下文一长就慢 | 分清冷 prefill 和缓存恢复；确认 dsh 走的是 1236 而不是直连 1234；历史/system prompt/工具表/模板变化都会触发重算 |
| 缓存突然失效 | 比 token 前缀；换工具表、模板、消息或压缩都要重算。**别把 `GUARD_STRICT` 改 0** |
| 搜索失败 / 模型说没浏览器 | 查 `cordis.patch.yml` 的 `web-local` / `mcp-browser`、实际工具列表、`dsh.stderr.log`；搜索靠 Bing 页面/RSS + 本地正文提取，会受限流/验证码/改版影响 |
| `ERR_PROXY_CONNECTION_FAILED` | 浏览器连不上代理，跟模型/KV 无关；别为修 dsh 关掉系统代理 |
| `page.evaluate: Execution context was destroyed` | 导航/刷新把旧 JS 上下文销毁了；`browser_open` 或 `reload` 之后**下一次调用**再读，别在同一个 evaluate 里刷新后继续等 |
| 输出被截断 / 疑似死循环 | 看 finish reason、输出额度、是否重复思考、有没有新证据；保持 xhigh，**别**用强关思考/降 xhigh/乱加惩罚当修法 |
| 交付对了但待办停在 1/3 | 普通回复不会自动改 todo 面板；收尾插件最多提醒一次，由模型按真实结果更新 |
| 非 50 系想跑 | 必须按自己的架构重编译（本 Release 是 `sm120a`），改文件名没用；其他 50 系也不自动获得本机专用调度 |

日志：`runtime\logs\engine.stderr.log`、`engine.stdout.log`、`cache_guard.log`、`dsh.stderr.log`、`dsh.stdout.log`。**对外贴日志前删 token / cookie / 私人任务内容。**

---

## 7. 边界与注意（别把宣传当承诺）

- **256K 是配置的逻辑容量**，不是「所有历史都记得」。KVMem 是选择性注意力；已完成 128K/200K 合成召回，**256K 未做整模型压力测试**。200K 冷预填充维护者测得 424.62 秒。
- **召回/速度是维护者单机**（5070 Ti Laptop + 32GB + 驱动 617.14）实测，不是保底。README 明确说「不是总体能力或速度承诺」，误调用**尚未根治**。
- Release 里的 847 MB 是**预编译引擎 zip**，不是源码；源码在 `engine/`，非 50 系要自己编译。
- **dsh 锁 `0.1.5-rc.3`**，补丁带版本检查。别单独升级 dsh 指望旧补丁继续生效；版本不符就退回固定版本或另做适配。
- 许可：引擎/代码 Apache-2.0；两个模型 **Apache-2.0 与 Swift Open License v1.0 混合**——Swift 部分有商用收入门槛（同控制集团上一财年 US$1,000,000，超过需单独商业许可）。商业使用前读包内 `model-notices/` 与 `licenses/`。
- 该包发布验收覆盖「35,053 文件校验 / 离线安装 / 两模型路由 / 配置切换 / 便携 dsh 网页 200」，**不等于**真实长任务质量验收；它自己也这么写。

---

## 8. 本机不适用的依据（记录，避免以后重复评估）

当前服务器是 Ubuntu 26.04 / GTX 1060 Mobile 6GB（sm_61）/ 15 GiB RAM：

| 要求 | 本机 |
|---|---|
| Windows x64（`.exe` + `.ps1` + `.cmd`） | Linux |
| `sm120a`（Blackwell）+ CUDA 13 | Pascal，CUDA 13 已移除支持 |
| 12 GB 显存 | 6 GB |
| 32 GB RAM（含 7 GiB Host KV） | 15 GiB |
| Node 24+ | v22.23.3（nvm 可升） |
| dsh 0.1.5-rc.3 | 0.1.7-rc.1 |

该方案能在 12GB 卡上跑 27B 的前提就是「页池 + 7 GiB RAM KV」，本机这两项都不够；本机已有的 27B Q4 实测 2.2 tok/s / 4K 上下文（见 `MEMORY.md` §7）已经说明同一结论。