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.7.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: 29.7 MB
Release files / aria_engine-1.7.1-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.7.1-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
9e75b0a07679ef7fb4f3a3fab6009f8f57af1596b30eb5ed9f7168ad9a2e8de4
|
|
BLAKE2b-256 checksum How to use checksums |
3432af539dda6e739c5da912a39ed7e341fa3b8aeb551cce9a826464ca61a201
|
| 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.7.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.7.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 |
eee9d686dee9aacdca2acc04eec39c9d66935c5189b2db01fa623c92c9a57c11
|
|
BLAKE2b-256 checksum How to use checksums |
e74ea8056612e37e78d3059f558281aabc88d2c5d2fdc0f97446a1bc05aaabae
|
| 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.7.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.7.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 |
44157ad33d45219c5fabc4f3319e9851a309970a64171f7e1c66351c3ac636ab
|
|
BLAKE2b-256 checksum How to use checksums |
a955eb389b0e6495e09a40364129685e4d31bfc2c6635d977257f05ae4929ce2
|
| 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.7.1-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.7.1-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
65471af480a47172a96cdb44d9a4485097b0e55948458221f53180c34488b627
|
|
BLAKE2b-256 checksum How to use checksums |
bbfd008a171ade00e421dac592890e57e74bae1e90a2647f59d5f96177d30983
|
| 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.7.1-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.7.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
40aafef09a160aa263d48c492ca2e652f78e205568a807930d390d9f29198f07
|
|
BLAKE2b-256 checksum How to use checksums |
b59ce28c68a1a2f2803a1ccf5701cc9377ed2f9cf9cf8039a0943378dd72d180
|
| 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.7.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.7.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 |
7b060f2f885cdb4a6daa0efcb911544de80d46b1a2ffc90c9a202e5c70b78264
|
|
BLAKE2b-256 checksum How to use checksums |
fa5a47d39df42c02309d09f3e76847a4bf50857b0ca8e207be925d71b62571b5
|
| 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.7.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.7.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 |
8bde47591794b8367a2a92b9b3c1d3af594758fb89136bc30a5b6a6b85527e42
|
|
BLAKE2b-256 checksum How to use checksums |
389ff52bd0424a1de72c772a787e52b3dec259334eb7a52622e701fec1754a1b
|
| 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.7.1-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.7.1-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f360593519e03ff39e63741cc3895a427da3c480ec3cc06f413bcf26b4c22c99
|
|
BLAKE2b-256 checksum How to use checksums |
ec978dbbfcd18b68789b5b284f33eb3b1cf7a4e8115c9bcb937a18d5fbdbe0ad
|
| 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.7.1-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.7.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
6ac1173126766973d72e3761b34198f821d5cbdf61e60d3859dae525c909b636
|
|
BLAKE2b-256 checksum How to use checksums |
ab433abd45054d19a9eef5e5a499a56616ba68a1ac028693f138ea539457e9cb
|
| 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.7.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.7.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 |
59f9c54d24a05afe418242ebb2a05ef8afb2d6146e84ad2b534ab2512d3bb2ed
|
|
BLAKE2b-256 checksum How to use checksums |
e8274bb1a22d3e812f1cbc65f631b349f007c61e610edd5c9659c7ae6ae83e74
|
| 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.7.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.7.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 |
5e9af99d07357c51a999019d87b68c3e99d2c2d24ddfc574215d4778ed0d67d7
|
|
BLAKE2b-256 checksum How to use checksums |
db40c8f8dd6bc3d3eba1af7a2bff14d90ff436598942d635e2aaa289d3210602
|
| 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.7.1-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.7.1-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d713b294c5d7a66008828cd415ecea8c0d774c29f0ffce9d790ce13d3785f1bc
|
|
BLAKE2b-256 checksum How to use checksums |
7b99d82dbba434ec95a9a0d13ffc96f6bac5e35fb9fa3db59bf95fe2a5721784
|
| 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.7.1-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.7.1-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
eded3871d5838113442adf22b72d3c234e69904b6d16bff3f266868a0be9e9d0
|
|
BLAKE2b-256 checksum How to use checksums |
ffd6d05bb50c3ce8c50191da324cc6be1180e593b7fc91e5fa4da10f7a8e9834
|
| 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.7.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.7.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 |
ec69bbd316723503c1d1620f5f24020c59592fa8b05deb31917faf339449f9d1
|
|
BLAKE2b-256 checksum How to use checksums |
d486c6159d43773d0b8ebc503cf9882d7f1232ba0ebd0d5fc4b5ad91a56fd101
|
| 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.7.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.7.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 |
d7514b937e0a720e285479cf37f7be379f615e614caecca1ed668186f4e2d532
|
|
BLAKE2b-256 checksum How to use checksums |
32b3f4814043f7d9382bc7402a1753f546d8de1922dfd1bf306b8db2d7dcf555
|
| 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.7.1-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.7.1-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
19d4ff7afded4ec643492eb3230956c7ca9f17ced203e889e4d19a8a143fa152
|
|
BLAKE2b-256 checksum How to use checksums |
c1354346104db2e21ff3a7ce0971c7c23563a8a42e87ac827a1b12fcbb3ef0ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
