From 51d3aafe133461acb1b477a62ab29844cbf6e452 Mon Sep 17 00:00:00 2001 From: Alec Flowers Date: Thu, 29 Oct 2026 12:08:12 -0700 Subject: [PATCH 1/2] docs(build): fix protoc, Python and binding features in building-from-source - Step 1: protoc must be 3.15+; Ubuntu 22.04 installs protoc 30.2 from the protobuf releases (apt ships 3.12, which rejects relay.proto). - Step 3: create the venv with Python 3.12; uv downloads it if needed. - Step 5: build the bindings with the release wheel's feature set so dynamo.indexer, slot_tracker and select_service work. - Troubleshooting entries for both errors; zh-CN mirror updated. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Alec Flowers --- .../building-from-source.md | 33 +++++++++++++++++-- .../building-from-source.md | 33 +++++++++++++++++-- 2 files changed, 60 insertions(+), 6 deletions(-) diff --git a/docs/fern/pages/developer-guide/advanced-customizations/building-from-source.md b/docs/fern/pages/developer-guide/advanced-customizations/building-from-source.md index 8657f448cafb..72a5a0a188d6 100644 --- a/docs/fern/pages/developer-guide/advanced-customizations/building-from-source.md +++ b/docs/fern/pages/developer-guide/advanced-customizations/building-from-source.md @@ -18,6 +18,21 @@ This guide covers Ubuntu and macOS. For a containerized dev environment that han sudo apt install -y build-essential libhwloc-dev libudev-dev pkg-config libclang-dev protobuf-compiler python3-dev cmake ``` +Dynamo needs `protoc` 3.15 or newer: + +- **Ubuntu 24.04:** the `protobuf-compiler` package above is enough. +- **Ubuntu 22.04:** also install protoc 30.2 from the protobuf releases: + +```bash +sudo apt install -y unzip +PROTOC_ZIP="protoc-30.2-linux-$(uname -m | sed s/aarch64/aarch_64/).zip" +curl -fsSLO "https://github.com/protocolbuffers/protobuf/releases/download/v30.2/${PROTOC_ZIP}" +unzip -o "${PROTOC_ZIP}" -d "$HOME/.local" +rm "${PROTOC_ZIP}" +export PATH="$HOME/.local/bin:$PATH" +protoc --version +``` + **macOS:** ```bash @@ -42,10 +57,10 @@ Install [uv](https://docs.astral.sh/uv/#installation) if you don't have it: curl -LsSf https://astral.sh/uv/install.sh | sh ``` -Create and activate a virtual environment: +Create and activate a Python 3.12 virtual environment. If Python 3.12 is not installed, uv downloads it. ```bash -uv venv .venv +uv venv --python 3.12 .venv source .venv/bin/activate ``` @@ -59,11 +74,15 @@ uv pip install pip 'maturin[patchelf]' ## 5. Build the Rust Bindings +Build with the same features as the [release wheel](https://github.com/ai-dynamo/dynamo/blob/main/container/templates/wheel_builder.Dockerfile): + ```bash cd lib/bindings/python -maturin develop --uv +maturin develop --uv --features kv-indexer,slot-tracker,select-service,mm-routing,ais-forward-pass,request-trace-s3 ``` +To annotate Nsight Systems profiles, add `nvtx` to the feature list. + ## 6. Install GPU Memory Service ```bash @@ -123,6 +142,14 @@ If `maturin develop` fails with linker errors, verify all system dependencies ar sudo apt install -y build-essential libhwloc-dev libudev-dev pkg-config libclang-dev protobuf-compiler python3-dev cmake ``` +**`protoc failed: relay.proto: This file contains proto3 optional fields`** + +Install protoc 30.2 as shown in step 1, then check that `protoc --version` prints `libprotoc 30.2`. + +**`dynamo.indexer is not available in this build`** + +Rebuild the bindings with the `--features` list from step 5. + **Virtual environment not activated** Maturin builds against the active Python interpreter. If you see errors about Python or site-packages, ensure your virtual environment is activated: diff --git a/docs/fern/translations/zh-CN/pages/developer-guide/advanced-customizations/building-from-source.md b/docs/fern/translations/zh-CN/pages/developer-guide/advanced-customizations/building-from-source.md index 66abb917436e..4ab202608710 100644 --- a/docs/fern/translations/zh-CN/pages/developer-guide/advanced-customizations/building-from-source.md +++ b/docs/fern/translations/zh-CN/pages/developer-guide/advanced-customizations/building-from-source.md @@ -18,6 +18,21 @@ description: 从源代码构建 Dynamo，用于开发和贡献 sudo apt install -y build-essential libhwloc-dev libudev-dev pkg-config libclang-dev protobuf-compiler python3-dev cmake ``` +Dynamo 需要 `protoc` 3.15 或更高版本： + +- **Ubuntu 24.04：** 上面的 `protobuf-compiler` 软件包即可。 +- **Ubuntu 22.04：** 还需从 protobuf releases 安装 protoc 30.2： + +```bash +sudo apt install -y unzip +PROTOC_ZIP="protoc-30.2-linux-$(uname -m | sed s/aarch64/aarch_64/).zip" +curl -fsSLO "https://github.com/protocolbuffers/protobuf/releases/download/v30.2/${PROTOC_ZIP}" +unzip -o "${PROTOC_ZIP}" -d "$HOME/.local" +rm "${PROTOC_ZIP}" +export PATH="$HOME/.local/bin:$PATH" +protoc --version +``` + **macOS：** ```bash @@ -42,10 +57,10 @@ source $HOME/.cargo/env curl -LsSf https://astral.sh/uv/install.sh | sh ``` -创建并激活虚拟环境： +创建并激活 Python 3.12 虚拟环境。如果没有安装 Python 3.12，uv 会自动下载。 ```bash -uv venv .venv +uv venv --python 3.12 .venv source .venv/bin/activate ``` @@ -59,11 +74,15 @@ uv pip install pip 'maturin[patchelf]' ## 5. 构建 Rust 绑定 +使用与[发布版 wheel](https://github.com/ai-dynamo/dynamo/blob/main/container/templates/wheel_builder.Dockerfile) 相同的 features 进行构建： + ```bash cd lib/bindings/python -maturin develop --uv +maturin develop --uv --features kv-indexer,slot-tracker,select-service,mm-routing,ais-forward-pass,request-trace-s3 ``` +如需在 Nsight Systems profile 中添加标注，请在 feature 列表中加上 `nvtx`。 + ## 6. 安装 GPU Memory Service ```bash @@ -123,6 +142,14 @@ pre-commit run --all-files sudo apt install -y build-essential libhwloc-dev libudev-dev pkg-config libclang-dev protobuf-compiler python3-dev cmake ``` +**`protoc failed: relay.proto: This file contains proto3 optional fields`** + +按第 1 步安装 protoc 30.2，然后确认 `protoc --version` 输出 `libprotoc 30.2`。 + +**`dynamo.indexer is not available in this build`** + +使用第 5 步中的 `--features` 列表重新构建绑定。 + **虚拟环境未激活** Maturin 会针对当前激活的 Python 解释器进行构建。如果你看到与 Python 或 site-packages 相关的错误，请确保虚拟环境已激活： From 460600ec5af9eecc6b67e779aad4560f70f81858 Mon Sep 17 00:00:00 2001 From: Alec Flowers Date: Fri, 30 Oct 2026 10:46:49 -0700 Subject: [PATCH 2/2] docs(build): show minimal and release-feature bindings builds Step 5 now offers a plain `maturin develop --uv` first and the release-wheel feature build second, and names what the minimal build leaves out. Same change in the zh-CN mirror. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Alec Flowers --- .../advanced-customizations/building-from-source.md | 11 +++++++++-- .../advanced-customizations/building-from-source.md | 11 +++++++++-- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/fern/pages/developer-guide/advanced-customizations/building-from-source.md b/docs/fern/pages/developer-guide/advanced-customizations/building-from-source.md index 72a5a0a188d6..b425608df9a5 100644 --- a/docs/fern/pages/developer-guide/advanced-customizations/building-from-source.md +++ b/docs/fern/pages/developer-guide/advanced-customizations/building-from-source.md @@ -74,13 +74,20 @@ uv pip install pip 'maturin[patchelf]' ## 5. Build the Rust Bindings -Build with the same features as the [release wheel](https://github.com/ai-dynamo/dynamo/blob/main/container/templates/wheel_builder.Dockerfile): +Run one of these builds: ```bash cd lib/bindings/python + +# Minimal build +maturin develop --uv + +# Build with the same features as the release wheels maturin develop --uv --features kv-indexer,slot-tracker,select-service,mm-routing,ais-forward-pass,request-trace-s3 ``` +The minimal build leaves out the [release wheel](https://github.com/ai-dynamo/dynamo/blob/main/container/templates/wheel_builder.Dockerfile) features: the standalone KV indexer, slot tracker and select service (some router tests start these), multimodal KV routing, the AISimulate perf model and S3 request traces. + To annotate Nsight Systems profiles, add `nvtx` to the feature list. ## 6. Install GPU Memory Service @@ -148,7 +155,7 @@ Install protoc 30.2 as shown in step 1, then check that `protoc --version` print **`dynamo.indexer is not available in this build`** -Rebuild the bindings with the `--features` list from step 5. +Rebuild the bindings with the release-wheel `--features` list from step 5. **Virtual environment not activated** diff --git a/docs/fern/translations/zh-CN/pages/developer-guide/advanced-customizations/building-from-source.md b/docs/fern/translations/zh-CN/pages/developer-guide/advanced-customizations/building-from-source.md index 4ab202608710..83d9979c5ae9 100644 --- a/docs/fern/translations/zh-CN/pages/developer-guide/advanced-customizations/building-from-source.md +++ b/docs/fern/translations/zh-CN/pages/developer-guide/advanced-customizations/building-from-source.md @@ -74,13 +74,20 @@ uv pip install pip 'maturin[patchelf]' ## 5. 构建 Rust 绑定 -使用与[发布版 wheel](https://github.com/ai-dynamo/dynamo/blob/main/container/templates/wheel_builder.Dockerfile) 相同的 features 进行构建： +任选以下一种构建方式： ```bash cd lib/bindings/python + +# Minimal build +maturin develop --uv + +# Build with the same features as the release wheels maturin develop --uv --features kv-indexer,slot-tracker,select-service,mm-routing,ais-forward-pass,request-trace-s3 ``` +最小构建不包含[发布版 wheel](https://github.com/ai-dynamo/dynamo/blob/main/container/templates/wheel_builder.Dockerfile) 的以下 features：独立的 KV indexer、slot tracker 和 select service（部分 router 测试会启动它们）、多模态 KV 路由、AISimulate 性能模型以及 S3 请求追踪。 + 如需在 Nsight Systems profile 中添加标注，请在 feature 列表中加上 `nvtx`。 ## 6. 安装 GPU Memory Service @@ -148,7 +155,7 @@ sudo apt install -y build-essential libhwloc-dev libudev-dev pkg-config libclang **`dynamo.indexer is not available in this build`** -使用第 5 步中的 `--features` 列表重新构建绑定。 +使用第 5 步中发布版 wheel 的 `--features` 列表重新构建绑定。 **虚拟环境未激活**