ai-dynamo/nixl

# NVIDIA 推理 Xfer 库 (NIXL) NVIDIA Inference Xfer Library (NIXL) 旨在加速 AI 推理框架（如 NVIDIA Dynamo）中的点对点通信，同时通过模块化插件架构提供对各种类型内存（例如 CPU 和 GPU）及存储（例如文件、块和对象存储）的抽象。 [](https://opensource.org/licenses/Apache-2.0) [](https://github.com/ai-dynamo/nixl/releases/latest) ## 文档与资源 * [NIXL 概述](https://github.com/ai-dynamo/nixl/blob/main/docs/nixl.md) - 核心概念/架构概览 (`docs/nixl.md`) * [Python API](https://github.com/ai-dynamo/nixl/blob/main/docs/python_api.md) - Python API 使用方法和示例 (`docs/python_api.md`) * [后端指南](https://github.com/ai-dynamo/nixl/blob/main/docs/BackendGuide.md) - 后端/插件开发指南 (`docs/BackendGuide.md`) * [Telemetry](https://github.com/ai-dynamo/nixl/blob/main/docs/telemetry.md) - 可观测性与遥测详情 (`docs/telemetry.md`) * [Doxygen 指南](https://github.com/ai-dynamo/nixl/blob/main/docs/doxygen/nixl_doxygen.md) - API/类图概览 (`docs/doxygen/nixl_doxygen.md`) * [Doxygen 图片](https://github.com/ai-dynamo/nixl/tree/main/docs/doxygen) - 图表资源 (`docs/doxygen/`) * [NIXLBench 文档](https://github.com/ai-dynamo/nixl/blob/main/benchmark/nixlbench/README.md) - 基准测试使用指南 (`benchmark/nixlbench/README.md`) * [KVBench 文档](https://github.com/ai-dynamo/nixl/tree/main/benchmark/kvbench/docs) - KVBench 工作流程与教程 (`benchmark/kvbench/docs/`) ## 支持的平台 NIXL 仅支持 Linux 环境。已在 Ubuntu (22.04/24.04) 和 Fedora 上经过测试。目前不支持 macOS 和 Windows；请使用 Linux 主机或容器/虚拟机 (VM)。 ## 预构建发行版 ### PyPI Wheel 包含 UCX 在内的 nixl python API 和库可直接通过 PyPI 获取。 例如，如果你在 Linux 主机、容器或 VM 上运行 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](https://github.com/NVIDIA/gdrcopy) 可在 Github 上获取，它是实现最大性能所必需的，但 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= \ --with-verbs \ --with-dm \ --with-gdrcopy= $ make -j $ make -j install-strip $ ldconfig ``` ### ETCD (可选) NIXL 可以使用 ETCD 在分布式环境中进行元数据分发和节点间的协调。要在 NIXL 中使用 ETCD： #### 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](src/plugins/mooncake/README.md) - [POSIX](src/plugins/posix/README.md) - [GDS](src/plugins/cuda_gds/README.md) ## 快速入门 ### 构建与安装 ``` $ meson setup $ cd $ ninja $ ninja install ``` ### 构建选项 #### Release 构建 (默认) ``` $ meson setup ``` #### Debug 构建 ``` $ meson setup --buildtype=debug ``` #### NIXL 特定构建选项 ``` # 使用自定义选项的示例 $ meson setup \ -Dbuild_docs=true \ # Build Doxygen documentation -Ducx_path=/path/to/ucx \ # Custom UCX installation path -Dinstall_headers=true \ # Install development headers -Ddisable_gds_backend=false # Enable GDS backend ``` 常用构建选项： - `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 stub 库 ### 构建文档 如果你安装了 Doxygen，可以构建文档： ``` # 配置并启用文档 $ meson setup -Dbuild_docs=true $ cd $ ninja # 文档将生成在 /html 中 # 安装 (ninja install) 后，文档将位于 /share/doc/nixl/ 中 ``` ### Python 接口 NIXL 通过 pybind11 提供 Python 绑定。有关详细的 Python API 文档，请参阅 [docs/python_api.md](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/ `uv` 始终是必需的，*即使*你有其他类型的 Python 虚拟环境管理器，或者你正在使用未使用虚拟环境的系统级 Python 安装。 使用 `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/](examples/python/)。 ### Rust 绑定 #### 构建 - 使用 `-Drust=true` meson 选项来构建 rust 绑定。 - 使用 `--buildtype=debug` 进行 debug 构建 (默认为 release)。 - 或者手动构建： $ cargo build --release #### 安装 绑定将被安装在配置的安装前缀下的 `nixl-sys` 中。 可以使用 ninja 从项目构建目录中完成： ``` $ ninja install ``` #### 测试 ``` # Rust bindings 测试 $ cargo test ``` 通过添加到 `Cargo.toml` 在你的项目中使用： ``` [dependencies] nixl-sys = { path = "path/to/nixl/bindings/rust" } ``` ### 其他构建选项 有关更多构建选项，请参阅 [contrib/README.md](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 ``` 容器还在 /workspace/dist 中包含一个预构建的 python wheel，如果需要用于安装/分发的话。此外，wheel 可以使用单独的脚本构建（见下文）。 ### 构建 python wheel contrib 文件夹还包含一个脚本，用于构建带有 UCX 依赖项的 python wheel。请注意，需要先安装 UCX 和其他 NIXL 依赖项。 ``` $ ./contrib/build-wheel.sh ``` ## 使用 ETCD 运行 NIXL 可以使用 ETCD 在分布式节点之间进行元数据交换。这在容器化或云原生环境中特别有用。 ### 环境设置 要在 NIXL 中使用 ETCD，请设置以下环境变量： ``` # 设置 ETCD endpoints (必需) - 将 localhost 替换为 etcd 服务器的主机名 export NIXL_ETCD_ENDPOINTS="http://localhost:2379" # 设置 ETCD namespace (可选，默认为 /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 环境变量 # 运行示例。示例中的两个 agent 将通过 ETCD 交换 metadata # 并执行数据传输 .//examples/nixl_etcd_example ``` ### nixlbench 基准测试 为了进行更全面的测试，nixlbench 基准测试工具支持使用 ETCD 进行 worker 协调： ``` # 构建 nixlbench (详情参见 benchmark/nixlbench/README.md) cd benchmark/nixlbench meson setup build && cd build && ninja # 使用 ETCD 运行 benchmark ./nixlbench --etcd-endpoints http://localhost:2379 --backend UCX --initiator_seg_type VRAM ``` ## 代码示例 * [C++ 示例](https://github.com/ai-dynamo/nixl/tree/main/examples/cpp) * [Python 示例](https://github.com/ai-dynamo/nixl/tree/main/examples/python) ## 贡献 有关贡献指南，请参阅 [CONTRIBUTING.md](https://github.com/ai-dynamo/nixl/blob/main/CONTRIBUTING.md) (`CONTRIBUTING.md`)。 ## 第三方组件 本项目将下载并安装额外的第三方开源软件项目。在使用前，请查阅这些开源项目的许可条款。

标签：AI推理, Apache 2.0, API集成, C++, CPU-GPU互联, Dynamo, GPU通信, HPC, KVBench, NIXL, Python API, RDMA, Vectored Exception Handling, 内存管理, 分布式推理, 加速库, 可观测性, 可视化界面, 基础设施安全, 大模型推理, 存储抽象, 对象存储, 异构计算, 插件架构, 数据传输库, 数据擦除, 点对点通信, 请求拦截, 逆向工具, 预握手, 高性能计算