Inference Cookbook
Inference Cookbook

Rust-Python 互操作

Rust-Python 互操作基础

本文档介绍 Rust 与 Python 之间的互操作技术，为理解 Dynamo Python SDK 的实现奠定基础。

1. 为什么需要跨语言互操作

1.1 Dynamo 的技术选型

在设计 Dynamo 时，团队面临一个核心抉择：

语言优势劣势
Rust极致性能、内存安全、并发能力ML 生态较弱
PythonML/AI 生态主流、开发效率高性能较低、GIL 限制

最终方案是 Rust 核心 + Python 接口：

graph TB subgraph python["Python 应用层"] W["VllmWorker"] P["Processor"] R["Router"] end subgraph sdk["Dynamo SDK"] S["@service"] E["@dynamo_endpoint"] D["depends()"] end subgraph bindings["PyO3 Bindings"] DR["DistributedRuntime"] NS["Namespace"] CO["Component"] EP["Endpoint"] end subgraph rust["Rust Core Runtime"] TK["Tokio"] ET["etcd"] NA["NATS"] TC["TCP Pipeline"] end python --> sdk sdk --> bindings bindings --> rust

1.2 分层设计优势

用户友好                     性能优化
    ↑                          ↑
┌─────────────────────────────────────────────┐
│              Python 应用层                    │
│   - 直观的装饰器 API                          │
│   - 与 ML 生态无缝集成                        │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│              PyO3 绑定层                      │
│   - 类型安全的跨语言调用                       │
│   - 自动 GIL 管理                            │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│              Rust 核心运行时                   │
│   - 高性能异步 I/O                           │
│   - 零拷贝数据传输                            │
└─────────────────────────────────────────────┘

2. FFI 基础知识

2.1 Foreign Function Interface

FFI（Foreign Function Interface）是不同编程语言之间相互调用的机制：

graph LR subgraph lang1["语言 A"] A1["函数调用"] end subgraph ffi["FFI 层"] B1["ABI 转换"] B2["类型映射"] B3["内存管理"] end subgraph lang2["语言 B"] C1["目标函数"] end A1 --> B1 B1 --> B2 B2 --> B3 B3 --> C1

2.2 传统 FFI 方式

传统的 Rust-Python 互操作需要多个步骤：

// 1. Rust 代码编译为 C ABI 兼容的动态库
#[no_mangle]
pub extern "C" fn add_numbers(a: i32, b: i32) -> i32 {
    a + b
}
# 2. Python 使用 ctypes 调用
import ctypes

lib = ctypes.CDLL("./libmylib.so")
lib.add_numbers.argtypes = [ctypes.c_int32, ctypes.c_int32]
lib.add_numbers.restype = ctypes.c_int32

result = lib.add_numbers(1, 2)  # 3

这种方式的问题：

问题说明
类型不安全需要手动声明参数类型
复杂类型困难字符串、结构体处理繁琐
内存管理手动容易内存泄漏
无异常支持错误处理复杂

3. PyO3 框架

3.1 PyO3 简介

PyO3 是 Rust 生态中最成熟的 Python 绑定框架：

graph TB subgraph pyo3["PyO3 特性"] A["声明式宏"] B["类型安全"] C["GIL 管理"] D["异步支持"] end subgraph rust["Rust 代码"] E["#[pyclass]"] F["#[pymethods]"] G["#[pyfunction]"] end subgraph python["Python 模块"] H["类"] I["方法"] J["函数"] end A --> E A --> F A --> G E --> H F --> I G --> J

3.2 核心宏介绍

#[pyclass] - 定义 Python 类

#[pyclass]
struct Calculator {
    value: f64,
}

#[pymethods] - 定义方法

#[pymethods]
impl Calculator {
    // 构造函数
    #[new]
    fn new(initial: f64) -> Self {
        Calculator { value: initial }
    }

    // 实例方法
    fn add(&mut self, x: f64) {
        self.value += x;
    }

    // 带返回值的方法
    fn get_value(&self) -> f64 {
        self.value
    }

    // 静态方法
    #[staticmethod]
    fn create_zero() -> Self {
        Calculator { value: 0.0 }
    }
}

#[pyfunction] - 定义独立函数

#[pyfunction]
fn fibonacci(n: u32) -> u64 {
    match n {
        0 => 0,
        1 => 1,
        _ => fibonacci(n - 1) + fibonacci(n - 2),
    }
}

3.3 在 Python 中使用

from my_rust_module import Calculator, fibonacci

# 使用类
calc = Calculator(10.0)
calc.add(5.0)
print(calc.get_value())  # 15.0

# 使用函数
print(fibonacci(10))  # 55

4. GIL 管理

4.1 什么是 GIL

GIL（Global Interpreter Lock）是 Python 的全局解释器锁：

graph TB subgraph gil["GIL 工作原理"] T1["线程 1"] -->|等待| GIL["GIL 锁"] T2["线程 2"] -->|持有| GIL T3["线程 3"] -->|等待| GIL end subgraph effect["影响"] E1["同一时刻只有一个线程执行 Python 字节码"] E2["I/O 操作时自动释放"] E3["C 扩展可以手动释放"] end

4.2 PyO3 中的 GIL 处理

// 需要 GIL 的操作
fn with_gil(py: Python<'_>) {
    // 可以访问 Python 对象
    let dict = PyDict::new(py);
    dict.set_item("key", "value").unwrap();
}

// 释放 GIL 执行耗时操作
fn release_gil(py: Python<'_>) {
    py.allow_threads(|| {
        // 这里不能访问 Python 对象
        // 但可以并行执行 Rust 代码
        expensive_rust_computation();
    });
}

4.3 GIL 管理最佳实践

flowchart TD A["开始执行"] --> B{"需要访问
Python 对象?"} B -->|是| C["持有 GIL"] B -->|否| D["释放 GIL"] C --> E["访问 Python 对象"] D --> F["执行 Rust 计算"] E --> G{"还需要
Python 对象?"} F --> H["获取 GIL"] G -->|是| E G -->|否| D H --> I["返回结果"]
场景GIL 策略
访问 Python 对象必须持有 GIL
纯 Rust 计算释放 GIL
调用 Python 回调重新获取 GIL
长时间 I/O释放 GIL

5. 异步互操作

5.1 Rust Future 与 Python Coroutine

graph LR subgraph rust["Rust 异步"] RF["Future"] RR["Tokio Runtime"] end subgraph bridge["pyo3-async-runtimes"] B["future_into_py"] end subgraph python["Python 异步"] PC["Coroutine"] PR["asyncio"] end RF --> B B --> PC RR -.->|执行| RF PR -.->|调度| PC

5.2 转换实现

fn async_operation<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
    let data = self.inner.clone();

    // 将 Rust Future 转换为 Python coroutine
    pyo3_async_runtimes::tokio::future_into_py(py, async move {
        // 异步执行 Rust 代码
        let result = data.do_async_work().await?;

        // 返回值自动转换为 Python 对象
        Ok(result)
    })
}

在 Python 中使用：

import asyncio

async def main():
    runtime = DistributedRuntime(...)
    # 调用返回 coroutine
    namespace = await runtime.namespace("myns")
    component = await namespace.component("mycomp")

asyncio.run(main())

5.3 异步迭代器

对于流式响应，需要实现异步迭代器：

#[pyclass]
struct ResponseStream {
    inner: rs::ResponseStream,
}

#[pymethods]
impl ResponseStream {
    // __aiter__ 返回自身
    fn __aiter__(slf: PyRef<'_, Self>) -> PyRef<'_, Self> {
        slf
    }

    // __anext__ 返回下一个元素
    fn __anext__<'py>(&mut self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyAny>>> {
        let stream = self.inner.clone();

        pyo3_async_runtimes::tokio::future_into_py(py, async move {
            match stream.next().await {
                Some(Ok(item)) => Ok(Some(item)),
                Some(Err(e)) => Err(PyErr::new::<PyRuntimeError, _>(e.to_string())),
                None => Ok(None),  // 流结束
            }
        })
    }
}

Python 使用：

async for response in client.generate(request):
    print(response.text)

6. Maturin 构建工具

6.1 Maturin 简介

Maturin 是专门用于构建 Rust Python 扩展的工具：

graph LR subgraph input["输入"] RS["Rust 源码"] PY["Python 源码"] TM["pyproject.toml"] end subgraph maturin["Maturin"] B["编译 Rust"] P["打包 Python"] end subgraph output["输出"] WH["wheel 包"] end RS --> B PY --> P TM --> B TM --> P B --> WH P --> WH

6.2 项目配置

# pyproject.toml
[build-system]
requires = ["maturin>=1.0,<2.0"]
build-backend = "maturin"

[project]
name = "dynamo"
version = "0.1.0"

[tool.maturin]
module-name = "dynamo._core"
python-source = "python"
features = ["pyo3/extension-module"]

6.3 常用命令

命令说明
maturin develop开发模式，安装到当前环境
maturin build --release构建发布版 wheel
maturin publish发布到 PyPI
maturin build --target x86_64-unknown-linux-gnu交叉编译

6.4 构建流程

sequenceDiagram participant Dev as 开发者 participant Mat as Maturin participant Cargo as Cargo participant Pip as pip Dev->>Mat: maturin develop Mat->>Cargo: cargo build Cargo-->>Mat: .so/.dylib Mat->>Mat: 打包为 wheel Mat->>Pip: pip install Pip-->>Dev: 安装完成

7. 类型映射

7.1 基础类型映射

Rust 类型Python 类型
i32, i64, u32, u64int
f32, f64float
boolbool
Stringstr
Vec<T>list
HashMap<K, V>dict
Option<T>`T
Result<T, E>T (错误转为异常)

7.2 复杂类型转换

#[pyclass]
struct Config {
    #[pyo3(get, set)]
    name: String,

    #[pyo3(get, set)]
    values: Vec<i32>,

    #[pyo3(get, set)]
    metadata: HashMap<String, String>,
}

#[pymethods]
impl Config {
    #[new]
    fn new(name: String) -> Self {
        Config {
            name,
            values: Vec::new(),
            metadata: HashMap::new(),
        }
    }
}

总结

Rust-Python 互操作的关键要点：

  1. PyO3 框架：提供声明式宏，简化绑定编写
  2. GIL 管理：正确处理 GIL 以保证线程安全和性能
  3. 异步支持：pyo3-async-runtimes 桥接 Rust/Python 异步
  4. Maturin 构建：简化打包和发布流程

这套技术栈让 Dynamo 能够同时享受 Rust 的性能和 Python 的易用性。

参考资料

2026年1月29日
GitHub
PyO3 绑定实现