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.17.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.17.0-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.17.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
a3baa429c356b9c0e80b5f2193f5474641658131fd3e6839f79250aa6a9029ee
|
|
BLAKE2b-256 checksum How to use checksums |
2cfed4947766830c56a83753a116ef2cae06ac0d5c4456d71138d1e8edab02c2
|
| 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.17.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.17.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 |
d01bb1f374bec1bae3344ca7f8c88a6ac4a413bec1d7c0d65ace27a5083ee760
|
|
BLAKE2b-256 checksum How to use checksums |
057f64d1347e25a32b362768f3748d8c497c2efb4f37d1dde0d17dae1825949a
|
| 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.17.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.17.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 |
8840176cbf6a412224ba0c3f669af3939fdc60e36c4142acdff95ac17b52a674
|
|
BLAKE2b-256 checksum How to use checksums |
32c2f850356b5449dcfdaf3e030cb6c8e0de969e4adefdbcb7912240416af98e
|
| 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.17.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.17.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 |
67ca0164fa8b16bd58c53596a6e96f5ba7b25ec19d32e6401dc22e787dc71e2e
|
|
BLAKE2b-256 checksum How to use checksums |
3eb60e6e53f4cff9932687251d4ab1f54e52b1858f727e4de2107af0184bbf0a
|
| 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.17.0-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.17.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
4536aee417af93fdbc13998b57cf961dc287db3b917ecad4bc2ff4eb8dc37f6e
|
|
BLAKE2b-256 checksum How to use checksums |
f6b88567b271dce77e60c5c35113091c1bad23289b373b3e2419d7d34f171f28
|
| 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.17.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.17.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 |
ae03f2cbd1455cc97b4b6debfc0736112ea68e9c7de18729e8e90d49aaec572c
|
|
BLAKE2b-256 checksum How to use checksums |
a32799c87ed11a1ddf1d968fda697e40c4b24c096071908bbe4501412962d10b
|
| 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.17.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.17.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 |
fb3e1c1ed6057e8944061c219522cf6a55d17c503bcd1816359c3727bc7d343f
|
|
BLAKE2b-256 checksum How to use checksums |
bff770b69b43a6bd26d22fd24e5353a0cc90237c09e22190a8535b2f2bc9748e
|
| 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.17.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.17.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 |
0ef6a429846b532050386a581d9699d709737483eba9b5e6615598976f60a5d8
|
|
BLAKE2b-256 checksum How to use checksums |
2ca3ce8de192d8833fa571e9f7cea501c2b560a75629685e54cb80584a3ebdf9
|
| 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.17.0-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.17.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
872e9477850c5a86d46bac7039058158f9b2385b0813a6a8315443ef289f39ff
|
|
BLAKE2b-256 checksum How to use checksums |
30b5561369d47ca5cf62841c535e724fb01ee7676297ffc5443c4aa1009bf5f4
|
| 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.17.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.17.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 |
8fb41536bab127fa1bf9e19ad8155e9a7bd289642e879f799b4d0738600e6353
|
|
BLAKE2b-256 checksum How to use checksums |
b5a2bb04f4256c571e83f8fa0f695c64678c46e840d78e6d86ca8db1b51a9dfb
|
| 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.17.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.17.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 |
73675a83e5235ec3548c6b1781395bc74ab041f93d07034b7f668053ac40563f
|
|
BLAKE2b-256 checksum How to use checksums |
8cdf92aed666506521c7788bb69f437b14c062f3fa882fccd526ee103fe70cd5
|
| 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.17.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.17.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 |
a51a416aef26ed038997f718142303d6c8641a0fab009b60f10098981bf78cf6
|
|
BLAKE2b-256 checksum How to use checksums |
58210dd8f5dd9fe73b91d29a18a6696f0945f7b8d005ffbe32e4a691beb5c180
|
| 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.17.0-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.17.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
554a18119461cd2d00c2649ae70179f9205eb5808b6e0b2cfd4b0a380361ae52
|
|
BLAKE2b-256 checksum How to use checksums |
c720239fc478257b265fdf1252a0f58f3415dc5e9e0125008c01beecd49b78ce
|
| 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.17.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.17.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 |
af23e5913c4dd0cf2de1374416bd48c1b7f028b012d6cbcc4088f5a4c86fde27
|
|
BLAKE2b-256 checksum How to use checksums |
b453d9bf2f4657db6db688229fabb4935773e5014ee5155b578a5c80189aa401
|
| 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.17.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.17.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 |
373d5afb5863dc16cd58656cc3241ec1ede00bcbca0fa81f494db8574a03b5a3
|
|
BLAKE2b-256 checksum How to use checksums |
04808b80845388a50dba3d9381933c2cea139a1dfd2e5d9fde4824d517676baf
|
| 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.17.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.17.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 |
657229058036e696f9fe6bfa9fee1fa163706688918420b77b0652a2943eca50
|
|
BLAKE2b-256 checksum How to use checksums |
519cec8f5d31ee38f91ebb079cdf5f0dd96b06a6c24e62a4b536fa77da2b3041
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
