安装 SGLang

安装 SGLang#

您可以使用以下方法之一安装 SGLang。

本页面主要适用于常见的 NVIDIA GPU 平台。对于其他或较新的平台，请参阅 AMD GPU、Intel Xeon CPU、TPU、NVIDIA DGX Spark、NVIDIA Jetson、昇腾 NPU 和 Intel XPU 的专用页面。

方法 1：使用 pip 或 uv#

推荐使用 uv 以获得更快的安装速度

pip install --upgrade pip
pip install uv
uv pip install "sglang" --prerelease=allow

常见问题的快速修复

  • 如果您遇到 OSError: CUDA_HOME environment variable is not set。请通过以下任一方案将其设置为您的 CUDA 安装根目录

    1. 使用 export CUDA_HOME=/usr/local/cuda-<your-cuda-version> 来设置 CUDA_HOME 环境变量。

    2. 先按照 FlashInfer 安装文档 安装 FlashInfer，然后再按上述方法安装 SGLang。

方法 2：从源码安装#

# Use the last release branch
git clone -b v0.5.6.post2 https://github.com/sgl-project/sglang.git
cd sglang

# Install the python packages
pip install --upgrade pip
pip install -e "python"

常见问题的快速修复

  • 如果您想开发 SGLang，可以尝试开发版 Docker 镜像。请参考 设置 Docker 容器。Docker 镜像为 lmsysorg/sglang:dev。

方法 3：使用 Docker#

Docker 镜像可在 Docker Hub 上的 lmsysorg/sglang 获取，基于 Dockerfile 构建。请将下方的 <secret> 替换为您的 HuggingFace Hub 令牌。

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000

对于生产部署，请使用 runtime 变体镜像，它通过排除构建工具和开发依赖项，体积显著减小（减少约 40%）

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest-runtime \
    python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000

您也可以在 此处 找到 nightly（每日构建）版 Docker 镜像。

方法 4：使用 Kubernetes#

请查看 OME，这是一个用于大型语言模型（LLM）企业级管理和推理服务的 Kubernetes Operator。

更多

  1. 选项 1：用于单节点推理（通常在模型大小可放入单个节点内的 GPU 时）

    执行命令 kubectl apply -f docker/k8s-sglang-service.yaml，以创建 K8s Deployment 和 Service（以 llama-3.1-8b 为例）。

  2. 选项 2：用于多节点推理（通常当大型模型需要多个 GPU 节点时，例如 DeepSeek-R1）

    根据需要修改 LLM 模型路径和参数，然后执行命令 kubectl apply -f docker/k8s-sglang-distributed-sts.yaml，以创建两个节点的 K8s StatefulSet 和推理服务。

方法 5：使用 Docker Compose#

更多

如果您计划将其作为一项服务来运行，推荐使用此方法。更好的方法是使用 k8s-sglang-service.yaml。

  1. 将 compose.yml 复制到您的本地机器

  2. 在终端中执行命令 docker compose up -d。

方法 6：通过 SkyPilot 在 Kubernetes 或云端运行#

更多

要在 Kubernetes 或 12 个以上的云平台上部署，您可以使用 SkyPilot。

  1. 安装 SkyPilot 并设置 Kubernetes 集群或云访问权限：参见 SkyPilot 文档。

  2. 通过单个命令在您自己的基础设施上部署并获取 HTTP API 端点

SkyPilot YAML：sglang.yaml 
# sglang.yaml
envs:
  HF_TOKEN: null

resources:
  image_id: docker:lmsysorg/sglang:latest
  accelerators: A100
  ports: 30000

run: |
  conda deactivate
  python3 -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000

# Deploy on any cloud or Kubernetes cluster. Use --cloud <cloud> to select a specific cloud provider.
HF_TOKEN=<secret> sky launch -c sglang --env HF_TOKEN sglang.yaml

# Get the HTTP API endpoint
sky status --endpoint 30000 sglang

  1. 要通过自动扩缩容和故障恢复进一步扩展部署规模，请查看 SkyServe + SGLang 指南。

方法 7：在 AWS SageMaker 上运行#

更多

要在 AWS SageMaker 上部署 SGLang，请查看 AWS SageMaker Inference

要使用您自己的容器托管模型，请按照以下步骤操作

  1. 使用 sagemaker.Dockerfile 以及 serve 脚本构建 Docker 容器。

  2. 将您的容器推送到 AWS ECR。

Dockerfile 构建脚本：build-and-push.sh 
#!/bin/bash
AWS_ACCOUNT="<YOUR_AWS_ACCOUNT>"
AWS_REGION="<YOUR_AWS_REGION>"
REPOSITORY_NAME="<YOUR_REPOSITORY_NAME>"
IMAGE_TAG="<YOUR_IMAGE_TAG>"

ECR_REGISTRY="${AWS_ACCOUNT}.dkr.ecr.${AWS_REGION}.amazonaws.com"
IMAGE_URI="${ECR_REGISTRY}/${REPOSITORY_NAME}:${IMAGE_TAG}"

echo "Starting build and push process..."

# Login to ECR
echo "Logging into ECR..."
aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${ECR_REGISTRY}

# Build the image
echo "Building Docker image..."
docker build -t ${IMAGE_URI} -f sagemaker.Dockerfile .

echo "Pushing ${IMAGE_URI}"
docker push ${IMAGE_URI}

echo "Build and push completed successfully!"

  1. 在 AWS SageMaker 上部署模型进行推理，请参考 deploy_and_serve_endpoint.py。欲了解更多信息，请查看 sagemaker-python-sdk。

    1. 默认情况下，SageMaker 上的模型服务器将运行以下命令：python3 -m sglang.launch_server --model-path opt/ml/model --host 0.0.0.0 --port 8080。这是在 SageMaker 上托管您自己模型的最佳方式。

    2. 若要修改模型服务参数，通过指定带有 SM_SGLANG_ 前缀的环境变量，serve 脚本允许使用 python3 -m sglang.launch_server --help 命令行中的所有可用选项。

    3. 服务脚本会自动将所有带有 SM_SGLANG_ 前缀的环境变量从 SM_SGLANG_INPUT_ARGUMENT 转换为 --input-argument，以便由 python3 -m sglang.launch_server 命令行解析。

    4. 例如，要使用推理（reasoning）解析器运行 Qwen/Qwen3-0.6B，只需添加额外的环境变量 SM_SGLANG_MODEL_PATH=Qwen/Qwen3-0.6B 和 SM_SGLANG_REASONING_PARSER=qwen3。

常见注意事项#

  • FlashInfer 是默认的注意力机制内核后端。它仅支持 sm75 及以上架构。如果您在 sm75+ 设备（例如 T4、A10、A100、L4、L40S、H100）上遇到任何 FlashInfer 相关问题，请通过添加 --attention-backend triton --sampling-backend pytorch 切换到其他内核，并在 GitHub 上提交 issue。

  • 要在本地重新安装 flashinfer，请使用以下命令：pip3 install --upgrade flashinfer-python --force-reinstall --no-deps，然后使用 rm -rf ~/.cache/flashinfer 删除缓存。

目录