企业官网建设流程全解析

一个监听器服务多个大模型：Lucebox模型负载均衡与多GPU部署实战

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

Lucebox 是一个面向消费级显卡与异构硬件的LLM 推测式推理服务器（speculative inference server），它允许你用一个 HTTP 监听器同时服务多个大模型：Qwen 跑在独立显卡上，DeepSeek 跑在 APU 核显上，请求按"主设备优先 + 容量回退"的模型负载均衡策略自动分流。本文将带你完成 Lucebox 的多 GPU 部署实战，从单命令配置到混合 NVIDIA/AMD 平台的进阶用法。

为什么需要"一个监听器 + 模型负载均衡"

传统做法是每张 GPU 起一个推理进程、每个模型一个端口，客户端要自己维护路由表。Lucebox 的模型负载均衡（Model Load Balancing）把这件事收敛到一个进程、一个端口：

• 每个模型独立持有自己的 tokenizer、后端、调度器与 KV 缓存池，互不干扰；
• 客户端继续用标准 OpenAI Chat Completions / Anthropic Messages / Responses 接口，无需任何改造；
• 响应中的model字段会明确告知实际生成答案的模型，方便排查与日志。

官方设计文档见 server/docs/MODEL_LOAD_BALANCING.md。

Lucebox 模型负载均衡的工作机制

理解三个核心概念，就能掌握整个路由行为：

1. 主设备优先，容量回退（primary-first fallback）每个生成请求都优先发给配置的主 GPU；当主模型无法接纳请求（并发槽位占满、KV 池预留不足）时，自动尝试其余模型块。这是"偏好 + 容量回退"，不是轮询，也没有"模型绑定"——请求里写什么model名都不影响路由。

2. 准入由调度器原子判定监听器只负责预留模型槽位，真正的接纳判断由每个模型的调度器在工作线程上完成，原子地检查真实槽位、prompt KV 预留量与现有解码器的余量。引擎忙碌时会在任何响应头发出之前把请求退回给监听器重试，不会污染流式输出。

3. 有界等待队列所有候选模型都忙时，请求进入内存等待队列，上限由--routing-queue-limit控制（默认 32，设为 0 则立即拒绝）。等待不占用 GPU 序列槽位；若有模型因上下文限制永远装不下该请求，直接返回 400 而不是排队。

此外，/v1/models列出已加载模型名；/props与/status/json暴露路由模式routing: "primary-first"、等待数、队列上限，以及每个模型的capacity、in_flight、执行模式与设备落位——是运维巡检的好帮手。

多 GPU 部署：一条命令加载两个模型

下面以"Qwen 3.8 27B 在 R9700（hip:0）+ DeepSeek V4 Flash 在 Strix Halo（hip:1）"为例，展示完整的负载均衡启动方式：

luce_server --load-balancing --load-balancing-primary-gpu hip:0 \ --model /models/qwen38-27b.gguf \ --model-name qwen --target-device hip:0 \ --draft /models/qwen38-dflash2.gguf --draft-device hip:0 \ --max-ctx 4096 --max-concurrency 4 --kv-pool-tokens 16384 \ --cache-type-k q8_0 --cache-type-v q8_0 \ --routing-queue-limit 32 \ --host 127.0.0.1 --port 8080 \ --model /models/deepseek-v4-flash.gguf \ --model-name ds4 --target-device hip:1 \ --max-ctx 8192 --max-concurrency 1 \ --ds4-fused-decode --ds4-expert-top-k 6 --ds4-prefill exact

配置要点：

启动后发送请求即可，model字段可填auto或任意别名：

{"model":"auto","messages":[{"role":"user","content":"Write a Python parser."}],"max_tokens":512,"stream":true}

想把主设备换成 Strix Halo 上的 DS4？只需把--load-balancing-primary-gpu改为hip:1，两个模型的落位保持不变。🎯

混合 GPU 平台：让每张卡跑最擅长的活

Lucebox 的多 GPU 能力不止"多模型分卡"，还包括同一模型的异构拆分：

• 双卡张量并行：2× RTX 3090 + NVLink 跑 Qwen 3.8 27B，--target-devices cuda:0,cuda:1 --target-split-mode tensor --peer-access，实测 79.7 tok/s 解码；
• 专家级异构并行：DeepSeek V4 用--profile ds4-r9700-strix，把稠密计算、热专家和 DSpark 草稿器放在 R9700（hip:0），其余路由专家放在 Strix Halo（--expert-device hip:1），实测 86 tok/s 解码、2K 上下文下 788 tok/s prefill。

完整硬件与参数矩阵见 server/docs/RECOMMENDED_SETUPS.md，DeepSeek V4 的双卡配置细节见 server/docs/DS4.md。

💡 小提示：先运行luce_server --list-devices打印每张 GPU 的backend:N索引、架构与显存，再确定--target-device的值；也可以直接传--target-device auto，容器会自动挑"模型装得下、优先独立显卡"的那张卡。

Docker 快速部署：容器自动挑选 GPU

如果不想自己编译，Lucebox 提供预构建 Docker 镜像：NVIDIA 用:cuda12标签，AMD 用:rocm标签。

# 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 选择与上下文长度估算，--target-device、--max-ctx、--profile等参数可直接跟在镜像名后面覆盖默认值；devices子命令可预览自动落位结果。环境变量方式（LUCE_TARGET、LUCE_TARGET_DEVICE、LUCE_MAX_CTX等）适合 compose 文件，详见 server/scripts/entrypoint.sh。

进阶：跨 CUDA / HIP 的混合后端拆分

更复杂的场景——例如 CUDA 编译的服务器进程 + HIP 编译的远端守护进程——Lucebox 也支持目标模型按层拆分跨后端执行：本地进程跑前段层组，边界激活通过 IPC 交给backend_ipc_daemon执行剩余层、最终 norm 与 LM head，DFlash 推测解码同样可以跨越这条边界。

./build-cuda/luce_server models/Qwen3.6-27B-Q4_K_M.gguf \ --target-devices cuda:0,hip:0 \ --target-layer-split 0.5,0.5 \ --target-shard-ipc-bin build-hip/backend_ipc_daemon \ --target-shard-ipc-work-dir /tmp/target_shard \ --host 127.0.0.1 --port 18080

注意只支持一个后端边界（一个本地点组 + 一个远端组）。PFlash/DFlash 的跨后端拆分与完整标志说明见 server/docs/MIXED_BACKEND.md。

常见疑问与避坑清单 📋

• 请求会中途换模型吗？不会。负载均衡在生成开始前选定模型，准入后该请求始终留在该模型上；即使中途 KV 池耗尽，也只按调度器原有策略处理，不会迁移。
• 为什么我的请求被退回？若所有候选模型都"永远装不下"该请求（上下文/池限制），服务器直接返回 400；并发占满则等待，超过--routing-queue-limit返回 503。
• token 计数要注意：负载均衡启用后，不同模型 tokenizer 不同，计 token 的请求必须显式指定模型名。
• 命名约束：启用负载均衡时模型名必须唯一、非空且不能叫auto；启动时会拒绝修改共享进程策略的选项（KVFlash、Spark、PFlash、远端草稿等）。
• 压测参考：官方主机测试套件覆盖主优先回退、槽位/KV 回退、队列溢出与排空、取消与关闭等 496 项检查，test_model_routing.cpp走真实 HTTP，可参考 server/test/test_model_routing.cpp。

文档速查

小结

Lucebox 的模型负载均衡让"多 GPU、多模型、单监听器"变成一条启动命令的事：每个模型独立落位、独立调度，主设备优先 + 容量回退 + 有界队列保证了请求总会被路由到真正有空闲的引擎上。从单卡 Qwen 到 R9700 + Strix Halo 的异构专家并行，再到跨 CUDA/HIP 的层级拆分，消费者级硬件也能拼出一台不输数据中心的推理节点。🚀

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