设置模型开机自启动

适用场景

本章节用于配置基于 vLLM 部署的模型在系统开机或重启后自动启动。示例以 AIBook 1.4.2 推荐的 MUSA Graph 启动方式为准，支持用户按实际 conda 环境、模型路径和启动参数进行替换。

注意

以下示例使用文本生成模型 gptq-Qwen3-8B。如果需要自启动多模态、Embedding 或 Reranker 模型，请将脚本最后的 vllm serve 命令替换为“快速开始”章节中对应模型类型的启动命令。

操作步骤

步骤 1：创建模型自启动脚本

登录设备并切换到模型部署用户。下面以 dev 用户为例，脚本保存到 /home/dev/mt/vllm/model_scripts/start_model.sh：

mkdir -p /home/dev/mt/vllm/model_scripts
vim /home/dev/mt/vllm/model_scripts/start_model.sh

写入以下内容，并按实际环境修改 CONDA_SH、CONDA_ENV、MODEL_PATH 和端口等参数：

#!/bin/bash
set -euo pipefail

LOG_DIR="/home/dev/mt/vllm/model_scripts"
LOG_FILE="${LOG_DIR}/model_start.log"
CONDA_SH="/home/dev/miniforge3/etc/profile.d/conda.sh"
CONDA_ENV="v1.4.2"
MODEL_PATH="/home/dev/models/gptq-Qwen3-8B"
PORT=8000

mkdir -p "${LOG_DIR}"
: > "${LOG_FILE}"

log() {
  echo "[$(date '+%F %T')] $*" >> "${LOG_FILE}"
}

log "加载 conda 配置：${CONDA_SH}"
source "${CONDA_SH}"

log "激活 conda 环境：${CONDA_ENV}"
conda activate "${CONDA_ENV}"

export PATH="/usr/local/musa/bin:${PATH}"
export LD_LIBRARY_PATH="${CONDA_PREFIX}/lib:/usr/local/musa/lib:${LD_LIBRARY_PATH:-}"
export TRITON_CACHE_DIR="/tmp/triton"

log "CONDA_PREFIX=${CONDA_PREFIX}"
log "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}"
log "TRITON_CACHE_DIR=${TRITON_CACHE_DIR}"

if command -v musaInfo >/dev/null 2>&1; then
  log "记录 musaInfo 输出"
  musaInfo >> "${LOG_FILE}" 2>&1 || true
fi

log "清理系统页面缓存"
sudo -n sh -c "echo 3 > /proc/sys/vm/drop_caches" >> "${LOG_FILE}" 2>&1 || \
  log "跳过 drop_caches：当前用户无免密 sudo 权限或系统不允许"

log "启动 vLLM 服务，模型：${MODEL_PATH}"
exec env ENABLE_MUSA_MMA=1 VLLM_USE_V1=1 vllm serve "${MODEL_PATH}" \
  --host 127.0.0.1 \
  --port "${PORT}" \
  -tp 1 \
  --gpu_memory_utilization 0.7 \
  --quantization gptq \
  --block_size 32 \
  --num-gpu-blocks-override 512 \
  --max-model-len 16384 \
  --max-num-seqs 1 \
  --swap_space 0 \
  --trust-remote-code \
  --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}' \
  >> "${LOG_FILE}" 2>&1

提示

CONDA_PREFIX 只有在 conda activate 之后才可靠，因此脚本需要先激活 conda 环境，再设置 LD_LIBRARY_PATH="$CONDA_PREFIX/lib:..."。

保存后添加可执行权限：

chmod +x /home/dev/mt/vllm/model_scripts/start_model.sh

步骤 2：配置 crontab 开机自启

打开 crontab：

crontab -e

在文件末尾添加以下内容：

@reboot bash /home/dev/mt/vllm/model_scripts/start_model.sh

保存后检查配置：

crontab -l

如果能看到新增的 @reboot 行，说明配置已经写入。

注意事项

启动参数

• AIBook 1.4.2 推荐使用 MUSA Graph 启动，即保留 --compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'。
• 使用 MUSA Graph 时不要再添加 --enforce-eager，否则会强制使用 eager 模式，无法进行图捕获。
• 如果自启动模型为 Qwen3-30B-A3B-GPTQ-Int4，可按“快速开始”章节的专用启动方式，在 exec env 后增加 VLLM_MUSA_ATTN=tilelang；其他模型不要默认增加该环境变量。
• 多模态图片模型需要额外增加 --limit-mm-per-prompt '{"image":1}'；Qwen3-VL 2B/4B 不需要 --hf-overrides，Qwen3-VL 8B/30B-A3B 需要额外增加 --hf-overrides '{"text_config":{"tie_word_embeddings":false}}'。
• Embedding 模型需要使用 --runner pooling --convert embed，Reranker 模型需要使用 --runner pooling --convert classify，不要使用普通 chat 模型的启动方式。

权限与登录

• 如果脚本中需要执行 sudo -n sh -c "echo 3 > /proc/sys/vm/drop_caches"，请确保当前用户有免密 sudo 权限；没有权限时脚本会跳过该步骤，不影响继续启动模型。
• 如果遇到 MUSA 设备初始化失败，需确认当前用户已加入 render、video 用户组：

sudo usermod -aG render,video $USER

• 部分桌面设备需要连接显示器并解锁桌面，或在系统设置中配置自动登录。

日志排查

脚本日志默认写入：

/home/dev/mt/vllm/model_scripts/model_start.log

启动失败时，优先查看该日志中的 conda 激活、MUSA 环境、模型加载和 vLLM 报错信息。

验证模型自启效果

配置完成后重启设备：

sudo reboot

重启完成后检查日志：

cat /home/dev/mt/vllm/model_scripts/model_start.log

如果日志中出现 Application startup complete，通常表示 vLLM 服务已经启动。也可以使用以下命令确认服务健康状态：

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/v1/models

关闭模型开机自启

打开 crontab：

crontab -e

找到自启动配置并注释或删除：

# @reboot bash /home/dev/mt/vllm/model_scripts/start_model.sh

保存后执行：

crontab -l

如果看不到未注释的 @reboot 行，说明模型开机自启已经关闭。