NVIDIA 推理传输库 (NIXL)

NVIDIA 推理传输库 (NIXL) 旨在加速 NVIDIA Dynamo 等 AI 推理框架中的点对点通信，同时通过模块化的插件架构为多种类型的内存（例如 CPU 和 GPU）以及存储（例如文件、块和对象存储）提供抽象层。

文档与资源

• NIXL 概述 - 核心概念/架构概述 (docs/nixl.md)

• Python API - Python API 的使用方法及示例 (docs/python_api.md)

• 后端指南 - 后端/插件开发指南 (docs/BackendGuide.md)

• 遥测 - 可观测性与遥测细节 (docs/telemetry.md)

• Doxygen 指南 - API/类图概览 (docs/doxygen/nixl_doxygen.md)

• Doxygen 图片 - 图表资源 (docs/doxygen/)

• NIXLBench 文档 - 基准测试使用指南 (benchmark/nixlbench/README.md)

• KVBench 文档 - KVBench 工作流与教程 (benchmark/kvbench/docs/)

支持的平台

NIXL 目前仅支持 Linux 环境。已在 Ubuntu (22.04/24.04) 和 Fedora 上进行过测试。macOS 和 Windows 当前不支持；请使用 Linux 主机或容器/虚拟机。

预编译发行版

PyPI Wheel

nixl 的 Python API 和库（包括 UCX）可以直接通过 PyPI 获得。 例如，如果您在 Linux 主机、容器或虚拟机上运行 GPU，可以执行以下安装命令：

对于 CUDA 12，可执行：

pip install nixl[cu12]

对于 CUDA 13，可执行：

pip install nixl[cu13]

为保持向后兼容性，pip install nixl 将自动安装 nixl[cu12]，继续无缝兼容 CUDA 12 用户，而无需更改下游项目的依赖项。

如果环境中同时安装了 nixl-cu12 和 nixl-cu13，则优先使用 nixl-cu13。

源码构建的先决条件（Linux）

Ubuntu:

$ sudo apt install build-essential cmake pkg-config

Fedora:

$ sudo dnf install gcc-c++ cmake pkg-config

Python

$ pip3 install meson ninja pybind11 tomlkit

UCX

NIXL 已在 UCX 1.20.x 版本上进行了测试。

GDRCopy 在 GitHub 上可用，对于实现最佳性能至关重要，但即使没有 GDRCopy，UCX 和 NIXL 也能正常工作。

$ git clone https://github.com/openucx/ucx.git
$ cd ucx
$ git checkout v1.20.x
$ ./autogen.sh
$ ./contrib/configure-release-mt       \
    --enable-shared                    \
    --disable-static                   \
    --disable-doxygen-doc              \
    --enable-optimizations             \
    --enable-cma                       \
    --enable-devel-headers             \
    --with-cuda=<cuda 安装路径>         \
    --with-verbs                       \
    --with-dm                          \
    --with-gdrcopy=<gdrcopy 安装路径>
$ make -j
$ make -j install-strip
$ ldconfig

ETCD（可选）

NIXL 可以使用 ETCD 在分布式环境中进行元数据分发和节点间协调。要将 ETCD 与 NIXL 结合使用：

ETCD 服务器和客户端

$ sudo apt install etcd etcd-server etcd-client

# 或者使用 Docker
$ docker run -d -p 2379:2379 quay.io/coreos/etcd:v3.5.1

ETCD CPP API

从 https://github.com/etcd-cpp-apiv3/etcd-cpp-apiv3 安装。

$ sudo apt install libgrpc-dev libgrpc++-dev libprotobuf-dev protobuf-compiler-grpc
$ sudo apt install libcpprest-dev
$ git clone https://github.com/etcd-cpp-apiv3/etcd-cpp-apiv3.git
$ cd etcd-cpp-apiv3
$ mkdir build && cd build
$ cmake ..
$ make -j$(nproc) && make install

其他插件

部分插件可能有额外的构建要求，请参阅以下内容：

• Mooncake
• POSIX
• GDS

开始使用

构建与安装

$ meson setup <构建目录名称>
$ cd <构建目录名称>
$ ninja
$ ninja install

构建选项

发布版本（默认）

$ meson setup <构建目录名称>

调试版本

$ meson setup <构建目录名称> --buildtype=debug

NIXL 特定的构建选项

# 示例：自定义选项
$ meson setup <构建目录名称> \
    -Dbuild_docs=true \           # 构建 Doxygen 文档
    -Ducx_path=/path/to/ucx \     # 自定义 UCX 安装路径
    -Dinstall_headers=true \      # 安装开发头文件
    -Ddisable_gds_backend=false   # 启用 GDS 后端

常见构建选项：

• build_docs: 构建 Doxygen 文档（默认：false）
• ucx_path: UCX 安装路径（默认：系统路径）
• install_headers: 安装开发头文件（默认：true）
• disable_gds_backend: 禁用 GDS 后端（默认：false）
• cudapath_inc, cudapath_lib: 自定义 CUDA 路径
• static_plugins: 以逗号分隔的静态构建插件列表
• enable_plugins: 以逗号分隔的启用插件列表（例如 -Denable_plugins=UCX,POSIX）。不能与 disable_plugins 同时使用。
• disable_plugins: 以逗号分隔的禁用插件列表（例如 -Ddisable_plugins=GDS）。不能与 enable_plugins 同时使用。

环境变量

有几个环境变量可用于配置构建：

• NIXL_NO_STUBS_FALLBACK: 如果未设置或设为 0，则在库构建失败时构建 NIXL 存根库。

构建文档

如果您已安装 Doxygen，可以构建文档：

# 配置时启用文档生成
$ meson setup <构建目录名称> -Dbuild_docs=true
$ cd <构建目录名称>
$ ninja

# 文档将生成在 <构建目录名称>/html 中
# 安装完成后（ninja install），文档将在 <prefix>/share/doc/nixl/ 中可用

Python 接口

NIXL 通过 pybind11 提供了 Python 绑定。有关详细的 Python API 文档，请参阅 docs/python_api.md。

安装 Python 绑定的首选方式是从 PyPI 使用 pip：

pip install nixl[cu12]

或者对于 CUDA 13 版本：

pip install nixl[cu13]

从源码安装

先决条件：

• uv：https://docs.astral.sh/uv/getting-started/installation/
• tomlkit：https://pypi.org/project/tomlkit/
• PyTorch：https://pytorch.org/get-started/locally/

即使您使用其他类型的 Python 虚拟环境管理器，或直接使用系统范围的 Python 安装而不使用虚拟环境，uv 仍然是必需的。

使用 uv 创建 Python 虚拟环境的示例：

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:${PATH}"

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install tomlkit

使用 python-virtualenv 的示例：

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:${PATH}"

python3 -m venv .venv
source .venv/bin/activate
pip install tomlkit

不使用虚拟环境而直接使用系统范围 Python 安装的示例：

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:${PATH}"

pip install tomlkit

然后按照 PyTorch 官网上的说明安装 PyTorch：https://pytorch.org/get-started/locally/

安装完先决条件后，您可以从源码构建并安装 NIXL 二进制文件和 Python 绑定。您需要执行以下步骤：

1. 构建并安装 NIXL 二进制文件。
2. 构建并安装特定于 CUDA 平台的包（nixl-cu12 或 nixl-cu13）。
3. 构建并安装 nixl 元包。

对于 CUDA 12：

pip install .
meson setup build
ninja -C build install
pip install build/src/bindings/python/nixl-meta/nixl-*-py3-none-any.whl

对于 CUDA 13：

pip install .
./contrib/tomlutil.py --wheel-name nixl-cu13 pyproject.toml
meson setup build
ninja -C build install
pip install build/src/bindings/python/nixl-meta/nixl-*-py3-none-any.whl

要检查安装是否成功，可以运行以下命令：

python3 -c "import nixl; agent = nixl.nixl_agent('agent1')"

如果安装成功，应输出：

2026-01-08 13:36:27 NIXL INFO    _api.py:363 Backend UCX was instantiated
2026-01-08 13:36:27 NIXL INFO    _api.py:253 Initialized NIXL agent: agent1

您还可以运行一个完整的 Python 示例来测试安装：

python3 examples/python/expanded_two_peers.py --mode=target --use_cuda=true --ip=127.0.0.1 --port=4242 &
sleep 5
python3 examples/python/expanded_two_peers.py --mode=initiator --use_cuda=true --ip=127.0.0.1 --port=4242

更多 Python 示例请参阅 examples/python/。

Rust 绑定

构建

• 使用 -Drust=true meson 选项来构建 Rust 绑定。
• 使用 --buildtype=debug 进行调试构建（默认为 release）。
• 或者手动构建：

  $ cargo build --release
  

安装

绑定将被安装到配置的安装前缀下的 nixl-sys 目录中。 可以通过 ninja 从项目构建目录完成安装：

$ ninja install

测试

# Rust 绑定测试
$ cargo test

在您的项目中使用时，只需在 Cargo.toml 中添加：

[dependencies]
nixl-sys = { path = "path/to/nixl/bindings/rust" }

其他构建选项

更多构建选项请参阅 contrib/README.md。

构建 Docker 容器

要构建 Docker 容器，首先克隆当前仓库。此外，在尝试构建容器之前，请确保您能够拉取 Docker 镜像到本地机器。

在克隆的 NIXL 仓库根目录下运行以下命令：

$ ./contrib/build-container.sh

默认情况下，容器基于 Ubuntu 24.04 构建。若要构建适用于 Ubuntu 22.04 的容器，请使用 --os 选项，如下所示：

$ ./contrib/build-container.sh --os ubuntu22

要查看容器支持的所有选项，可以运行：

$ ./contrib/build-container.sh -h

容器还包含预构建的 Python wheel 文件，位于 /workspace/dist 目录下，便于安装或分发。此外，也可以使用单独的脚本构建该 wheel 文件（见下文）。

构建 Python wheel 文件

contrib 文件夹中还包含一个用于构建带有 UCX 依赖项的 Python wheel 文件的脚本。请注意，UCX 和其他 NIXL 依赖项必须已安装。

$ ./contrib/build-wheel.sh

使用 ETCD 运行

NIXL 可以使用 ETCD 在分布式节点之间交换元数据。这在容器化或云原生环境中尤为有用。

环境设置

要将 ETCD 与 NIXL 结合使用，需设置以下环境变量：

# 设置 ETCD 端点（必填）——将 localhost 替换为 ETCD 服务器的主机名
export NIXL_ETCD_ENDPOINTS="http://localhost:2379"

# 设置 ETCD 命名空间（可选，默认为 /nixl/agents）
export NIXL_ETCD_NAMESPACE="/nixl/agents"

运行 ETCD 示例

NIXL 包含一个演示使用 ETCD 进行元数据交换和数据传输的示例：

# 如果尚未运行 ETCD 服务器，请启动一个
# 例如：
# docker run -d -p 2379:2379 quay.io/coreos/etcd:v3.5.1

# 按照上述方法设置 ETCD 环境变量

# 运行示例。示例中的两个代理将通过 ETCD 交换元数据，并执行数据传输
./<nixl_build_path>/examples/nixl_etcd_example

nixlbench 基准测试

为了进行更全面的测试，nixlbench 基准测试工具支持使用 ETCD 进行工作节点协调：

# 构建 nixlbench（详情请参阅 benchmark/nixlbench/README.md）
cd benchmark/nixlbench
meson setup build && cd build && ninja

# 使用 ETCD 运行基准测试
./nixlbench --etcd-endpoints http://localhost:2379 --backend UCX --initiator_seg_type VRAM

代码示例

• C++ 示例

• Python 示例

贡献指南

有关贡献指南，请参阅 CONTRIBUTING.md（CONTRIBUTING.md）。

第三方组件

本项目会下载并安装额外的第三方开源软件项目。在使用这些开源项目之前，请务必查看其许可证条款。

NIXL 快速上手指南

NVIDIA Inference Xfer Library (NIXL) 是一个用于加速 AI 推理框架中点对点通信的库，支持多种内存（CPU/GPU）和存储后端的抽象。

1. 环境准备

系统要求

• 操作系统：仅支持 Linux（推荐 Ubuntu 22.04/24.04 或 Fedora）。
• 硬件：需要 NVIDIA GPU 环境。
• 不支持：macOS 和 Windows。

前置依赖安装

Ubuntu:

sudo apt install build-essential cmake pkg-config

Fedora:

sudo dnf install gcc-c++ cmake pkg-config

Python 工具链:

pip3 install meson ninja pybind11 tomlkit

可选依赖 (ETCD - 用于分布式元数据协调):

# 使用 apt 安装
sudo apt install etcd etcd-server etcd-client

# 或使用 Docker 运行
docker run -d -p 2379:2379 quay.io/coreos/etcd:v3.5.1

注意：若需从源码构建高性能版本，还需手动编译安装 UCX (v1.20.x) 和 GDRCopy，具体步骤请参考官方文档。大多数用户建议直接使用 PyPI 预编译包。

2. 安装步骤

方式一：通过 PyPI 安装（推荐）

这是最简单的方式，已包含 UCX 等核心依赖。

对于 CUDA 12 用户:

pip install nixl[cu12]

对于 CUDA 13 用户:

pip install nixl[cu13]

提示：直接运行 pip install nixl 默认会安装 CUDA 12 版本以保持向后兼容。如果环境中同时存在 cu12 和 cu13 包，cu13 优先。

方式二：从源码构建

如果你需要自定义插件或开发后端，可从源码构建。

1. 配置与编译:

meson setup <build_dir>
cd <build_dir>
ninja
sudo ninja install

2. 常用构建选项示例:

meson setup <build_dir> \
    -Dbuild_docs=true \
    -Ducx_path=/path/to/ucx \
    -Denable_plugins=UCX,POSIX

3. 安装 Python 绑定 (源码方式): 需先安装 uv 和 tomlkit，然后执行：

# CUDA 12 示例
pip install .
meson setup build
ninja -C build install
pip install build/src/bindings/python/nixl-meta/nixl-*-py3-none-any.whl

3. 基本使用

验证安装

运行以下命令检查是否安装成功：

python3 -c "import nixl; agent = nixl.nixl_agent('agent1')"

成功输出示例：

2026-01-08 13:36:27 NIXL INFO    _api.py:363 Backend UCX was instantiated
2026-01-08 13:36:27 NIXL INFO    _api.py:253 Initialized NIXL agent: agent1

简单通信示例

NIXL 支持多进程/多节点间的点对点数据传输。以下是一个简单的双节点测试示例（需在支持 CUDA 的环境中运行）：

终端 1 (启动目标节点):

python3 examples/python/expanded_two_peers.py --mode=target --use_cuda=true --ip=127.0.0.1 --port=4242 &

等待 5 秒后，在终端 2 (启动发起节点):

sleep 5
python3 examples/python/expanded_two_peers.py --mode=initiator --use_cuda=true --ip=127.0.0.1 --port=4242

分布式环境配置 (可选)

如果在集群或容器化环境中使用 ETCD 进行元数据交换，需设置以下环境变量：

export NIXL_ETCD_ENDPOINTS="http://<etcd-server-ip>:2379"
export NIXL_ETCD_NAMESPACE="/nixl/agents"

更多高级用法（如 Rust 绑定、自定义后端开发）请参考项目 docs/ 目录下的详细文档。