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

Total release size: 30.1 MB

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

Download URL	aria_engine-1.18.1-cp313-cp313-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`b9bda95f4a9a25167ffbabef6df4658064146ba6e2f4b509a44047c8565c768e`
BLAKE2b-256 checksum How to use checksums	`c125775e0e5f54245d58324a37d8ba8259d5bdba578312ea151e14a79a7b15d6`
Upload date	Sep 1, 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.18.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.18.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	`92182166796d3dae7b0212aa2c9731bc1bf739decfbe8859c400e878af3e0a9b`
BLAKE2b-256 checksum How to use checksums	`07c0004a8c7b7dff0876dbde996924a6b3ab934dbe8f38e6050f3d258fc139d9`
Upload date	Sep 1, 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.18.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.18.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	`7ae316d94d447e5d32ca61d0a9d1e90204f214c7ae5bd14bcb8a7ee32755ae26`
BLAKE2b-256 checksum How to use checksums	`dfa19db92a9540641091cec60fd42c669b1abf720dbd2612631fd83c515eecd0`
Upload date	Sep 1, 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.18.1-cp313-cp313-macosx_11_0_arm64.whl

Download URL	aria_engine-1.18.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	`23c91bb7cee595cc6050e326f282288ba5248670e119ec77bd4c3a94a543c5fa`
BLAKE2b-256 checksum How to use checksums	`340aa968234389ce41197fb0f9baf75f1098a431260db9994c873c8dd8b29c67`
Upload date	Sep 1, 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.18.1-cp312-cp312-win_amd64.whl

Download URL	aria_engine-1.18.1-cp312-cp312-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.12 Windows x86-64
SHA-256 checksum How to use checksums	`1c55bc1cb1945323ee97b0e4fc807263a92cc56780781433c4159f1c06b5f005`
BLAKE2b-256 checksum How to use checksums	`4ace11d422488b39cc61bede260c7d095ff2fac8346881320359f81ec040e340`
Upload date	Sep 1, 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.18.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.18.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	`dec26382751767cd851ab7b35888e82fef68c67ce4275fb4b98f7f8b41cf0e7b`
BLAKE2b-256 checksum How to use checksums	`755ae7bebca7cb6b7644e0fa072909be8ab9f1cba05da6f06fece652f9893566`
Upload date	Sep 1, 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.18.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.18.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	`3338857145a20136b7af0e67a866a7e51881ef801bf91d2d51a106d189bf687b`
BLAKE2b-256 checksum How to use checksums	`e0c889933ef423bfcb022742596f792d37cd83a6e29bb1ad8e9d3644bf3a58de`
Upload date	Sep 1, 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.18.1-cp312-cp312-macosx_11_0_arm64.whl

Download URL	aria_engine-1.18.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	`520e21dee44980ce766737c0a0696e3e87ec784cb6ce087e93af1ed304a43b48`
BLAKE2b-256 checksum How to use checksums	`16c4930ccb3c934f0d1bb08d8be6e976d0ca5de9891fe844f850130401fb110d`
Upload date	Sep 1, 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.18.1-cp311-cp311-win_amd64.whl

Download URL	aria_engine-1.18.1-cp311-cp311-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`6e7a21a522a989db4ca6c29cb51caccec017f9551045a0db61c37f2a83fd8be5`
BLAKE2b-256 checksum How to use checksums	`9db03ed7c8a0e2ada72eb5e02116991ea1cf40cde0c911821855fcbb3c005166`
Upload date	Sep 1, 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.18.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.18.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	`b75192aaebe0f2404345b996a113cd73e57bcf99001a574af670a9825372654e`
BLAKE2b-256 checksum How to use checksums	`403389c29fc523be275f75885a458d52da8981649e5e5a6d1d13d45e4db8700d`
Upload date	Sep 1, 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.18.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.18.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	`138e60bf7408af58fd09d93dc13d7fc4be64461971dd9e08203cb25513a8c5c5`
BLAKE2b-256 checksum How to use checksums	`d2a70a5d5930559c2227e0a3bc5b60f23059315fc7a7500c2fe4db97b34adb9b`
Upload date	Sep 1, 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.18.1-cp311-cp311-macosx_11_0_arm64.whl

Download URL	aria_engine-1.18.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	`040ed079a479e71cecf52b66f7c31a67cddba730e0524be671851d5857a1516f`
BLAKE2b-256 checksum How to use checksums	`48ecb79d92bce3d6e7108cab02d2c38e8dc802a323f8976bf2a2168f8a8432c8`
Upload date	Sep 1, 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.18.1-cp310-cp310-win_amd64.whl

Download URL	aria_engine-1.18.1-cp310-cp310-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.10 Windows x86-64
SHA-256 checksum How to use checksums	`679da70f3e1323f4089d511efe8bc2bb76fd5f88d6021bc2be6f36c0c9ded8e4`
BLAKE2b-256 checksum How to use checksums	`36d852f73a9d3c3005d2f0109855804c738b814be7fa0707391c207fd730bd83`
Upload date	Sep 1, 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.18.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.18.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	`fdb2bbb83736c659b4065086ec89eeaf0427a0ba859e476ba6927418b73048a8`
BLAKE2b-256 checksum How to use checksums	`d8cbc3c247ed1cc1c208aecd38444b65824d6f900da275e349026910c71eec80`
Upload date	Sep 1, 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.18.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.18.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	`ba70a46e25d6aeb0f7d9fa83731dcad25315a74f340696964fabcec1392958ae`
BLAKE2b-256 checksum How to use checksums	`4e3d8c62f25d4612317a33a53435e592be89103fd9e658c2b92ab278546244c1`
Upload date	Sep 1, 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.18.1-cp310-cp310-macosx_11_0_arm64.whl

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