1. 主页

使用 SGLang 推理引擎

在 DGX Spark 上安装并使用 SGLang

基本思路

SGLang 是一个面向大型语言模型和视觉语言模型的快速服务框架，它通过协同设计后端运行时和前端语言，使您与模型的交互更加快速和可控。此配置在采用 Blackwell 架构的单个 NVIDIA Spark 设备上使用优化的 NVIDIA SGLang NGC 容器，提供 GPU 加速推理，并且所有依赖项均已预装。

您将完成

您将在 NVIDIA Spark 设备上以服务器和离线推理模式部署 SGLang，从而实现高性能的 LLM 服务，支持文本生成、聊天补全和使用 DeepSeek-V2-Lite 等模型的视觉语言任务。

前置知识

  • 熟悉 Linux 系统的终端环境操作

  • 了解 Docker 容器和容器管理

  • 熟悉 NVIDIA GPU 驱动程序和 CUDA 工具包概念

  • 熟悉 HTTP API 端点和 JSON 请求/响应处理

先决条件

  • 采用 Blackwell 架构的 NVIDIA Spark 设备

  • 已安装 Docker Engine 并正在运行：docker --version

  • 已安装 NVIDIA GPU 驱动程序：nvidia-smi

  • 已配置 NVIDIA Container Toolkit ：docker run --rm --gpus all lmsysorg/sglang:spark nvidia-smi

  • 足够的磁盘空间（可用空间大于 20GB）：df -h

  • 具备拉取 NGC 容器的网络连接：ping nvcr.io

辅助文件

模型支持矩阵

以下模型在 Spark 上受 SGLang 支持。所有列出的模型可随时可用：

模型
量化方案
支持状态
Hugging Face 标识
DeepSeek-R1-Distill-Qwen-7B
FP8
Checkmark
RedHatAI/DeepSeek-R1-Distill-Qwen-7B-FP8-dynamic
DeepSeek-R1-Distill-Qwen-14B
BF16
Checkmark
deepseek-ai/DeepSeek-R1-Distill-Qwen-14B
DeepSeek-V2-Lite
BF16
Checkmark
deepseek-ai/DeepSeek-V2-Lite
Qwen3-8B
FP8
Checkmark
nvidia/Qwen3-8B-FP8
Qwen3-8B
NVFP4
Checkmark
nvidia/Qwen3-8B-FP4
Qwen3-14B
FP8
Checkmark
nvidia/Qwen3-14B-FP8
Qwen3-14B
NVFP4
Checkmark
nvidia/Qwen3-14B-FP4
Qwen3-32B
NVFP4
Checkmark
nvidia/Qwen3-32B-FP4

注意：

对于 NVFP4 模型，请添加 --quantization modelopt_fp4 参数。

时间和风险

  • 预计时间：初始设置和验证需要 大约 1 小时

  • 风险等级：低 - 使用预构建、经过验证的 SGLang 容器，配置极少

  • 回滚：使用 docker stop 和 docker rm 停止并移除容器

  • 最后更新时间：2026年1月2日

    • 添加模型支持矩阵

第 1 步 – 验证系统先决条件

请先确认您的 NVIDIA Spark 设备满足所有要求再继续操作。此步骤将在您的主机系统上运行，以确保 Docker、GPU 驱动程序和容器工具包已正确配置。

# Verify Docker installation
docker --version

# Check NVIDIA GPU drivers
nvidia-smi

# Verify Docker GPU support
docker run --rm --gpus all lmsysorg/sglang:spark nvidia-smi

# Check available disk space
df -h /

如果您看到权限被拒绝错误（例如尝试连接到 Docker 守护程序套接字时出现权限被拒绝的错误），请将您的用户添加到 docker 组，这样您就不需要使用 sudo 运行命令了。

sudo usermod -aG docker $USER
newgrp docker

第 2 步 – 拉取 SGLang 容器

下载最新的 SGLang 容器。此步骤在主机上运行，​​根据您的网络连接速度，可能需要几分钟时间。

# Pull the SGLang container
docker pull lmsysorg/sglang:spark

# Verify the image was downloaded
docker images | grep sglang

第 3 步 - 启动 SGLang 容器以进入服务器模式

以服务器模式启动 SGLang 容器，启用 HTTP API 访问。这将在容器内运行推理服务器，并将其暴露在 30000 端口上以供客户端连接。

# Launch container with GPU support and port mapping
docker run --gpus all -it --rm \
  -p 30000:30000 \
  -v /tmp:/tmp \
  lmsysorg/sglang:spark \
  bash

第 4 步 - 启动 SGLang 推理服务器

在容器内，使用支持的模型启动 HTTP 推理服务器。此步骤在 Docker 容器内运行，并启动 SGLang 服务器守护进程。

# Start the inference server with DeepSeek-V2-Lite model
python3 -m sglang.launch_server \
  --model-path deepseek-ai/DeepSeek-V2-Lite \
  --host 0.0.0.0 \
  --port 30000 \
  --trust-remote-code \
  --tp 1 \
  --attention-backend flashinfer \
  --mem-fraction-static 0.75 &

# Wait for server to initialize
sleep 30

# Check server status
curl http://localhost:30000/health

第 5 步 - 测试客户端-服务器端推理

在主机系统的新终端中，测试 SGLang 服务器 API，确保其正常工作。这将验证服务器是否接受请求并生成响应。

# Test with curl
curl -X POST http://localhost:30000/generate \
  -H "Content-Type: application/json" \
  -d '{
      "text": "What does NVIDIA love?",
      "sampling_params": {
          "temperature": 0.7,
          "max_new_tokens": 100
      }
  }'

第 6 步 - 测试 Python 客户端 API

创建一个简单的 Python 脚本来测试通过编程方式访问 SGLang 服务器。该脚本在主机系统上运行，演示如何将 SGLang 集成到应用程序中。

import requests

# Send prompt to server
response = requests.post('http://localhost:30000/generate', json={
  'text': 'What does NVIDIA love?',
  'sampling_params': {
      'temperature': 0.7,
      'max_new_tokens': 100,
  },
})

print(f"Response: {response.json()['text']}")

第 7 步 - 验证安装

确认服务器模式和离线模式均运行正常。此步骤验证 SGLang 的完整配置，确保可靠运行。

# Check server mode (from host)
curl http://localhost:30000/health
curl -X POST http://localhost:30000/generate -H "Content-Type: application/json" \
  -d '{"text": "Hello", "sampling_params": {"max_new_tokens": 10}}'

# Check container logs
docker ps
docker logs <CONTAINER_ID>

第 8 步 - 清理和回滚

停止并移除容器以清理资源。此步骤会将系统恢复到初始状态。

警告：

这将停止所有 SGLang 容器并删除临时数据。

# Stop all SGLang containers
docker ps | grep sglang | awk '{print $1}' | xargs docker stop

# Remove stopped containers
docker container prune -f

# Remove SGLang images (optional)
docker rmi lmsysorg/sglang:spark

第 9 步 - 后续步骤

SGLang 部署成功后，您现在可以：

  • 使用 /generate 端点，将 HTTP API 集成到您的应用程序中

  • 通过更改 --model-path 参数尝试不同的模型

  • 通过调整 --tp（张量并行），利用多个 GPU 进行扩展

  • 使用您选择的容器编排平台部署生产工作负载

常见问题及其解决方案：

错误
原因
修复
容器启动失败，出现 GPU 错误
缺少 NVIDIA 驱动程序/工具包
安装 nvidia-container-toolkit，重启 Docker
服务器响应 404 或连接被拒绝
服务器尚未完全初始化
等待 60 秒，检查容器日志
模型加载过程中出现内存不足错误
GPU 内存不足
使用较小的模型或提高 --tp 参数
模型下载失败
网络连接问题
请检查网络连接，重试下载
访问 /tmp 目录的权限被拒绝
卷挂载问题
使用完整路径：-v /tmp:/tmp 或创建专用目录

注意：

DGX Spark 使用统一内存架构 (UMA)，支持 GPU 和 CPU 之间的动态内存共享。由于许多应用程序仍在更新以利用 UMA，即使在 DGX Spark 的内存容量范围内，您也可能会遇到内存问题。如果发生这种情况，请手动刷新缓冲区缓存：

sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'

资源

SGLang 文档

DGX Spark 文档

DGX Spark 论坛