Getting Started

本地安装

以 Markdown 格式查看

本指南介绍如何在配备一个或多个 GPU 或 XPU 的本地机器或 VM 上安装并运行 Dynamo。完成后，你将拥有一个可工作的 OpenAI 兼容端点，用于提供模型服务。

对于生产环境的多节点集群，请参阅 Kubernetes 部署指南。如需为开发从源码构建，请参阅从源码构建。

系统要求

要求支持范围
GPUNVIDIA Ampere、Ada Lovelace、Hopper、Blackwell
OSUbuntu 22.04、Ubuntu 24.04
架构x86_64、ARM64（ARM64 需要 Ubuntu 24.04）
CUDA12.9+ 或 13.0+（B300/GB300 需要 CUDA 13）
Python3.10、3.12
驱动575.51.03+（CUDA 12）或 580.00.03+（CUDA 13）

TensorRT-LLM 不支持 Python 3.11。

如需查看包含后端框架版本在内的完整兼容性矩阵，请参阅支持矩阵。

安装 Dynamo

选项 A：容器（推荐）

容器已预安装所有依赖项。无需额外设置。

$# SGLang
$docker run --gpus all --network host --rm -it nvcr.io/nvidia/ai-dynamo/sglang-runtime:1.2.1
$
$# TensorRT-LLM
$docker run --gpus all --network host --rm -it nvcr.io/nvidia/ai-dynamo/tensorrtllm-runtime:1.2.1
$
$# vLLM
$docker run --gpus all --network host --rm -it nvcr.io/nvidia/ai-dynamo/vllm-runtime:1.2.1

如需在同一个容器中运行 frontend 和 worker，可选择：

  • 使用 & 在后台运行进程（请参阅下方“运行 Dynamo”部分），或
  • 打开第二个终端并使用 docker exec -it <container_id> bash

如需查看可用版本，请参阅发布产物； 如需运行说明，请参阅各后端指南：SGLang | TensorRT-LLM | vLLM

选项 B：从 PyPI 安装

仅支持 vLLM 和 SGLang。TensorRT-LLM 请使用选项 A。

$# Install uv (recommended Python package manager)
$curl -LsSf https://astral.sh/uv/install.sh | sh
$
$# Create virtual environment
$uv venv venv
$source venv/bin/activate
$uv pip install pip

为你选择的后端安装系统依赖项和 Dynamo wheel：

SGLang

$sudo apt install python3-dev
$uv pip install --prerelease=allow "ai-dynamo[sglang]"

vLLM

$sudo apt install python3-dev libxcb1
$uv pip install --prerelease=allow "ai-dynamo[vllm]"

运行 Dynamo

发现后端

Dynamo 组件通过共享后端相互发现。可使用两个选项：

后端何时使用设置
File单机、本地开发无需设置 — 将 --discovery-backend file 传递给所有组件。事件平面会自动默认使用 ZMQ（无需 NATS）。
etcd多节点、生产环境需要正在运行的 etcd 实例（如果未指定标志，则为默认值）。事件平面默认使用 NATS。

本指南使用 --discovery-backend file。如需设置 etcd，请参阅服务发现。

验证安装（可选）

验证 CLI 已安装并可调用：

$python3 -m dynamo.frontend --help

如果你克隆了仓库，可以运行其他系统检查：

$python3 dev/sanity_check.py

启动 Frontend

$# Start the OpenAI compatible frontend (default port is 8000)
$python3 -m dynamo.frontend --discovery-backend file

如需在单个终端中运行（在容器中很有用），追加 > logfile.log 2>&1 & 以在后台运行进程：

$python3 -m dynamo.frontend --discovery-backend file > dynamo.frontend.log 2>&1 &

启动 Worker

在另一个终端中（如果使用后台模式，也可以在同一个终端中），为你选择的加速器和后端启动 worker：

SGLang

$python3 -m dynamo.sglang --model-path Qwen/Qwen3-0.6B --discovery-backend file

TensorRT-LLM

$python3 -m dynamo.trtllm --model-path Qwen/Qwen3-0.6B --discovery-backend file

在这种本地单机设置中，警告 Cannot connect to ModelExpress server/transport error. Using direct download. 是预期行为（没有正在运行的 ModelExpress server），可以安全忽略。在配置了 MODEL_EXPRESS_URL 的 Kubernetes 部署中， 此警告，或相关的 Failed to resolve local model path after server download， 表示已配置 ModelExpress，但它实际上没有提供缓存模型； 请参阅 Kubernetes 中的模型缓存 了解正确配置。

vLLM

$python3 -m dynamo.vllm --model Qwen/Qwen3-0.6B --discovery-backend file

测试你的部署

$curl localhost:8000/v1/chat/completions \
>  -H "Content-Type: application/json" \
>  -d '{"model": "Qwen/Qwen3-0.6B",
>       "messages": [{"role": "user", "content": "Hello!"}],
>       "max_tokens": 50}'

故障排除

CUDA/驱动版本不匹配

运行 nvidia-smi 检查你的驱动版本。Dynamo 对 CUDA 12 需要驱动 575.51.03+，对 CUDA 13 需要驱动 580.00.03+。B300/GB300 GPU 需要 CUDA 13。完整要求请参阅支持矩阵。

模型无法装入 GPU（OOM）

默认模型 Qwen/Qwen3-0.6B 需要约 2GB GPU 内存。更大的模型需要更多 VRAM：

模型大小近似 VRAM
7B14-16 GB
13B26-28 GB
70B140+ GB（多 GPU）

从小模型开始，并根据你的硬件逐步扩展。

TensorRT-LLM

TensorRT-LLM 仅支持容器路径。请使用 tensorrtllm-runtime 容器（选项 A）。

容器运行但未检测到 GPU

确保你向 docker run 传递了 --gpus all。如果没有此标志，容器将无法访问 GPU：

$# Correct
$docker run --gpus all --network host --rm -it nvcr.io/nvidia/ai-dynamo/sglang-runtime:1.2.1
$
$# Wrong -- no GPU access
$docker run --network host --rm -it nvcr.io/nvidia/ai-dynamo/sglang-runtime:1.2.1

vLLM worker 启动失败：FlashInfer sampler 的 JIT 与 CUDA 13 wheels

在 CUDA 13 安装环境下运行 vLLM worker 时，worker 可能在启动阶段因 FlashInfer JIT 错误而中止：

RuntimeError: Engine core initialization failed.
...
cuda/std/__cccl/cuda_toolkit.h:41: error: "CUDA compiler and CUDA toolkit headers are incompatible"

为 CUDA 13 安装解析出的 CUDA wheels 可能存在版本偏差：torch 将运行时头文件锁定到 13.0，而 vLLM 的 tilelang 依赖会拉取 nvidia-cuda-nvcc 13.2。FlashInfer 使用 nvcc 针对这些头文件编译其 sampler 内核，版本不匹配会导致构建失败。此问题在上游 flashinfer#3493 中追踪。

设置 VLLM_USE_FLASHINFER_SAMPLER=0，让 vLLM 回退到原生 sampler：

$export VLLM_USE_FLASHINFER_SAMPLER=0

后续步骤