---
name: local-llm-tuning
description: 本地大模型后部署调优：Modelfile参数调节→单变量实验→评测集对比→Prompt固化。与 local-llm-recommendation（选型）互补。
version: 1.0.0
---

# Local LLM Tuning（本地大模型调优）

⚠️ **用户纠正信号：「我的意思是优化我的本地大模型不是我学习」**——当用户说"优化本地模型"，他们指的是让现有的模型更好用（调参+Prompt+推理加速），**不是**学习怎么训练模型。不要在用户问优化时推销训练教程（LoRA/SFT/预训练）。

当用户说"优化我的本地模型"、"调参数"、"让模型更聪明"、"模型太笨"、"能不能调一下"时激活。**不是**装新模型，而是优化已有的模型。

## 核心原则：证据驱动，单变量测试

```
绝不一次改两个参数——不知道哪个起了作用。
```

### 区分"观测"与"宣传"
- **观测（Observation）**：自己在机器上跑出来的数据。可信，可复现。
- **宣传（Claim）**：GitHub README / 抖音视频里的结论。待验证，不可直接引用数值。
- 对GitHub工具：先**看源码理解它做了什么**，再验证，不直接依赖。
- 不说"零风险"，说**"低风险，可逆，值得先试"**——改动前先确认版本/硬件支持。

### 实验记录规范（E-series）

每次实验记一条，格式如下：

| 实验 | 改动 | 指标 | 结果 | 根因 |
|:----:|------|------|:----:|------|
| E-003 | FA=ON | TTFT, tok/s, 回答是否为空 | ❌ 回答为空 | Blackwell未适配 |

**否定结论也是有效产出**——记录根因和修复路径，避免下次再试。

## 🔴 前置步骤（必须先做）：确认实际运行的后端

**⚠️ 2026-07-22 教训：** 不要假设用户在用 Ollama。先验尸再动手。

用户可能嘴上说"本地模型"，但实际后端有三种可能：

| 后端 | 发现方式 | 对应文件/进程 |
|------|---------|-------------|
| **Ollama** | `tasklist \| findstr ollama` | `ollama.exe`，端口 11434 |
| **llama.cpp server** | `netstat -ano \| findstr "8080\|8081"` | `llama-server.exe`，GGUF 文件 |
| **自定义代理** | 查 config.yaml 的 `custom_providers` | 任意端口 |

### Step 0：先查后干（5 秒）

```bash
# 1. 查进程
cmd.exe /c "tasklist /FI \"IMAGENAME eq ollama.exe\" 2>nul"
cmd.exe /c "tasklist /FI \"IMAGENAME eq llama-server.exe\" 2>nul"

# 2. 查端口
cmd.exe /c "netstat -ano | findstr 11434"
cmd.exe /c "netstat -ano | findstr 8080"
cmd.exe /c "netstat -ano | findstr 8081"

# 3. 查 config
grep -A5 "custom_providers" /c/Users/*/AppData/Local/hermes/config.yaml 2>/dev/null

# 4. 查模型文件
find /c/Users/*/Desktop -name "*.gguf" -maxdepth 3 2>/dev/null
find /d/ -name "*.gguf" -maxdepth 2 2>/dev/null
```

**如果发现用户是 llama.cpp：** 跳过所有 `ollama` 相关操作，直接查 `start_local_models.bat` 或 `llama-server.exe` 的启动参数。

**警告：** 如果先修 Ollama Modelfile 才发现后端是 llama.cpp，整个修复过程白干。先查后端，再动手。

### 🔴 陷阱：创建实验变体后必须清理

创建 `hermes-qwen3-t02`、`hermes-ctx-32k` 这类实验模型后，用户会说：
> **"这些不都是你搞出来的"**

**规则：** 每创建实验变体后，要么立即删（确认不需要），要么在用户说停之前主动清理。

```bash
# 删除单个
ollama rm hermes-qwen3-t02

# 批量删除实验变体
for m in hermes-qwen3-long hermes-qwen3-daily hermes-qwen3-pro hermes-qwen3-t08 hermes-qwen3-t02 hermes-qwen3-t04 hermes-qwen3-baseline hermes-ctx-32k hermes-ctx-16k hermes-ctx-4k; do
  ollama rm "$m" 2>/dev/null
done
```

**2026-07-22 具体案例：** 7 个实验变体 + 3 个 ctx 变体 = 10 个垃圾模型，用户问"这些不都是你搞出来的"。

## 优化流程

### Step 0a：硬件基线确认
```bash
nvidia-smi --query-gpu=name,memory.total,memory.free --format=csv,noheader
ollama list
```

### Step 1：建专属 Modelfile（代替直接用官方模型）

```bash
ollama show <base-model> --modelfile > Modelfile
# 或从头写
cat > Modelfile << 'EOF'
FROM <base-model>:latest
PARAMETER temperature 0.2
PARAMETER top_k 20
PARAMETER top_p 0.95
PARAMETER repeat_penalty 1
PARAMETER stop "<|im_start|>"
PARAMETER stop "<|im_end|>"
SYSTEM ""
EOF
ollama create my-custom-model -f Modelfile
```

### Step 2：单变量实验

一次只改一个参数，其他保持不变：

| 参数 | 典型实验范围 | 效果 | 建议起点 |
|------|------------|------|---------|
| temperature | 0.2 / 0.4 / 0.6 / 0.8 | 越低越专注准确，越高越有创造 | 从默认下探到0.2 |
| num_ctx | 4096 / 8192 / 32768 / 65536 | 越大记忆越长但显存占用高 | 够用就行，别盲目开满 |
| top_p | 0.85 / 0.90 / 0.95 | 核采样阈值 | 0.95通常够 |
| repeat_penalty | 1.0 / 1.05 / 1.1 | 防重复，但太高会打断正常输出 | 从1.0开始 |

**已知结论（Qwen3-8B on RTX 5060 8GB）：**
- temperature=0.2 效果最佳：回答最完整、结构最清晰、有效回答率最高
- temperature=0.6（默认）反而是最差的：一半题目被截断或空回答
- temperature=0.4 和 0.8 表现接近，介于两者之间

### Step 3：建评测集

准备一套固定问题（建议20题），覆盖你的主要使用场景。每次改参数后都跑同一套题。

**评测集设计原则：**
- 覆盖不同任务类型（编程/领域知识/语言学习/工具规划）
- 答案长度不同（有简答有长答）
- 问题固定，不变

示例结构：5题C语言 + 5题领域架构 + 5题语言学习 + 5题工具规划

### Step 4：跑对比

```python
# 核心流程：用 Ollama API 批量跑多个模型，记录指标
import urllib.request, json

def test_model(name, question):
    data = json.dumps({
        'model': name,
        'messages': [{'role': 'user', 'content': question}],
        'stream': False,
        'options': {'num_predict': 600}  # Qwen3 thinking模式消耗多，设大些
    }).encode('utf-8')
    req = urllib.request.Request('http://localhost:11434/api/chat', data=data)
    req.add_header('Content-Type', 'application/json')
    resp = json.loads(urllib.request.urlopen(req, timeout=120).read().decode('utf-8'))
    content = resp['message']['content']
    return {
        'content': content,
        'ttft_ms': resp['prompt_eval_duration'] // 1000000,
        'tokens': resp['eval_count'],
        'speed': resp['eval_count'] / max(resp['eval_duration']/1e9, 0.001),
        'total_ms': resp['total_duration'] // 1000000
    }
```

**重点指标（按优先级）：**
1. 有效回答率（非空内容占比）
2. 平均回答长度
3. 首字延迟(TTFT)
4. 生成速度(tok/s)

### Step 5：Prompt 固化

把你每次都要说的内容写进 Modelfile 的 SYSTEM 块：

```bash
cat > Modelfile_pro << 'EOF'
FROM my-custom-model
SYSTEM "你是吉冠佳的AI助手。回答简洁、结构化、侧重考点。先判断再回答。"
PARAMETER temperature 0.2
...
EOF
ollama create my-final-model -f Modelfile_pro
```

## 优化优先级框架（按成本/收益排序）

不要一上来就调框架或改系统配置。按这个顺序走：

| 层级 | 项目 | 时间 | 效果 |
|:----:|------|:----:|:----:|
| 🥇 **第一梯队** | 建Modelfile → 调temperature → Prompt固化 | 5-30分钟 | 有效回答率 60%→90% |
| 🥈 **第二梯队** | autotune → 更新Ollama版本 | 30-60分钟 | KV缓存 -66%，速度+5% |
| 🥉 **第三梯队** | 换推理框架(llama.cpp/vLLM) | 数小时 | 不确定，维护成本高 |

除非 Ollama 真成瓶颈，否则不建议上第三梯队。

## autotune 集成

autotune 是一个零配置的推理优化中间件，直接优化你的 Ollama 模型，不修改任何代码。

### 安装与设置
```bash
pip install llm-autotune
autotune start --model <你的模型名>
```

### 验证效果
```bash
autotune proof --model <你的模型名>   # 45秒验证
autotune proof-suite --model <你的模型名>  # 20分钟全统计
```

### 已验证效果（Qwen3-8B + RTX 5060 8GB）
| 指标 | 关闭 autotune | 开启 autotune | 变化 |
|------|:------------:|:-------------:|:----:|
| KV cache 占用 | 576 MB | **198 MB** | **−66%** |
| 生成速度 | 59.6 tok/s | **62.7 tok/s** | +5% |
| 首字延迟 | ~3125ms | ~3103ms | 接近 |

最直接的收益是 **378MB RAM 释放**——对于 8GB 显存的机器，这意味着其他应用（Chrome/VS Code）不会因为模型驻留而被挤掉。

### 运行方式
autotune 提供 OpenAI 兼容 API（端口 8765）和命令行聊天两种模式：
```bash
autotune chat --model <你的模型名>     # 终端聊天
autotune serve                          # API 服务 (localhost:8765)
```

## 小模型优化策略（4B-8B，用 Ollama + Hermes 场景）

### GPU 利用率诊断：ollama ps PROCESSOR 列

模型加载后，立刻检查 GPU 利用率：

```bash
ollama ps
# 输出示例:
# NAME          SIZE     PROCESSOR          CONTEXT
# qwen3-vl:4b   3.5 GB   78%/22% CPU/GPU    131072
```

**解读 PROCESSOR 列：**
- `100% GPU` → ✅ 模型完全跑在显卡上，速度最优
- `XX%/YY% CPU/GPU` → ⚠️ 部分计算落在 CPU 上，显存不够
- `100% CPU` → ❌ 模型没用到显卡

**根因：** 模型总需求 > 可用 VRAM。需求 = 模型权重 + 视觉编码器（如有）+ KV 缓存（由 `num_ctx` 决定）+ 中间缓冲区。

**修复：减少 `num_ctx` 释放 VRAM，让更多模型层放到 GPU 上：**

```bash
# 检查当前 num_ctx
ollama show <model> --modelfile | grep num_ctx

# 建 Modelfile 降低上下文
cat > Modelfile_gpu << 'EOF'
FROM <model>
PARAMETER num_ctx 4096
EOF
ollama create <model>-gpu -f Modelfile_gpu

# 验证
ollama run <model>-gpu "hi" > /dev/null 2>&1
ollama ps
```

**实际案例（qwen3-vl:4b on RTX 5060 8GB）：**
| 配置 | Context | PROCESSOR | VRAM |
|------|:-------:|:---------:|:----:|
| 默认 | 131072 | 78% CPU | 7.3GB |
| `num_ctx 4096` | 4096 | **100% GPU** | 7.7GB |

### 核心发现：模型越小，prompt 越要短

| 模型 | 大小 | 最佳 System Prompt 长度 |
|------|------|----------------------|
| Qwen3-2507-4B | 2.5GB | ≤500 字符（超过会丢失细节） |
| Qwen3-8B | 5.2GB | ≤1200 字符 |
| DeepSeek/云端 | — | 数万字符 |

**陷阱：** 给 4B 模型写 1200 字 system prompt → 它会记住"你是谁"但丢失"H-004 是什么"这类细节。不是不会答，是 prompt 太长截断了。

### 最佳实践：知识库作为工具（替代长 Prompt）

4B 模型无法消化长 system prompt。正确做法：短 prompt + 知识库工具：

```bash
FROM qwen3:4b-instruct-2507-q4_K_M
SYSTEM "你是小Q，本地助手。教单词格式见下方例子。不知道的查知识库或搜索。"
```

然后建一个 `xiaoq_knowledge_base.md` 文件，让模型通过 `read_knowledge` 工具自己读取。

### Qwen3-2507 系列 vs 旧版

Qwen3-2507 是 2026 年 7 月发布的重大更新版：

| 能力 | Qwen3-8B（旧） | Qwen3-2507-4B（新） |
|------|--------------|-------------------|
| 工具调用 | ❌ 不支持结构化 tool_calls | ✅ 原生支持 |
| 大小 | 5.2GB | 2.5GB |
| 指令遵循 | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| 速度 | ~21秒/词 | ~9秒/词（短prompt） |

**Ollama 模型名：** `qwen3:4b-instruct-2507-q4_K_M`

### Tool Calling 完整流程

```python
import urllib.request, json, subprocess

# Step 1: 发消息 + tools 声明
data = json.dumps({
    'model': 'hermes-xiaoq',
    'messages': [{'role': 'user', 'content': '搜索2026年四级考试时间'}],
    'tools': [{
        'type': 'function',
        'function': {
            'name': 'search_web',
            'description': '搜索互联网',
            'parameters': {'type': 'object', 'properties': {'query': {'type': 'string'}}, 'required': ['query']}
        }
    }],
    'stream': False
}).encode('utf-8')
req = urllib.request.Request('http://localhost:11434/api/chat', data=data)
req.add_header('Content-Type', 'application/json; charset=utf-8')
resp = json.loads(urllib.request.urlopen(req, timeout=60).read())
msg = resp['message']

# Step 2: 检查 tool_calls
if msg.get('tool_calls'):
    for tool in msg['tool_calls']:
        fn_name = tool['function']['name']
        args = tool['function']['arguments']
        query = args['query'] if isinstance(args, dict) else json.loads(args)['query']
        
        # 执行工具
        result = subprocess.run(
            ['python', '-m', 'anysearch_cli', 'search', query],
            capture_output=True, text=True, timeout=30
        ).stdout
        
        # Step 3: 把结果喂回模型（完整消息历史）
        data2 = json.dumps({
            'model': 'hermes-xiaoq',
            'messages': [
                {'role': 'user', 'content': '搜索2026年四级考试时间'},
                {'role': 'assistant', 'content': None, 'tool_calls': msg['tool_calls']},
                {'role': 'tool', 'content': result, 'name': fn_name}
            ],
            'stream': False
        }).encode('utf-8')
        final = json.loads(urllib.request.urlopen(
            urllib.request.Request('http://localhost:11434/api/chat', data=data2,
                headers={'Content-Type': 'application/json; charset=utf-8'}), timeout=60).read())
        print(final['message']['content'])
```

**关键点：**
- tool 参数必须是 `{'type': 'function', 'function': {...}}` 格式
- arguments 可能是 dict（已解析）或 string（需 json.loads）
- 第二轮必须传完整消息历史（user → assistant(tool_calls) → tool(result)）
- qwen3:8b（旧版）不支持此功能，qwen3-2507-4B 才支持

### 交互模式 vs 批量模式

小模型（4B）不适合做多轮交互（等→判→出下一题），因为每次 API 调用独立。

**解决方案：** 脚本控制流程，模型只出题和判卷，脚本负责循环。

### System Prompt 格式：具体例子 > 抽象描述

4B 模型理解抽象描述差，但复制具体例子效果很好：

```bash
# ❌ 抽象描述（模型可能理解错）
SYSTEM "教单词格式：词根+同义词3个+长得像3个，用逗号分隔"

# ✅ 具体例子（模型会模仿格式）
SYSTEM "教单词格式：
**central** — 中心的，核心的
**词根：** cen-（拉丁语，中心）
**同义词：** core（核心），key（关键），main（主要）
**长得像：** center（中心），century（世纪），certain（确定的）
> The central idea is about love."
```

## Qwen3 特殊注意事项

### Thinking 模式
Qwen3 系列会在 API 响应中返回 `message.thinking` 字段（思考过程）。这意味着：
- 每个回答的 token 预算被分成「思考」和「输出」两部分
- `num_predict` 需要设得比正常模型大（建议 600+，一般任务 800）
- 回答长度为 0 但 thinking 不为空 → token 预算不够，不是模型不会答
- 调高 `num_predict` 或降低 temperature 能改善

### API 端点
始终用 `/api/chat` 而非 `/api/generate`：
```bash
# ✅ 正确
POST http://localhost:11434/api/chat
# ❌ 会丢失格式
POST http://localhost:11434/api/generate
```

### 中文编码
bash curl 传中文可能乱码，始终用 Python：
```python
# ✅ Python utf-8 编码
# ❌ bash curl 中文可能乱码
```

## Flash Attention & KV Cache 兼容性陷阱

### 问题：Blackwell GPU（RTX 5060+）与 Ollama 不兼容

Ollama 环境变量 `OLLAMA_FLASH_ATTENTION=1` 和 `OLLAMA_KV_CACHE_TYPE=q8_0` 在 **NVIDIA Blackwell 架构（Compute Capability 12.0）** 上不可用：

| 环境变量 | RTX 5060 上的表现 |
|----------|------------------|
| `OLLAMA_FLASH_ATTENTION=1` | 短 prompt 正常但回答为空，长 prompt 超时 |
| `OLLAMA_KV_CACHE_TYPE=q8_0` | 同 FA 问题，KVC 量化依赖 Flash Attention |

**根因：** Ollama 0.31.1 底层 llama.cpp 的 Flash Attention 实现尚未适配 Blackwell 架构。

### 检测方法

```bash
# 1. 确认 GPU 架构
nvidia-smi --query-gpu=name,compute_cap,driver_version --format=csv,noheader
# RTX 5060 → Compute Capability 12.0（Blackwell）

# 2. 确认 Ollama 版本
ollama --version

# 3. 测试 FA 是否兼容
# 启动服务
set OLLAMA_FLASH_ATTENTION=1 && ollama serve
# 测试简单对话
python -c "
import urllib.request, json
data = json.dumps({'model':'<your-model>','messages':[{'role':'user','content':'你好'}],'stream':False}).encode()
req = urllib.request.Request('http://localhost:11434/api/chat', data=data)
resp = json.loads(urllib.request.urlopen(req,timeout=30).read().decode())
c = resp['message']['content']
print(f'回答为空: {len(c)==0}')
"
```

### 恢复方法（FA/KV 崩溃后 VRAM 泄漏）

当 FA=ON 或 KV=q8_0 导致 Ollama 崩溃后，GPU 显存可能无法释放（Windows 上常见）：

```bash
# 1. 杀所有 Ollama 进程
taskkill /f /im ollama.exe
taskkill /f /im ollama_llama_server.exe

# 2. 检查 VRAM 是否释放
nvidia-smi --query-gpu=memory.used --format=csv,noheader
# 如果仍高（>7GB），说明泄漏

# 3. 唯一修复（Windows 无命令行重置方案）
# 方案A：重启电脑（最快，15秒）
# 方案B：设备管理器 → 禁用显卡 → 重新启用
```

### 当前已知兼容矩阵

| Ollama版本 | GPU架构 | Flash Attention | KV Cache q8_0 |
|:---------:|:-------:|:--------------:|:-------------:|
| 0.31.1 | Ampere(CC 8.0+) | ✅ | ✅ |
| 0.31.1 | Ada(CC 8.9) | ✅ | ✅ |
| 0.31.1 | **Blackwell(CC 12.0)** | ❌ 回答为空 | ❌ 依赖FA |
| 0.32.1 | Blackwell | ⚠️ 待测试 | ⚠️ 待测试 |

## MoE 异构计算：低显存跑大模型（llama.cpp CPU offload）

对于 MoE 架构大模型（如 Qwen3.6-35B-A3B），可用 llama.cpp 的 MoE 异构计算特性，**用 CPU 内存换显存空间**。

### 原理

| 组件 | 存放位置 | 原因 |
|------|---------|------|
| Attention 层 + 路由网络 | GPU 显存 | 计算密集，需要低延迟 |
| MoE 专家层 | CPU 内存 | 每次只激活部分专家，CPU 带宽够 |
| KV Cache | GPU（压缩后） | Q4_K_M 量化后约 2-3GB |

### 硬件要求

| 组件 | 最低 | 推荐 |
|------|------|------|
| GPU 显存 | 8GB（6GB可用）| 12GB |
| CPU 核心 | 8核 | 16核+ |
| 系统内存 | 32GB DDR4 | 64GB DDR5 |
| 指令集 | AVX2 | AVX-512 |

### Qwen3.6-35B-A3B 实测速度参考

| 显存 | 策略 | 速度 |
|:----:|------|:----:|
| 8GB（如 RTX 5060） | Attention GPU，MoE 专家 CPU | ~15-25 tok/s |
| 12GB | 同上，更多层留 GPU | ~30-40 tok/s |
| 24GB+ | 全 GPU | ~50-60 tok/s |

### 实现步骤

```bash
# 1. 下载 GGUF（约20GB）
# 从 HuggingFace 或 ModelScope 获取 Qwen3.6-35B-A3B Q4_K_M

# 2. 编译 llama.cpp（需 CUDA 支持）
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# 3. 运行（MoE 专家层 CPU offload）
./build/bin/llama-cli -m qwen3.6-35b-a3b-q4_k_m.gguf \
  -ngl 99 \                    # 尽可能多层放GPU
  --moe-expert-offload \        # MoE专家层offload到CPU
  --cache-type-k q8_0 \         # KV cache量化
  --cache-type-v q8_0 \
  -fa \                         # Flash Attention
  -p "你的问题"
```

> **注意：** Ollama 对 MoE offload 支持较弱，大 MoE 模型建议用原生 llama.cpp。

## 评测集的完整流程（从20题到结果分析）

### 多阶段评测策略

当模型数量多（4个变体 × 20题 = 80次调用，约40分钟），建议分阶段：

**第一阶段（快速筛选）：** 只跑10题（C语言5 + 领域架构5）
- 识别出明显差或好的版本
- 约15分钟

**第二阶段（完整验证）：** 跑剩余10题（英语5 + 工具规划5）
- 验证第一阶段结论是否全面
- 约15分钟

**第三阶段（报表）：** 合并两阶段数据，输出最终结论

### 结果保存

每次评测结果写入文件，以便后续对比。这样下次升级 Ollama 或改参数后，可以跟历史数据对照。

## 网络：模型下载代理检测

### 检测系统 VPN 代理端口

Windows 终端（git-bash）不自动走系统代理。下载模型前先找代理：

```bash
# 查注册表（Clash/SS/V2Ray 都写这）
reg query "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v ProxyServer
# → 127.0.0.1:7890

# 确认代理可用的同时验证网络连通性
for port in 7890 7891 10809 10808 1080 3128 8080; do
  code=$(curl -s --proxy "http://127.0.0.1:$port" \
    -o /dev/null -w "%{http_code}" \
    "https://huggingface.co" --connect-timeout 3 2>&1)
  [ "$code" != "000" ] && echo "✅ 端口 $port 可用: HTTP $code"
done
```

### 带代理下载模型

```bash
# 单次下载
curl -L --proxy http://127.0.0.1:7890 \
  -o model.gguf "https://huggingface.co/org/repo/resolve/main/file.gguf"

# 设环境变量（会话内所有 curl 生效）
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
curl -L -o model.gguf "https://huggingface.co/..."
```

### HuggingFace 模型文件结构（视觉模型）

视觉模型（如 Qwen2.5-VL）需要两个文件：
- `Qwen2.5-VL-3B-Instruct-Q4_K_M.gguf` — 模型本体（~2GB）
- `mmproj-Qwen2.5-VL-3B-Instruct-Q8_0.gguf` — 视觉投影矩阵（~800MB）

`llama-qwen2vl-cli.exe` 需要 `-m model.gguf` 和 `--mmproj mmproj.gguf` 两个参数。

**非视觉模型** 只需要一个 `.gguf` 文件。

## llama.cpp 函数调用（对接 Hermes 必需）

**陷阱：** `llama-server` 启动时必须加 `--jinja` 参数，否则模型不会输出 `tool_calls`，Hermes 接了也用不了工具。

详情见 `references/llama-function-calling.md`。原生支持工具调用的模型：Qwen 2.5（推荐）、Llama 3.x、Hermes 2/3、Functionary v3.x、Mistral Nemo。不带 `--jinja` → 聊天正常但工具调用永远不触发。

## llama.cpp 服务器恢复记录（2026-07-22 案例）

用户实际使用 llama.cpp 而非 Ollama，但我先修了半天的 Ollama Modelfile。完整恢复过程和配置见 `references/2026-07-22-llamacpp-server-recovery.md`。

## llama.cpp Hermes 上下文兼容性

llama.cpp 服务器的 `--ctx-size` 必须 ≥ 65536 才能通过 Hermes Agent 初始化检查。具体命令和验证方法见 `references/llamacpp-hermes-context-compat.md`。

## 已知陷阱

- ❌ 一次改多个参数 → 不知道哪个改变了结果
- ❌ 凭感觉判断变好 → 必须用固定评测集跑分
- ❌ `num_ctx` 盲目开满 → 显存吃光还变慢，够用就行
- ❌ 用 `/api/generate` 测 Qwen3 → 内容可能丢失
- ❌ num_predict 设太小 → Qwen3 thinking 把预算吃光，什么也吐不出
- ❌ bash curl 传中文 → 可能乱码，模型答非所问
- ❌ 推荐环境变量前没确认版本支持 → `ollama serve --help | grep <var>` 先确认
- ❌ 通过API传`num_ctx`给Qwen3 → thinking模式不兼容，回答为空。必须用Modelfile方式
- ❌ Ollama崩溃后直接重试 → 先`taskkill /f /im llama-server.exe` 清VRAM残留
- ❌ 在Blackwell GPU上开FA/KV量化 → 当前Ollama版本不支持，回答为空
- ❌ **`ollama rm` 连带删除基模型** → 如果自定义模型（如 `hermes-xiaoq`）基于某个基模型，删除基模型会让所有依赖它的自定义模型不可用。删除前先用 `ollama list` 确认。`ollama rm qwen3:8b` 不会删 `hermes-xiaoq`（它是独立模型），但删 `qwen3:4b-instruct-2507-q4_K_M` 会让基于它的模型全失效。
- ❌ **用抽象描述代替具体例子教4B模型格式** → 写"同义词3个+长得像3个，逗号分隔"模型可能理解错（变成编号列表）。在system prompt里写一个具体例子模型会完美模仿格式。
- ❌ **视觉模型加载后显存爆炸** → qwen3-vl:4b（3.3GB 磁盘）加载后占用约 7.3GB 显存。正常现象：权重 3.3G + 视觉编码器 1.5G + KV 缓存 1.5G + 中间缓冲区 1G + 其他进程 ≈ 7.3G。不是显存泄露。
- ❌ **GGUF 文件损坏不检查** → 启动失败时查服务端日志发现 "invalid magic characters: 'Inva', expected 'GGUF'"，`ls -la` 一看文件只有 29 字节（文件被覆盖为错误消息 "Invalid username or password."）。三件事：
  1. 每次启动失败先 `ls -la *.gguf` 检查文件大小是否合理（8B Q4_K_M ≈ 5.0GB，3B Q4_K_M ≈ 2.0GB）
  2. 同目录下有 `mlabonne_*` 命名的是备份/重命名下载版，可以拿来用
  3. 29 字节的损坏文件 mv 成 `.bak`，不要原地重试
- ❌ **llama.cpp --ctx-size 开满 64K 后模型超时/回应为空** → 8GB 显存上 Qwen3-8B Q4_K_M 的 KV Cache 占 3-8GB（视 ctx-size），模型权重占 ~5GB。实际可用的 ctx-size *上下文-显存映射：llamacpp-hermes-context-compat.md 中的 VRAM 表*。
  如果 max_tokens 设太小（如 50），Qwen3 思考模式（reasoning_content）会把预算全吃掉，最终 content 为空。设 max_tokens ≥ 256 以上。