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.21.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.21.0
File	Interpreter	ABI	Platform	Reset
aria_engine-1.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.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.21.0-cp313-cp313-win_amd64.whl

Download URL	aria_engine-1.21.0-cp313-cp313-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`8c230b1baa11be026d1f14a81c0d59f14833a15f180cbd2a3b57c692a6872a40`
BLAKE2b-256 checksum How to use checksums	`1e35e49218f72c0ddf1758f77569d5613f13d9c28260d7c53d4978385d65f86c`
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.21.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.21.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	`fdb6565f68c6835a9ffea6c9f2aa32d171021b6fd6f7c8c19e52aa608eede7a9`
BLAKE2b-256 checksum How to use checksums	`4b6098613bfebd00186c5bc2a6bf730b8f69ffb72a503bd751a368650c79c7a6`
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.21.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.21.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	`024a9b87d9a701a2571859c5365469522498da38f0bf00e043a68a1e062d19c4`
BLAKE2b-256 checksum How to use checksums	`060aaf2cf2894a890de39a033c2168675b53995fc27613c161151a2f33415233`
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.21.0-cp313-cp313-macosx_11_0_arm64.whl

Download URL	aria_engine-1.21.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	`35b4d0cd4644cae50f067bc3ab1103d94eb8ffef490b5628809b0ababf600c77`
BLAKE2b-256 checksum How to use checksums	`953025e37a587bbfbe964ed66ec912abf761840f865853a26513d6fe5b46a9a1`
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.21.0-cp312-cp312-win_amd64.whl

Download URL	aria_engine-1.21.0-cp312-cp312-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.12 Windows x86-64
SHA-256 checksum How to use checksums	`b0b28ea17ca1730b2a1912442ca732c04a19a15ed08dab9881cfb2fe0db21816`
BLAKE2b-256 checksum How to use checksums	`773a6187a9861f82b6c5f2612600f2bd7f6a1d2a72257db7e29594749f8a5bbf`
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.21.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.21.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	`e979149c8cae7d4ad361ebf765ea681500a5480d2df9cf142d5a13d1198ff283`
BLAKE2b-256 checksum How to use checksums	`912036c0bd8f84084d9de68e73e589e2afc25ef49478fa968794c44ed43f5723`
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.21.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.21.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	`4a1a6fdcb92fd191065a6a7cdab97538009e6d70146dff61a9692f1d630a13f1`
BLAKE2b-256 checksum How to use checksums	`cb351838fc7a6ab3aea4542c198e2bda81df2d2e2e21d617d18d4879f9980dc8`
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.21.0-cp312-cp312-macosx_11_0_arm64.whl

Download URL	aria_engine-1.21.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	`1fdbefe1f260ed4f539dfa77ed5ecfec51bfd89d07ecdbc08d6d8e99c0f474ae`
BLAKE2b-256 checksum How to use checksums	`195216f8a7503e0ab9bb53ebc388d7040af4b4787247fb38e2b389842fce13e0`
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.21.0-cp311-cp311-win_amd64.whl

Download URL	aria_engine-1.21.0-cp311-cp311-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`1f3ffd65d40da15925845606f1dfea6c29c2aa99f8132f1c97d03e4f58f03f8a`
BLAKE2b-256 checksum How to use checksums	`16ebd89b817aec4b0bc73f0bd3f878f0d00e1638ad2627d86e3ba7197da3809e`
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.21.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.21.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	`0b98ab8be7de6e893fec6fe697ae3e5c2fa261dc591a815e1d53da850388e03d`
BLAKE2b-256 checksum How to use checksums	`e5f3e5d5c938e8907b7f125f05d4e2719a22042448a450528427de618448c20e`
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.21.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.21.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	`8517f733c0cb2be711ef16546531c74ed24e50bdfab4e55b4378aa0cb532236c`
BLAKE2b-256 checksum How to use checksums	`e8ded8dd6323d1d4475c0dceff181847cf21e5ea0a339654dac03ee937a63124`
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.21.0-cp311-cp311-macosx_11_0_arm64.whl

Download URL	aria_engine-1.21.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	`d1cddc082c3034a71870be7e2f433bfa8ce123d0c5e844748aa1a2222616ccda`
BLAKE2b-256 checksum How to use checksums	`a60dbeaeb78be419f7e3aa5c691723929900372feaa7b998062617c83cfd2719`
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.21.0-cp310-cp310-win_amd64.whl

Download URL	aria_engine-1.21.0-cp310-cp310-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.10 Windows x86-64
SHA-256 checksum How to use checksums	`c27dfaea5f469cae012781dde5aefa0e3c8083f5d6f4ad5f953ee414286823bd`
BLAKE2b-256 checksum How to use checksums	`7a5fd72146840d9af69006b7971ed34eda40cd743edf6b41537a367d3f143733`
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.21.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.21.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	`5cc9fe73e9275cc7459bffd56d3cf851352395485aaa8c9f0affb5ae62f46ec3`
BLAKE2b-256 checksum How to use checksums	`e1bbb60f43adebed3e2b102fabbb752e3946eb809c29fafea56d7b1622af24a2`
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.21.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.21.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	`c8ead30061bf84a4f7dbfed350cdf4910847d289b0d525978f2eafc6c7210350`
BLAKE2b-256 checksum How to use checksums	`265629747449fdcac54f2b7a11e1f087545806403bcf82e9ef00f4eadfdeb993`
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.21.0-cp310-cp310-macosx_11_0_arm64.whl

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