ghcr.io/luce-org/lucebox-hub:sha-1b11c50-rocm Docker 镜像 |...

ghcr.iolinux/amd64sha-1b11c50-rocm大小: 6.27 GB更新于 2026年7月12日

让 AI 帮你使用轩辕镜像？ · 展开查看说明 · 点击收起说明

如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。

只需在 AI 对话中先发送下面这句话即可：

请先完整阅读并严格遵守以下文档中的全部规则与要求：

https://xuanyuan.cloud/agents.md

在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。

查看 agents.md 用法指南与完整示范。国内用户首推元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。若 AI 无法访问外链，可打开说明文档复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。

为速度而构建的本地LLM推理服务器。具备自定义内核、推测性预填充与解码功能。我们引擎中的每项优化均针对特定模型系列和硬件目标。

推理引擎优化

每项优化均包含独立的设置说明和基准测试备注。

支持的模型与草稿模型

所有加速比均相对于官方llama.cpp测量（-fa 1，匹配KV量化）。综合加速比 = （TTFT × 解码）的几何平均值√（当两个阶段均进行基准测试时）；否则为单阶段加速比。草稿模型发布于 https://huggingface.co/Lucebox%E3%80%82

模型	加速比
Qwen 3.5-0.8B (Megakernel)	~2×
Qwen 3.6-27B + PFlash	~5.6×
Qwen 3.6-27B + DDTree	4.84×
Laguna-XS-2.1 33B + PFlash	8.2× @256K
Laguna-XS-2.1 33B + DFlash	1.7× @256K
Qwen 3.6-27B HIP	~2.6×
Gemma-4-26B-A4B	1.31×

草稿模型	阶段
https://huggingface.co/Lucebox/Qwen3.6-27B-DFlash-GGUF	decode
https://huggingface.co/Lucebox/gemma-4-26B-A4B-it-DFlash-GGUF	decode
https://huggingface.co/Lucebox/gemma-4-31B-it-DFlash-GGUF	decode
https://huggingface.co/Qwen/Qwen3-0.6B	prefill

已测试设备（GPU/APU）

参考目标：RTX 3090（Ampere sm_86）——所有标题数据的基准设备。其他NVIDIA架构由CMake / setup.py自动检测；AMD HIP后端单独说明（Strix Halo部分）。

	架构	GPU	最低CUDA / ROCm版本	状态	基准测试
	Ampere `sm_86`	RTX 3090, A-series	CUDA 12.0	✅ reference	megakernel · dflash
	Blackwell `sm_120`	RTX 5090	CUDA 12.8	✅ 205 tok/s, 4.84×	↗
	Blackwell `sm_121`	DGX Spark / GB10	CUDA 12.9	✅ megakernel NVFP4	↗
	Turing `sm_75`	RTX 2080 Ti	CUDA 12.0	✅ 53 tok/s DFlash	↗
	Ada `sm_89`	RTX 40xx	CUDA 12.0	🟡 community WSL2 bench	↗
—	Blackwell `sm_110`	Jetson AGX Thor	CUDA 13.0	🟡 builds, unbenched	—
	Volta `sm_70` / Pascal `sm_61`	V100, P40	CUDA 12.0	🟡 fallback paths, unbenched	—
	RDNA3.5 `gfx1151`	Ryzen AI MAX+ 395 / Strix Halo	ROCm 6+	✅ 37 tok/s HIP	↗
	RDNA3 `gfx1100`	Radeon RX 7900 XTX	ROCm 6+	✅ 50 tok/s HIP	↗
—	RDNA4 `gfx1201`	Radeon AI PRO R9700	ROCm 6.4+	✅ 55 tok/s HIP	↗

server/（DFlash）使用CMake 3.18+构建，并直接包含所需的ggml源代码；仅Block-Sparse-Attention仍是git子模块。server/不需要PyTorch。optimizations/megakernel/是唯一需要PyTorch 2.0+的组件（CUDAExtension链接到torch C++库）。功耗调优：sudo nvidia-smi -pl 220（3090的最佳设置，其他显卡需重新测试）。

测试工具快速入门

harness/ 包含RTX 3090客户端启动器和Lucebox服务器兼容性的回归测试。可在Claude Code、Codex、OpenCode、Hermes、Pi、OpenClaw或Open WebUI中运行Lucebox，或检查服务器变更是否仍能与这些客户端兼容。

客户端	启动器
Claude Code	`run_claude_code.sh`
Codex	`run_codex.sh`
OpenCode	`run_opencode.sh`
Hermes	`run_hermes.sh`
Pi	`run_pi.sh`
OpenClaw	`run_openclaw.sh`
Open WebUI	`run_openwebui.sh`

所有启动器都会启动原生C++ HTTP服务器（dflash_server）。可通过环境变量覆盖默认设置：

DFLASH_SERVER_BIN=server/build/dflash_server \
DFLASH_TARGET=server/models/Qwen3.6-27B-Q4_K_M.gguf \
DFLASH_DRAFT=server/models/draft/dflash-draft-3.6-q4_k_m.gguf \
MAX_CTX=32768 BUDGET=22 VERIFY_MODE=ddtree \
harness/clients/run_codex.sh

对于无草稿模型的目标（如Gemma），只需设置DFLASH_TARGET或传递DRAFT=none；测试工具不会将默认Qwen草稿模型附加到自定义目标。

启动器脚本会在.harness-work/目录下自动安装缺失的真实客户端CLI。如需手动预安装：

python3 harness/client_test_runner.py install --clients codex,hermes,openwebui

如需针对运行中的服务器获取直接的TPS/TTFT数值：

python3 harness/client_test_runner.py bench \
--url http://127.0.0.1:8000 \
--suite he,agent \
--n-sample 3

Docker快速入门

GHCR上的预构建镜像跟踪main分支。无需CUDA工具包或构建过程。拉取镜像、挂载权重并启动服务。OpenAI兼容API位于:8000端口。

GPU	镜像标签
NVIDIA (CUDA 12+)	`:cuda12`
AMD (ROCm 6+)	`:rocm`

首先将GGUF模型目标放入server/models/，然后访问:8000/v1/chat/completions。完整教程见Docker博客。

安装与运行：

# 1. 拉取对应GPU的镜像
docker pull ghcr.io/luce-org/lucebox-hub:cuda12 # NVIDIA
docker pull ghcr.io/luce-org/lucebox-hub:rocm # AMD

# 2. 下载目标模型到server/models/，并将DFlash草稿模型下载到server/models/draft/
# （入口点仅会自动发现该目录下的草稿模型；若无草稿模型，服务器将仅运行目标模型，速度较慢）
hf download unsloth/Qwen3.6-27B-GGUF Qwen3.6-27B-Q4_K_M.gguf \
--local-dir server/models/
hf download Lucebox/Qwen3.6-27B-DFlash-GGUF dflash-draft-3.6-q4_k_m.gguf \
--local-dir server/models/draft/

# 3a. NVIDIA (CUDA 12+)
docker run --rm --gpus all -p 8000:8080 \
-v "$PWD/server/models:/opt/lucebox-hub/server/models" \
ghcr.io/luce-org/lucebox-hub:cuda12

# 3b. AMD (ROCm 6+，Strix Halo / RX 7900)
docker run --rm --device /dev/kfd --device /dev/dri \
--group-add video --group-add render --security-opt seccomp=unconfined \
-p 8000:8080 -v "$PWD/server/models:/opt/lucebox-hub/server/models" \
ghcr.io/luce-org/lucebox-hub:rocm

然后访问:8000/v1/chat/completions（OpenAI兼容）。

运行服务器

默认配置：RTX 3090上的Qwen 3.6-27B Q4_K_M目标模型 + Lucebox Q4_K_M DFlash草稿模型。DDTree预算=22，TQ3_0 KV缓存，全注意力。OpenAI兼容HTTP服务位于:8000端口。

# 构建（需CUDA 12+，CMake 3.18+）
git clone --recurse-submodules https://github.com/Luce-Org/lucebox-hub && cd lucebox-hub
cmake -B server/build -S server -DCMAKE_BUILD_TYPE=Release
cmake --build server/build --target dflash_server -j

运行（TQ3_0 KV 自动启用；设为=0可禁用）

DFLASH27B_KV_TQ3=1 \
./server/build/dflash_server server/models/Qwen3.6-27B-Q4_K_M.gguf \
--draft server/models/draft/dflash-draft-3.6-q4_k_m.gguf \
--ddtree --ddtree-budget 22 --port 8000

KV缓存有限驻留（KVFlash）

通过固定的GPU槽位池对注意力KV缓存进行分页；冷64 token块驻留在主机内存中，位精确且可召回。解码速度不再依赖于上下文长度，驻留KV在任何上下文下均保持池大小。默认关闭；适用于所有模型系列。基于Drafter评分的驻留是所有系列的默认方式：服务器会在模型旁查找Qwen3-0.6B drafter（或通过--prefill-drafter指定）并延迟加载它作为相关性评分器，以决定哪些块保持驻留——非Qwen目标模型（laguna、gemma4）通过为drafter重新 token 化上下文文本来弥合分词器差异。当没有drafter时，LRU是备选方案，也可通过--kvflash-policy lru显式选择。各模型的具体数据参见 Luce KVFlash →。

标志 / 环境变量	默认值	作用
`--kvflash`	off	驻留池大小。`auto` 会根据GPU自动调整：权重和预留空间后剩余VRAM的一半，按模型的KV密度计算，上限为解码速度接稳最优值的大小（默认，可通过`DFLASH_KVFLASH_MAX_POOL`覆盖），并受`--max-ctx`限制。显式值会四舍五入到256，被`--max-ctx`钳制，并以受保护的最小值为下限，确保驱逐时总有可替换的块。
`--kvflash-policy {drafter,lru,qk}`	`drafter`	驻留策略。`lru` 会禁用drafter的探测/加载（仅基于最近度的分页，无额外VRAM占用）。`qk`（仅Qwen35）通过目标模型自身的池化键与解码查询进行比对来评分驻留，以极低的重评分成本实现与drafter相当的召回率，且无需额外模型驻留。
`--kvflash-tau N`	`64`	重选间隔下限（仅drafter策略）；实际间隔会随历史长度增长，以限制重评分开销。
`DFLASH_KVFLASH=N`	off	`--kvflash`的环境变量等效形式。
`DFLASH_KVFLASH_TAU=N`	`64`	`--kvflash-tau`的环境变量等效形式。

标志 / 环境变量	默认值	作用
`--target-device`	`cuda:0`	目标后端（例如 `cuda:0`、`hip:0`）
`--draft-device`	与目标相同	草稿后端；混合后端需使用 `--draft-ipc-bin`
`--target-gpu N`	`0`	目标 GPU 索引
`--draft-gpu N`	与目标相同	草稿 GPU 索引；将草稿卸载到第二块 GPU
`--target-devices` / `--target-layer-split`	单 GPU	在多个 GPU 间拆分目标层
`--draft-ipc-bin`	—	进程外草稿二进制文件（混合 CUDA/HIP）
`--peer-access`	off	启用目标 GPU 之间的 P2P 访问
`--chunk N`	后端默认值	预填充微批大小
`--no-cors`	CORS 启用	禁用 CORS 头
`DFLASH_TARGET_GPU=N`	`0`	`--target-gpu` 的环境变量等效形式
`DFLASH_DRAFT_GPU=N`	与目标相同	`--draft-gpu` 的环境变量等效形式
`DFLASH_MODEL_NAME=`	`dflash`	`--model-name` 的环境变量等效形式；设置 `/v1/models` ID 并选择匹配的 `share/model_cards/ .json`

MoE 专家卸载（Spark）

针对专家无法放入 VRAM 的 MoE 目标模型（laguna、qwen35/qwen36）。--spark 会自调优热/冷专家拆分、有界 GPU 缓存以及基于实时流量的放置配置文件；通过默认的单图融合路径，解码性能接近全 GPU 上限。详见 Luce Spark →。

标志 / 环境变量	默认值	作用
`--spark`	off	一键自动调优：启用有界专家缓存，根据 VRAM 目标调整大小，自动加载并持续保存放置配置文件（`.gguf.spark.csv`）。
`--spark-vram`	整卡	Spark 可使用的总 VRAM；在此限制下调整热层 + 缓存 + KV 的大小。
`DFLASH_SPARK=1`	off	`--spark` 的环境变量等效形式。
`DFLASH_SPARK_VRAM_MB=N`	—	`--spark-vram` 的环境变量等效形式（单位：MB）。
`DFLASH_ _EXPERT_CACHE=1`	off	有界 GPU 专家缓存（为 `LAGUNA` 或 `QWEN35MOE`）；预热后冷缺失率趋近于 0。
`DFLASH_ _CACHE_SLOTS=N`	auto	每层的缓存槽数。
`DFLASH_LAGUNA_NO_SINGLE_GRAPH=1`	off	回退到逐层解码，而非默认的单图融合混合模式。

DFlash 基准测试 → · DFlash 博客 → · PFlash 基准测试 → · PFlash 博客 → · 每台机器快速启动（DGX Spark、Jetson Thor、HIP）→

运行 Megakernel 基准测试（Qwen 3.5-0.8B）

独立 Python 基准测试；24 层融合为一个持久化 CUDA 调度。 413 tok/s 解码速度、21,347 预填充速度、1.87 tok/J（220W 功耗），对比 llama.cpp BF16。

uv sync --extra megakernel
uv run --directory megakernel python final_bench.py

方法	预填充（pp520）	解码（tg128）	tok/J
Megakernel `@220W`	21,347	413	1.87
llama.cpp BF16 `@350W`	11,247	267	0.76
PyTorch HF	7,578	108	n/a

设置 → · 基准测试 → · 博客 →

Blackwell（RTX 5090、DGX Spark / GB10）： 安装时自动检测；NVFP4 解码路径在 GB10 上可达约 194 tok/s。详见 optimizations/megakernel/README.md#blackwell-sm_120--sm_121a。

教程

各优化项和测试工具设置的视频教程。


Luce KVFlash ▶ ***

项目存在的意义

本地 AI 应该是默认选择，而非特权。私有数据、无按 token 计费、无供应商锁定。能够运行高性能模型的硬件早已进入普通桌面，但从中榨取真实吞吐量的软件却尚未普及。

目前没有任何工具是为本地 AI 推理构建的。大多数机器只是将普通 GPU 连接到桌面 CPU，运行通用运行时，从未针对底层芯片优化内核。在相同的 27B 模型上，DGX Spark 或 Mac Studio 往往浪费了四到六倍的实际吞吐量。过去十年，通用框架之所以胜出，是因为为每款芯片手动调优的成本高于回报：一套框架，在所有硬件上表现平平，在任何硬件上都不卓越。推测解码、推测预填充、融合巨核、校准 MoE 专家卸载等技术能将闲置芯片性能提升 3-10 倍，但这些技术仍被锁定在数据中心 GPU 的 BF16 权重上，消费级显卡只能继承残羹冷炙。

查看基准测试和相关机器信息，请访问 lucebo*。**

贡献请求

▮▮▮▮▮▮▮▮▮▮ HIP/CUDA 内核优化
▮▮▮▮▮▮▮▮▮▯ 推测推理优化
▮▮▮▮▮▮▮▯▯▯ 新增消费级 GPU/APU 支持
▮▮▮▮▮▮▮▯▯▯ 推理引擎调试
▮▮▮▮▮▮▯▯▯▯ 添加新性能基准测试
▮▮▮▮▮▯▯▯▯▯ 测试工具集成改进

引用

@software{lucebox_2026,
title = {面向特定消费级硬件的快速LLM推测性推理服务器。},
author = {Lucebox},
url = {https://github.com/Luce-Org/lucebox-hub},
year = {2026}
}

社区

*****：*.gg/yHfswqZmJQ
网站：lucebo***
问题反馈：https://github.com/Luce-Org/lucebox-hub/issues
博客：lucebo***/blog

Apache 2.0 · Lucebo***

轩辕镜像配置手册

按平台快速找到配置文档

一键安装

一键安装 Docker

Linux Docker 一键安装

AI

用 AI 使用轩辕镜像

agents.md · AI 对话 · 提示词

Docker

登录仓库拉取

登录认证 · 私有仓库

专属域名拉取

免登录 · 高速拉取

Linux

Docker 镜像配置

Windows / Mac

Docker Desktop 配置

MacOS OrbStack

OrbStack 容器

Apple Container

macOS 原生容器

Docker Compose

Compose 项目配置

NAS

群晖

Synology 配置

飞牛

fnOS 镜像配置

绿联

绿联 NAS

威联通

QNAP 配置

极空间

极空间 NAS

Unraid

Unraid NAS

企业仓库

其他仓库

ghcr · Quay · nvcr

Harbor 镜像源

Proxy Repository 对接

Portainer 镜像源

Registries 配置

Nexus 镜像源

Docker Proxy 缓存

开发工具

Dev Containers

VS Code 开发容器

Podman

Podman 配置指南

Singularity / Apptainer

HPC 科学计算容器

Kubernetes

K8s Containerd

Kubernetes · Containerd

K3s

轻量级集群

面板 / 网络

爱快路由

爱快 4.0 · iKuai 镜像加速

宝塔面板

一键配置镜像源

需要其他帮助？请查看我们的常见问题Docker 镜像访问常见问题解答或提交工单

镜像拉取常见问题

功能

版本功能对比

功能对比 · 版本选择

支持的镜像仓库

Docker Hub · GCR · GHCR

专属域名用法

专属域名 · 开启停用 · 多仓库

新手拉取配置

docker search 限制

专属域名 · Hub 搜索

不支持 push

仅支持 pull · 不支持

拉取速度原因

带宽 · 缓存 · 冷热镜像

错误码

402 与流量用尽

402 · 流量包 · 充值

401 认证失败

401 · docker login

manifest unknown

标签错误 · 镜像不存在

410 Gone 排查

410 · Docker 升级

429 限流

免费版 · 专业版 · 企业版 · 请求频率

其他报错

DNS 超时

DNS 解析 · 网络超时

TLS 证书失败

no matching manifest（架构）

账号

失败是否计费

manifest · blob · 计费

申请开发票（企业 / 个人）

企业 · 个人 · 工单

修改登录密码

网站 · 仓库 · 重置

注销账户

工单 · 数据 · 注销

原理

mirrors 不生效

daemon.json · 重启

去掉域名前缀

docker tag · 重命名

指定架构拉取

ARM64 · AMD64 · 多架构

latest 与「最新」

digest · 版本号 · 标签

查看全部问题→

用户好评

来自真实用户的反馈，见证轩辕镜像的优质服务

oldzhang

运维工程师

Linux服务器

"Docker访问体验非常流畅，大镜像也能快速完成下载。"