Metadata-Version: 2.4
Name: ai-dynamo
Version: 0.7.1
Summary: Distributed Inference Framework
Project-URL: Repository, https://github.com/ai-dynamo/dynamo.git
Author-email: "NVIDIA Inc." <sw-dl-dynamo@nvidia.com>
License: Apache-2.0
License-File: LICENSE
Keywords: distributed,dynamo,genai,inference,llm,nvidia
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: ai-dynamo-runtime==0.7.1
Requires-Dist: click<8.2.0
Requires-Dist: distro
Requires-Dist: fastapi>=0.115.0
Requires-Dist: filelock
Requires-Dist: kubernetes<33.0.0,>=32.0.1
Requires-Dist: prometheus-client<1.0,>=0.23.1
Requires-Dist: pytest>=8.3.4
Requires-Dist: setuptools
Requires-Dist: transformers<=4.57.1,>=4.56.0
Requires-Dist: typer
Requires-Dist: types-psutil>=7.0.0.20250218
Provides-Extra: sglang
Requires-Dist: nixl[cu12]<=0.7.1; extra == 'sglang'
Requires-Dist: sglang==0.5.4.post3; extra == 'sglang'
Requires-Dist: uvloop; extra == 'sglang'
Provides-Extra: trtllm
Requires-Dist: tensorrt-llm==1.2.0rc3; extra == 'trtllm'
Requires-Dist: uvloop; extra == 'trtllm'
Provides-Extra: vllm
Requires-Dist: nixl[cu12]<=0.7.1; extra == 'vllm'
Requires-Dist: uvloop; extra == 'vllm'
Requires-Dist: vllm[flashinfer]==0.11.0; extra == 'vllm'
Description-Content-Type: text/markdown



![Dynamo banner](./docs/images/frontpage-banner.png)

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![GitHub Release](https://img.shields.io/github/v/release/ai-dynamo/dynamo)](https://github.com/ai-dynamo/dynamo/releases/latest)
[![Discord](https://dcbadge.limes.pink/api/server/D92uqZRjCZ?style=flat)](https://discord.gg/D92uqZRjCZ)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ai-dynamo/dynamo)

| **[Roadmap](https://github.com/ai-dynamo/dynamo/issues/2486)** | **[Support matrix](https://github.com/ai-dynamo/dynamo/blob/main/docs/reference/support-matrix.md)** | **[Documentation](https://docs.nvidia.com/dynamo/latest/index.html)** | **[Examples](https://github.com/ai-dynamo/dynamo/tree/main/examples)** | **[Prebuilt containers](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/ai-dynamo/collections/ai-dynamo)** | **[Design Proposals](https://github.com/ai-dynamo/enhancements)** | **[Blogs](https://developer.nvidia.com/blog/tag/nvidia-dynamo)**

# NVIDIA Dynamo

High-throughput, low-latency inference framework designed for serving generative AI and reasoning models in multi-node distributed environments.

## Latest News

- [08/05] Deploy `openai/gpt-oss-120b` with disaggregated serving on NVIDIA Blackwell GPUs using Dynamo [➡️ link](./docs/backends/trtllm/gpt-oss.md)

## The Era of Multi-GPU, Multi-Node

  Multi Node Multi-GPU topology

Large language models are quickly outgrowing the memory and compute budget of any single GPU. Tensor-parallelism solves the capacity problem by spreading each layer across many GPUs—and sometimes many servers—but it creates a new one: how do you coordinate those shards, route requests, and share KV cache fast enough to feel like one accelerator? This orchestration gap is exactly what NVIDIA Dynamo is built to close.

Dynamo is designed to be inference engine agnostic (supports TRT-LLM, vLLM, SGLang or others) and captures LLM-specific capabilities such as:

- **Disaggregated prefill & decode inference** – Maximizes GPU throughput and facilitates trade off between throughput and latency.
- **Dynamic GPU scheduling** – Optimizes performance based on fluctuating demand
- **LLM-aware request routing** – Eliminates unnecessary KV cache re-computation
- **Accelerated data transfer** – Reduces inference response time using NIXL.
- **KV cache offloading** – Leverages multiple memory hierarchies for higher system throughput

  Dynamo architecture

## Framework Support Matrix

| Feature                                                                                           | vLLM | SGLang | TensorRT-LLM |
| ------------------------------------------------------------------------------------------------- | ---- | ------ | ------------ |
| [**Disaggregated Serving**](/docs/design_docs/disagg_serving.md)                                 | ✅   | ✅     | ✅           |
| [**Conditional Disaggregation**](/docs/design_docs/disagg_serving.md#conditional-disaggregation) | 🚧   | 🚧     | 🚧           |
| [**KV-Aware Routing**](/docs/router/kv_cache_routing.md)                                    | ✅   | ✅     | ✅           |
| [**Load Based Planner**](docs/planner/load_planner.md)                                      | 🚧   | 🚧     | 🚧           |
| [**SLA-Based Planner**](docs/planner/sla_planner.md)                                        | ✅   | ✅     | ✅           |
| [**KVBM**](docs/kvbm/kvbm_architecture.md)                                               | ✅   | 🚧     | ✅           |

To learn more about each framework and their capabilities, check out each framework's README!

- **[vLLM](docs/backends/vllm/README.md)**
- **[SGLang](docs/backends/sglang/README.md)**
- **[TensorRT-LLM](docs/backends/trtllm/README.md)**

Built in Rust for performance and in Python for extensibility, Dynamo is fully open-source and driven by a transparent, OSS (Open Source Software) first development approach.

# Installation

The following examples require a few system level packages.
Recommended to use Ubuntu 24.04 with a x86_64 CPU. See [docs/reference/support-matrix.md](docs/reference/support-matrix.md)

## 1. Initial setup

The Dynamo team recommends the `uv` Python package manager, although any way works. Install uv:

```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Install Python development headers

Backend engines require Python development headers for JIT compilation. Install them with:

```bash
sudo apt install python3-dev
```

### Install etcd and NATS (required)

To coordinate across a data center, Dynamo relies on etcd and NATS. To run Dynamo locally, these need to be available.

- [etcd](https://etcd.io/) can be run directly as `./etcd`.
- [nats](https://nats.io/) needs jetstream enabled: `nats-server -js`.

To quickly setup etcd & NATS, you can also run:

```bash
# At the root of the repository:
docker compose -f deploy/docker-compose.yml up -d
```

## 2. Select an engine

We publish Python wheels specialized for each of our supported engines: vllm, sglang, and trtllm. The examples that follow use SGLang; continue reading for other engines.

```
uv venv venv
source venv/bin/activate
uv pip install pip

# Choose one
uv pip install "ai-dynamo[sglang]"  #replace with [vllm], [trtllm], etc.
```

## 3. Run Dynamo

### Sanity check (optional)

Before trying out Dynamo, you can verify your system configuration and dependencies:

```bash
./deploy/sanity_check.py
```

This is a quick check for system resources, development tools, LLM frameworks, and Dynamo components.

### Running an LLM API server

Dynamo provides a simple way to spin up a local set of inference components including:

- **OpenAI Compatible Frontend** – High performance OpenAI compatible http api server written in Rust.
- **Basic and Kv Aware Router** – Route and load balance traffic to a set of workers.
- **Workers** – Set of pre-configured LLM serving engines.

```
# Start an OpenAI compatible HTTP server, a pre-processor (prompt templating and tokenization) and a router.
# Pass the TLS certificate and key paths to use HTTPS instead of HTTP.
python -m dynamo.frontend --http-port 8000 [--tls-cert-path cert.pem] [--tls-key-path key.pem]

# Start the SGLang engine, connecting to NATS and etcd to receive requests. You can run several of these,
# both for the same model and for multiple models. The frontend node will discover them.
python -m dynamo.sglang --model deepseek-ai/DeepSeek-R1-Distill-Llama-8B
```

#### Send a Request

```bash
curl localhost:8000/v1/chat/completions   -H "Content-Type: application/json"   -d '{
    "model": "deepseek-ai/DeepSeek-R1-Distill-Llama-8B",
    "messages": [
    {
        "role": "user",
        "content": "Hello, how are you?"
    }
    ],
    "stream":false,
    "max_tokens": 300
  }' | jq
```

Rerun with `curl -N` and change `stream` in the request to `true` to get the responses as soon as the engine issues them.

### Deploying Dynamo

- Follow the [Quickstart Guide](docs/kubernetes/README.md) to deploy on Kubernetes.
- Check out [Backends](examples/backends) to deploy various workflow configurations (e.g. SGLang with router, vLLM with disaggregated serving, etc.)
- Run some [Examples](examples) to learn about building components in Dynamo and exploring various integrations.

### Benchmarking Dynamo

Dynamo provides comprehensive benchmarking tools to evaluate and optimize your deployments:

- **[Benchmarking Guide](docs/benchmarks/benchmarking.md)** – Compare deployment topologies (aggregated vs. disaggregated vs. vanilla vLLM) using AIPerf
- **[SLA-Driven Dynamo Deployments](docs/planner/sla_planner_quickstart.md)** – Optimize your deployment to meet SLA requirements

# Engines

Dynamo is designed to be inference engine agnostic. To use any engine with Dynamo, NATS and etcd need to be installed, along with a Dynamo frontend (`python -m dynamo.frontend [--interactive]`).

## vLLM

```
uv pip install ai-dynamo[vllm]
```

Run the backend/worker like this:

```
python -m dynamo.vllm --help
```

vLLM attempts to allocate enough KV cache for the full context length at startup. If that does not fit in your available memory pass `--context-length <value>`.

To specify which GPUs to use set environment variable `CUDA_VISIBLE_DEVICES`.

## SGLang

```
# Install libnuma
apt install -y libnuma-dev

uv pip install ai-dynamo[sglang]
```

Run the backend/worker like this:

```
python -m dynamo.sglang --help
```

You can pass any sglang flags directly to this worker, see https://docs.sglang.ai/advanced_features/server_arguments.html . See there to use multiple GPUs.

## TensorRT-LLM

It is recommended to use [NGC PyTorch Container](https://catalog.ngc.nvidia.com/orgs/nvidia/containers/pytorch) for running the TensorRT-LLM engine.

> [!Note]
> Always match the PyTorch container tag with the TensorRT-LLM version you plan to use. For Dynamo `0.7.0` we validate against `tensorrt-llm==1.2.0rc2` inside `nvcr.io/nvidia/pytorch:25.10-py3`. For other releases, inspect [`container/Dockerfile.trtllm`](container/Dockerfile.trtllm) or the [TensorRT-LLM Dockerfile.multi](https://github.com/NVIDIA/TensorRT-LLM/blob/main/docker/Dockerfile.multi) to find the recommended `BASE_TAG`.

> [!Important]
> Launch container with the following additional settings `--shm-size=1g --ulimit memlock=-1`

### Install prerequisites

```
# Optional step: Only required for Blackwell and Grace Hopper
uv pip install torch==2.7.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

# Required until the trtllm version is bumped to include this pinned dependency itself
uv pip install "cuda-python>=12,<13"

sudo apt-get -y install libopenmpi-dev
```

> [!Tip]
> You can learn more about these prequisites and known issues with TensorRT-LLM pip based installation [here](https://nvidia.github.io/TensorRT-LLM/installation/linux.html).

### Install TensorRT-LLM wheels with `uv`

> [!Warning]
> `uv pip install ai-dynamo[trtllm]` fails for `tensorrt-llm==1.2.0rc2` because the placeholder wheel cannot download the actual artifact from `https://pypi.nvidia.com/`. Use the direct-wheel workflow we ship in [`container/Dockerfile.trtllm`](container/Dockerfile.trtllm#L156).

```bash
export ARCH_ALT=$(uname -m)
export TENSORRTLLM_INDEX_URL="https://pypi.nvidia.com/"
export TENSORRTLLM_PIP_WHEEL="https://pypi.nvidia.com/tensorrt-llm/tensorrt_llm-1.2.0rc2-cp312-cp312-linux_${ARCH_ALT}.whl"

uv pip install --index-strategy=unsafe-best-match \
  --extra-index-url "${TENSORRTLLM_INDEX_URL}" \
  "${TENSORRTLLM_PIP_WHEEL}" \
  triton==3.5.0 \
  "ai-dynamo[trtllm]==0.7.0"
```

> [!Tip]
> If `uv` is not available, `pip install --extra-index-url https://pypi.nvidia.com/ tensorrt-llm==1.2.0rc2` also works, although it downloads more data and is noticeably slower.

Run the backend/worker like this:

```
python -m dynamo.trtllm --help
```

To specify which GPUs to use set environment variable `CUDA_VISIBLE_DEVICES`.

# Developing Locally

## 1. Install libraries

**Ubuntu:**

```
sudo apt install -y build-essential libhwloc-dev libudev-dev pkg-config libclang-dev protobuf-compiler python3-dev cmake
```

**macOS:**

- [Homebrew](https://brew.sh/)

```
# if brew is not installed on your system, install it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

- [Xcode](https://developer.apple.com/xcode/)

```
brew install cmake protobuf

## Check that Metal is accessible
xcrun -sdk macosx metal
```

If Metal is accessible, you should see an error like `metal: error: no input files`, which confirms it is installed correctly.

## 2. Install Rust

```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

## 3. Create a Python virtual env:

Follow the instructions in [uv installation](https://docs.astral.sh/uv/#installation) guide to install uv if you don't have `uv` installed. Once uv is installed, create a virtual environment and activate it.

- Install uv

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

- Create a virtual environment

```bash
uv venv dynamo
source dynamo/bin/activate
```

## 4. Install build tools

```
uv pip install pip maturin
```

[Maturin](https://github.com/PyO3/maturin) is the Rust<->Python bindings build tool.

## 5. Build the Rust bindings

```
cd lib/bindings/python
maturin develop --uv
```

## 6. Install the wheel

```
cd $PROJECT_ROOT
uv pip install -e .
```

You should now be able to run `python -m dynamo.frontend`.

Remember that nats and etcd must be running (see earlier).

Set the environment variable `DYN_LOG` to adjust the logging level; for example, `export DYN_LOG=debug`. It has the same syntax as `RUST_LOG`.

If you use vscode or cursor, we have a .devcontainer folder built on [Microsofts Extension](https://code.visualstudio.com/docs/devcontainers/containers). For instructions see the [ReadMe](.devcontainer/README.md) for more details.
