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> - 都找不到 →
RuntimeError（提示安装 wheel 或设置ARIA_FFI_LIB）
源码安装（开发）
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.14.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.14.1-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.14.1-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
22bba881e497c11ef9abcaf737aa901b3a40d5032b140a2e2cd786b50ce8a9b9
|
|
BLAKE2b-256 checksum How to use checksums |
645f8592d1962817481347902342ffeb5fe137cb298d73dba05325bbfba088fd
|
| 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.14.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.14.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 |
c70ea4ceffb2ef1d15ac9c29b03d53265fd5673a78fa07e05712ee0022ba9534
|
|
BLAKE2b-256 checksum How to use checksums |
87d90c5a5918bef835cdf73ccb9331b5095a5dad6c5fcbc2a430eb92ec4c3f1d
|
| 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.14.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.14.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 |
c5ae465679e47eccc1a0da1da263f1714a249312e3b6addfcd3a3a5d076a3f7f
|
|
BLAKE2b-256 checksum How to use checksums |
150af39a06efcab8b91c3ee43d46b8eab6cc661edcf8b7d9d92b332b6384ac57
|
| 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.14.1-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.14.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 |
06a3e35c751887bc656f4057519f3e0006c473692a40c23d7dfc1d5d9ce1af96
|
|
BLAKE2b-256 checksum How to use checksums |
ed2de748127fb071a125a36c6bdbb4671f3d55a9ec70cec35a31b39909fdfd53
|
| 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.14.1-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.14.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
fcd78b7c06c5ab43d58a6cd9eb2d47f811753a122b39f053c70dfab8fd602e42
|
|
BLAKE2b-256 checksum How to use checksums |
812d820c39fff064114a02a63d3814ec846848c47cd3c2fbf679a214a20e6dc1
|
| 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.14.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.14.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 |
9cc31a1dc1eeefbb2eeca573b7e8cea2bcdde43346024922e7de6969d1b791a7
|
|
BLAKE2b-256 checksum How to use checksums |
584f39210f94eeecd49d15e640fd5a6773ff28b4f030faad2274b6219ceab926
|
| 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.14.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.14.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 |
3ce549360c85f8d427af0e4c1c81f8cb94c409b3b66855209afa1e5e8a85a274
|
|
BLAKE2b-256 checksum How to use checksums |
5d5dbd3fafc457c828c4fa8648672ac70471b5cf21aaef0c269746d10934d6a9
|
| 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.14.1-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.14.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 |
38b7d2254313b2ccceaf7fbf6c07d725bb1973cf9b01b18400410c0607b9e8d6
|
|
BLAKE2b-256 checksum How to use checksums |
4c11988c6cb1d4682872809257ab94a961e9415ed048a4972ab0bd255a57a74e
|
| 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.14.1-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.14.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
5792bcc3d0691cd8cccf319eedea30f5ed7c2c4f2c6b6406d4c966a4580025d7
|
|
BLAKE2b-256 checksum How to use checksums |
4275981d6c8276408d297f6e561ffe0cd27f7f78c0b52c1252156e7cb6bb7ddd
|
| 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.14.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.14.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 |
e2d071242dc7d1d241b340555bfa3844dc9b5d89e9b15a6a5544c368a67e098b
|
|
BLAKE2b-256 checksum How to use checksums |
ca22196387b32775cfdf56a877eb61956e1760f4370516cbb2f5546c0cf5cf1c
|
| 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.14.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.14.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 |
1907ba09e6458f0ccc0baafbff7bcd9860897fef2b423a833d642027d0633fe5
|
|
BLAKE2b-256 checksum How to use checksums |
33f40ca086131283c2bf40e9b1afee43fab3d9b44b7e1b296d4b6b0e625a45ac
|
| 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.14.1-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.14.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 |
d07dae4527560144b6eda6eae15238e35d9432292724be92c532ec14985764da
|
|
BLAKE2b-256 checksum How to use checksums |
811e68546c6f371df21ac2fe5e9015ec40a00a022ae04d3751de5ad1a39ea74d
|
| 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.14.1-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.14.1-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
cab88c331a6c06d248a5199596c8357d8ea5a0393352f615e012f2fa3d311317
|
|
BLAKE2b-256 checksum How to use checksums |
07cf5cb8e34d2d6641bbbe893366e0068015036ea0c118a34a9de77d6f0121ed
|
| 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.14.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.14.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 |
99e1f679281e05915522404a0a76c1b2c632cd9806b721f8fc6f94e480b79601
|
|
BLAKE2b-256 checksum How to use checksums |
40c0b1c31b2e281cbdf56c5e88454068604cd0cff0c523d911c9521986a691fe
|
| 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.14.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.14.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 |
95f8b35ccd08f650bd8bb34f54424c7cec937abc7a3661150d67ff4b1fe00707
|
|
BLAKE2b-256 checksum How to use checksums |
ec7437deddbe74e0f9c81f0a8fb61e4adac250ee3f6a4092b515418cb0623b4d
|
| 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.14.1-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.14.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 |
c989a92270eaf81b677e1593166c36265d1947cc9ad742a1661cc19819cdfa88
|
|
BLAKE2b-256 checksum How to use checksums |
05fe3c1ebe8d4c36004fa0bf60d6cecd320353d1a33409ca9846f969d1b8d1c7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
