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.19.1

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

Total release size: 30.1 MB

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

Download URL	aria_engine-1.19.1-cp313-cp313-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`631a5902c80604952714f6a3c88ba5f1d40dfe92ec7776a6cf083da8a60c7919`
BLAKE2b-256 checksum How to use checksums	`532c62fd60451e2ec95e20dbf2e165f07cd4780032faeaee3201bc0d569c3ee9`
Upload date	Sep 2, 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.19.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.19.1-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	`05e154288bc1e4db8b219989f261a2062be7842c81a45321345421d712f33069`
BLAKE2b-256 checksum How to use checksums	`3f59a2613dc8b8b4f25753debd94d506cc416c645ae21e070c8fee6bd76a3e28`
Upload date	Sep 2, 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.19.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.19.1-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	`9409d1570eca5747fde065a038c00af3c2002b14c741135c7715c149dfe0e00f`
BLAKE2b-256 checksum How to use checksums	`aba899cf20cbb62629346856245a0c923c91054fa7e2c8b469be63057e16a3ad`
Upload date	Sep 2, 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.19.1-cp313-cp313-macosx_11_0_arm64.whl

Download URL	aria_engine-1.19.1-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	`5b441774906132f5fd8839735fb656ec39f89da5224777209b2bfed2391a3bd9`
BLAKE2b-256 checksum How to use checksums	`6207e703fc01b67aa31b75d0632b4fcc749b37b3c63f66d519ae5442956934c2`
Upload date	Sep 2, 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.19.1-cp312-cp312-win_amd64.whl

Download URL	aria_engine-1.19.1-cp312-cp312-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.12 Windows x86-64
SHA-256 checksum How to use checksums	`ddf2a8266207aa16569d8dd026a7a14d642833d05c91ab6f9cefeabc84aeaa2c`
BLAKE2b-256 checksum How to use checksums	`fbb313e9ae57046ea28c0ba74c59b8b8fd666cbf96280f5d0ed213d30e6468f8`
Upload date	Sep 2, 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.19.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.19.1-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	`73034cd4cd5e49dda31caed2fc7a89988a2da4dce289ae147e2ad8701b311d35`
BLAKE2b-256 checksum How to use checksums	`4ce4a85c95073d5c6bafcd0b6b7cbc1e83cf4b90cce07fe480ade4c9edaba9f6`
Upload date	Sep 2, 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.19.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.19.1-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	`2c6251710e2aead29c2184819730a1798d732910a0432ffb7d89c53995776cf7`
BLAKE2b-256 checksum How to use checksums	`7e5967ac3bdfe700e7294e8b6d7a1633607234d172a3789da0925a25a8426515`
Upload date	Sep 2, 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.19.1-cp312-cp312-macosx_11_0_arm64.whl

Download URL	aria_engine-1.19.1-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	`cc43a401ee19b1ecd8335cb253980a7664ee6452e33c02b328aec7a0cf4502a7`
BLAKE2b-256 checksum How to use checksums	`51f9a8e08dcb339ee0d62a205b81145e3adfffdc4421ef2cd67dbd8bab8ad57e`
Upload date	Sep 2, 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.19.1-cp311-cp311-win_amd64.whl

Download URL	aria_engine-1.19.1-cp311-cp311-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`ce16cb0f584aba892096421aac697feb239297f5caa242f7848d494b017769fe`
BLAKE2b-256 checksum How to use checksums	`cf4bf43b010fe35fb256104917d7dc0b81321725c951c903b7656340e9219884`
Upload date	Sep 2, 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.19.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.19.1-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	`49e2f31fc3ba9f7aaf17c6589a3f1bcd6be13f8443a7be57f890e622e182e645`
BLAKE2b-256 checksum How to use checksums	`8a9308ea50461aa3a593dee0dba29a0a2208b18031f570c9537f2621ac9dd9fd`
Upload date	Sep 2, 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.19.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.19.1-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	`bf00c0c296759f15dbe02ece7dc69cf3ed9a2af94a4c35e6ab96520c2f725b0d`
BLAKE2b-256 checksum How to use checksums	`e9322a0b7eafb73c101cc15eaf23fa241a7daac02131df7fc420f0c0b0712c01`
Upload date	Sep 2, 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.19.1-cp311-cp311-macosx_11_0_arm64.whl

Download URL	aria_engine-1.19.1-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	`8ad80dff5f10a3fb78a597e2a9734026df44dd235dfc88e26ae93ddefb93b43b`
BLAKE2b-256 checksum How to use checksums	`3168adc1c045bbba7c2a60ee72f5afdce16d333a806c22c20dd7261d8d08a017`
Upload date	Sep 2, 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.19.1-cp310-cp310-win_amd64.whl

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

Download URL	aria_engine-1.19.1-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	`0eb670e2e06438e08f5a8fa7967edb1add5b06345ca72a9f032acd962f3e67ca`
BLAKE2b-256 checksum How to use checksums	`cc201fcfb77d802a044fb3460f6fa7f24d3cd68c2af2b6316f4454a3628b7d8c`
Upload date	Sep 2, 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.19.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.19.1-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	`e8cfc70cf606ce6c6719d49b5901385685300c5fc8c26dd2204b2e2a52ac308d`
BLAKE2b-256 checksum How to use checksums	`761194c7f12e58317d8652da0bddf6a9673949ec467a7634e60617721458ee05`
Upload date	Sep 2, 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.19.1-cp310-cp310-macosx_11_0_arm64.whl

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