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 auth 相同；未传则读
~/.ariacompute/config.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 auth; does not write config.yml):
eng = Engine()
eng.auth(hf_token="hf_...")
eng.open("gemma-4-e2b-it_q4")
print(eng.complete([{"role":"user","content":"hi"}], {"max_tokens": 16}))
Engine.auth sets Config / Run fields on that instance only. CLI aria-engine auth still writes ~/.ariacompute/config.yml; the SDK never does. Empty fields still fall back to reading that file for hub download. Also: eng.auth_status(), eng.auth_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 手动输入）。
1 maintainer
Metadata
1 maintainer
Release files for aria-engine 1.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 30.2 MB
Release files / aria_engine-1.16.0-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.16.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
3a08081778d686738bc60ddf2aee019424b289d445377d47960619de2a18bd57
|
|
BLAKE2b-256 checksum How to use checksums |
2a29bd88ee5b7b5e0ba2d4ef5d7d45d5518e74e4757be7c43a38f760ed18ad9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.16.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 |
9c04c6fe5dfbdbeebf00110bbc4082607d1d2b23e4637413391bee7663bddb17
|
|
BLAKE2b-256 checksum How to use checksums |
e8ad90a59233514a3f9b7a276eac62e88d833e9634f0c619154fd06d82026d01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.16.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 |
8c03cb294ff585cf5db75dc901cb0567562a8a24540ff911a10058926589c330
|
|
BLAKE2b-256 checksum How to use checksums |
7cca6a7134b82a851288a85facc2e7665e67b7d8d3d98bd173d86ec3ba100bb4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.16.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 |
bc558743a05612cde33f0ae6b7cf3e31caa27cd1b4e01c16e4343e8cbd680cc0
|
|
BLAKE2b-256 checksum How to use checksums |
58e256f07dd60e8cc334b8332283cdd2cfc377fe71d1c42baf938153cbbb3872
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.16.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
f794be4cd89d48f826819a9a60d6ad4fda022cd25687235a30fdfd6f3558eab1
|
|
BLAKE2b-256 checksum How to use checksums |
8fc10a8738dd7752bea84d15185848c0c457ceed7d9e85133f5d0d6eeb288f36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.16.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 |
8dddff0b7ed727f7da02bac496905ab112069734847d0309a2b35284d9cdafbb
|
|
BLAKE2b-256 checksum How to use checksums |
c9074e8e9fe6e60231e94adccc386e505df2b4674b1b2a9564f673609658ad7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.16.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 |
f7776bf983e5a014fa76b5ef52c6cb4725cbd85a32bcb026dc41a07d68cd9901
|
|
BLAKE2b-256 checksum How to use checksums |
c355a1920becb8e74bf265d2d47db9f454c4e28d30d469f1537173fa6cc859d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.16.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 |
c12f207a935ffa9234141f0ef105c1e229c32fea3fd42307b5a3f8aaed077ec6
|
|
BLAKE2b-256 checksum How to use checksums |
cd2d4b0382a60c5b31ec0f3374b4c85e7c9307cc6c0b2346211da1b778324026
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.16.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
6e2b8c77982ec3b694727950bde1662bf4283b06d6d32b459b5487c149dc7d53
|
|
BLAKE2b-256 checksum How to use checksums |
488f27719e81c9e19a0a27c696b9065716fee8d20e8ccf50fffc8ce60627df23
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.16.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 |
c6bdaced1ac6f769c87feb2ced15f3a058e5a88b03aafc1e39fc46b4925d3a61
|
|
BLAKE2b-256 checksum How to use checksums |
89f2b39306a8ecfbaacff72948568225c22e6decfbbe05fb253c82321fed5db5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.16.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 |
4fce7cba1d109bf5c17713f9f82b21f29f293d92e01761d5f2c3652452262f8d
|
|
BLAKE2b-256 checksum How to use checksums |
bca4353470915cdd1db7582843aec139816ac19e015a1ec88ad2bc7e3ac0ba7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.16.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 |
519b2d35660c150a3cdd4c9cc4b4ac06fa869316f13ab4b73e1e0301b65bae89
|
|
BLAKE2b-256 checksum How to use checksums |
48d26c533ecdf2ee745e821569766ab2bd90504a0fe7c6c2970a44fbe38883bc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.16.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
7064ef593ead5202de475710a9efa1fabb1efc8de049325ce7863e046d718863
|
|
BLAKE2b-256 checksum How to use checksums |
a0ae09c72dd659c160cd52f458df106b1f2fc5b60d8a4ff8693a6e4e90cd27ae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.16.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 |
12c107b1928a9fda0b4550b12f92b1c7cba3fed3f43e9e66ab410a096be68437
|
|
BLAKE2b-256 checksum How to use checksums |
f294eb577a6c183670cc3637b54c377947c4dc51661f165236efd7e03be2b227
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.16.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 |
821094981f5c79d436eed6551762dbbbf6cf7579c951247c8ac5d119f078e2d6
|
|
BLAKE2b-256 checksum How to use checksums |
f118adf68afda8672be2265e7b5a3c0f1d2d552c7626db819298d144176ea5d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aria_engine-1.16.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.16.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 |
403fa160294e7221e85bcadef378d0db8b84d7b7a549192327648d773ca3cd6c
|
|
BLAKE2b-256 checksum How to use checksums |
37775200ae65042ee0c10dc46d41cfbc44ab6428c19805baa55954dbe21cd496
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
