5分钟搭建本地大模型推理服务Lucebox Docker部署快速教程NVIDIA/AMD双栈全支持【免费下载链接】luceboxLLM speculative inference server for heterogeneous hardware consumer GPUs项目地址: https://gitcode.com/gh_mirrors/lu/luceboxLucebox 是一款开源的本地大模型推理服务LLM 推测推理服务器面向消费级 GPU 与异构硬件深度优化。本教程带你用Lucebox Docker 部署在 NVIDIACUDA 12或 AMDROCm 6显卡上 5 分钟拉起一个OpenAI 兼容 API的推理服务——不需要编译、不需要配 Python 环境两条docker run命令就能跑通。 Lucebox 是什么为什么选它Lucebox 的核心卖点是推测推理Speculative Decoding由一个轻量草稿模型先打草稿主模型一次性批量校验实测可将解码速度提升到普通自回归的3~5 倍同时保持输出质量不变。对新手最友好的三点 OpenAI 兼容 API提供/v1/chat/completions、/v1/messagesAnthropic、/v1/responses等标准端点现有代码改个base_url即可接入 消费级显卡全覆盖NVIDIA 从 RTX 2080 Tism_75到 RTX 5090sm_120AMD 覆盖 RDNA3/RDNA4RX 7900 XTX、R9700、Strix Halo 等 预构建 Docker 镜像官方提供:cuda12与:rocm两个镜像GPU 环境全部打包好 部署前准备模型文件该放哪里Docker 镜像采用模型挂载设计——镜像本身不含模型你把权重放到宿主机目录再映射进容器即可。约定两个路径镜像内为/opt/lucebox-hub/server/models内容宿主机目录说明目标模型server/models/主模型 GGUF 权重如Qwen3.6-27B-Q4_K_M.gguf草稿模型server/models/draft/与目标匹配的 DFlash 草稿 GGUF可选用于推测加速模型获取可参考 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 12NVIDIA 侧只需--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 6AMD 侧不使用--gpus而是直接暴露 KFD 与 DRI 设备节点并放开 seccomp 限制docker run --rm --device /dev/kfd --device /dev/dri \ --group-add video --group-add render --security-opt seccompunconfined \ -p 8000:8080 \ -v $PWD/server/models:/opt/lucebox-hub/server/models \ ghcr.io/luce-org/lucebox-hub:rocm⚠️AMD 避坑重点:rocm镜像默认基于 ROCm 6.4.1Strix Halo/gfx1151 推荐版本。若宿主机驱动是 ROCm 7.x请在本地重建时指定ROCM_VERSION7.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。️ 常见问题排查清单现象原因与解决NVIDIA 启动即退出宿主机未安装 nvidia-container-toolkit--gpus all报 unknown flagAMD 无输出、显存不涨漏挂--device /dev/kfd --device /dev/dri或用户不在render组容器内看不到模型挂载路径写错镜像内固定为/opt/lucebox-hub/server/models想进容器调试追加子命令shelldocker run ... ghcr.io/luce-org/lucebox-hub:cuda12 shell改端口/监听地址通过环境变量LUCE_PORT、LUCE_HOST覆盖环境变量参考️ 进阶从源码自建镜像如果你需要定制 GPU 架构如只编译本机 sm_120 以加速构建可克隆仓库自行构建——Dockerfile要求构建上下文里已含 vendored ggml 源码因此必须用--recurse-submodulesgit clone --recurse-submodules https://gitcode.com/gh_mirrors/lu/lucebox cd lucebox # NVIDIA只编译本机架构跳过多架构编译 LUCE_CUDA_ARCHES120 docker buildx bake cuda12-local --load # AMD默认 gfx1151可用 LUCE_HIP_ARCHES 扩展 docker buildx bake rocm-local --load构建配方与架构清单详见 docker-bake.hcl 和 scripts/build_image.sh。 延伸阅读主题文档API 端点与请求参数server/docs/API.md推荐模型与硬件配置server/docs/RECOMMENDED_SETUPS.md环境变量参考server/docs/ENVIRONMENT.md服务器架构原理server/docs/ARCHITECTURE.md客户端接入Claude Code / Open WebUI 等harness/README.md至此一个支持 NVIDIA/AMD 双栈、OpenAI 兼容的本地大模型推理服务已在你的机器上运行。下一步可以尝试在 server/docs/RECOMMENDED_SETUPS.md 中为你的显卡挑选对应的模型配置把推测解码的提速真正跑起来。【免费下载链接】luceboxLLM speculative inference server for heterogeneous hardware consumer GPUs项目地址: https://gitcode.com/gh_mirrors/lu/lucebox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考