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- / sk-bf-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 手动输入）。

Metadata

Release files for aria-engine 1.22.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for aria-engine 1.22.0
File	Interpreter	ABI	Platform	Reset
aria_engine-1.22.0-cp313-cp313-win_amd64.whl 1.7 MB Sep 4, 2026	CPython 3.13	CPython 3.13	Windows x86-64	Details
aria_engine-1.22.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 2.1 MB Sep 4, 2026	CPython 3.13	CPython 3.13	Linux glibc 2.17+ x86-64	Details
aria_engine-1.22.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 2.0 MB Sep 4, 2026	CPython 3.13	CPython 3.13	Linux glibc 2.17+ ARM64	Details
aria_engine-1.22.0-cp313-cp313-macosx_11_0_arm64.whl 1.8 MB Sep 4, 2026	CPython 3.13	CPython 3.13	macOS 11.0+ ARM64	Details
aria_engine-1.22.0-cp312-cp312-win_amd64.whl 1.7 MB Sep 4, 2026	CPython 3.12	CPython 3.12	Windows x86-64	Details
aria_engine-1.22.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 2.1 MB Sep 4, 2026	CPython 3.12	CPython 3.12	Linux glibc 2.17+ x86-64	Details
aria_engine-1.22.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 2.0 MB Sep 4, 2026	CPython 3.12	CPython 3.12	Linux glibc 2.17+ ARM64	Details
aria_engine-1.22.0-cp312-cp312-macosx_11_0_arm64.whl 1.8 MB Sep 4, 2026	CPython 3.12	CPython 3.12	macOS 11.0+ ARM64	Details
aria_engine-1.22.0-cp311-cp311-win_amd64.whl 1.7 MB Sep 4, 2026	CPython 3.11	CPython 3.11	Windows x86-64	Details
aria_engine-1.22.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 2.1 MB Sep 4, 2026	CPython 3.11	CPython 3.11	Linux glibc 2.17+ x86-64	Details
aria_engine-1.22.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 2.0 MB Sep 4, 2026	CPython 3.11	CPython 3.11	Linux glibc 2.17+ ARM64	Details
aria_engine-1.22.0-cp311-cp311-macosx_11_0_arm64.whl 1.8 MB Sep 4, 2026	CPython 3.11	CPython 3.11	macOS 11.0+ ARM64	Details
aria_engine-1.22.0-cp310-cp310-win_amd64.whl 1.7 MB Sep 4, 2026	CPython 3.10	CPython 3.10	Windows x86-64	Details
aria_engine-1.22.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 2.1 MB Sep 4, 2026	CPython 3.10	CPython 3.10	Linux glibc 2.17+ x86-64	Details
aria_engine-1.22.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 2.0 MB Sep 4, 2026	CPython 3.10	CPython 3.10	Linux glibc 2.17+ ARM64	Details
aria_engine-1.22.0-cp310-cp310-macosx_11_0_arm64.whl 1.8 MB Sep 4, 2026	CPython 3.10	CPython 3.10	macOS 11.0+ ARM64	Details

Total release size: 30.2 MB

Release files / aria_engine-1.22.0-cp313-cp313-win_amd64.whl

Download URL	aria_engine-1.22.0-cp313-cp313-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`bc72e4634633625fb9095d1c0de51b4d617babc3e850ec0192cdb0346672f73c`
BLAKE2b-256 checksum How to use checksums	`6a257932dae190803ec0fb8a7104140c93eaa5cb30899565aebab60f3b3c6054`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.22.0-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	`94c80625e7dfafc67932c9603fdda330802b68cedccf3183b7baa17efb91d7b5`
BLAKE2b-256 checksum How to use checksums	`2b4d628860cdc06ab2a1c2ccc8e93e1005705b3e4f3f2b1e39c7a2661aac62fe`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.22.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	`89abc11388b8d2c2dacd2656790a3fbf5e93d0224b75f9699cbe83d46a4df492`
BLAKE2b-256 checksum How to use checksums	`564313d11dc01a8f7db5fbf82a5eb3c66626c97df9245f4a36c0ffe020d21acd`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp313-cp313-macosx_11_0_arm64.whl

Download URL	aria_engine-1.22.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	`8a3eacca728ab44724d2405d3bcd7a1b9aa9f3c06fda52cdabf69bc9ddcc5db9`
BLAKE2b-256 checksum How to use checksums	`1c25346eb0ee7d458231af6928621fbbe90e8024c2c75a289409601928353547`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp312-cp312-win_amd64.whl

Download URL	aria_engine-1.22.0-cp312-cp312-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.12 Windows x86-64
SHA-256 checksum How to use checksums	`8134daad83d5073e3593512d681e276455a7ffbd52065060031f2580aea0d36b`
BLAKE2b-256 checksum How to use checksums	`9e5908eea685412332a0603739398af78782893e8b1d22fe2525b497fab22dfe`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.22.0-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	`73b33a28f2d410b0992bbab26717d67c701c8d60a82066a548b72fe64d69b3fa`
BLAKE2b-256 checksum How to use checksums	`997b656f30a54b00ffffad211ee5778dea35ab5fd64d1f27f8935453c7bd55c1`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.22.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	`acc2c62d39555182c08c640206299fb00efa06414105424bacdb31f0b5df0259`
BLAKE2b-256 checksum How to use checksums	`998bf8cd83524501f9ae0bd1a0e145ab3dcde347e67273c815bb5ca0138ee642`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp312-cp312-macosx_11_0_arm64.whl

Download URL	aria_engine-1.22.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	`81542c98c6dac8b5d5c8e91f40c24f44ff6ce255973bc7b3f3d8048032107c72`
BLAKE2b-256 checksum How to use checksums	`befa5c8473083029af77886e9abbdfc50395b5ee4290d908a9749c2223874e88`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp311-cp311-win_amd64.whl

Download URL	aria_engine-1.22.0-cp311-cp311-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`c089e20b2250146b7e5e1ac167d4f8a3247183452641403aef677511298b1ab6`
BLAKE2b-256 checksum How to use checksums	`0a61184212cdf70ebb2d53b5432c36a8041bea92fbc217c315b54651051ecdf5`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.22.0-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	`0eee813e92da1f511b7f6d2d3bf4d1afed2a906be0131e6065b96a71ea9f8e39`
BLAKE2b-256 checksum How to use checksums	`813811cd96a405308c789db2030cf18227274d0f4c4d31dbfd2ad55fde1ec3c6`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.22.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	`e66f344cd9ae31c9d2b4d31bb1758a83f31ee571f45ec999f15f7592ee9992b4`
BLAKE2b-256 checksum How to use checksums	`858a5bb49ae0dea277459f5ffb96f0e3430cf4d624b1265b82490ecb7ef05912`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp311-cp311-macosx_11_0_arm64.whl

Download URL	aria_engine-1.22.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	`f98b2a755c9386323288f1cc1ba09d369d44b04c23a608293d1903049c296bec`
BLAKE2b-256 checksum How to use checksums	`c1154c6fed6247459cc9530af3d1203123d728e2e3061f653a102540f6540709`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp310-cp310-win_amd64.whl

Download URL	aria_engine-1.22.0-cp310-cp310-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.10 Windows x86-64
SHA-256 checksum How to use checksums	`22b85f6e793b4889f97591e2f8bcdd0b4f027b5f11fec818b6395656c154951f`
BLAKE2b-256 checksum How to use checksums	`b86233abf7da8eb5d7831daf1728139ecb234b3fe8c918552ccec6b0b8889e6b`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.22.0-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	`002f140ff59e77c79dd1fe90a914b45797c063ff5b40f4f736b818b3fc2155ab`
BLAKE2b-256 checksum How to use checksums	`d5dce8a1de892916c09e2528ae7b9af81616b70af661a3689dac28ef130669f6`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.22.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	`b71d4a7e39e89fd78eb6f77df7d16561691e9e2fe32cb3113afacd4afd6e4ece`
BLAKE2b-256 checksum How to use checksums	`627e32baf9775a72cee7278f7552b7a8fcb2bc4ee0a509f93877761bb73fbfb2`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / aria_engine-1.22.0-cp310-cp310-macosx_11_0_arm64.whl

Download URL	aria_engine-1.22.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	`36761143002703f3752cf91c8818c72f24c9b4a38de637dddd4fa728068f6554`
BLAKE2b-256 checksum How to use checksums	`78e59dc8d726451d6f4eff7c577b1326efa6fc27744d54026347b12296415407`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`