# 1) 装 maturin（pyo3 官方的构建工具，负责打包 wheel、装进虚拟环境） pip install maturin # 2) 生成项目脚手架：--bindings pyo3 是关键 maturin new --bindings pyo3 fasttext-rs cd fasttext-rs # 3) 目录结构（maturin 会自动生成 pyproject.toml 与 src/lib.rs） # fasttext-rs/ # ├── Cargo.toml # ├── pyproject.toml # Python 侧的打包元数据（模块名、构建后端） # ├── python/ # 纯 Python 包装层（可选，用于加类型提示与友好 API） # └── src/lib.rs # Rust 入口 # 4) 开发：编译并安装到当前虚拟环境（改代码后重新跑一次） maturin develop --release # 5) 发布：产出 wheel，供 pip install maturin build --release # 产物在 target/wheels/，文件名形如 mylib-0.1.0-cp39-abi3-macosx_11_0_arm64.whl

# Cargo.toml [package] name = "fasttext-rs" version = "0.1.0" edition = "2021" [lib] # 扩展模块必须是 cdylib（动态库），不能是 rlib name = "fasttext_rs" # 注意：这个名字就是 Python 里 import 的名字，用下划线 crate-type = ["cdylib"] [dependencies] # abi3-py39：用"受限 API"，一个 wheel 同时支持 CPython 3.9+ # 代价是只能用 PEP 384 保证的那部分 API；绝大多数场景够用 pyo3 = { version = "0.29", features = ["extension-module", "abi3-py39"] } # numpy 互操作：让 pyo3 认识 numpy 数组 numpy = "0.27" # pyproject.toml [build-system] requires = ["maturin>=1.0,<2.0"] build-backend = "maturin" [project] name = "fasttext-rs" requires-python = ">=3.9" [tool.maturin] # 告诉 maturin 这不是普通 bin，而是 pyo3 扩展 bindings = "pyo3" features = ["pyo3/extension-module"]

use pyo3::exceptions::PyValueError; use pyo3::prelude::*; use std::collections::HashMap; /// 用 #[pyfunction] 暴露一个函数。签名会被自动转换成 Python 可调用对象。 // Rust 的返回值会自动转成 Python 对象；出错时返回 PyErr，Python 侧变成异常 #[pyfunction] fn count_tokens(text: &str, sep: char) -> usize { text.split(sep).filter(|s| !s.is_empty()).count() } /// 返回 PyResult 表示"可能抛异常"。错误类型会自动映射成 Python 异常 #[pyfunction] fn parse_id(raw: &str) -> PyResult<u64> { raw.trim() .parse::<u64>() // PyValueError 对应 Python 的 ValueError，比抛 RuntimeError 友好得多 .map_err(|e| PyValueError::new_err(format!("非法 id {raw:?}: {e}"))) } /// 用 #[pyclass] 把 Rust 结构体暴露成 Python 类 // 注意：pyclass 要求字段可通过 getter 访问，字段本身默认不暴露 #[pyclass] struct Counter { counts: HashMap<String, u64>, } #[pymethods] impl Counter { // #[new] 标记的是 Python 的 __init__ #[new] fn new() -> Self { Counter { counts: HashMap::new() } } /// 累加计数。&mut self 在 Python 侧表现为普通方法调用 fn add(&mut self, key: &str) { *self.counts.entry(key.to_string()).or_insert(0) += 1; } // #[getter] 让方法变成属性访问（Python 里写 c.total 而不是 c.total()） #[getter] fn total(&self) -> u64 { self.counts.values().sum() } fn top(&self, py: Python<'_>, n: usize) -> PyResult<Vec<(String, u64)>> { // 返回 Vec 会被转成 Python list；元素是元组则转成 tuple let mut v: Vec<(String, u64)> = self.counts.iter().map(|(k, &c)| (k.clone(), c)).collect(); v.sort_by(|a, b| b.1.cmp(&a.1)); v.truncate(n); // 想让 Python 能做类型标注，可以返回 dict 或自定义类型，见 pyproject 的 stub 生成 Ok(v) } // __repr__ 让 print(obj) 输出可读内容，调试时非常有用 fn __repr__(&self) -> String { format!("Counter(keys={}, total={})", self.counts.len(), self.total()) } } /// #[pymodule] 是模块入口，函数名要和 lib name 一致 // pyo3 0.29 的写法：参数是 &Bound<'_, PyModule>，不再需要传 py #[pymodule] fn fasttext_rs(m: &Bound<'_, PyModule>) -> PyResult<()> { // wrap_pyfunction! 把 Rust 函数包装成 Python 可调用对象再加进模块 m.add_function(wrap_pyfunction!(count_tokens, m)?)?; m.add_function(wrap_pyfunction!(parse_id, m)?)?; m.add_class::<Counter>()?; // 顺手把版本号暴露给 Python，排查"装的是哪个版本"时省事 m.add("__version__", env!("CARGO_PKG_VERSION"))?; Ok(()) }

import fasttext_rs print(fasttext_rs.__version__) print(fasttext_rs.count_tokens("a,b,,c", ",")) # 3 try: fasttext_rs.parse_id("abc") except ValueError as e: # Rust 的 PyValueError 变成了 Python ValueError print("捕获到:", e) c = fasttext_rs.Counter() for w in "the cat the dog the".split(): c.add(w) print(c.total) # 5 —— 注意没有括号，因为用了 #[getter] print(c.top(2)) # [('the', 3), ('cat', 1)] print(repr(c))

use pyo3::prelude::*; /// 反例：整个计算都持有 GIL，其他 Python 线程全部被挡住 #[pyfunction] fn sum_sqrt_bad(data: Vec<f64>) -> f64 { // CPU 密集循环里一直握着 GIL —— 多线程 Python 程序完全无法并行 data.iter().map(|x| x.sqrt()).sum() } /// 正例：把数据搬进 Rust 之后立刻 detach，计算期间把 GIL 让出去 #[pyfunction] fn sum_sqrt(py: Python<'_>, data: Vec<f64>) -> f64 { // 注意：Vec<f64> 已经从 Python 侧拷贝成 Rust 的所有权数据了， // 所以闭包里不再需要访问任何 Python 对象 —— 这是 detach 能成立的前提 py.detach(|| { // 这里没有 GIL，其他 Python 线程可以继续跑 data.iter().map(|x| x.sqrt()).sum() }) } /// detach 内不能碰 Python 对象；如果算到一半要回调 Python，必须重新 attach #[pyfunction] fn batched_with_callback(py: Python<'_>, data: Vec<f64>, cb: PyObject) -> PyResult<f64> { let chunk = 1000; let mut acc = 0.0; for part in data.chunks(chunk) { // 1) 先 detach 做重活，数据是 Rust 自己的，安全 let sub: f64 = py.detach(|| part.iter().map(|x| x.sqrt()).sum()); acc += sub; // 2) 需要调 Python 时，回到持有 GIL 的上下文里调用（这里 py 令牌仍然可用） cb.call1(py, (sub,))?; } Ok(acc) }

use pyo3::exceptions::{PyFileNotFoundError, PyRuntimeError, PyValueError}; use pyo3::prelude::*; use pyo3::{create_exception, exceptions::PyException}; // 策略 1：直接用内置异常类型（推荐用于通用错误） #[pyfunction] fn read_config(path: &str) -> PyResult<String> { std::fs::read_to_string(path).map_err(|e| match e.kind() { // 让 Python 侧能写 except FileNotFoundError，符合它的习惯 std::io::ErrorKind::NotFound => PyFileNotFoundError::new_err(format!("配置文件不存在: {path}")), std::io::ErrorKind::PermissionDenied => PyErr::new::<pyo3::exceptions::PyPermissionError, _>(format!("无权限读取 {path}")), _ => PyRuntimeError::new_err(e.to_string()), }) } // 策略 2：自定义异常类型，让调用方能精确 catch // 生成的 ModelError 可以在 Python 里 from fasttext_rs import ModelError 后 except ModelError create_exception!(fasttext_rs, ModelError, PyException, "模型加载或推理失败"); // 策略 3：用 thiserror 定义 Rust 侧错误，再集中映射一次（中大型项目推荐） #[derive(Debug, thiserror::Error)] pub enum FastTextError { #[error("模型文件损坏: {0}")] CorruptModel(String), #[error("不支持的编码 {0}")] BadEncoding(String), #[error(transparent)] Io(#[from] std::io::Error), } // 实现 From<FastTextError> for PyErr，之后函数里就能直接 `?` impl From<FastTextError> for PyErr { fn from(e: FastTextError) -> Self { match e { // 自定义异常 + 原始信息，两边好处都占 FastTextError::CorruptModel(msg) => ModelError::new_err(msg), FastTextError::BadEncoding(enc) => PyValueError::new_err(format!("编码不支持: {enc}")), FastTextError::Io(e) => e.into(), } } } // 策略 4：Rust panic 的兜底。panic 会被 pyo3 转成 PanicException 抛给 Python， // 但那不是"正常错误" —— 生产代码里应该把可能 panic 的地方改成返回 Result #[pyfunction] fn divide(a: f64, b: f64) -> PyResult<f64> { if b == 0.0 { // 显式返回异常，比让它 panic 好得多 return Err(PyValueError::new_err("除数不能为 0")); } Ok(a / b) }

use numpy::{IntoPyArray, PyArray2, PyArrayMethods, PyReadonlyArray2}; use pyo3::prelude::*; /// 零拷贝：PyReadonlyArray2 借用 numpy 的缓冲区，不复制数据 // 'py 生命周期保证"这个视图不会活过 GIL 的持有期"，所以是安全的 #[pyfunction] fn row_sums<'py>(x: PyReadonlyArray2<'py, f32>) -> Vec<f32> { // as_array 拿到 ndarray 的视图（还是零拷贝） let arr = x.as_array(); // 维度顺序要自己确认：numpy 的 shape 是行优先 [rows, cols] let rows = arr.shape()[0]; let cols = arr.shape()[1]; let mut out = Vec::with_capacity(rows); for r in 0..rows { let mut s = 0.0f32; for c in 0..cols { s += arr[[r, c]]; } out.push(s); } out } /// 返回 numpy 数组：into_pyarray 会把 Rust 的 Array 转成 numpy 数组 // 传 ndarray::Array2 进去可以零拷贝转成 numpy（所有权转移给 Python） #[pyfunction] fn normalize<'py>( py: Python<'py>, x: PyReadonlyArray2<'py, f32>, ) -> Bound<'py, PyArray2<f32>> { let view = x.as_array(); // 计算出一个新的 ndarray（这次确实产生了新内存） let sum = view.sum(); let out = view.mapv(|v| v / sum.max(f32::EPSILON)); // into_pyarray 把 ndarray 的所有权交给 Python，零拷贝 out.into_pyarray(py) } /// 释放 GIL 做重计算：先把数据拷成 Rust 自己的 ndarray，再 detach #[pyfunction] fn heavy_matmul(py: Python<'_>, a: PyReadonlyArray2<'_, f32>, b: PyReadonlyArray2<'_, f32>) -> PyResult<Py<PyArray2<f32>>> { // 关键：to_owned() 把 numpy 缓冲区拷成 Rust 自有内存，之后就可以安全 detach let a = a.as_array().to_owned(); let b = b.as_array().to_owned(); let c = py.detach(|| a.dot(&b)); // 这里没有 GIL，其他线程能跑 // Py<PyArray2> 是 Send 的拥有型句柄，适合从函数里返回或跨线程传递 Ok(c.into_pyarray(py).unbind()) } // 注意一：数组可能是非连续的（切片、转置的结果）， // as_array() 仍能正确处理，但内存访问会慢；性能敏感时先 as_standard_layout() // 注意二：PyReadonlyArray 只读；要原地修改用 PyArray2 的 readonly/writeable 变体 // （需要 Python 侧传入可写数组，否则会抛异常）

# 内嵌模式：绝对不能开 extension-module，否则链接不到 libpython [dependencies] pyo3 = { version = "0.29", features = ["auto-initialize"] } // src/main.rs —— 一个能把业务数据交给 Python 脚本处理的 Rust 服务片段 use pyo3::prelude::*; use pyo3::types::{PyDict, PyList}; fn run_user_script(script_path: &str, records: &[Record]) -> PyResult<Vec<String>> { // attach 拿到 GIL；首次调用会初始化解释器（因为开了 auto-initialize） Python::attach(|py| { // 1) 把脚本文件当模块加载（比 exec 一段字符串更可控，能看到行号） let source = std::fs::read_to_string(script_path) .map_err(|e| pyo3::exceptions::PyIOError::new_err(e.to_string()))?; let module = PyModule::from_code(py, &std::ffi::CString::new(source).unwrap(), script_path, "user_script")?; // 2) 把 Rust 数据转成 Python 列表传进去 let py_records = PyList::empty(py); for r in records { let d = PyDict::new(py); d.set_item("id", &r.id)?; d.set_item("amount", r.amount)?; py_records.append(d)?; } // 3) 调用脚本里的 transform 函数，拿回结果 let func = module.getattr("transform")?; let result = func.call1((py_records,))?; // extract 做类型转换：类型不符会抛 TypeError 而不是 UB result.extract::<Vec<String>>() }) } // 被处理的业务数据需要能转成 Python 对象 struct Record { id: String, amount: f64 } // 一个最容易被忽略的现实约束：内嵌解释器是【进程级单例】， // 高并发下所有请求都在抢同一把 GIL，性能会直接退化成单线程 —— // 所以内嵌 Python 通常只用于"低频、可选、可用脚本化配置"的场景， // 高 QPS 的热路径永远不要走"Rust 内嵌调 Python"

# .github/workflows/release.yml - uses: PyO3/maturin-action@v1 with: # manylinux 是"兼容绝大多数 Linux 发行版"的构建环境（内部用旧 glibc 编译） target: x86_64-unknown-linux-gnu manylinux: auto args: --release --out dist --features pyo3/abi3-py39 - uses: PyO3/maturin-action@v1 with: target: aarch64-apple-darwin # Apple Silicon args: --release --out dist --features pyo3/abi3-py39 - uses: PyO3/maturin-action@v1 with: target: x86_64-pc-windows-msvc args: --release --out dist --features pyo3/abi3-py39 # 用 abi3 之后：3 个平台 × 1 个 Python 版本 = 3 个 wheel， # 不开 abi3 就要 × 6 个 Python 版本 = 18 个 wheel # 最后一步：发布到 PyPI（用 trusted publishing，不要存长期 token） - uses: pypa/gh-action-pypi-publish@release/v1