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.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.14.0-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.14.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
0355c7192c773543d0e261d06dab2aabd7f096780f4841f66be10052b1e8537d
|
|
BLAKE2b-256 checksum How to use checksums |
69c45ff424af01fbd65d7bf3d7c663c80a689b74ee60b4afffda4fa0aa3a634b
|
| 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.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.14.0-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 |
2b314b75eb92b8c18fc1706744bdb1b9bbfde1d209189c551b1556fe6f6b2e5f
|
|
BLAKE2b-256 checksum How to use checksums |
7c4b78fb6c77ac9c391d830d7e6a3e9b7858e2cc93f67fadf061ad1eb688a2ba
|
| 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.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.14.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 |
17b5e95e1eff2eea209daf93587186f86381f1c6210cb5abdc86a98130e9d623
|
|
BLAKE2b-256 checksum How to use checksums |
4364fa84af87b560cb7943d496bd8ee600da1fd829d89d87233622319c43cdcd
|
| 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.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.14.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 |
834a8d0d1d1f2043b77784308fb4d0c0295947842f30a8108107d4bf61040620
|
|
BLAKE2b-256 checksum How to use checksums |
52c65cc75b1b2d20428725197f9511f37f5a1940ffe17ce7fbbb08e54a4e8928
|
| 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.0-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.14.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
b1cf1aaadfd81e4b102571ecf054f9a2eab2a9e41c772e5b67cf3c3d3a282cd0
|
|
BLAKE2b-256 checksum How to use checksums |
0a2e8afa6c0c0d19fe7a8b12b61167cf4e35958391cfb3ef206cc2fba3d52267
|
| 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.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.14.0-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 |
0e3e6d14431a21b9f4b02b540fdb0483d4ea645697d02b85f5bc54e00684cfe3
|
|
BLAKE2b-256 checksum How to use checksums |
19dfade590d5eabe1b80f7bcbeb1945cc92638d8f876982db23428843e4795a5
|
| 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.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.14.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 |
671527a619462638b08bfbba86a5cde8b5f3758e0b111ec9af622e4174d1e4b7
|
|
BLAKE2b-256 checksum How to use checksums |
46ad0966142719eb71882e9f1b028048aaa23f5393352d5eebead3f7e2c49524
|
| 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.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.14.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 |
4f6e072765cb65a29e7fa35fb64ee56fde87dff97ec01b43a1ec8f36e260bc06
|
|
BLAKE2b-256 checksum How to use checksums |
14ff5d01e5d460d2b9675981c3b97a23a39943c2266805e08f23f09456f1920a
|
| 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.0-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.14.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c568200d18f512ef64f198041cb1ad5345cb0655cc957f74dc44dfbe57dd21c1
|
|
BLAKE2b-256 checksum How to use checksums |
709fa3fff2bb638add449299cbd290bfb248e47428c11648d392448c1f86b3e1
|
| 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.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.14.0-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 |
76e11ad7ba27ddef52f67ea5fa5a4dab1ac866f534ad45de0d466b2cf491fe26
|
|
BLAKE2b-256 checksum How to use checksums |
6274b5ac8c7b854a33fb5e9664e40f733b42ede6cf4eb685f30891b52ba518ec
|
| 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.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.14.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 |
2a2faf1e7e86c21610381a6c3cf489d1bea8820fa4f501f3844d4a7f5c184592
|
|
BLAKE2b-256 checksum How to use checksums |
f4ffcf9498b793c00ee3508ac81d57e7ec406e32d6526763ba63e1f719ca09e8
|
| 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.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.14.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 |
66ee7ecd9348a0afd642c6d4020199d8afc6dcbdf4da3cf76daaf13b6015d648
|
|
BLAKE2b-256 checksum How to use checksums |
72cd7549b6c5c4b062890c56ccd9ec01367c1e51dc3bdc57a9f9b2fd3ad081ad
|
| 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.0-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.14.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
2103135581dbb57cd29911ffc884d04af70ab9b3854182bc557079adb806c189
|
|
BLAKE2b-256 checksum How to use checksums |
14f235d127752271f03b4f176be4eb89506df4c6bf0bf8f546e72026d1ffe4c5
|
| 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.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.14.0-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 |
a0d1ecdbda858a197a5b95db30b3813cfe09a7cd9e222f22f6b33e91831b68ec
|
|
BLAKE2b-256 checksum How to use checksums |
29d9d9713482b36cc903a5ca9462683c75b4668b036b84a09bb171db419141a1
|
| 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.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.14.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 |
c99e180052ec25635f6fbff84e2fed41443c51056a65904043e60b983c76d353
|
|
BLAKE2b-256 checksum How to use checksums |
eda5fed76938be1a4a4e7e41b6243ff35038d8a4013c238cfd150011bb8a9e91
|
| 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.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.14.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 |
4c391979b5db59f463d34376370967082aac6ae0111db89b90f9b159d356e84e
|
|
BLAKE2b-256 checksum How to use checksums |
6707f7b22832945778fe2629786691e12c6a8d2161456ec76989b75e035fc0ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
