5分钟搭建本地大模型推理服务：Lucebox Docker部署快速教程（NVIDIA/AMD双栈全支持）

5分钟搭建本地大模型推理服务：Lucebox Docker部署快速教程（NVIDIA/AMD双栈全支持）

【免费下载链接】luceboxLLM speculative inference server for heterogeneous hardware & consumer GPUs项目地址: https://gitcode.com/gh_mirrors/lu/lucebox

Lucebox 是一款开源的本地大模型推理服务（LLM 推测推理服务器），面向消费级 GPU 与异构硬件深度优化。本教程带你用Lucebox Docker 部署，在 NVIDIA（CUDA 12+）或 AMD（ROCm 6+）显卡上 5 分钟拉起一个OpenAI 兼容 API的推理服务——不需要编译、不需要配 Python 环境，两条docker run命令就能跑通。

🎯 Lucebox 是什么？为什么选它

Lucebox 的核心卖点是推测推理（Speculative Decoding）：由一个轻量草稿模型先"打草稿"，主模型一次性批量校验，实测可将解码速度提升到普通自回归的3~5 倍，同时保持输出质量不变。

对新手最友好的三点：

• 🔌 OpenAI 兼容 API：提供/v1/chat/completions、/v1/messages（Anthropic）、/v1/responses等标准端点，现有代码改个base_url即可接入
• 🎮 消费级显卡全覆盖：NVIDIA 从 RTX 2080 Ti（sm_75）到 RTX 5090（sm_120），AMD 覆盖 RDNA3/RDNA4（RX 7900 XTX、R9700、Strix Halo 等）
• 📦 预构建 Docker 镜像：官方提供:cuda12与:rocm两个镜像，GPU 环境全部打包好

📦 部署前准备：模型文件该放哪里

Docker 镜像采用"模型挂载"设计——镜像本身不含模型，你把权重放到宿主机目录再映射进容器即可。

约定两个路径（镜像内为/opt/lucebox-hub/server/models）：

模型获取可参考 README.md 中的 Quick Start，典型方式：

# 目标模型放进 server/models/ huggingface-cli download unsloth/Qwen3.6-27B-GGUF \ Qwen3.6-27B-Q4_K_M.gguf --local-dir server/models # 匹配草稿模型放进 server/models/draft/（自动发现，无需额外配置） huggingface-cli download Lucebox/Qwen3.6-27B-DFlash-GGUF \ dflash-draft-3.6-q4_k_m.gguf --local-dir server/models/draft

💡 草稿模型放在draft/目录下会被 entrypoint 自动发现，不需要传任何额外参数。

🚀 NVIDIA 显卡：一条命令启动（CUDA 12+）

NVIDIA 侧只需--gpus all，官方预构建镜像:cuda12基于 CUDA 12.8，覆盖 sm_75~sm_120 全架构（fat binary 编译）：

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

参数解读：

• -p 8000:8080：容器内服务默认监听 8080（由镜像内LUCE_PORT控制），映射到宿主机 8000 端口
• -v ...server/models：模型目录挂载，对应 Dockerfile 中声明的VOLUME /opt/lucebox-hub/server/models

🎮 AMD 显卡：一条命令启动（ROCm 6+）

AMD 侧不使用--gpus，而是直接暴露 KFD 与 DRI 设备节点，并放开 seccomp 限制：

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

⚠️AMD 避坑重点：:rocm镜像默认基于 ROCm 6.4.1（Strix Halo/gfx1151 推荐版本）。若宿主机驱动是 ROCm 7.x，请在本地重建时指定ROCM_VERSION=7.2.2，保持镜像与宿主机大版本一致，否则可能出现加载模型时崩溃——详见 Dockerfile.rocm 顶部注释与 docker-bake.hcl。

✅ 3 行 curl 验证推理服务

服务启动后，依次执行（宿主机终端）：

# 1. 健康检查 curl -s http://127.0.0.1:8000/health # 2. 查看已加载模型 curl -s http://127.0.0.1:8000/v1/models # 3. 发起第一次对话（OpenAI Chat Completions 格式） curl -s http://127.0.0.1:8000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"messages":[{"role":"user","content":"用一句话介绍 Lucebox"}],"max_tokens":128,"temperature":0}'

能收到流式/非流式 JSON 回复，说明你的本地大模型推理服务已经就绪。完整端点与参数支持（stream、top_p、tools、reasoning等）见 server/docs/API.md。

🛠️ 常见问题排查清单

🏗️ 进阶：从源码自建镜像

如果你需要定制 GPU 架构（如只编译本机 sm_120 以加速构建），可克隆仓库自行构建——Dockerfile要求构建上下文里已含 vendored ggml 源码，因此必须用--recurse-submodules：

git clone --recurse-submodules https://gitcode.com/gh_mirrors/lu/lucebox cd lucebox # NVIDIA：只编译本机架构，跳过多架构编译 LUCE_CUDA_ARCHES=120 docker buildx bake cuda12-local --load # AMD：默认 gfx1151，可用 LUCE_HIP_ARCHES 扩展 docker buildx bake rocm-local --load

构建配方与架构清单详见 docker-bake.hcl 和 scripts/build_image.sh。

📚 延伸阅读

至此，一个支持 NVIDIA/AMD 双栈、OpenAI 兼容的本地大模型推理服务已在你的机器上运行。下一步可以尝试在 server/docs/RECOMMENDED_SETUPS.md 中为你的显卡挑选对应的模型配置，把推测解码的提速真正跑起来。

【免费下载链接】luceboxLLM speculative inference server for heterogeneous hardware & consumer GPUs项目地址: https://gitcode.com/gh_mirrors/lu/lucebox