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 auth 相同；未传则读
~/.ariacompute/config.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:
with Engine("gemma-4-e2b-it_q4", hf_token="hf_...") as eng:
print(eng.complete([{"role":"user","content":"hi"}], {"max_tokens": 16}))
动态库查找顺序
_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.15.1
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.15.1-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.15.1-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
7fc92db95de23768bc3b06d70341961c4391e4eae2b9d64ba14d36de18b8e003
|
|
BLAKE2b-256 checksum How to use checksums |
8ad5e630a06137911c59c3f75349eb02e5b94e7865d23ab54846b9162ae4ae5e
|
| 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.15.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.15.1-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 |
c4f71ab4e66cd87f5ff68dab9ceb15e623f9ef2f80c0f56b2dafa25003035a5b
|
|
BLAKE2b-256 checksum How to use checksums |
a54a26aa22d97190a6cc87865123e3f7bc79ebef7eaf2b442c8b4c8e13f7bd0d
|
| 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.15.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.15.1-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 |
e419bf3f4c13470938fc4dd9217590a0b6e104260418f4b5e149f804488dbe06
|
|
BLAKE2b-256 checksum How to use checksums |
baee92c89d5074df05dbe6998f880fc0c4b9b0cf3384d6089168185c712283d2
|
| 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.15.1-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.15.1-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 |
322efcec44b2528e28c12eaf557b3366e943227b7214f0ef371f72f02051c6b9
|
|
BLAKE2b-256 checksum How to use checksums |
87318962f66c0305ba2ddeb9fbb3d65b9bbe54d46ff72a964d96f3001c3f219d
|
| 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.15.1-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.15.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
9619b9c75c5cafe3ba5cd4959ee603125a62a418f25298f32ea2d0499b688993
|
|
BLAKE2b-256 checksum How to use checksums |
731e9d7f453cfcb6e120bab34e809bf5d5db53c0b1f9f1e82d9d7d8f647f09c9
|
| 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.15.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.15.1-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 |
9d9c63486e33aab28aa7914e85db445282e3f31d9bd509c5e1f9aecbaca450d7
|
|
BLAKE2b-256 checksum How to use checksums |
132f973260979e4e48c2ee6777c2d32a605fdabc5c1225437bbe7b432b8baa86
|
| 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.15.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.15.1-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 |
34d42b873aa3ef33547122586647bbd0968f3eb1fc563b7d6d576e4e3e1a9afd
|
|
BLAKE2b-256 checksum How to use checksums |
40c95f9f544732bc9cd4ff341bda07698467fd7868e4b088a9c29f9ed08712d1
|
| 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.15.1-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.15.1-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 |
a880123c9fb42ce68e3619b450c98ad2924fe3980742347e9cdde1aae8d2d245
|
|
BLAKE2b-256 checksum How to use checksums |
3b65f7d00f40958bf35a96652a32825ee5b4603e60a5925daa3c61b1a842f6b3
|
| 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.15.1-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.15.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
e8457da6fb5dd232a2984f6da8936320a5338d838ddaccbf48ec76286866ab79
|
|
BLAKE2b-256 checksum How to use checksums |
f6b44093aad2135277ca0af6beea4676cce3825d2b37bf973f97f651f520709b
|
| 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.15.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.15.1-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 |
38fb76eddec3f205635fc23fe96e6a26cd98fa565bb9cf9f048fc7e0d5e169ff
|
|
BLAKE2b-256 checksum How to use checksums |
42e37a5f083e741deb655d731477da6b3a67fa59d00889a6de49e26425c7e9ac
|
| 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.15.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.15.1-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 |
b3ff02e29b6eca80664f9378b9b157397c4203243df239137c836169be1d29d6
|
|
BLAKE2b-256 checksum How to use checksums |
4c70b09ca0efb1489f3d3c57e1da5e193f2e22780b9037d69b1abee8ed539e19
|
| 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.15.1-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.15.1-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 |
98565e80ede40e07e19d9a2fbfc48a07a59b2e2292c195eff76b9631ed6a8a90
|
|
BLAKE2b-256 checksum How to use checksums |
9f95102ccd006c6e41cee6eddc014b7830cfb66568e048c45c35aa1f23303533
|
| 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.15.1-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.15.1-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c6563bcb29f01222ddc03b644c4c50812fb6baba4e1ae38b9f7a70bd0e404c1e
|
|
BLAKE2b-256 checksum How to use checksums |
8ce0efacf88e1ac125567d92575d66f985ee3f89e57ee34695d916d5705340f9
|
| 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.15.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.15.1-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 |
fd56ecc762dbd8b04b7966b22b3d1e5d1164053a610c0e818bef82ed6b9060a8
|
|
BLAKE2b-256 checksum How to use checksums |
4f883e125c58298cdbcddff3e7ce8979450fbf76c8ba93d089f15b20ebbac992
|
| 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.15.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.15.1-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 |
012de48d150fb4533ff0472cdc807247f09b62161ce3099f539df1ca4909aee8
|
|
BLAKE2b-256 checksum How to use checksums |
175b531d8759259d2ccccb9edc781b60f80b7f358fd287854f3b6a38ac8cf875
|
| 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.15.1-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.15.1-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 |
a89fbb555ca3434b2f04a64fcd599b446d2a8ada99e4d2f09987ff5a9c17215a
|
|
BLAKE2b-256 checksum How to use checksums |
f68936f614e1246915a203d8af1b4352a323ad10723e057ab2c29c70edaecb0e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
