Diffusion 模型部署

本章节包含 Qwen-Image，Minimax-H3，Wan2.2 模型的部署指导。

Minimax-H3

权重与镜像

• 模型权重下载。

• 请使用 版本发布信息-镜像地址 中 Minimax-H3 的专属镜像。

启动脚本示例

• SGLANG_MINIMAX_H3_MOORCAT_BLOCKSPARSE=1 打开 SparseAttn，可按需关闭。

• SGLANG_CACHE_DIT_ENABLED=true 打开 CacheDit，可按需关闭。

• 自定义脚本中以下变量：

变量	示例	含义
SGLANG_ROOT	/workspace/sglang	代码目录
MODEL_PATH（FL2VA）	/data/models/MiniMax-H3/FL2VA	t2va / fl2va 权重
MODEL_PATH（Ref2VA）	/data/models/MiniMax-H3/Ref2VA	ref2va 权重
OUTPUT_ROOT	/data/minimax_h3_run	服务输出根目录
PORT	FL2VA=30010，Ref2VA=30020	HTTP 端口

启动脚本 serve_minimax_h3.sh

#!/usr/bin/env bash
set -euo pipefail
# Three launch strategies (one process = one checkpoint):
#   bash scripts/serve_minimax_h3_best.sh t2va    # FL2VA, fast text-only Qwen TP
#   bash scripts/serve_minimax_h3_best.sh fl2va   # FL2VA, multimodal Qwen (t2va+fl2va)
#   bash scripts/serve_minimax_h3_best.sh ref2va  # Ref2VA, multimodal Qwen
#
# GPU count (same flags; SP = Ulysses = NUM_GPUS):
#   NUM_GPUS=8 bash scripts/serve_minimax_h3_best.sh fl2va   # default
#   NUM_GPUS=4 MUSA_VISIBLE_DEVICES=0,1,2,3 ...
#   NUM_GPUS=2 MUSA_VISIBLE_DEVICES=0,1 ...
#
# Defaults:
#   t2va  -> PORT=30010 MASTER=30455 NCCL=30456
#   fl2va -> PORT=30011 MASTER=30465 NCCL=30466
#   ref2va-> PORT=30020 MASTER=30555 NCCL=30556

TASK="${1:-}"
if [[ -z "${TASK}" ]]; then
  echo "usage: $0 {t2va|fl2va|ref2va}" >&2
  exit 1
fi

SGLANG_ROOT="${SGLANG_ROOT:-/workspace/sglang}"
export SGLANG_ROOT
cd "${SGLANG_ROOT}"

NUM_GPUS="${NUM_GPUS:-8}"
case "${NUM_GPUS}" in
  2|4|8) ;;
  *)
    echo "NUM_GPUS must be 2, 4, or 8 (got ${NUM_GPUS})" >&2
    exit 1
    ;;
esac
SP_DEGREE="${SP_DEGREE:-${NUM_GPUS}}"
ULYSSES_DEGREE="${ULYSSES_DEGREE:-${NUM_GPUS}}"

# Moorcat is an installed AOT package. Its Python wrapper and native extension
# are resolved from site-packages; no moorcat source/build checkout is needed.
unset MOORCAT_ROOT MOORCAT_EXT_DIR MOORCAT_EXT_DIR_OVERRIDE
export PYTHONPATH="${SGLANG_ROOT}/python:/usr/local/lib/python3.10/dist-packages/tilelang/3rdparty/tvm/python${PYTHONPATH:+:${PYTHONPATH}}"
export SGLANG_DIFFUSION_PLATFORM_OVERRIDE=musa
export MUSA_VISIBLE_DEVICES="${MUSA_VISIBLE_DEVICES:-0,1,2,3,4,5,6,7}"
export PYTORCH_MUSA_ALLOC_CONF="${PYTORCH_MUSA_ALLOC_CONF:-expandable_segments:True}"
# Timing/debug shells often leave this on; it serializes every kernel and
# cannot reproduce the 8-GPU pixel baseline.
unset MUSA_LAUNCH_BLOCKING CUDA_LAUNCH_BLOCKING SGLANG_MINIMAX_H3_MOORCAT_TIMING
export MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE="${MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE:-768}"

# ---- shared best perf / anti-OOM ----
export SGLANG_CACHE_DIT_ENABLED=true
export MINIMAX_H3_VAE_CPU_OFFLOAD=false
export MINIMAX_H3_VAE_PARALLEL_DECODE=1
export MINIMAX_H3_DIT_CPU_OFFLOAD=true
export MINIMAX_H3_DIT_LAYERWISE_OFFLOAD=true
export MINIMAX_H3_DIT_OFFLOAD_PREFETCH_SIZE=3
# Keep one rolling resident layer.  The final layer starts the next request's
# first-layer copy so the inter-step H2D bubble is hidden by tail computation.
export SGLANG_LAYERWISE_INITIAL_PREFETCH_SIZE="${SGLANG_LAYERWISE_INITIAL_PREFETCH_SIZE:-1}"
export SGLANG_LAYERWISE_REFILL_BATCH_SIZE="${SGLANG_LAYERWISE_REFILL_BATCH_SIZE:-1}"
export SGLANG_LAYERWISE_LOW_WATERMARK="${SGLANG_LAYERWISE_LOW_WATERMARK:-0}"
export SGLANG_LAYERWISE_WRAPAROUND_PREFETCH="${SGLANG_LAYERWISE_WRAPAROUND_PREFETCH:-1}"
export SGLANG_MINIMAX_H3_RELEASE_DIT_BEFORE_DECODE=false
export SGLANG_MINIMAX_H3_TILELANG_MODULATION=true
export SGLANG_MINIMAX_H3_QK_ROPE_BF16_TILELANG=true
export SGLANG_MINIMAX_H3_SWIGLU_BF16_TILELANG=true
export SGLANG_MINIMAX_H3_BF16_QKV_TILESCALE="${SGLANG_MINIMAX_H3_BF16_QKV_TILESCALE:-true}"
# Output TileScale skews ranks around sparse attention; keep generic A2A.
export SGLANG_MINIMAX_H3_BF16_OUTPUT_TILESCALE=false
export SGLANG_MINIMAX_H3_MOORCAT_BLOCKSPARSE="${SGLANG_MINIMAX_H3_MOORCAT_BLOCKSPARSE:-1}"
export SGLANG_MINIMAX_H3_MOORCAT_PROFILE_PAIRING="${SGLANG_MINIMAX_H3_MOORCAT_PROFILE_PAIRING:-0}"
# Full FA is faster at ratio=0.55; switch to sparse from ratio=0.45 down
# (topk_ratio_list[2]=0.55 stays dense, [3]=0.45 is the first sparse step).
export SGLANG_MINIMAX_H3_MOORCAT_MAX_SPARSE_RATIO="${SGLANG_MINIMAX_H3_MOORCAT_MAX_SPARSE_RATIO:-0.45}"
export SGLANG_MINIMAX_H3_MOORCAT_FUSED_CUBE_POOL="${SGLANG_MINIMAX_H3_MOORCAT_FUSED_CUBE_POOL:-1}"
unset MOORCAT_LEGACY_K64_PACK
# native128 / cube [8,4,4] is the production sparse kernel. block64 is opt-in.
MOORCAT_BLOCK_SIZE="${SGLANG_MINIMAX_H3_MOORCAT_BLOCK_SIZE:-128}"
export SGLANG_MINIMAX_H3_MOORCAT_BLOCK_SIZE="${MOORCAT_BLOCK_SIZE}"
DEFAULT_MOORCAT_CONFIG='{"local_cube_size":[8,4,4],"topk_ratio_list":[1.0,1.0,0.55,0.45,0.35,0.35,0.30,0.25,0.25,0.20,0.20,0.20,0.15,0.15,0.15,0.10,0.10,0.10,0.10,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05,0.05]}'
export SGLANG_MINIMAX_H3_MOORCAT_CONFIG="${SGLANG_MINIMAX_H3_MOORCAT_CONFIG:-${DEFAULT_MOORCAT_CONFIG}}"
if [[ "${MOORCAT_BLOCK_SIZE}" == "64" ]]; then
  export SGLANG_MINIMAX_H3_MOORCAT_CONFIG="${SGLANG_MINIMAX_H3_MOORCAT_CONFIG/\[8,4,4\]/[4,4,4]}"
elif [[ "${MOORCAT_BLOCK_SIZE}" != "128" ]]; then
  echo "SGLANG_MINIMAX_H3_MOORCAT_BLOCK_SIZE must be 64 or 128" >&2
  exit 1
fi
export SGLANG_MINIMAX_H3_DIRECT_PEER_HOST_ENTRY_BARRIER=true
export SGLANG_MINIMAX_H3_SYNC_DENOISE_UPDATES=false
export SGLANG_MINIMAX_H3_VALIDATE_DENOISE_TENSORS=false
export SGLANG_MINIMAX_H3_MATE_SAGE_ATTENTION=false
export SGLANG_MINIMAX_H3_SAGE_PREQUANT_QKV_TILESCALE=false
export SGLANG_MINIMAX_H3_QK_ROPE_FP8_QUANT_TILELANG=false
export SGLANG_MINIMAX_H3_REPORT_DENOISE_COMPUTE=true
export SGLANG_SERVER_WARMUP_MAX_VIDEO_FRAMES="${SGLANG_SERVER_WARMUP_MAX_VIDEO_FRAMES:-362}"
unset MCCL_BUFFSIZE

case "${TASK}" in
  t2va|T2VA)
    # Fast text path: persistent Qwen TP text-only shards (no per-request H2D).
    # Accepts t2va only — fl2va/ref2va will fail on this server.
    STRATEGY="t2va_text_only_tp"
    MODEL_PATH="${MODEL_PATH:-/data/models/FL2VA}"
    PORT="${PORT:-30010}"
    MASTER_PORT="${MASTER_PORT:-30455}"
    NCCL_PORT="${NCCL_PORT:-30456}"
    export MINIMAX_H3_TEXT_ENCODER_CPU_OFFLOAD=false
    export SGLANG_MINIMAX_H3_QWEN_TP_TEXT_ONLY=1
    export SGLANG_MINIMAX_H3_QWEN_TP_RELEASE_AFTER_ENCODE=true
    TEXT_ENCODER_CPU_OFFLOAD_CLI=false
    ACCEPTS="t2va"
    ;;
  fl2va|FL2VA)
    # Multimodal Qwen on rank0 with CPU offload between encodes.
    # Can accept both t2va and fl2va; text encode pays H2D each request.
    STRATEGY="fl2va_multimodal_qwen"
    MODEL_PATH="${MODEL_PATH:-/data/models/FL2VA}"
    PORT="${PORT:-30011}"
    MASTER_PORT="${MASTER_PORT:-30465}"
    NCCL_PORT="${NCCL_PORT:-30466}"
    export MINIMAX_H3_TEXT_ENCODER_CPU_OFFLOAD=true
    export SGLANG_MINIMAX_H3_QWEN_TP_TEXT_ONLY=0
    export SGLANG_MINIMAX_H3_QWEN_TP_RELEASE_AFTER_ENCODE=false
    TEXT_ENCODER_CPU_OFFLOAD_CLI=true
    ACCEPTS="t2va+fl2va"
    ;;
  ref2va|Ref2VA)
    # Multimodal Qwen for image/audio/video references; Ref2VA checkpoint.
    STRATEGY="ref2va_multimodal_qwen"
    MODEL_PATH="${MODEL_PATH:-/data/models/Ref2VA}"
    PORT="${PORT:-30020}"
    MASTER_PORT="${MASTER_PORT:-30555}"
    NCCL_PORT="${NCCL_PORT:-30556}"
    export MINIMAX_H3_TEXT_ENCODER_CPU_OFFLOAD=true
    export SGLANG_MINIMAX_H3_QWEN_TP_TEXT_ONLY=0
    export SGLANG_MINIMAX_H3_QWEN_TP_RELEASE_AFTER_ENCODE=false
    TEXT_ENCODER_CPU_OFFLOAD_CLI=true
    ACCEPTS="ref2va"
    ;;
  *)
    echo "usage: $0 {t2va|fl2va|ref2va}" >&2
    exit 1
    ;;
esac

OUTPUT_ROOT="${OUTPUT_ROOT:-/data/workspace/minimax_h3_run}"
SERVER_OUTPUT_DIR="${SERVER_OUTPUT_DIR:-${OUTPUT_ROOT}/server-${PORT}}"
mkdir -p "${SERVER_OUTPUT_DIR}"

if [[ ! -f "${MODEL_PATH}/model_index.json" ]]; then
  echo "missing model: ${MODEL_PATH}/model_index.json" >&2
  exit 1
fi

if [[ "${MOORCAT_BLOCK_SIZE}" == "128" ]]; then
  MOORCAT_CUBE="[8,4,4]"
else
  MOORCAT_CUBE="[4,4,4]"
fi

echo "TASK=${TASK}"
echo "STRATEGY=${STRATEGY}"
echo "ACCEPTS=${ACCEPTS}"
echo "MODEL_PATH=${MODEL_PATH}"
echo "NUM_GPUS=${NUM_GPUS} SP_DEGREE=${SP_DEGREE} ULYSSES_DEGREE=${ULYSSES_DEGREE}"
echo "PORT=${PORT} MASTER_PORT=${MASTER_PORT} NCCL_PORT=${NCCL_PORT}"
echo "QWEN_TP_TEXT_ONLY=${SGLANG_MINIMAX_H3_QWEN_TP_TEXT_ONLY}"
echo "QWEN_TP_RELEASE_AFTER_ENCODE=${SGLANG_MINIMAX_H3_QWEN_TP_RELEASE_AFTER_ENCODE}"
echo "TEXT_ENCODER_CPU_OFFLOAD=${MINIMAX_H3_TEXT_ENCODER_CPU_OFFLOAD}"
echo "SERVER_OUTPUT_DIR=${SERVER_OUTPUT_DIR}"
echo "LAYERWISE_RESERVOIR=initial:${SGLANG_LAYERWISE_INITIAL_PREFETCH_SIZE},refill:${SGLANG_LAYERWISE_REFILL_BATCH_SIZE},low:${SGLANG_LAYERWISE_LOW_WATERMARK},wraparound:${SGLANG_LAYERWISE_WRAPAROUND_PREFETCH}"
echo "DIT_OFFLOAD_PREFETCH_SIZE=${MINIMAX_H3_DIT_OFFLOAD_PREFETCH_SIZE}"
echo "QKV_TILESCALE=${SGLANG_MINIMAX_H3_BF16_QKV_TILESCALE} OUTPUT_TILESCALE=${SGLANG_MINIMAX_H3_BF16_OUTPUT_TILESCALE}"
echo "MOORCAT_BLOCK_SIZE=${MOORCAT_BLOCK_SIZE} cube=${MOORCAT_CUBE} max_sparse_ratio=${SGLANG_MINIMAX_H3_MOORCAT_MAX_SPARSE_RATIO}"
echo "MOORCAT_SOURCE=installed-package"
echo "REFERENCE_IMAGE_SHORT_EDGE=${MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE}"
echo "WARMUP_MODE=request WARMUP_STEPS=2 MEMORY=vae_opt BF16_OPT=1"

exec sglang serve \
  --model-type diffusion \
  --model-path "${MODEL_PATH}" \
  --num-gpus "${NUM_GPUS}" \
  --sp-degree "${SP_DEGREE}" \
  --ulysses-degree "${ULYSSES_DEGREE}" \
  --trust-remote-code \
  --dit-cpu-offload true \
  --dit-layerwise-offload true \
  --dit-offload-prefetch-size "${MINIMAX_H3_DIT_OFFLOAD_PREFETCH_SIZE}" \
  --vae-cpu-offload false \
  --text-encoder-cpu-offload "${TEXT_ENCODER_CPU_OFFLOAD_CLI}" \
  --warmup-mode request \
  --minimax-h3-adaln-online true \
  --warmup-steps 20 \
  --host 0.0.0.0 \
  --port "${PORT}" \
  --master-port "${MASTER_PORT}" \
  --nccl-port "${NCCL_PORT}" \
  --strict-ports \
  --output-path "${SERVER_OUTPUT_DIR}"

服务拉起示例：

命令	默认端口	适用场景
MODEL_PATH=/data/models/MiniMax-H3/FL2VA bash scripts/serve_minimax_h3.sh t2va	30010	t2va
MODEL_PATH=/data/models/MiniMax-H3/FL2VA bash scripts/serve_minimax_h3.sh fl2va	30011	fl2va
MODEL_PATH=/data/models/MiniMax-H3/Ref2VA bash scripts/serve_minimax_h3.sh ref2va	30020	ref2va

Qwen/Qwen-Image

启动脚本 qwen_image_server.sh

#!/bin/bash
sglang serve --model-path /data/models/Qwen-Image --served-model-name qwen-image --port 20133 --num-gpus 2 --ulysses-degree 1 --ring-degree 2 --warmup

Qwen/Qwen-Image-Edit

启动脚本 qwen_image_edit_server.sh

#!/bin/bash
sglang serve --model-path /data/models/Qwen-Image-Edit --served-model-name qwen-image-edit --port 20133  --num-gpus 1 --warmup

Wan2.2-I2V-A14B-Diffusers

启动脚本 wan_i2v_server.sh

#!/bin/bash
sglang serve --model-path /data/models/Wan2.2-I2V-A14B-Diffusers --served-model-name wan2.2-i2v-a14b-diffusers --port 20133 --num-gpus 2 --warmup

Wan2.2-T2V-A14B-Diffusers

启动脚本 wan_t2v_server.sh

#!/bin/bash
sglang serve --model-path /data/models/Wan2.2-T2V-A14B-Diffusers --served-model-name wan2.2-t2v-a14b-diffusers --port 20133 --num-gpus 2 --warmup