Rust 项目如何配置 ONNX Runtime 库获取策略（ORT_RUST_STRATEGY 的 download、system 与 compile）-育师

Rust 项目如何配置 ONNX Runtime 库获取策略（ORT_RUST_STRATEGY 的 download、system 与 compile）

【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime

在 Rust 项目中集成 ONNX Runtime 时，最先要解决的问题是构建阶段去哪里找 ONNX Runtime 动态库：onnxruntime-rs的构建脚本 build.rs 会在cargo build时根据环境变量ORT_RUST_STRATEGY选择不同的库获取策略——download（从上游下载预编译包）、system（指向本机已安装的版本）、compile（从源码编译）。本文基于 rust/README.md 和 rust/BUILD.md 说明三种策略的配置方法、适用条件，以及如何用示例程序验证配置是否生效。

onnxruntime-rs 由两个 crate 组成（见 rust/Cargo.toml 工作区定义）：

onnxruntime-sys：C API 的低层绑定；
onnxruntime：高层安全 API。

库的获取逻辑全部在onnxruntime-sys的构建脚本中执行，两种策略之外的细节（支持的平台、报错信息）也都能从该文件确认。

三种策略各自解决什么问题

prepare_libort_dir()会读取ORT_RUST_STRATEGY，取值与行为对应如下：

取值	行为	配套环境变量
`download`	下载预编译的 onnxruntime 包并解压到构建目录（`target`下的`onnxruntime`子目录）	`ORT_RUST_USE_CUDA=1`可下载 CUDA 版本
`system`	直接使用本机已安装的版本	`ORT_RUST_LIB_LOCATION`指向安装路径
`compile`	用 cmake 从 vendored 源码编译出共享库（`onnxruntime_BUILD_SHARED_LIB=ON`，CUDA 时追加`onnxruntime_USE_CUDA=ON`）	无

关于默认值，文档内部存在一处不一致：rust/README.md 写明 “compile: To compile the library. This is the default.”，而 build.rs 中未设置ORT_RUST_STRATEGY（Err(_)分支）时实际走的是prepare_libort_dir_compiled()的注释虽写着 download 是默认，但Ok("download")分支才是显式 download 的入口——两处表述冲突，本文不替文档统一口径。建议显式设置ORT_RUST_STRATEGY，不依赖默认行为。

准备条件

Rust 工具链（cargo、rustc），获取方式按 rust/BUILD.md 指引到 rustup.rs；
compile策略额外需要：cmake、Python 3 解释器、clang（用于解析 C 头文件生成绑定）、平台编译器；
system策略需要本机已有 onnxruntime 安装，并知道其安装路径；
如果要在 onnxruntime 仓库内部构建 Rust 绑定（如运行集成测试），需要完整克隆仓库并初始化子模块：

git clone https://github.com/microsoft/onnxruntime cd onnxruntime git submodule update --init --recursive

策略一：download（预编译包）

设置环境变量后构建即可，构建脚本会按目标平台拼接预编译包文件名并下载、解压：

ORT_RUST_STRATEGY=download cargo build --manifest-path rust/Cargo.toml

构建脚本能识别的平台组合（超出范围会直接 panic 并提示改用system策略）：

CPU：Linux x86_64、macOS x86_64、macOS aarch64、Windows i686、Windows x86_64（rust/README.md 给出的支持列表）；
GPU（CUDA）：Linux x86_64、Windows x86_64，需额外设置ORT_RUST_USE_CUDA=1（仅支持 Linux 或 Windows）：

ORT_RUST_STRATEGY=download ORT_RUST_USE_CUDA=1 cargo build --manifest-path rust/Cargo.toml

下载的包名由三元组（OS、架构、加速器）和版本号拼成，版本号读取自 rust/onnxruntime-sys/vendor/onnxruntime-src/VERSION_NUMBER 中include_str!的文件，因此 vendored 目录需要先就位（见 compile 策略一节）。不支持的平台组合会报出类似Unsupported prebuilt triplet: ...的 panic，提示Please use ORT_RUST_STRATEGY=system and ORT_RUST_LIB_LOCATION=/path/to/onnxruntime。

注意：download策略需要访问网络（构建脚本用 ureq 发起下载，超时 300 秒），离线环境应改用system或compile。

策略二：system（本机已安装的库）

ORT_RUST_LIB_LOCATION指向 onnxruntime 安装目录（脚本取该目录下的include与lib子目录用于生成绑定和链接）：

ORT_RUST_STRATEGY=system ORT_RUST_LIB_LOCATION=/path/to/onnxruntime cargo build --manifest-path rust/Cargo.toml

其中/path/to/onnxruntime需替换为你本机 onnxruntime 安装的实际路径。

rust/README.md 特别提示：system策略下，运行构建出的二进制（例如测试）时，如果库不在系统库路径中，至少 macOS 上会加载失败，报错形如（文档示例）：

dyld: Library not loaded: @rpath/libonnxruntime.1.7.1.dylib Referenced from: onnxruntime-rs.git/target/debug/deps/onnxruntime_sys-22eb0e3e89a0278c Reason: image not found

文档给出两种修复方式，任选其一：

设置LD_LIBRARY_PATH指向库所在路径；
在项目.cargo/config中加入 linker flag，提供完整路径（文档示例，/full/path/to/onnxruntime/lib需替换为你本机库路径）：

[target.aarch64-apple-darwin] rustflags = ["-C", "link-args=-Wl,-rpath,/full/path/to/onnxruntime/lib"]

策略三：compile（从源码编译）

该策略通过 cmake 构建 vendored 的 onnxruntime 源码（onnxruntime-sys/vendor/onnxruntime-src），并开启onnxruntime_BUILD_SHARED_LIB；设置ORT_RUST_USE_CUDA为1/yes/true/on之一时追加onnxruntime_USE_CUDA=ON。

前提是把 onnxruntime 仓库内容复制进 vendor 目录。rust/justfile 的vendor配方（在rust/目录下执行just vendor）会执行：mkdir -p ./onnxruntime-sys/vendor/onnxruntime-src，然后拷贝../onnxruntime、../cmake、../include、../tools/ci_build、../samples、../requirements.txt.in、../VERSION_NUMBER到 vendor 目录，并删除vendor/onnxruntime-src/cmake/external/onnx。该配方会把仓库根目录的文件复制到rust/onnxruntime-sys/vendor/下，不修改这些源文件本身。

之后正常构建：

ORT_RUST_STRATEGY=compile cargo build --manifest-path rust/Cargo.toml

由于会完整编译 onnxruntime 本体，所需依赖见上文“准备条件”（cmake、Python 3、clang、平台编译器），耗时也最长。

验证配置是否生效

配置完成后，文档给出的验证路径是运行示例程序或集成测试。

方式一：运行示例（rust/README.md Example 一节）

先下载示例模型 SqueezeNet 1.0（ONNX version 1.3, Opset 8）：

curl -LO "https://github.com/onnx/models/raw/main/vision/classification/squeezenet/model/squeezenet1.0-8.onnx"

再运行高层 API 示例 rust/onnxruntime/examples/sample.rs：

cargo run --example sample

该示例加载本地squeezenet1.0-8.onnx，对输入/输出形状做了断言（输入[1, 3, 224, 224]，输出[1, 1000, 1, 1]），成功时打印各类别的 Score（README 中的完整输出为文档示例，数值随运行时环境变化，不应作为固定预期）。低层 crate 对应示例是c_api_sample：

cargo run --example c_api_sample

方式二：仓库内构建并跑测试（rust/BUILD.md）

在 onnxruntime 仓库根目录执行：

CARGO_TARGET_DIR=build/rust cargo build --manifest-path rust/Cargo.toml

CARGO_TARGET_DIR只是把产物放到onnxruntime/build/rust而不是rust/target。测试命令：

CARGO_TARGET_DIR=build/rust cargo test --manifest-path rust/Cargo.toml --features model-fetching

也可以显式指定共享库绝对路径（运行时由 rust/onnxruntime/tests/integration_tests.rs 通过RUST_ONNXRUNTIME_LIBRARY_PATH加载，示例程序同理）：

RUST_ONNXRUNTIME_LIBRARY_PATH=<absolute path to shared library/libonnxruntime.so> CARGO_TARGET_DIR=build/rust cargo test --manifest-path rust/Cargo.toml --features model-fetching

其中<absolute path to shared library/libonnxruntime.so>需替换为共享库的实际绝对路径。集成测试会下载模型、执行推理并校验结果（model-fetchingfeature 用于从 ONNX Model Zoo 拉取模型，见 rust/onnxruntime/Cargo.toml）。

限制与注意事项

rust/README.md 明确标注：这是实验性、进行中的工作，not complete/working/safe；基础推理可用，但 ONNX Runtime 很多控制推理过程的选项尚未暴露；
download策略的平台支持范围有限，超出的平台组合构建会 panic 并建议改走system；
system策略在 macOS 上运行产物时可能出现上文 dyld 报错，需按文档设置LD_LIBRARY_PATH或 rpath；
构建脚本对ORT_RUST_STRATEGY做了rerun-if-env-changed注册，切换策略后需要重新构建才会生效；
默认值在 README 与 build.rs 注释间不一致（README 称compile为默认，build.rs 注释称download为默认），请显式设置环境变量。

如果你的目标平台不在预编译支持列表内，或者仓库内的 Rust 绑定尚不满足需求（例如缺少所需的推理选项），可以先用system策略指向自行安装的 onnxruntime 版本验证 API 行为，再决定是否提交 issue 或自行扩展绑定。

【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考