一、前置条件#

1. 安装 Docker
2. 安装 docker-compose
3. 安装 CUDA
4. 设备示例：Jetson AGX Thor

二、安装编译依赖#

1
sudo apt update && sudo apt install -y build-essential git libopenblas-dev

三、拉取 llama.cpp 源码（国内加速克隆）#

1
# 加速克隆源码
2
git clone https://ghproxy.com/https://github.com/ggml-org/llama.cpp.git
3
# 进入项目目录
4
cd llama.cpp

四、编译 llama.cpp#

1
# 编译（带 CUDA 支持）
2
make clean && CUDA=1 make -j$(nproc)

五、下载模型#

1. 量化版本选择

• Q4_K_P：显存占用低，适合小显存设备
• Q8_K_P：输出精度更高，显存占用更大
• 多模态模型额外下载配套 mmproj 视觉文件

2. HuggingFace 镜像替换规则

1
原地址：  https://huggingface.co/xxx/模型仓库名
2
加速地址：https://hf-mirror.com/xxx/模型仓库名

3. 路径统一

将下载完成的 .gguf 模型放入项目内 models/ 文件夹，统一路径避免读取报错。

六、测试推理（验证编译与模型可用）#

1
./main \
2
  -m models/你的模型.gguf \
3
  --flash-attn \
4
  --mlock \
5
  -np $(nproc) \
6
  -c 8192

参数说明：

七、配置 systemd 常驻后台服务#

实现开机自启、崩溃自动重启：

1
[Unit]
2
Description=Llama.cpp Local LLM Service
3
After=network.target
4

5
[Service]
6
User=你的用户名
7
WorkingDirectory=/home/你的用户名/llama.cpp
8
ExecStart=/home/你的用户名/llama.cpp/server -m models/你的模型.gguf --flash-attn --mlock -c 8192
9
Restart=always
10
RestartSec=5
11

12
[Install]
13
WantedBy=multi-user.target

加载并启动：

1
sudo systemctl daemon-reload    # 重载系统服务配置
2
sudo systemctl enable llama     # 设置开机自启
3
sudo systemctl start llama      # 启动推理服务
4
journalctl -u llama -f          # 实时查看运行日志

八、部署 AstrBot（Agent 侧）#

1
mkdir astrbot && cd astrbot
2
sudo docker run -itd -p 6185:6185 -p 6199:6199 \
3
  -v $PWD/data:/AstrBot/data \
4
  -v /etc/localtime:/etc/localtime:ro \
5
  -v /etc/timezone:/etc/timezone:ro \
6
  --name astrbot \
7
  m.daocloud.io/docker.io/soulter/astrbot:latest

到这一步，一个能跑、能自启、带 Agent 的本地推理环境就搭好了。但它能跑多长的上下文、能跑多大的模型，取决于下面这部分。

九、关键发现：它不是 dense 模型#

用十六进制编辑器（或 strings + 头解析）看 GGUF 元数据，关键两行：

1
general.architecture = qwen35
2
qwen35.block_full_attention_interval = 4

qwen35 是混合架构：65 层里每 4 层才有 1 层全注意力，也就是只有 16 层需要存 KV 缓存；其余 49 层是 SSM（线性注意力），状态复杂度是 O(1)，几乎不随上下文长度增长。

按 dense（65 层全注意力）去估 KV 显存，会高估 3~4 倍。我一开始算的上下文档位直接砍半就对了。

这也是为什么很多「27B 需要 XX GB」的经验公式在混合架构上会严重失准。

十、上下文甜点与断崖（实测 prefill 吞吐）#

光看「能不能启动」没用——KV 溢出时它不报错，只会静默变慢。真正要看的是 prefill 吞吐曲线：

断崖清晰地落在 65536 与 98304 之间。我现在的默认：

1
-c 65536 -ctk q4_0 -ctv q4_0 -np 1
2
KVBUDGET=1200 MiB

中文 token 密度按文体取：连续自然语言约 0.595 字/token，编号条目式 0.654~0.747 字/token，估算可用上下文长度时别用 1<1>。

前缀缓存默认开启：同一段系统提示词第二轮起几乎不用重算，每轮省 6~7 秒。

十一、上下文压缩代理 ctx-proxy#

单卡 27B 的上下文再怎么抠也有限，长对话还是会顶到上限。我在客户端和推理服务之间加了一层零第三方依赖的压缩代理（ctx-proxy.py），客户端把 API 地址从 8080 改成 8787 即可，其余配置不动。

压缩策略按代价递增分四级：

• L0 原样透传
• L1 截断超长单条
• L2 滚动摘要（把早期对话压成摘要）
• L3 硬丢弃早期内容

事后若上游仍报超限，则激进压缩重试。

两个关键坑：

1. Qwen3 默认 thinking 会把 content 掏空——答案写进 reasoning_content，content 是空的。代理默认注入 enable_thinking=False 并剔除历史里的 reasoning；需要思考链时再用 think 参数开。
2. KV_SAFE_CAP = 42000：不必把 -c 顶到 65536，光是对话逼近上限就够让 KV 挤出显存、prefill 暴跌十几倍。提前压缩比撞墙再救更稳。

十二、写 .bat / 代理时的踩坑清单#

1. .bat 必须 CRLF，中文必须存 GBK/CP936（chcp 65001 也救不了），可靠写回路径只有 PowerShell GetEncoding(936) 并回环校验。
2. llama-server --list-devices 会永久污染控制台代码页（改成 65001），导致后续中文乱码 → 每次调用后立刻 chcp 936；注意 chcp 会覆盖 errorlevel，要先存退出码。
3. 代理窗口中文乱码修了三版才对：最终用控制台 WriteConsoleW 写 UTF-16，由系统转码，不要在 Python 里猜代码页。
4. 单实例守卫：一张 12GB 卡只能跑一个 27B-IQ2_M 实例；端口自动顺延会造出「僵尸实例」（/health 正常但补全 502）。
5. --tools 有 7 个内置工具，schema 约 800 token；--agent/-ag ≈ --tools all --ui-mcp-proxy。