--served-model-name qwen38-awq \
--host 0.0.0.0 \
--port 8002 \
--dtype float16 \
--attention-backend TRITON_ATTN \
--tensor-parallel-size 1 \
--gpu-memory-utilization 0.98 \
--max-num-batched-tokens 512 \
--max-num-seqs 2 \
--max-model-len 4096 \
--limit-mm-per-prompt '{"image": 1, "video": 0}' \
--mm-processor-kwargs '{"max_pixels": 262144}' \
--compilation-config '{"cudagraph_mode": "PIECEWISE"}' \
--trust-remote-code > ~/vllm.log 2>&1 &

拉取分支命令：
cd ~/llama.cpp

拉取 PR #27342 到本地分支（不动当前分支）

git fetch origin pull/27342/head:pr-27342

独立工作树，编译产物隔离

git worktree add ~/llama-dflash pr-27342
cd ~/llama-dflash
export PATH=/usr/local/cuda/bin:$PATH
cmake -B build \
-DGGML_CUDA=ON \
-DGGML_CUDA_ARCHITECTURES="75" \
-DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc \
-DCMAKE_BUILD_TYPE=Release
cmake --build build -j $(nproc)

优化命令：
./build/bin/llama-server \

-m /data/models/unsloth-qwen3.8-27b/Qwen3.8-27B-Q4_K_M.gguf \
--port 8000 --host 0.0.0.0 \
-t 12 --threads-batch 12 \
--n-gpu-layers 99 \
-c 102400 --batch-size 1024 --ubatch-size 512 \
--flash-attn on --cont-batching \
--spec-type draft-mtp --spec-draft-n-max 3 --spec-draft-p-min 0.7 \
--cache-type-k q4_0 --cache-type-v q4_0 \
--cache-ram 8192 \
--parallel 1 --temp 0.7 --top-p 0.8 --top-k 20 --presence-penalty 1.0

（去告警）最终命令：./build/bin/llama-server \
-m /data/models/unsloth-qwen3.8-27b/Qwen3.8-27B-Q4_K_M.gguf \
--port 8000 --host 0.0.0.0 \
-t 12 --threads-batch 12 \
--n-gpu-layers 99 \
-c 102400 --batch-size 1024 --ubatch-size 512 \
--flash-attn on --cont-batching \
--spec-type draft-mtp --spec-draft-n-max 2 --spec-draft-p-min 0.7 \
--cache-type-k q4_0 --cache-type-v q4_0 \
--cache-ram 8192 \
--parallel 1 --temp 0.7 --top-p 0.8 --top-k 20 --presence-penalty 1.0

应用
KnowFlow v2.1.8（RAGFlow slim）
服务器
7.6GB RAM · 无 Swap · 公网
日期
2026-08-26
状态
已解决 · 登录恢复
00
摘要
故障表象是「登录页能正常打开，提交任何凭证都提示网络异常」。实际排查下来，这不是单点故障，而是三个先后叠加、彼此独立的问题：

其一，宿主机内存只有官方要求的一半，Elasticsearch 按默认配置拿到约 4GB 堆，17 小时内被内核 OOM Killer 处决 31 次。其二，早期排障时在 extra_hosts 里写死了 es01 的容器 IP，容器重建后该 IP 变更，ragflow-server 的所有 ES 请求都打进了黑洞地址，127 秒超时后进程退出——且以退出码 0 退出，restart: on-failure 策略判定其为正常退出、不再拉起，服务就此躺平。其三，前两个问题修复、链路全通之后登录仍然失败：knowflow-backend 的 RBAC 初始化有一个 60 秒的等表窗口，而 ragflow-server 首次冷启动建表需要约 75 秒，管理员账号的创建在窗口关闭 13 秒后才轮到执行，从未发生，登录报「邮箱未注册」。

三处全部处理之后，登录恢复正常。

3
叠加根因
网络 / 内存 / 竞态
31
ES 17 小时内
被 OOM 重启次数
13秒
RBAC 等待窗口与
建表完成的时间差
0.01s
修复后 ES 健康检查耗时
（修复前 127 秒超时）
01
环境信息
项目 内容
管理面板 1Panel
应用版本 KnowFlow v2.1.8（镜像 zxwei/knowflow:v2.1.8，内含 RAGFlow v2.1.2-189-gdd54c95f slim）
部署路径 /home/1panel/KnowFlow/docker（docker compose 管理）
文档引擎 Elasticsearch 8.11.3（容器 ragflow-es-01，服务名 es01）
其他容器 MySQL 8.0.39 · Valkey 8 · MinIO · Gotenberg 8 · knowflow-backend · ragflow-server
容器网络 docker_ragflow（bridge）
端口映射
宿主机端口 容器端口 用途
8088（原 80） ragflow-server:80 Web 入口（nginx，登录页在此）
8443（原 443） ragflow-server:443 HTTPS
1200 es01:9200 Elasticsearch API（外部访问）
5455 mysql:3306 MySQL
5000 knowflow-backend:5000 RBAC 后端（登录接口）
3000 / 6379 / 9000-9001 gotenberg / redis / minio 文档转换 / 缓存 / 对象存储
硬件与官方要求对照
项目 本机实际 官方要求[1]
内存 7.6GB，无 Swap ≥ 16GB
磁盘 / CPU 未核查 磁盘 ≥ 50GB，CPU ≥ 4 核
伏笔内存一项差了一半，是后面所有问题的物质基础。官方 README 对硬件要求有明确说明[1]，部署前应当先对齐。

02
故障现象
浏览器能正常打开 http://IP:8088/login——说明 nginx 与前端静态资源本身正常。
提交任意账号密码，页面统一提示「网络异常，您的网络发生异常，无法连接服务器」。
1Panel 界面显示各服务「启动中」，看起来一切都在跑。
事实：docker compose ps 只列出 6 个容器，ragflow-server 不在其中；加 -a 后显示 Exited (0)。
前端这个「网络异常」提示对应的场景是请求超时或代理层无响应，与凭证对错无关——密码错误会返回明确的文案。而「容器在跑」的错觉来自两点：compose 默认不显示已退出容器，以及 RAGFlow 官方 FAQ 强调的——容器状态 Up 不等于服务健康[5]。

03
故障因果链总览
图 1三个根因如何层层传导为「登录失败」
根因三 · RBAC 初始化竞态

根因二 · extra_hosts 硬编码 IP 失效

根因一 · Elasticsearch 反复 OOM

宿主机内存 7.6GB，无 Swap
低于官方要求的 16GB

.env 默认 MEM_LIMIT = 8GB
ES 堆自动取一半 ≈ 4GB

ES 被 OOM Killer 反复处决
17 小时内重启 31 次

早期排障在 extra_hosts
写死 es01:172.19.0.4

容器重建后 es01 实际 IP
变为 172.20.0.6

ragflow-server 的 ES 请求
全部打入黑洞，127 秒超时

knowflow-backend 等待建表
上限 30 次 × 2 秒 = 60 秒

ragflow-server 加载 deepdoc 模型
约 75 秒后才建好三张表

RBAC 初始化放弃执行
user 表始终为空

ragflow-server 报
ES unhealthy in 120s 后退出

退出码为 0，restart: on-failure
判定正常退出，不再拉起

ragflow-server 长期 Exited
8088 端口无人应答

登录页提示「网络异常」

链路修复后登录
报 109 邮箱未注册

三个根因相互独立：只修任何一个，登录都不会成功。这也是本次排障反复「修完还是不行」的原因。

04
根因分析
4.1 根因一：extra_hosts 硬编码 IP，随容器重建失效
来龙去脉。初次部署时 ragflow-server 反复退出，日志报 Failed to resolve 'es01'。当时为快速恢复，在 ragflow 服务的 extra_hosts 中写入了 es01 当时的容器 IP（172.19.0.4），服务一度恢复。随后一次 docker compose down && docker compose rm -f && docker compose up -d 重建了全部容器——bridge 网络的 IP 由 Docker 按启动顺序分配，重建后 es01 拿到的是 172.20.0.6，而旧映射没有清除。

证据。两条 inspect 输出直接对比：

ragflow-server 容器实际生效的 extra_hosts

["es01:172.19.0.4","host.docker.internal:host-gateway"]

es01 容器当前 IP

es01 当前IP: docker_ragflow = 172.20.0.6
识别特征。黑洞 IP 的行为是「包发出去，永远等不到回应」——超时发生在 127 秒量级，而不是「连接拒绝」。ragflow-server 日志里整齐划一的 GET http://es01:9200/ [status:N/A duration:127.2s] 就是这个特征。

最容易误判的一处当时用临时容器 curl http://es01:9200 返回 401，得出「网络是通的、只缺认证」的结论——这个结论对临时容器成立，对 ragflow-server 不成立：临时容器没有 extra_hosts 覆盖，走的是 Docker 内置 DNS；ragflow-server 的解析被 hosts 劫持了。用「别的容器能通」验证「这个容器能通」，在存在 hosts 覆盖时不成立。
正解。同一 compose 网络内，服务名本来就能直接解析，extra_hosts 只在跨网络访问宿主机等场景需要。修复方式是删除这一行，而不是把 IP 更新成新值——下次重建它还会变。

4.2 根因二：内存超限，ES 反复被 OOM 处决
证据链。

宿主机内存

Mem: total 7.6G used 6.9G free 128M available 57M
Swap: 0B 0B 0B

ES 容器重启计数（容器创建约 17 小时）

RestartCount=31

内核 OOM 记录（两次选中 RSS 最大的 java 进程，即 ES）

Killed process 5246 (java) ... anon-rss:4426688kB ≈ 4.2GB
Killed process 19456 (java) ... anon-rss:4096060kB ≈ 3.9GB
机理。官方 .env 默认 MEM_LIMIT=8073741824（8GB），注释写明需按宿主机内存调整[3]；compose 将它作为 es01 的 mem_limit[4]。ES 8 在未显式设置 ES_JAVA_OPTS 时，堆自动取容器内存限制的一半，即约 4GB。7.6GB 的机器上，MySQL、MinIO、Redis、knowflow-backend、ragflow-server 各占一块之后，剩余内存兜不住 4GB 堆加 JVM 非堆开销，内核 OOM Killer 每次都选中 RSS 最大的 java 进程——这正是 dmesg 里两处 Killed process (java) 的来历。

处理。MEM_LIMIT 降为 2147483648（2GB，堆约 1GB）。代价是文档量大、并发高的场景下 ES 会吃紧；长期方案仍是把内存补到 16GB 以上，或显式设置更小的堆并接受性能折损。

4.3 放大因素：Exited(0) × restart: on-failure
ragflow-server 因 ES 不健康抛出异常，但入口脚本最终以退出码 0 结束。compose 里的重启策略是 restart: on-failure[2]——只重启「失败」（非零退出码）的容器。退出码 0 被判定为正常退出，哪怕 ES 后来恢复 healthy，ragflow-server 也不会自己起来。所以现场呈现的是：6 个依赖容器 Up、主角 Exited、登录页报网络异常，且没有任何自动恢复的迹象。

排查上的两个对应教训：docker compose ps 不加 -a 看不到退出的容器；看到 Exited (0) 不要想当然认为「正常退出、没有问题」。

4.4 根因三：RBAC 初始化竞态——60 秒窗口 vs 75 秒建表
现象。前两个根因修复后，ES 健康检查 200、ragflow-server 横幅出现、登录接口返回 200，链路明明全通了——但页面报 109 Email: admin@gmail.com is not registered。换官方默认凭证 admin / 12345678 登录，同样报未注册。

查证。三条证据指向同一个事实——管理员账号从未被创建：

.env 中没有覆盖管理员定义（走 compose 默认值）

$ grep -E 'MANAGEMENT_ADMIN' .env
（无输出）

rag_flow 库的 user 表是空的——「未注册」是真话

$ SELECT email, nickname FROM user;
Empty set

knowflow-backend 日志：等表等了 30 次，放弃

等待以下表创建: user, tenant, user_tenant
等待数据库就绪... (尝试 30/30)
ERROR - RBAC初始化最终失败，已达到最大重试次数
图 2竞态时间线：两个进程的窗口只差 13 秒
knowflow-backend · 等待 user / tenant / user_tenant 建表
09:52:02 → 09:53:04
ragflow-server · CPU 加载 deepdoc 模型并初始化 web 数据
09:52:12 → 09:53:17
09:53:04 RBAC 初始化放弃
09:53:17 三张表建好
13 秒之差
09:52:00
09:52:30
09:53:00
09:53:30
整栈冷启动实测：表建好时，knowflow-backend 已在 13 秒前放弃等待——初始化逻辑不会再来第二次。
机理。knowflow-backend 启动时等待 user / tenant / user_tenant 三张表就绪，重试上限 30 次 × 2 秒 = 60 秒；而 ragflow-server 首次冷启动要在 CPU 上加载 deepdoc 的 det.onnx / rec.onnx 模型并初始化 web 数据，本机耗时约 75 秒。竞态只在整栈同时冷启动时触发——一旦错过窗口，RBAC 初始化不会重试，user 表从此为空。

处理。此时三张表早已存在，单独 docker restart knowflow-backend 即可，初始化立即成功、管理员账号落库。管理员凭证取 compose 中 MANAGEMENTADMIN* 环境变量的默认值（admin / 12345678），本机 .env 未覆盖[2]。

复发风险每次整栈冷启动（服务器重启、compose down/up）都可能再次触发该竞态。若重启后登录报「邮箱未注册」，先执行 docker restart knowflow-backend，不要急着怀疑密码。

05
排查过程复盘
阶段 动作 发现 / 结果
初次部署 docker compose up -d ragflow-server 反复退出，日志报 Failed to resolve 'es01'
初排 ① extra_hosts 写入 es01:172.19.0.4 服务一度恢复——同时埋下根因二（IP 随重建失效）
初排 ② docker compose config 发现 extra_hosts 重复定义导致 YAML 解析错误，删除重复项
初排 ③ down && rm -f && up -d 容器全部启动，但登录仍报网络异常（此时旧 IP 已失效、ES 仍在被 OOM）
本次 ① docker compose ps 6 个容器在跑，ragflow-server 缺席
本次 ② docker compose ps -a ragflow-server Exited (0)
本次 ③ docker logs ragflow-server ES 检查全部 status:N/A duration:127s → unhealthy in 120s → 退出
本次 ④ inspect es01 / free -h / dmesg RestartCount=31；内存 7.6G 可用 57M；OOM 处决 java 两次
本次 ⑤ inspect 对比 extra_hosts 与 es01 IP 172.19.0.4 ≠ 172.20.0.6，坐实黑洞映射
修复 ① 删除 extra_hosts 中 es01 硬编码行 仅剩 host.docker.internal:host-gateway
修复 ② MEM_LIMIT 改为 2147483648 es01 重建，Memory=2147483648，RestartCount 归零
修复 ③ docker compose up -d 7 个容器全部启动，ES healthy，ragflow-server 横幅出现，POST /v1/user/login 200 ×3
新现象 页面登录 改报 109 邮箱未注册——链路问题已清，转入账号问题
查证 grep .env / 查 user 表 / backend 日志 user 表为空；RBAC 30 次等待失败，确认初始化从未执行
修复 ④ docker restart knowflow-backend 管理员账号创建，登录成功
06
修复措施
所有改动前先备份：docker-compose.yml.bak.0826、.env.bak.0826（与原文件同目录）。

1
删除 extra_hosts 中硬编码的 es01 映射
cd /home/1panel/KnowFlow/docker
cp docker-compose.yml docker-compose.yml.bak.$(date +%m%d)
sed -i '/es01:172.19.0.4/d' docker-compose.yml
grep -n -A3 'extra_hosts' docker-compose.yml
验证点：ragflow 服务下 extra_hosts 仅剩 host.docker.internal:host-gateway。同网络内服务名交给 Docker DNS 解析。

2
ES 内存限制降为 2GB
cp .env .env.bak.$(date +%m%d)
sed -i 's/^MEM_LIMIT=.*/MEM_LIMIT=2147483648/' .env
grep -n 'MEM_LIMIT' .env
验证点：输出 MEM_LIMIT=2147483648。ES 堆随之降为约 1GB，退出被反复 OOM 的循环。

3
重建容器
docker compose up -d

验证两项改动均已生效

docker inspect ragflow-server --format '{{json .HostConfig.ExtraHosts}}'
docker inspect ragflow-es-01 --format 'Memory={{.HostConfig.Memory}}'
预期：ExtraHosts 只剩 host-gateway；Memory=2147483648。随后 docker logs -f ragflow-server，等到 ASCII 横幅再试登录——官方文档明确说明横幅出现前登录会报网络异常[1]。

4
补做 RBAC 初始化（针对竞态）
docker restart knowflow-backend
docker logs knowflow-backend --tail 40
适用条件：链路已通但登录报「邮箱未注册」。表已存在时重启即完成管理员创建。整栈冷启动后若复发，重复本步即可。

07
修复验证
指标 修复前 修复后
ES 健康检查 status:N/A，duration 127 秒超时 status:200，duration 0.01 秒
ES 稳定性 17 小时重启 31 次（OOM） RestartCount 0（限内存 2GB 后）
ragflow-server Exited (0)，无自动拉起 Up，横幅 + HTTP server start (0.0.0.0)
登录接口 前端拿不到响应（网络异常） POST /v1/user/login → 200
登录结果 — 成功进入系统
08
常用命令速查
目的 命令 备注
查看所有容器（含已退出） docker compose ps -a 不加 -a 看不到 Exited 的容器
跟踪 ragflow 启动 docker logs -f ragflow-server 看到 ASCII 横幅才算就绪[1]
看 backend 日志 docker compose logs knowflow-backend --tail 50 RBAC 初始化结果在这里
查容器当前 IP docker inspect ragflow-es-01 --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} = {{$v.IPAddress}}{{end}}' 重建后会变化
查容器生效的 extra_hosts docker inspect ragflow-server --format '{{json .HostConfig.ExtraHosts}}' 排查 hosts 劫持
查重启次数 / 内存限制 docker inspect ragflow-es-01 --format 'RestartCount={{.RestartCount}}' RestartCount 持续增长 = 异常
容器内测 ES docker exec ragflow-server curl -s -u elastic:<密码> http://es01:9200 401 也说明网络通、只缺认证
查用户表 docker exec ragflow-mysql mysql -uroot -p<密码> -e "USE rag_flow; SELECT email FROM `user`;" 空表 = 管理员未创建
验证 compose 配置 docker compose config YAML 语法与变量检查
查 OOM 记录 dmesg | grep -i "killed process" 配合 free -h 使用
整栈重启 docker compose down && docker compose up -d 冷启动后留意第 4 步竞态
09
经验与注意事项
不要把容器 IP 写进 extra_hosts。bridge 网络的 IP 由 Docker 分配，容器重建即变。同网络内服务名解析是 Docker DNS 的本职；确需跨网络访问时，建共享 external network，而不是维护 IP 清单。
官方硬件要求要当真。7.6GB 跑一个要求 16GB 的栈，ES 默认 8GB 的 MEM_LIMIT 就是定时炸弹。部署前先对齐 .env 中 MEM_LIMIT 与实际内存[3]。
docker compose ps 默认不显示退出容器，排查第一步先加 -a；同时记住 Exited (0) 不等于「正常」——on-failure 策略不会拉起退出码为 0 的容器[2]。
「临时容器能通」不能证明「目标容器能通」。hosts 覆盖只作用于被注入的容器，验证连通性要在目标容器内部执行。
复合故障按证据链逐层剥。本次网络、内存、竞态三个问题独立存在，修任何一个都不够；每修一项就验证一项，不要多变量混着改。
整栈冷启动后登录报「未注册」，先 docker restart knowflow-backend（60 秒等表窗口小于首次建表耗时），排除初始化竞态后再怀疑密码。
判断服务真就绪看日志横幅，不是容器状态 Up——官方文档对登录时机有同样的说明[1][5]。
安全提醒（公网部署必读） 本机为公网 IP 直连部署。默认管理员凭证为 compose 默认值 admin / 12345678[2]，必须立即通过页面或 .env 修改；3306、6379、9200、5000、9000 等容器端口已映射到公网网卡，建议用防火墙 / 安全组收敛到仅 8088 / 8443 可达，其余端口限制来源 IP 或改为仅监听内网。
文档地址

优化命令：
yblgt@yblgt-ThinkP710:~/llama.cpp$ ./build/bin/llama-server -m /data/models/unsloth-qwen3.8-27b/Qwen3.8-27B-Q4_K_M.gguf --port 8000 --host 0.0.0.0 -t 12 --threads-batch 12 --n-gpu-layers 99 -c 102400 --batch-size 1024 --ubatch-size 512 --flash-attn on --cont-batching --spec-typ
e draft-mtp --spec-draft-n-max 2 --spec-draft-p-min 0.7 --cache-type-k q4_0 --cache-type-v q4_0 --parallel 1 --temp 0.7 --mlock --no-warmup --prio 3 --cache-ram 0 --top-p 0.8 --top-k 20 --presence-penalty 1.0

方案二Thinking模式：
yblgt@yblgt-ThinkP710:~/llama.cpp$ ./build/bin/llama-server -m /data/models/unsloth-qwen3.8-27b/Qwen3.8-27B-Q4_K_M.gguf --port 8000 --host 0.0.0.0 -t 12 --threads-batch 12 --n-gpu-layers 99 -c 102400 --batch-size 1024 --ubatch-size 512 --flash-attn on --cont-batching --spec-typ
e draft-mtp --spec-draft-n-max 2 --spec-draft-p-min 0.7 --cache-type-k q4_0 --cache-type-v q4_0 --parallel 1 --temp 1.0 --mlock --no-warmup --prio 3 --cache-ram 0 --top-p 0.95 --top-k 20 --presence-penalty 0.0

这是官方推荐的安装方式。uv 是一个快速的 Python 环境管理器，能自动处理 PyTorch 与 CUDA 版本的匹配问题 。

1. 安装系统依赖和 uv 工具
   bash

更新系统并安装编译工具和 Python 开发头文件

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential python3.12 python3.12-venv python3.12-dev git-lfs

安装 uv 工具

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env

注意：python3.12-dev 包提供了编译必需的 Python.h 头文件，缺少它可能导致安装失败 。

2. 创建并进入项目目录
   bash

mkdir -p ~/projects/vllm && cd ~/projects/vllm

3. 创建并激活 Python 虚拟环境
   bash

uv venv myenv --python 3.12 --seed
source myenv/bin/activate

4. 安装 vLLM

在虚拟环境中，使用 uv 安装 vLLM，它会自动检测当前 CUDA 驱动并选择合适的 PyTorch 后端 。
bash

uv pip install vllm --torch-backend=auto

5. 验证安装
   bash

python3 -c "import vllm; print(vllm.version)"

如果成功打印出版本号，说明安装成功

启动服务与运行模型

完成安装后，你可以通过以下两种方式之一启动 vLLM 服务。
离线推理方式（Python 脚本）

创建一个 Python 文件，例如 run.py，用于加载模型并执行推理 。
python

from vllm import LLM, SamplingParams

1. 加载模型，替换为你的模型路径或 Hugging Face 名称

llm = LLM(model="deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B", tensor_parallel_size=1)

2. 设置采样参数

sampling_params = SamplingParams(temperature=0.7, top_p=0.9, max_tokens=512)

3. 执行推理

outputs = llm.generate(["解释量子计算的基本原理"], sampling_params)

4. 打印结果

for output in outputs:
print(output.outputs[0].text)

然后在终端执行：python3 run.py
OpenAI 兼容服务器方式

这是最常用的方式，可以启动一个 HTTP 服务供其他程序调用 。

创建一个启动脚本 start_server.sh：
bash

!/bin/bash

source ~/projects/vllm/myenv/bin/activate
vllm serve <你的模型名称或路径> \
--host 0.0.0.0 \
--port 8000 \
--dtype auto \
--gpu-memory-utilization 0.85 \
--max-model-len 32768 \
--trust-remote-code

赋予执行权限并运行：
bash

chmod +x start_server.sh
./start_server.sh

调整参数：
docker run -d \
--runtime=nvidia --gpus=all \
-v /path/to/your/model:/model \
-p 8000:8000 \
vllm/vllm-openai:v0.8.5 \ # 注意，此处指定了特定版本
--model /model \
--tensor-parallel-size 1 \ # 单卡设为1；如果你有2张就设为2
--quantization awq \ # 根据你下载的模型量化类型调整
--dtype auto \
--max-model-len 16384 \ # 可适当降低以防显存溢出
--gpu-memory-utilization 0.9 \
--swap-space 32 # 设置swap空间，防止KV Cache溢出

最稳妥的方式是使用 Ubuntu 的官方源来安装驱动，它能自动处理依赖关系，避免冲突。

更新系统并安装驱动工具
bash

sudo apt update
sudo apt upgrade -y
sudo apt install -y ubuntu-drivers-common build-essential

自动安装推荐驱动（最简单）
这条命令会自动检测你的显卡并安装最合适的驱动版本。
bash

sudo ubuntu-drivers autoinstall

安装完成后，务必重启系统：
bash

sudo reboot

验证驱动安装
重启后，运行 nvidia-smi，你应该能看到 GPU 信息、驱动版本和最高支持的 CUDA 版本。例如，输出可能会显示 CUDA Version: 12.4。

安装 CUDA 工具包
为了让 llama.cpp 在编译时能用到 CUDA，需要安装开发工具包。通过 NVIDIA 官方网络源安装是最简单的方式。
bash

# 下载并安装 CUDA 密钥环
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb

# 更新源并安装 CUDA 工具包
sudo apt update
sudo apt install -y cuda-toolkit

配置环境变量
将 CUDA 添加到 PATH，方便后续使用。
bash

echo 'export PATH=/usr/local/cuda/bin${PATH:+:${PATH}}' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc
source ~/.bashrc

最后，运行 nvcc --version 验证 CUDA 编译器是否安装成功。

2. 安装与编译 llama.cpp

llama.cpp 支持从源码编译，这样能确保你的机器获得最优性能。

安装编译依赖
bash

sudo apt install -y cmake git

克隆源码
bash

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

创建构建目录并编译
使用 CMake 进行编译。关键在于通过 -DGGML_CUDA=ON 开启 CUDA 支持。-j 参数可以加快编译速度。
bash

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DGGML_CUDA=ON
cmake --build . --config Release -j $(nproc)

编译完成后，可执行文件（如 llama-server, llama-cli）就在 build/bin/ 目录下

3 个模型 hf 下载命令（直接复制运行）
全部自动存到 /data/models 里

1. Qwen3.5-27B 4-bit
   hf download Qwen/Qwen3.5-27B-Instruct-GGUF qwen3.5-27b-instruct-q4_0.gguf --local-dir /data/models

hf download hf-mirror.com/HauhauCS/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf
正在下载
hf download HauhauCS/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive --local-dir ./Qwen3.6-35B-A3B-Uncensored Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-IQ4_XS.gguf

hf download unsloth/Qwen3.6-35B-A3B-MTP-GGUF \
--local-dir ./Qwen3.6-35B-A3B-MTP \
--include "IQ4_XS.gguf"

hf download bartowski/DeepSeek-R1-Distill-Qwen-32B-GGUF \
--local-dir ./DeepSeek-R1-Distill \
--include "IQ4_XS.gguf"

hf download google/gemma-4-31B-it-qat-q4_0-gguf \
--local-dir ./gemma-4-31b \
--include "*.gguf"

hf download Jackrong/Qwopus3.6-27B-Coder-GGUF \
--include "Q4_K_M.gguf" \
--local-dir ./qwopus-27b-coder

hf download Jackrong/Qwopus3.6-35B-A3B-V1-GGUF \
--include "IQ4_XS.gguf" "mmp.gguf" \
--local-dir ./qwopus-35b-v1

hf download Mia-AiLab/Qwable-3.6-27b \
--include "*.gguf" \
--local-dir ./qwable-27b

hf download unsloth/Qwen3.6-27B-MTP-GGUF \
--include "IQ4_XS.gguf" \
--local-dir ./unsloth-qwen27b

hf download unsloth/Llama-3.3-70B-Instruct-GGUF \

--include "IQ4_XS.gguf" \
--local-dir ./llama70b

hf download Jackrong/Qwopus3.6-35B-A3B-v1-MTP-GGUF \
--include "IQ4_XS.gguf" \
--local-dir ./qwopus-35b-v1-mtp

hf download Anbeeld/Qwen3.6-27B-DFlash-GGUF \
--include "Q4_K_M.gguf" \
--local-dir ./unsloth-qwen27b

hf download unsloth/Qwen3.6-27B-GGUF \
--include "mm.gguf" \
--local-dir ./unsloth-qwen27b

hf download Anbeeld/Qwen3.6-35B-A3B-DFlash-GGUF \
--include "IQ4_XS.gguf" \
--local-dir ./unsloth-qwen3.6-35b-a3b

hf download unsloth/Qwen3.6-35B-A3B-GGUF \
--include "UD-IQ4_XS.gguf" \
--include "mm.gguf" \
--local-dir ./unsloth-qwen3.6-35b-a3b

hf download unsloth/Qwen3-VL-30B-A3B-Instruct-GGUF \
--include "Q4_K_M.gguf" "mmp.gguf" \
--local-dir ./nsloth-qwen3-vl-30b

hf download Brian6145/Qwen3.6-27B-Claude-Opus-Sonnet-DistilledV2-MTP-GGUF \
--include "Q4_K_M.gguf" "mmp.gguf" \
--local-dir ./brian6145-27b

hf download Anbeeld/Qwen3.6-27B-DFlash-GGUF \
--include "Q5_K_M.gguf" "mmp.gguf" \
--local-dir ./anbeeld-dflash-27b

hf download incoai/Qwen3.8-27B-DFlash2-GGUF \

--include "Q4_K_M.gguf" \
--local-dir /data/models/Qwen3.8-27B-DFlash2

./build/bin/llama-server \
-m /data/models/unsloth-qwen3-vl-30b/Qwen3-VL-30B-A3B-Instruct-Q4_K_M.gguf \
--mmproj /data/models/unsloth-qwen3-vl-30b/mmproj-F16.gguf \
--port 8000 --host 0.0.0.0 \
-t 6 \
--threads-batch 6 \
--n-gpu-layers 60 \
-c 24576 \
--batch-size 512 \
--ubatch-size 256 \
--flash-attn on \
--cont-batching \
--cache-type-k q4_0 \
--cache-type-v q4_0 \
--parallel 1 \
--temp 0.7 \
--top-p 0.8 \
--top-k 20 \
--presence-penalty 1.5 \
--jinja \
--mlock \
--no-warmup \
--prio 3 \
--image-min-tokens 1024

sudo apt update
sudo apt install build-essential cmake git

确保已安装 CUDA Toolkit

克隆仓库并编译：

git clone https://github.com/Anbeeld/beellama.cpp.git
cd beellama.cpp

针对 RTX 2080 Ti (Turing 架构, compute capability 7.5) 进行编译

cmake -B build -DGGML_CUDA=ON -DGGML_NATIVE=ON \
-DGGML_CUDA_FA=ON -DGGML_CUDA_FA_ALL_QUANTS=ON \
-DCMAKE_CUDA_ARCHITECTURES=75 \
-DCMAKE_BUILD_TYPE=Release

cmake --build build -j
注意: DCMAKE_CUDA_ARCHITECTURES=75 是为 RTX 2080 Ti 设置的。如果你不确定，可以省略此选项，CMake 会自动检测。

4. 模型准备
   你需要下载三个文件（以 Qwen 3.6 27B 为例）：
   主模型 (Target Model):
   高精度版: Qwen3.6-27B-Q5_K_S.gguf (来自 unsloth/Qwen3.6-27B-GGUF)
   高速/低显存版: Qwen3.6-27B-Q4_K_M.gguf 或 Qwen3.6-27B-IQ4_XS.gguf (来自 cHunter789/Qwen3.6-27B-i1-IQ4_XS-GGUF)
   DFlash 草稿模型 (Draft Model):
   从 Anbeeld/Qwen3.6-27B-DFlash-GGUF 下载，例如 Qwen3.6-27B-DFlash-Q4_K_M.gguf。
   多模态投影器 (可选, mmproj):
   如果需要视觉功能，从 unsloth/Qwen3.6-27B-GGUF 下载 mmproj-BF16.gguf。
   将这些文件放在一个易于访问的目录中，例如 ~/models/。
5. 启动服务器（针对 22GB 显存优化）
   考虑到你的 RTX 2080 Ti 有 22GB 显存（略少于官方推荐的 24GB），我们采用高速/低显存组合，并进行适当调整以确保稳定运行。
   5.1 基础启动命令（无视觉）

./build/bin/llama-server \
-m "~/models/Qwen3.6-27B-Q4_K_M.gguf" \
--spec-draft-model "~/models/Qwen3.6-27B-DFlash-Q4_K_M.gguf" \
--spec-type dflash \
--spec-dflash-cross-ctx 512 \
--port 8080 \
-np 1 \
--kv-unified \
-ngl all \
--spec-draft-ngl all \
-b 2048 -ub 512 \
--ctx-size 65536 \ # 将上下文减少到 64K 以适应 22G 显存
--cache-type-k turbo3_tcq \
--cache-type-v turbo3_tcq \ # 使用 TCQ 压缩进一步节省显存
--flash-attn on \
--no-mmap --mlock \
--temp 0.6 --top-k 20 --top-p 1.0 --min-p 0.0
5.2 启动命令（带视觉）
bash

./build/bin/llama-server \
-m "~/models/Qwen3.6-27B-Q4_K_M.gguf" \
--mmproj "~/models/mmproj-BF16.gguf" \
--no-mmproj-offload \ # 将 mmproj 卸载到 CPU 以节省 GPU 显存
--spec-draft-model "~/models/Qwen3.6-27B-DFlash-Q4_K_M.gguf" \
--spec-type dflash \
--spec-dflash-cross-ctx 512 \
--port 8080 \
-np 1 \
--kv-unified \
-ngl all \
--spec-draft-ngl all \
-b 2048 -ub 512 \
--ctx-size 65536 \
--cache-type-k turbo3_tcq \
--cache-type-v turbo3_tcq \
--flash-attn on \
--no-mmap --mlock \
--temp 0.6 --top-k 20 --top-p 1.0 --min-p 0.0

5.3 关键参数解释
-m: 主模型路径。
--spec-*: DFlash 相关配置，启用推测解码。
--ctx-size 65536: 重要！将上下文长度从默认的 100K+ 降低到 64K，这是为了适配 22GB 显存。
--cache-type-k/v turbo3_tcq: 重要！使用 TCQ 压缩技术大幅减小 KV 缓存占用。turbo3_tcq 在显存和精度之间取得了较好的平衡。
--spec-dflash-cross-ctx 512: 减少草稿模型能看到的上下文，进一步节省显存。
--no-mmproj-offload: 对于独立显卡，将视觉模块卸载到 CPU 可以释放宝贵的 GPU 显存。
-ngl all: 将所有模型层加载到 GPU 上。

6. 故障排除
   显存不足 (Out of VRAM):
   进一步降低 --ctx-size (例如 32768)。
   尝试使用 turbo2_tcq 作为缓存类型（但会损失更多精度）。
   将主模型换成 IQ4_XS 版本。
   DFlash 未生效:
   检查日志中是否有 dflash: 或 speculative 相关信息。
   确认草稿模型是专门为 DFlash 准备的，而不是普通的 Qwen 模型。
   TCQ 缓存类型报错:
   确保你使用的是 CUDA 后端编译的版本。TCQ (turbo*_tcq) 仅支持 CUDA。
   通过以上配置，你应该能够在你的 RTX 2080 Ti 22GB + Ubuntu 系统上成功运行 BeeLlama.cpp，并利用 DFlash 和 TCQ 技术获得高效的推理体验。

首先，进入 llama.cpp 项目目录，拉取最新的代码。然后，根据官方推荐，清理旧版的 Web UI 构建文件，并确保 Node.js 环境是最新的，这是为了构建内置 Web UI 所必需的。

cd ~/llama.cpp
git pull origin master # 拉取最新代码

清理旧 Web UI 构建文件

rm -rf tools/ui/dist

清理旧编译文件，保证全新编译

rm -rf build

安装或更新 Node.js 和 npm (用于构建 UI 资源)

这里使用了 NodeSource 的脚本安装 Node.js 20.x 版本

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

重新编译

mkdir build && cd build
cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DGGML_CUDA=ON \
-DLLAMA_CURL=ON \
-DLLAMA_SERVER=ON
make -j$(nproc)

参数：
-DGGML_CUDA=ON 启用 NVIDIA CUDA GPU 加速
-DGGML_CUDA_F16=ON 启用 FP16 计算（可选，提升性能）
-DLLAMA_CURL=ON 启用 HTTP/HTTPS 网络支持（Web UI 需要）
-DLLAMA_SERVER=ON 编译 llama-server（Web UI 服务）
-DLLAMA_AVX2=ON 启用 AVX2 指令集优化（Intel CPU）

另一个：
cd ~/llama.cpp
git pull origin master # 拉取最新代码

清理旧 Web UI 构建文件

rm -rf tools/ui/dist

清理旧编译文件，保证全新编译

rm -rf build

安装或更新 Node.js 和 npm (用于构建 UI 资源)

这里使用了 NodeSource 的脚本安装 Node.js 20.x 版本

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

mkdir build && cd build

配置 CMake。你原来的 CUDA、CURL 等选项都保留着

cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DGGML_CUDA=ON \
-DLLAMA_CURL=ON \
-DLLAMA_SERVER=ON # 这个选项会构建内置 Web UI

开始编译，使用所有 CPU 核心加速

make -j$(nproc)

速度快专用：(占用20388M,写文章速度80T/S)
./build/bin/llama-server -m /data/models/other/qwopus3.6-35b-a3b-v1/Qwopus3.6-35B-A3B-v1-IQ4_XS.gguf --mmproj /data/models/other/qwopus3.6-35b-a3b-v1/mmproj-F32.gguf --port 8000 --host 0.0.0.0 -t 12 --threads-batch 12 --n-gpu-layers 999 -c 102400 --batch-size 1024 --ubatch-size 512 --flash-attn on --cont-batching --cache-type-k q4_0 --cache-type-v q4_0 --parallel 1 --temp 0.6 --mlock --no-warmup --prio 3 --cache-ram 0 --image-min-tokens 1024

写代码专用：（不带图,占用20007M,写文章速度40T/S）
./build/bin/llama-server -m /data/models/other/qwen3.6-27b-mtp/Qwen3.6-27B-MTP-Q4_K_M.gguf --port 8000 --host 0.0.0.0 -t 12 --threads-batch 12 --n-gpu-layers 999 -c 102400 --batch-size 1024 --ubatch-size 512 --flash-attn on --cont-batching --spec-type draft-mtp --spec-draft-n-max 2 --spec-draft-p-min 0.5 --cache-type-k q8_0 --cache-type-v q8_0 --parallel 1 --temp 0.2 --top-p 0.9 --mlock --no-warmup --prio 3 --cache-ram 0

12B:

下载主模型（推荐 Q4_K_M 版本，性能与体积平衡）

hf download bartowski/gemma-4-12B-it-GGUF --local-dir ./gemma-4-12b --include "gemma-4-12B-it-Q4_K_M.gguf"

下载视觉编码器（必须，让模型能看图）

hf download unsloth/gemma-4-12b-it-GGUF --local-dir ./gemma-4-12b --include "mmproj-F16.gguf"

你的固定基础配置

BASE="/home/yblgt/llama.cpp/build/bin/llama-bench \
--model /data/models/qwen3.6-27b-mtp/Qwen3.6-27B-MTP-Q4_K_M.gguf \
-t 6 \
-ngl 81 \
--flash-attn 1 \
-n 256 -p 512 \
-r 3"

测试不同的 batch-size 和 ubatch-size 组合

for batch in 512 1024 1536 1920 2048 4096; do
for ubatch in 256 512 768 1024); do
echo "=== Testing batch=$batch ubatch=$ubatch ==="
$BASE --batch-size $batch --ubatch-size $ubatch
done
done

加入线程
bash

!/bin/bash

基础配置（不再包含 -t）

BASE="/home/yblgt/llama.cpp/build/bin/llama-bench \
--model /data/models/qwen3.6-27b-mtp/Qwen3.6-27B-MTP-Q4_K_M.gguf \
-ngl 81 \
--flash-attn 1 \
-n 256 -p 512 \
-r 3"

测试不同的线程数、batch-size 和 ubatch-size 组合

for t in 6 12; do
for batch in 512 1024 1536 1920 2048 4096; do
for ubatch in 256 512 768 1024); do
echo "=== Testing threads=$t batch=$batch ubatch=$ubatch ==="
$BASE -t $t --batch-size $batch --ubatch-size $ubatch
done
done
done