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

Metadata

Release files for aria-engine 1.20.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.20.0
File	Interpreter	ABI	Platform	Reset
aria_engine-1.20.0-cp313-cp313-win_amd64.whl 1.7 MB Sep 3, 2026	CPython 3.13	CPython 3.13	Windows x86-64	Details
aria_engine-1.20.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 2.1 MB Sep 3, 2026	CPython 3.13	CPython 3.13	Linux glibc 2.17+ x86-64	Details
aria_engine-1.20.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 2.0 MB Sep 3, 2026	CPython 3.13	CPython 3.13	Linux glibc 2.17+ ARM64	Details
aria_engine-1.20.0-cp313-cp313-macosx_11_0_arm64.whl 1.8 MB Sep 3, 2026	CPython 3.13	CPython 3.13	macOS 11.0+ ARM64	Details
aria_engine-1.20.0-cp312-cp312-win_amd64.whl 1.7 MB Sep 3, 2026	CPython 3.12	CPython 3.12	Windows x86-64	Details
aria_engine-1.20.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 2.1 MB Sep 3, 2026	CPython 3.12	CPython 3.12	Linux glibc 2.17+ x86-64	Details
aria_engine-1.20.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 2.0 MB Sep 3, 2026	CPython 3.12	CPython 3.12	Linux glibc 2.17+ ARM64	Details
aria_engine-1.20.0-cp312-cp312-macosx_11_0_arm64.whl 1.8 MB Sep 3, 2026	CPython 3.12	CPython 3.12	macOS 11.0+ ARM64	Details
aria_engine-1.20.0-cp311-cp311-win_amd64.whl 1.7 MB Sep 3, 2026	CPython 3.11	CPython 3.11	Windows x86-64	Details
aria_engine-1.20.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 2.1 MB Sep 3, 2026	CPython 3.11	CPython 3.11	Linux glibc 2.17+ x86-64	Details
aria_engine-1.20.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 2.0 MB Sep 3, 2026	CPython 3.11	CPython 3.11	Linux glibc 2.17+ ARM64	Details
aria_engine-1.20.0-cp311-cp311-macosx_11_0_arm64.whl 1.8 MB Sep 3, 2026	CPython 3.11	CPython 3.11	macOS 11.0+ ARM64	Details
aria_engine-1.20.0-cp310-cp310-win_amd64.whl 1.7 MB Sep 3, 2026	CPython 3.10	CPython 3.10	Windows x86-64	Details
aria_engine-1.20.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 2.1 MB Sep 3, 2026	CPython 3.10	CPython 3.10	Linux glibc 2.17+ x86-64	Details
aria_engine-1.20.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 2.0 MB Sep 3, 2026	CPython 3.10	CPython 3.10	Linux glibc 2.17+ ARM64	Details
aria_engine-1.20.0-cp310-cp310-macosx_11_0_arm64.whl 1.8 MB Sep 3, 2026	CPython 3.10	CPython 3.10	macOS 11.0+ ARM64	Details

Total release size: 30.2 MB

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

Download URL	aria_engine-1.20.0-cp313-cp313-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`ebc8cf1ab823dcd1de9f381d4f17635a88952c17800dbba486ec9952f527ee7e`
BLAKE2b-256 checksum How to use checksums	`adac7d8e7b28cac36eb180e47107484c45727d6e78654002375bd8e8d6c90b69`
Upload date	Sep 3, 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.20.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.20.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	`ecfd8c6cfe747401f56cdb5e2f8074113286c040a62eccba918f663811c15eaa`
BLAKE2b-256 checksum How to use checksums	`fbaa6e9510fb0c78382cdaa212525844e2b6d7675576c995d6c28c9434744345`
Upload date	Sep 3, 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.20.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.20.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	`b7993c2a55a32e860a6ca73417a8a5fe702ee3bedcb6880b7f05cdca90d28098`
BLAKE2b-256 checksum How to use checksums	`1bcdd2f285551df78106b37417cde9ff6c97b7d627522d4d9c75f8b45d2a81f6`
Upload date	Sep 3, 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.20.0-cp313-cp313-macosx_11_0_arm64.whl

Download URL	aria_engine-1.20.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	`c1f7ae279e964bfb5955a5c088ad5116406dfdcdc2568cbb1e89591de40148bc`
BLAKE2b-256 checksum How to use checksums	`63879127365f8339838c79a1536447a947f6229b2ce0ca212b9144d6c9ad0451`
Upload date	Sep 3, 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.20.0-cp312-cp312-win_amd64.whl

Download URL	aria_engine-1.20.0-cp312-cp312-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.12 Windows x86-64
SHA-256 checksum How to use checksums	`fd03b4b279a672d3e26274ab59b2af57f5c05c74cbedd3e01456633b84b8befe`
BLAKE2b-256 checksum How to use checksums	`181c0cefcdd0783d175726a781a8c7af7a6d30a36f0213fbd66d53c3302411f5`
Upload date	Sep 3, 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.20.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.20.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	`25a6c2e1231ff415433013d6553b6d3faaf21bcb28ad4a34566e0f54ab12b9ac`
BLAKE2b-256 checksum How to use checksums	`e1058ef197f1a274f222f7b9e0cae6b6d1c826a36517936cab36fbecffdb05cf`
Upload date	Sep 3, 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.20.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.20.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	`47d3d3a776341111d0dc32a3e4f47716f2b0848d4a915e94afbf48b7755aa5f4`
BLAKE2b-256 checksum How to use checksums	`50fa99ff924325033c07061de4ee15621db9001113a87a4be46294c76b4eed43`
Upload date	Sep 3, 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.20.0-cp312-cp312-macosx_11_0_arm64.whl

Download URL	aria_engine-1.20.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	`1e81491abe7df35ef41627962f7c3355cc1c701de20142473424395f365c3ca8`
BLAKE2b-256 checksum How to use checksums	`7526280c92a6e3538f81153724c13ccc51f290b0fac54b89d1e8d96c06c703cb`
Upload date	Sep 3, 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.20.0-cp311-cp311-win_amd64.whl

Download URL	aria_engine-1.20.0-cp311-cp311-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`083c8f2f31bbed6f7e9bcf2bd5471afb62e4f811447fd169ad2add61389d876f`
BLAKE2b-256 checksum How to use checksums	`6fc947507aee745e91badcd9c1f9052c725bc822114014e564c036f4e07ce021`
Upload date	Sep 3, 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.20.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.20.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	`6bdad3e6922e4afd9632df170694554fee4d5d5e7d1313e4ae9ef59e6ec45279`
BLAKE2b-256 checksum How to use checksums	`1c29b7674939ed27d737648a38e42b36e062382290f87d11d42134bda0aff177`
Upload date	Sep 3, 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.20.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.20.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	`5e85ae7b6c8ddff940717c3be4828565995555d0986f039f3df13b385af5cbdb`
BLAKE2b-256 checksum How to use checksums	`8a1124386d3f15dd8017a19edc902f4c92c00d79bbf3eb495fb8b0154378ae08`
Upload date	Sep 3, 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.20.0-cp311-cp311-macosx_11_0_arm64.whl

Download URL	aria_engine-1.20.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	`59fecb91962aa041834ec7797d8527602f7d1628d0f538b5e7b4060b9881983e`
BLAKE2b-256 checksum How to use checksums	`842cd0fd3d787e489b06f7e7e8b412e87362825b652ec8fa6d72e168f135dd76`
Upload date	Sep 3, 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.20.0-cp310-cp310-win_amd64.whl

Download URL	aria_engine-1.20.0-cp310-cp310-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.10 Windows x86-64
SHA-256 checksum How to use checksums	`bec325e7c465150b1f5bd08ef8b3ddd7a234395d9625841f471073c1f13ae320`
BLAKE2b-256 checksum How to use checksums	`2efa361b2e6010b0a3f8ca1d641f621295733e3173c6ca8cf403251ad140609c`
Upload date	Sep 3, 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.20.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.20.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	`f7104073dfc168737f87e200a6244e09e9a2fb1c4a7ee3711a6a805576c876b7`
BLAKE2b-256 checksum How to use checksums	`28d287dd11f20f54ba91f5db7e962501d38dd2edeb0e679b690f24d6f47804a1`
Upload date	Sep 3, 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.20.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.20.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	`4e6ce9c5ad89dd35e6189a6d688f3f3cb8cfcb3fbf49d66ae02d7e61babdd24f`
BLAKE2b-256 checksum How to use checksums	`8a91276fbacb9a5e39744f6cadee3f05d28b0f86acba2b587135ceafbd936dff`
Upload date	Sep 3, 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.20.0-cp310-cp310-macosx_11_0_arm64.whl

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