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.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.20.1
File	Interpreter	ABI	Platform	Reset
aria_engine-1.20.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-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.1-cp313-cp313-win_amd64.whl

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

Download URL	aria_engine-1.20.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	`2865954bfba7235025d31e28720494cab7d2da8f65c4f9a9be4f78cf4dfdac1d`
BLAKE2b-256 checksum How to use checksums	`05f936fe0d1b32c323ae2d8770cb789a37d7e4455d6500e05c26986c586ae636`
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.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.20.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	`33d39a65b773898d654c42814f572dcc562a42477598a10c851505f9982d80e3`
BLAKE2b-256 checksum How to use checksums	`8c9b477efa88c756eb0c6788d16e1a68ffedc496e06fbe66ea80b06f040b0968`
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.1-cp313-cp313-macosx_11_0_arm64.whl

Download URL	aria_engine-1.20.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	`b59673d77fe4b00bf8dfa6aaba94ed425315a9a79089f5970d8d01fce9159754`
BLAKE2b-256 checksum How to use checksums	`26c84ba1ad112bfbd808d49774572bfaa0355d2a3e02c6443677f9ee6f870419`
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.1-cp312-cp312-win_amd64.whl

Download URL	aria_engine-1.20.1-cp312-cp312-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.12 Windows x86-64
SHA-256 checksum How to use checksums	`29b28ec1cb9eff11a7798f73f117f3509dc827ead6aa1e1067334f4fe982327d`
BLAKE2b-256 checksum How to use checksums	`3eb24e10decd8d399effe0e5bcbbbfeeda56b390662bab666be3f0f3d752aafc`
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.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.20.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	`fbef774b228184f55e3bf7af2879782ecf5215956b49383a9f556f08b81ed447`
BLAKE2b-256 checksum How to use checksums	`24034f3c639d336f2c82c53ab05200bd54acffdc0455529949650476840f8fda`
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.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.20.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	`f53a69da3edae5ca955ce2d241d9ed74d7fab1246105d013c7145174ab03667d`
BLAKE2b-256 checksum How to use checksums	`1cabc3c2f39be4c20fa0aca4947be3494cdd92bb8662353ac7499581f13fbf8d`
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.1-cp312-cp312-macosx_11_0_arm64.whl

Download URL	aria_engine-1.20.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	`c3b2ea3c3347db59d013701342423df03103f49af4f3bcbb2925a7ab73fbcb84`
BLAKE2b-256 checksum How to use checksums	`44f53b20e2b128783830f660e717a9be3f43f16f3c0e7ee19b388abee41f0378`
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.1-cp311-cp311-win_amd64.whl

Download URL	aria_engine-1.20.1-cp311-cp311-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`569ca22287743933af1c3266d3911d2240161fd5929465025e52a04f256619de`
BLAKE2b-256 checksum How to use checksums	`10e5b2e55a2e9b2f11f1ec8993f98c5acf28ad2740d2375640bbdc09c1ccbb41`
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.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.20.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	`9fb398094084f1188a74bf2723575523d13edde8672cdbada400cd7fef9a6fab`
BLAKE2b-256 checksum How to use checksums	`e4f307a79c52e4cfa6e36d00dc5616fefe383bfe1a6b2177695f6f2ad1c3f389`
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.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.20.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	`728a7fe88722f0399c3aaf88733bc148276ae30844cbee705beed8c08af7ddf5`
BLAKE2b-256 checksum How to use checksums	`23b3a6e05895a385b73058c1c0e2a281bebf05ab3972fd8415a1b1f22e8155d2`
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.1-cp311-cp311-macosx_11_0_arm64.whl

Download URL	aria_engine-1.20.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	`e668b1190efeeb4e5b581b189e89ab3caa2ffbc0e1dea5b0163debadc1ce1e4f`
BLAKE2b-256 checksum How to use checksums	`ca8aeb549a540cf4ad87c5a055ae84b9e39a50b580e77b8a827f88b6e9e2189a`
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.1-cp310-cp310-win_amd64.whl

Download URL	aria_engine-1.20.1-cp310-cp310-win_amd64.whl
Size	1.7 MB
Tags	CPython 3.10 Windows x86-64
SHA-256 checksum How to use checksums	`6a32857ac44b10dce162a38a90ec8e1efcd71ef86765a9b7287545094b7a897b`
BLAKE2b-256 checksum How to use checksums	`98a1780f40e01765df48ab9c3ed4816d65628587cb7f5a2d90e5302a45292e84`
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.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	aria_engine-1.20.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	`bebf9d2ce9204a0adfd92b7b8e14ca9557cc27858669ded16dbbc60523c8ab92`
BLAKE2b-256 checksum How to use checksums	`6d10daf5d499c091b0841eef05d3ac2d9e86897d3d7f7303ac2dd544073dd867`
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.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL	aria_engine-1.20.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	`ce15766996dbdcaabd7686b7f7a04d44578778ed77899873571088a75102474d`
BLAKE2b-256 checksum How to use checksums	`208e73aad1a984b673d7e3b86fcc267c60b77de11dc758e50c371a7438694677`
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.1-cp310-cp310-macosx_11_0_arm64.whl

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