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 setup 相同；未传则读
~/.ariacompute/engine.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 (instance setup; does not write engine.yml):
eng = Engine()
eng.setup(hf_token="hf_...")
eng.open("gemma-4-e2b-it_q4")
print(eng.complete([{"role":"user","content":"hi"}], {"max_tokens": 16}))
Engine.setup sets Config / Run fields on that instance only. CLI aria-engine setup still writes ~/.ariacompute/engine.yml; the SDK never does. Empty fields still fall back to reading that file for hub download. Also: eng.setup_status(), eng.setup_clear().
动态库查找顺序
_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.19.2
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.19.2-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.19.2-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
f95346611c4289b5e9d2b27b231c223ebef10228487e6703bcd934d1a4115a35
|
|
BLAKE2b-256 checksum How to use checksums |
ba79a0abc7f7320817c0ad4109be0df9ccd44e86cdc61b7fa855e32a0dd21467
|
| 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.19.2-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.19.2-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 |
9ee889393a054970fcf63219ea4c82240f9894e72fd4e365fb8554be2789770b
|
|
BLAKE2b-256 checksum How to use checksums |
9342530750b1ffc0955c4dd5a4fcba1cc3a192addfa8cfb322c8a4029fc37d94
|
| 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.19.2-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.19.2-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 |
ea76827bccd866e85ffb5b41c2c580b99b5004eb0f0e10d48e83b8159116bd26
|
|
BLAKE2b-256 checksum How to use checksums |
382623a414819128dbd456567f58eac0f662654eae7f486b61cb3b5daed2a85c
|
| 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.19.2-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.19.2-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 |
6863fd583a855608a5f0626f830ed2c062205f35c1874fb82a011c953bbefcb2
|
|
BLAKE2b-256 checksum How to use checksums |
5ea131419a53bca03144efd0ab7619bded7f889444177c456f273bb9ff158acc
|
| 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.19.2-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.19.2-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d8cf95775c7bb5b1499a27df1d8c68c79035d05514115588f8fdce298bb01d64
|
|
BLAKE2b-256 checksum How to use checksums |
c1c0caa2c9170c17d1e88b08a30972600e1551be06a1fe38770ed55a73c49a10
|
| 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.19.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.19.2-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 |
e93bebd872dc5c0cca4e981e55b2f34bf4f0f33cf73b1b8a402126a0c11b2481
|
|
BLAKE2b-256 checksum How to use checksums |
0ce2300eb8414df7ea0c5337874b8609d778e3eaa1dc4cfe8e743291133f4200
|
| 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.19.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.19.2-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 |
2e18ce4a671a1fc594237055558271770ea39c559a73285fda6b08f7b6616704
|
|
BLAKE2b-256 checksum How to use checksums |
3bbd8a9021a9dca10f663f8c83f3fd513d5f0b50ed8eb603d3cc68f68c29d7ab
|
| 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.19.2-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.19.2-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 |
66a6f14be773f1742b6063821c2f6e9043016a119ec6285f8ba81b35fe63d648
|
|
BLAKE2b-256 checksum How to use checksums |
f783901e2760d880d0ca42b27869c76c75bd1cd831f3bfbed686b75facd3accf
|
| 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.19.2-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.19.2-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
757136f8b06c3b3805cee81e3fe9f7204abf8495ae91d43d57d237c7534e6707
|
|
BLAKE2b-256 checksum How to use checksums |
b02a6492118008e88fad78b54b2dc7e447d8a6ed57b322d384db079a566af572
|
| 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.19.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.19.2-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 |
fd6a417326fb8c3ebf0782fa1d6dc3f5781475d869ac906b24d5c259d1367524
|
|
BLAKE2b-256 checksum How to use checksums |
110fa11cfe25169089297c20d7a23ef6805d8d45282005364a60ce35badcfce0
|
| 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.19.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.19.2-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 |
14adf5b1784049ff3a4ac33dbac1ded0e64cd26d683916123a0a6de7fd891903
|
|
BLAKE2b-256 checksum How to use checksums |
b501752dc69f58731a1b55c62539a102ce35f64d6292594c0cfe1d40e43170a5
|
| 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.19.2-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.19.2-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 |
a90c26a2dce7390cead9f56fa76e1a3daeb8ec93ce6989a1a82b11f1b37ae4a9
|
|
BLAKE2b-256 checksum How to use checksums |
8c236346cc0e9089a3f2cc8c9d102886aa3305cacb75b7112299c797b185897a
|
| 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.19.2-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.19.2-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
e72604b1763999d328dc0d572c58c07de4dc6f5039ed37b95a17b3ba5d0abc76
|
|
BLAKE2b-256 checksum How to use checksums |
05e3c7712e7373ff9a98794c455b9c2c5cd5cfda5bf2c926dc9820637fdfd663
|
| 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.19.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.19.2-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 |
f85941ea7c4d7ce248a411b2aa56b7e8e41e51fbe61aaf6adb84e5601863b5de
|
|
BLAKE2b-256 checksum How to use checksums |
c3b2d35fb03b0d3f87de8fd9e5b3ac9c6a25e7c55cfa343fe374f634e504e95c
|
| 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.19.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.19.2-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 |
e76a1f8fb721aec92ea1104c6943c3dda5fc5985b62939f4d47cc52b91003ed1
|
|
BLAKE2b-256 checksum How to use checksums |
e545243e3da777cecebe77abec87eb2ad73c6286b0e2da75e4579ca54892e9f8
|
| 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.19.2-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.19.2-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 |
21510e3fa3b8e77857b20414113b61320366125e82485b5cc02404992bd1d3aa
|
|
BLAKE2b-256 checksum How to use checksums |
7ebb8b40f0d397e0f5290125b5c151db91d4a2c7d993676302fdff9143ab8720
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
