d3-edge 生产部署指南:vLLM Semantic Router 实现 861 req/s 高吞吐服务的完整步骤
d3-edge 生产部署指南:vLLM Semantic Router 实现 861 req/s 高吞吐服务的完整步骤
d3-edge 是 vLLM Semantic Router 团队发布的 0.6B 多模态决策模型,一次调用即可对文本、图像、视频同时回答选择题、是否题与评分题,并为每个选项给出概率。本文将带你完成 d3-edge 生产部署:借助 vLLM Semantic Router 的 Engine 模式,在单张 GPU 上稳定跑出 861 req/s(p99 < 1s)的高吞吐决策服务。全程无需写业务代码,按步骤执行命令即可上线。
🎯 为什么选 Engine 模式部署 d3-edge
d3-edge 有两种"跑法":
- AutoModel / 包内服务:模型运行在你自己的进程里,一次只处理一个请求,适合本地调试与离线脚本。
- Engine 模式(本文重点):由
vllm-sr serve -e在后台启动 System One API 服务,自动对并发请求做批处理——这正是 861 req/s 的来源。
同一台 GPU 上的吞吐量对比(官方 README.md 实测,单卡 AMD Instinct MI325X):
| 请求场景 | AutoModel | Engine(批处理,默认) | 提升 |
|---|---|---|---|
| 文本 · 1 个问题 | 142 req/s | 861 req/s | 6.1× |
| 图像 1.6MP · 8 个问题 | 3.7 req/s | 18.8 req/s | 5.1× |
| 10 秒视频 · 1 个问题 | 3.7 req/s | 8.7 req/s | 2.4× |
💡 一句话结论:单条短请求在本地进程里最快;但你要"对外提供服务",Engine 模式的并发批处理能把吞吐拉高一个数量级。
📦 部署前置条件与一键安装
环境要求
- 一张可用的 GPU(CUDA / ROCm),推荐 bfloat16 算力;
- 能访问模型仓库(首次启动会自动拉取镜像并下载模型);
- 依赖清单见 requirements.txt:
transformers==5.17.0、torch、safetensors、flash-linear-attention等。
一键安装 vLLM Semantic Router Engine
Engine 模式与 Decision 3.0 目前位于 dev 开发频道。执行官方安装脚本:
curl -fsSL https://vllm-sr.ai/install.sh | bash -s -- --channel dev --no-launch
export PATH="$HOME/.local/bin:$PATH"
平台会被自动识别;如需手动指定,可用
--platform auto|cpu|cuda|rocm。
🚀 启动 Engine 服务并验证健康状态
只需一条命令即可拉起服务:
vllm-sr serve -e vllm-sr/d3-edge
首次启动会完成镜像拉取与模型下载。启动后,用健康检查端点确认服务就绪:
curl -s localhost:8899/health
看到 "status": "ready" 即表示模型加载完成、可以接收决策请求。停止服务:
vllm-sr stop
⚠️ 包内自带的轻量 HTTP 服务为 d3_server.py(默认端口 8000,单请求串行),生产高吞吐请始终使用上面的 Engine 模式。
🧠 通过 System One API 发送决策请求
Engine 模式暴露 POST /v1/systemone 接口。一次请求可携带 state(文本)、images、videos 和一组 questions,所有问题共享同一份输入。
文本决策(最常用)
curl -s localhost:8899/v1/systemone -H 'content-type: application/json' -d '{
"model": "vllm-sr/d3-edge",
"state": "Write a Python function that merges two sorted lists.",
"questions": {
"kind": {"type": "choice", "instructions": "What kind of work is this?",
"criteria": {"code": "Writing or fixing code", "math": "Mathematics", "chat": "Anything else"}}
}
}'
返回结果里,answers 会对每个选项给出概率,便于你按阈值做路由。
图像 / 视频决策(多模态)
图像以 base64 data URL 放进 images,视频放进 videos。下图是仓库自带的示例收据,常用于"收据是否包含某商品 / 支付方式"这类决策场景:
curl -s localhost:8899/v1/systemone -H 'content-type: application/json' --data-binary @- <<EOF
{
"model": "vllm-sr/d3-edge",
"state": "Does the receipt list the blender? How was it paid?",
"images": ["data:image/png;base64,$(base64 -w0 receipt.png)"],
"questions": {
"on_receipt": {"type": "noul", "instructions": "Does the receipt list the blender?"},
"payment": {"type": "choice", "instructions": "How was the order paid?",
"criteria": {"card": null, "cash": null, "gift card": null}}
}
}
EOF
📌 图像在文本之前进入请求(每张最高 1.6MP);视频按 2 帧/秒读取(整段最多 32 帧)。
⚙️ 调优关键参数,逼近 861 req/s
Engine 模式默认开启批处理,并支持一组 vLLM 风格引擎参数,按需微调即可:
| 参数 | 作用 |
|---|---|
--max-num-batched-tokens |
限制单个批次的总 token 数 |
--max-num-seqs |
限制并发序列数 |
--batch-window-ms |
批处理等待窗口(毫秒),影响延迟/吞吐权衡 |
--dtype |
模型精度(生产建议 bfloat16) |
并发请求越多,批处理收益越大;短文本场景最易逼近 861 req/s 的峰值。
📊 资源与性能预期
| 指标 | 数值(单卡 MI325X) |
|---|---|
| 峰值吞吐 | 861 req/s(文本 1 问,批处理) |
| 尾延迟 | p99 < 1s |
| 显存峰值(批处理) | 19.9 GiB |
| 显存峰值(单请求/forward) | 15.9 GiB |
| 冷启动首答 | 约 11.6s(AutoModel 约 24.9s) |
常见延迟参考(批处理,热态 p50/p90):文本 1 问 ≈ 9.9/10.8 ms;图像 1.6MP 8 问 ≈ 111/113 ms;10 秒视频 1 问 ≈ 309/324 ms。
✅ 需要可复现性时,可改用"单请求/forward"模式:在相同 kernel 配置下,Engine 输出与 AutoModel 逐字节一致。
🧰 常见问题与排错清单
- 启动后端口无响应:先查
curl localhost:8899/health;确认--channel dev与 PATH 已导出。 - 返回 422 / invalid_questions:检查
questions结构,criteria需与问题类型匹配;请求体必须为合法 JSON。 - 吞吐远低于预期:确认并发客户端数足够(批处理需要并发才有收益),并核对该场景是否命中文本短请求。
- 显存吃紧:适当调小
--max-num-batched-tokens/--max-num-seqs,或评估改用单请求/forward 模式。 - 想理解内部实现:引擎入口见 d3_engine.py,运行核心见 d3_runtime.py,GPU 内核见 d3_kernels.py,模型定义见 modeling_d3.py,模型元信息见 MODEL_MANIFEST.json 与 config.json。
写在最后
d3-edge 用不到 1GB 级参数,就实现了"文本 + 图像 + 视频"三模态、一次调用多问并给出概率的决策能力;配合 vLLM Semantic Router 的 Engine 模式,单卡即可撑起 861 req/s 的生产级吞吐。完成本文步骤后,你已拥有一个可对外提供决策服务的高吞吐端点——下一步可以接入你的业务路由与告警监控。🎉
