ghcr.io/luce-org/lucebox-hub:sha-9cca94c-rocm

镜像名称：ghcr.io/luce-org/lucebox-hub 参考标签：latest

面向异构设备与消费级 GPU 的推测推理方案。 内置自定义内核、推测式预填充与解码逻辑，针对每一款模型与硬件目标完成专属调优。

---

推理引擎优化特性

---

支持的模型与草稿器

每个徽章可跳转至实测环境所使用的完整权重文件。草稿器徽章将跳转至已发布的量化版本，若需额外转换则跳转至源检查点。

已测试硬件（GPU/APU）

本引擎不绑定单一参考显卡。NVIDIA 架构可通过 CMake 选项指定；HIP 构建版本需针对设备对应的精确 gfx 架构生成。

单设备测试结果

异构与并行测试结果

以上测试使用了不同的提示词、量化方案与推理策略，仅用于验证对应配置的可用性，不代表跨硬件性能排名。

推荐配置方案

有关模型与硬件适配矩阵（包括单 GPU 与混合 GPU 配置文件）的内容，请参阅 推荐服务器配置。

DS4 指南中还记录了 Strix 长上下文稀疏验证器配置文件，以及 Qwen3-0.6B PFlash 集成方案。PFlash 是有损提示压缩技术；若需执行精确检索或真实上下文匹配基准测试，请将其关闭。

客户端测试套件

harness/ 目录可通过主流编码客户端运行 Lucebox，并校验服务器兼容性。

请先设置服务器二进制文件与模型路径，再运行对应启动器：

LUCE_SERVER_BIN=server/build/luce_server \
LUCE_TARGET=server/models/Qwen3.8-27B-UD-IQ4_XS.gguf \
LUCE_DRAFT=server/models/draft/qwen38-dflash2-q8_0.gguf \
MAX_CTX=32768 \
harness/clients/run_codex.sh

有关环境配置、无 draft 目标与基准测试的内容，请参阅 测试套件指南。

Docker 快速入门

GHCR 上的预构建镜像会跟踪 main 分支。挂载模型权重后，即可在 :8000 端口提供兼容 OpenAI 规范的 API 服务。

请将主模型文件放置在 server/models/ 目录下，对应的 draft 模型文件放置在 server/models/draft/ 目录下。

根据所用 GPU 运行对应镜像：

# NVIDIA 设备
docker run --rm --gpus all -p 8000:8080 \
-v "$PWD/server/models:/opt/lucebox-hub/server/models" \
ghcr.io/luce-org/lucebox-hub:cuda12

# AMD 设备
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

容器会自动选择可容纳目标模型的 GPU（优先选用独立显卡而非核显，均不满足时选用显存最大的设备），并根据该 GPU 的显存自动设置上下文大小。serve 是默认命令，你可以直接在镜像名称后追加 luce_server 参数（也可以显式指定 serve），传入的参数会覆盖容器默认值。--target-device、--max-ctx 和 --profile 等参数均支持直接使用：

# 列出所有 GPU、模型信息与自动放置逻辑选定的设备
docker run --rm -v ... ghcr.io/luce-org/lucebox-hub:rocm devices

# 在 Strix Halo 上以适配配置文件运行 DeepSeek V4（DSpark draft 模型位于 models/draft/ 目录下）
docker run --rm -p 8000:8080 -v ... ghcr.io/luce-org/lucebox-hub:rocm --profile ds4-strix

# 手动指定绑定设备
docker run --rm -p 8000:8080 -v ... ghcr.io/luce-org/lucebox-hub:rocm --target-device hip:1

LUCE_TARGET、LUCE_TARGET_DEVICE、LUCE_MAX_CTX 与 LUCE_ARGS 等环境变量可在 compose 文件中实现相同的配置效果，详见 server/scripts/entrypoint.sh 的头部说明。

运行服务器

本快速入门示例将运行上文提到的 R9700 配置文件。完整的参数参考请查看 服务器指南。

# 编译（ROCm 7.2+，RDNA4 架构）
git clone --recurse-submodules https://github.com/Luce-Org/lucebox.git
cd lucebox
cmake -S server -B server/build-hip -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_HIP_COMPILER=/opt/rocm/lib/llvm/bin/clang++ \
-DLUCE_GPU_BACKEND=hip \
-DLUCE_HIP_ARCHITECTURES=gfx1201 \
-DGGML_HIP_MMQ_MFMA=ON \
-DGGML_HIP_NO_VMM=ON
cmake --build server/build-hip --target luce_server -j"$(nproc)"

# 准备主模型与 DFlash2 draft 模型
mkdir -p models
huggingface-cli download unsloth/Qwen3.8-27B-GGUF \
Qwen3.8-27B-UD-IQ4_XS.gguf --local-dir models
huggingface-cli download incoai/Qwen3.8-27B-DFlash2 --local-dir models/dflash2
python server/scripts/convert_dflash_to_gguf.py \
models/dflash2/model.safetensors models/qwen38-dflash2-f16.gguf
python server/scripts/quantize_dflash_draft.py \
models/qwen38-dflash2-f16.gguf models/qwen38-dflash2-q8_0.gguf --scheme q8_0

# 运行适配好的配置文件
./server/build-hip/luce_server models/Qwen3.8-27B-UD-IQ4_XS.gguf \
--draft models/qwen38-dflash2-q8_0.gguf \
--draft-block-size 16 --max-ctx 131072 \
--cache-type-k q8_0 --cache-type-v q8_0 \
--port 8216

curl -s http://127.0.0.1:8216/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"messages":[{"role":"user","content":"Write a Python LRU cache."}],
"max_tokens":256,"temperature":0}'

若要支持最多 N 个并发请求，可使用以下启动命令（基于相同的 Qwen 主模型与 DFlash2 draft 模型）。请将 N 替换为所需的并发数（示例中设为 5），Qwen 会根据可用 GPU 显存自动调整共享 KV 池的大小。

N=5
./server/build-hip/luce_server models/Qwen3.8-27B-UD-IQ4_XS.gguf \
--draft models/qwen38-dflash2-q8_0.gguf \
--draft-block-size 16 --max-ctx 16384 \
--paged-attention --max-concurrency "$N" \
--cache-type-k q8_0 --cache-type-v q8_0 \
--port 8216

有关 Qwen 与 DeepSeek V4 Flash 的实测结果、延迟数据与启动设置，请参阅 Lucebox 中的连续批处理。

文档

各专项优化的基准测试结果随对应实现一同发布：DFlash、PFlash、Spark、KVFlash 与 Megakernel。

---

教程

提供各优化项与测试套件配置的视频教程。

---

Lucebox 专用设备

本地 AI 应当是默认选项，而非少数人才享有的特权。全程数据留存在本地、无按 Token 计费、也不存在厂商锁定。Lucebox 将 R9700 与 Strix Halo 搭配，交付预配置就绪、可直接运行的开源引擎。

你可以访问 lucebo*** 查看硬件详情和当前基准测试结果。

---

征集贡献

我们欢迎来自社区的定向贡献，贡献范围涵盖 CUDA 与 HIP 内核、投机推理、更多消费级 GPU 和 APU 的适配支持、性能基准测试以及客户端测试套件。

---

引用

@software{lucebox_2026,
title = {Lucebox: Speculative inference for heterogeneous consumer hardware},
author = {Lucebox},
url = {https://github.com/Luce-Org/lucebox},
year = {2026}
}

---

社区

• *******: ***.gg/yHfswqZmJQ
• 官网: lucebo***
• Issue 反馈: https://github.com/Luce-Org/lucebox/issues
• 博客: lucebo***/blog

---

Apache 2.0 许可 · Lucebo***