aria-engine (Python)
aria-engine 是 Aria 推理引擎的 Python SDK（ctypes 封装 libaria_ffi）。
通过 PyPI 安装的 平台 wheel 内已捆绑动态库，开箱即用，无需手动设置环境变量。
安装（PyPI 发布版）
pip install aria-engine
支持 Linux (x86_64 / aarch64 manylinux)、macOS (x86_64 / arm64)、Windows (x86_64)， Python 3.10+。wheel 内自带
libaria_ffi.so/.dylib/.dll。
用法
from aria_engine import Engine
with Engine("/path/to/bundle") as eng:
print(eng.complete([{"role":"user","content":"hi"}], {"max_tokens": 16}))
按模型名自动下载
Engine 同时接受本地 bundle 路径或 Aria 模型名（如 gemma-4-e2b-it_q4）。含 /
或本地已存在的值直接加载；否则由 SDK 从本区公开 hub 自动下载（.com → Hugging Face，
.cn → ModelScope；site 默认 https://ariacompute.com）到 ~/.ariacompute/models/{model} 再加载。
不再请求 Dashboard（避免 HTTP 403）。需授权的 hub 文件请传入 hf_token（.com）或
modelscope_api_token（.cn），字段名与 aria-engine setup 相同；未传则读
~/.ariacompute/engine.yml。Dashboard sk- / bfvk- token 不会当作 hub 凭证。
不读环境变量 HF_TOKEN / MODELSCOPE_API_TOKEN。
缓存中已有有效 bundle 时直接复用，不重复下载。
with Engine("gemma-4-e2b-it_q4") as eng:
print(eng.complete([{"role":"user","content":"hi"}], {"max_tokens": 16}))
# Gated Hugging Face files (instance setup; does not write engine.yml):
eng = Engine()
eng.setup(hf_token="hf_...")
eng.open("gemma-4-e2b-it_q4")
print(eng.complete([{"role":"user","content":"hi"}], {"max_tokens": 16}))
Engine.setup sets Config / Run fields on that instance only. CLI aria-engine setup still writes ~/.ariacompute/engine.yml; the SDK never does. Empty fields still fall back to reading that file for hub download. Also: eng.setup_status(), eng.setup_clear().
动态库查找顺序
_load_lib() 按以下顺序解析：
- 显式传入的
path - 环境变量
ARIA_FFI_LIB（源码安装 / 自定义路径时使用） - wheel 内捆绑的
aria_engine/lib/<libaria_ffi.so|dylib|dll> ~/.ariacompute/lib/（与aria-engine upgrade相同目录）- 都找不到 → 从本区 Releases 下载最新正式版
libaria_ffi_{ver}_{os}.tar.gz解压到~/.ariacompute/lib/（upgrade_url优先；否则.com→ GitHub，.cn→ Gitee）。失败明确报错。
aria-engine download 只拉模型 bundle，不会装 FFI；Python SDK 在 Engine(...) 加载前自动补齐。
源码安装（开发）
export ARIA_FFI_LIB=/path/to/libaria_ffi.so
pip install -e .
构建 wheel（cibuildwheel）
bash scripts/build-python-ffi.sh # 编译 libaria_ffi 并拷入 aria_engine/lib/
pip install cibuildwheel
cibuildwheel --platform linux # 或 macos / windows
发布到 PyPI
GitHub Release 触发 .github/workflows/publish-pypi.yml：五平台构建 + twine upload。
需要仓库 Secret PYPI_TOKEN（PyPI API token，project-scoped，owner ariacompute）。
版本号取 tag 去 v（也支持 workflow_dispatch 手动输入）。
1 maintainer
Metadata
1 maintainer
Release files for aria-engine 1.18.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 30.1 MB
Release files / aria_engine-1.18.0-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.18.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
0cd44c397b6dbbe0f289209ee169e7b6482c312c7ebf28e42233254488f08667
|
|
BLAKE2b-256 checksum How to use checksums |
0a86bbf9736f5bccdf990db3d0db9f0794c9eef0b2827a24416c9fb4634c9ce8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.18.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | CPython 3.13 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
75168bcaee30665a1683f288ed526899f8df6e6578edacd5fde45c7b4ce7851b
|
|
BLAKE2b-256 checksum How to use checksums |
5718afa9023b6e5b173da68e327ce3420a179d3a39163b3e646c4211ed9f6e99
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.18.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.13 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
96ea35790287ca99b901426aa301aca1510fb30a0a0a3c341bc5622dcc4d34d0
|
|
BLAKE2b-256 checksum How to use checksums |
fb93e77c4447164692300138b51f840eee59064dc8a970c33cedab6aa63ca724
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.18.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
9efc3bff1e43d13cfb5e479e44befdbf7351a94c3d7f5bed8250d134bd6c2037
|
|
BLAKE2b-256 checksum How to use checksums |
c3c6d905aad95eef4e6ba7493f0724c1a4cff3fbeafa699034e93e94a4f00eb5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.18.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
04826c3956186388b5a2b76cf8d52774eefc13b16c6765216b562a343dd9f5ca
|
|
BLAKE2b-256 checksum How to use checksums |
f7f52f9b77305bc191b59f80149651eef1a4c7c8a3e4706b0b59c67dacd57cba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.18.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
743a79eec55d0801c1af18b029dbe28a7237673c320cca646eb1df88c7566d37
|
|
BLAKE2b-256 checksum How to use checksums |
18e3a7fbffaced66dcaf0ede17d8098f028f61f5cc85f41af954b54194ff31f9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.18.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
23b9bb8333c348bde041dfe52b00506e837e048a03f89f984f923dba78a9efaf
|
|
BLAKE2b-256 checksum How to use checksums |
c5588a076532e5ec02ea0b7447343ae5879eff59879161ddc3ba4f482f18de9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.18.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
3be13d6a3e9104180d35caace3750699dd83a5f39993a0fd279e41d31366c23f
|
|
BLAKE2b-256 checksum How to use checksums |
ac77169076f5aff9fe65aa346bb785ef19155402597eae89208e6f884b1c4598
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.18.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
0fd47b3ae39928b48f20e2bb4f6d3652cec990ab836fecfa345684e21e509c2c
|
|
BLAKE2b-256 checksum How to use checksums |
e30247d82f00d71b869725b8e06e3e6c05af4f32e7c1c03aace881eb02184b3b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.18.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
2ca188039292321356d29398d127a3659985e82218f7c17103ddebacf3198eef
|
|
BLAKE2b-256 checksum How to use checksums |
f1b0cfb01adb677edead8965c9565f716e7af280fc1acf0c63eb979e9bcc014e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.18.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
de1453ab416769b1a6d222cb926ee14a2e9320356e4a2a85b552f862ebcce30e
|
|
BLAKE2b-256 checksum How to use checksums |
5dc46e945c716ee8917007739b9bdffa02adfafd68b6be212b4703fae545eb07
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.18.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e03d9d3c4104e21e31f22f37f881a99a08b3ef229d1c7bb2a770f67cd089cd38
|
|
BLAKE2b-256 checksum How to use checksums |
2effad5f980a857bf17980ea85d15c42c0eba4da9223e9bbb7b6bcf0389fdb52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.18.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
09a989f91c9801612b69514ff1e4553a6ccef5cc3011abc6b6c42da1f4b5c0ad
|
|
BLAKE2b-256 checksum How to use checksums |
1aeb55ea4ad37bbf91e773dd92c8fd1d4418546f14d4ccb59e5675edf2b43038
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.18.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
2aad83fc5efed70e494a839ded21d547eccd7a4162b396fc9ccca174066f3105
|
|
BLAKE2b-256 checksum How to use checksums |
b8478094f2d5a7e4b3714754a7560de27c8b67592146fdf12672f3522a53b811
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.18.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
e5a759625fd1e5c6cd156f1138ddf633a8f6aba28cfe1d4b63779954bc90cb0b
|
|
BLAKE2b-256 checksum How to use checksums |
1af7787f4ec859a2efb50ce6743253bd0bc05cbcbf5119bf65aeaa5b1c5e64b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.18.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.18.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
5341e61aaab2ee475032fdf2b4892d4fbb7754c1209496ce59735d920891f72b
|
|
BLAKE2b-256 checksum How to use checksums |
4601d37f8012df3df6b5ebe946a1cde712289e74b154d5c663d5b485eecc3ce8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
