ARTIFACT // CHECK-NVIDIA-VRAM-SPILL.SH (SHELL)
NVIDIA PC 模型加载与显存溢出 / PCIe 共享内存回退排查脚本 (check-nvidia-vram-spill.sh)
对比 nvidia-smi 物理显存占用与 ollama ps 的 GPU/CPU 层卸载比例，精准揪出因共享内存回退导致的 10 倍掉速。
[核心实测结论 / TL;DR]本配置包「NVIDIA PC 模型加载与显存溢出 / PCIe 共享内存回退排查脚本」（文件名：check-nvidia-vram-spill.sh，格式：SHELL）是 Tinker AI 实测工坊配套指南《nvidia-pc-vram-diagnostics》的参数化生产模板。支持在本地浏览器实时定制 待排查模型 Tag (TARGET_MODEL=qwen2.5:14b-instruct-q4_K_M)、测试上下文长度 (num_ctx) (TEST_CTX=16384) 等 2 项核心变量，默认遵循 127.0.0.1 回环绑定与最小权限规范。
01 // HOMELAB本地 AI / HomeLab· 验证日期：2026-10-23
查看全部 42 套配置附件 →check-nvidia-vram-spill.sh
查看配套实测指南 →NVIDIA PC 模型加载与显存溢出 / PCIe 共享内存回退排查脚本
对比 nvidia-smi 物理显存占用与 ollama ps 的 GPU/CPU 层卸载比例，精准揪出因共享内存回退导致的 10 倍掉速。
参数化定制变量 (Variables — 自动保存在本地浏览器)
UTF-8 编码 · 零延迟实时编译
#!/usr/bin/env bash
# Tinker AI — NVIDIA PC Model Loading & VRAM Spillover Diagnostic (Guide #2)
set -euo pipefail
MODEL="qwen2.5:14b-instruct-q4_K_M"
CTX="16384"
echo "=== [1/4] NVIDIA Driver, CUDA & Physical VRAM Baseline ==="
nvidia-smi --query-gpu=name,driver_version,memory.total,memory.used,memory.free --format=csv
echo "=== [2/4] Triggering Model Load ($MODEL @ num_ctx=$CTX) ==="
curl -sS http://127.0.0.1:11434/api/generate -d "{
\"model\": \"$MODEL\",
\"prompt\": \"Warmup VRAM allocation check.\",
\"stream\": false,
\"options\": { \"num_ctx\": $CTX }
}" > /dev/null
echo "=== [3/4] Inspecting Layer Offload Split (Look for 100% GPU vs CPU/GPU Split) ==="
ollama ps
echo "=== [4/4] Post-Load Physical VRAM Utilization ==="
nvidia-smi --query-gpu=memory.used,memory.free,utilization.gpu --format=csv
PARAMETER SPECIFICATION // 参数化变量规范说明表
「check-nvidia-vram-spill.sh」可定制环境变量与默认值说明
本配置模板（SHELL 格式）支持 2 项运行时参数注入，所有替换均在本地浏览器内完成。
| 模板占位符 | 参数用途说明 | 安全默认值 | 填写示例 |
|---|---|---|---|
{{TARGET_MODEL}} | 待排查模型 Tag | qwen2.5:14b-instruct-q4_K_M | qwen2.5:14b-instruct-q4_K_M |
{{TEST_CTX}} | 测试上下文长度 (num_ctx) | 16384 | 16384 |
PAIRED HARDWARE MANIFEST // 配套实测环境与边界记录
配套指南《一台现有 NVIDIA PC 的模型加载与显存排查：定位 PCIe 共享内存回退与 Docker GPU 透传》验证基线
实测硬件与操作系统 (Hardware & OS)
NVIDIA RTX 4070 12GB 独显 · 32GB DDR5 系统内存 · Ubuntu 24.04 与 Windows 11 WSL2 对照实测
锁定软件栈与模型版本 (Pinned Versions)
NVIDIA Driver 560.35 / CUDA 12.6Ollama 0.5.7nvidia-container-toolkit 1.16.2
离线与安全边界 (100% 本地独显闭环运行)
排查过程仅依赖本地 `nvidia-smi` 与 `ollama ps` 终端工具，零外部依赖。
已知限制与失败边界 (Known Limits)
- 新版 NVIDIA 驱动默认开启“CUDA 系统共享内存回退”：当模型总占用超出 12GB 物理显存哪怕 600MB，程序不会报 OOM 崩溃，而是经由 PCIe 总线借用慢速内存，导致生成速度暴跌 8–10 倍。
- 在 12GB 显卡上同时常驻 14B Q4_K_M 对话模型（9.0GB）与本地 Embedding 模型（0.6GB）时，留给 KV Cache 的空间不足 1.3GB，一旦 num_ctx > 4096 就会发生层溢出。
DEPLOYMENT CHECKLIST // 配置落地核验步骤
部署 check-nvidia-vram-spill.sh 后的 3 步验收清单
- 在目标 `num_ctx` 负载下执行 `ollama ps`，确认显示 `100% GPU` 而非 CPU/GPU 混合。
- 在 8GB–12GB 显卡环境下已配置 `OLLAMA_MAX_LOADED_MODELS=1` 与 `OLLAMA_KV_CACHE_TYPE=q8_0`。
- 若使用容器部署，已验证 `docker exec <container> nvidia-smi` 能正常打印显卡信息。