安装 SGLang

安装 SGLang#

您可以使用以下任何方法安装 SGLang。

关于运行 DeepSeek V3/R1，请参考 DeepSeek V3 支持。建议使用最新版本并通过 Docker 进行部署，以避免环境相关问题。

建议使用 uv 来安装依赖项，以便更快地安装

方法 1: 使用 pip 或 uv#

pip install --upgrade pip
pip install uv
uv pip install "sglang[all]>=0.4.6.post4"

常见问题的快速修复

  • SGLang 目前使用 torch 2.5，因此您需要安装适用于 torch 2.5 的 flashinfer。如果您想单独安装 flashinfer，请参考 FlashInfer 安装文档。请注意，FlashInfer 的 pypi 包名为 flashinfer-python，而不是 flashinfer。

  • 如果您遇到 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。

  • 如果您遇到 ImportError; cannot import name 'is_valid_list_of_images' from 'transformers.models.llama.image_processing_llama' 错误，请尝试使用 pyproject.toml 中指定的 transformers 版本。目前，只需运行 pip install transformers==4.51.1。

方法 2: 从源代码安装#

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

pip install --upgrade pip
pip install -e "python[all]"

注意：SGLang 目前使用 torch 2.5，因此您需要安装适用于 torch 2.5 的 flashinfer。如果您想单独安装 flashinfer，请参考 FlashInfer 安装文档。

如果您想开发 SGLang，建议使用 docker。请参考 设置 docker 容器 以获取指导。docker 镜像为 lmsysorg/sglang:dev。

注意：对于配备 Instinct/MI GPU 的 AMD ROCm 系统，请执行以下操作

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

pip install --upgrade pip
cd sgl-kernel
python setup_rocm.py install
cd ..
pip install -e "python[all_hip]"

方法 3: 使用 docker#

docker 镜像可在 Docker Hub 上获取，地址为 lmsysorg/sglang，由 Dockerfile 构建。将下面的 <secret> 替换为您的 huggingface hub token。

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

注意：对于配备 Instinct/MI GPU 的 AMD ROCm 系统，建议使用 docker/Dockerfile.rocm 构建镜像，示例如下

docker build --build-arg SGL_BRANCH=v0.4.6.post4 -t v0.4.6.post4-rocm630 -f Dockerfile.rocm .

alias drun='docker run -it --rm --network=host --device=/dev/kfd --device=/dev/dri --ipc=host \
    --shm-size 16G --group-add video --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
    -v $HOME/dockerx:/dockerx -v /data:/data'

drun -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    v0.4.6.post4-rocm630 \
    python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000

# Till flashinfer backend available, --attention-backend triton --sampling-backend pytorch are set by default
drun v0.4.6.post4-rocm630 python3 -m sglang.bench_one_batch --batch-size 32 --input 1024 --output 128 --model amd/Meta-Llama-3.1-8B-Instruct-FP8-KV --tp 8 --quantization fp8

方法 4: 使用 docker compose#

更多

如果您计划将其作为服务提供，建议使用此方法。更好的方法是使用 k8s-sglang-service.yaml。

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

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

方法 5: 使用 Kubernetes#

更多

  1. 选项 1: 用于单节点服务（通常当模型大小适合一个节点的 GPU 时）

    执行命令 kubectl apply -f docker/k8s-sglang-service.yaml，以创建 k8s 部署和服务，此处以 llama-31-8b 为例。

  2. 选项 2: 用于多节点服务（通常当大型模型需要不止一个 GPU 节点时，例如 DeepSeek-R1）

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

方法 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 指南。

常见注意事项#

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

  • 如果您只需要使用前端语言调用 OpenAI 模型，可以通过运行 pip install "sglang[openai]" 来避免安装其他依赖项。

  • 语言前端独立于后端运行时运行。您可以在本地安装前端而无需 GPU，而后端可以安装在具备 GPU 的机器上。要安装前端，运行 pip install sglang；要安装后端，运行 pip install sglang[srt]。srt 是 SGLang 运行时的缩写。

  • 要在本地重新安装 flashinfer，使用以下命令：pip install "flashinfer-python==0.2.5" -i https://flashinfer.ai/whl/cu124/torch2.6 --force-reinstall --no-deps，然后使用 rm -rf ~/.cache/flashinfer 删除缓存。

目录