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 从 Dashboard 私有源 自动下载（需 token，
site 默认 https://ariacompute.com）到 ~/.ariacompute/models/{model} 再加载。
缓存中已有有效 bundle 时直接复用，不重复下载。
with Engine("gemma-4-e2b-it_q4", token="API_TOKEN") 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.8.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.0 MB
Release files / aria_engine-1.8.1-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.8.1-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
4b4cc286b74c6d66445ba08a73902e094127ab08af160cb3af21f2ffea3ac6ea
|
|
BLAKE2b-256 checksum How to use checksums |
d2dad190ae9f7e035a80b7c446d7a69e5d7ea8b201ff22dbbb4b8a714aeeae60
|
| 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.8.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.8.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.13 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
77c768c6462c7a8ccb66b8c59252df0f310d4b71fce712248514237e2e732e10
|
|
BLAKE2b-256 checksum How to use checksums |
0407dcdccb4f87561bb100bf556ad91f1514c78b3c294f7d12d89e3ae034dcd3
|
| 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.8.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.8.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 |
a35ea657d1a86d826f30950b8e80f1ed76cc15ed11e2be1ccae394ad1e9d534a
|
|
BLAKE2b-256 checksum How to use checksums |
c624f852ded106ce9a4c78e62ebbc1c78aa78084816005affe6094326ab54157
|
| 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.8.1-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.8.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 |
0fef38a273edb00d18992a6e567c99cbeec24bcccb1131ec8ea7152b4eca1fc0
|
|
BLAKE2b-256 checksum How to use checksums |
8976191161e63e535cd9679e91ec7aeb36269e16bef45ab86f2b17b0eb84a2a0
|
| 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.8.1-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.8.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d172a643115b4bf3184a033e7e4e22d963ba69c912f1e4ccbb0ddf69f7a1ee4b
|
|
BLAKE2b-256 checksum How to use checksums |
bd2413649adecee5319a5b776c3228a665562a95bc4e0325cd8533fefc822a29
|
| 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.8.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.8.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
1b3e246931bacbae19486efa2c8fa523506bd3276bf2f7989f1d577fe84ea91b
|
|
BLAKE2b-256 checksum How to use checksums |
f7f655a402aca29801ca965a1c09bc79114e261231fd3cadc1078902772fac50
|
| 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.8.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.8.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 |
e46268446acede0f234dc0f5c1268b93e31db62301e5d3d81bf7f8d753961057
|
|
BLAKE2b-256 checksum How to use checksums |
1bf19877967825fcb7f52bb1c1466a84af73cc87928f825116cf487bde73f35f
|
| 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.8.1-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.8.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 |
7325919e290d19f499b57cb6cb6194e48de19cba755cbb2ee6494042ba026f1c
|
|
BLAKE2b-256 checksum How to use checksums |
cf762f46c8026425f7827f0d5753350d527007e0731c7303144139b93f082a1a
|
| 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.8.1-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.8.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c104bdd421956b1f8e63518a91c826a9b74731abee643917b3ff863f10c8a765
|
|
BLAKE2b-256 checksum How to use checksums |
caa5c82e8767679a8e386ff6167ce927f8e3b4b54e0df6c504401b2893d627bf
|
| 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.8.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.8.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
3f66aa364adf70520d094ee1c6dda6ab753345ed1d0d0d37fdb79c7023fd408d
|
|
BLAKE2b-256 checksum How to use checksums |
db3209e7b2a5bc88f7cd4171dcd7fee1cb0f0d4a07a7cbe46e2864abfcf11ae1
|
| 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.8.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.8.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 |
7de5090d874a15c5a7aa7f2e9032488df36fd141764973996cd529ef5def9b50
|
|
BLAKE2b-256 checksum How to use checksums |
f8e089ce88bd7bdb69422f4d0e6467117215567caa6cf61d832e49acd8319f45
|
| 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.8.1-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.8.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 |
bed408d69c687e513ce6f8367ba6495254267dd833ca28401009fd534b18a893
|
|
BLAKE2b-256 checksum How to use checksums |
68e083022be85818b74ffbb114588c9098a9185aa27e2c4fe18a1f956a32708a
|
| 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.8.1-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.8.1-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
db60eaaeabc6811d7e7a1a09e87e9d765ef3ead1ef2634294fdb392397bafff4
|
|
BLAKE2b-256 checksum How to use checksums |
8d687b9e8ec8932372685750518468894f61680cf576476265444141bb6793f3
|
| 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.8.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.8.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
6b350885bac10682c979a145ae7c0b7791a8356428fd08c5414baba8a2f1de06
|
|
BLAKE2b-256 checksum How to use checksums |
7be1e99edfebcb875bc1daa0989be2718719fcd331e06c55877079ff73317e98
|
| 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.8.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.8.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 |
fdc23aec11879886c96e0d9750e58500b87e5acd24c3a9e6aa82b83804c56e60
|
|
BLAKE2b-256 checksum How to use checksums |
68176822932693da95107a8c695efc4f82aea85b7cf85e01abd12ac2a43da4d9
|
| 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.8.1-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.8.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 |
0681785886d125eb9f8ef126ecdb91f23cc56166b2770bbb903a65d56eeaefb0
|
|
BLAKE2b-256 checksum How to use checksums |
7d48a05feec6756210c506207ea80a823c652682907985f09f8b4c89bd6e54b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
