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:
with Engine("gemma-4-e2b-it_q4", hf_token="hf_...") as eng:
print(eng.complete([{"role":"user","content":"hi"}], {"max_tokens": 16}))
动态库查找顺序
_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.15.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.1 MB
Release files / aria_engine-1.15.0-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.15.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
7ab2b984ea833e35dd2718eec32349392cf597fe5f5b49088dab3137230ff49f
|
|
BLAKE2b-256 checksum How to use checksums |
37e0972ed1a33ff1898e39e9c282a12f1e9ba68602b3362643f5e4868da4705c
|
| 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.15.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.15.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 |
2e4a9b4e8b6ba3e4d64122dcffa0cc3fec5db9f6f2cc6045db009e9e6e134afb
|
|
BLAKE2b-256 checksum How to use checksums |
fdb5f46d77d963d0c0a1d27ae98928e93312654e5cf67d29e288ac3135fc5c79
|
| 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.15.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.15.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 |
a5fc0710c7769ac06b7303ac7971615486b58d86426a7441a61c42dcb91efd90
|
|
BLAKE2b-256 checksum How to use checksums |
f040dc626516579c72f635c86dc91b258d5b3de98a957a17bbbbc7b50d0e0881
|
| 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.15.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.15.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 |
02d233ebdda90ddf072546cecab5ed6fe06eac9502e625329db5dcfd64d020b4
|
|
BLAKE2b-256 checksum How to use checksums |
b5ab315988d119b1364056a7118521714918a6dcc5d585eb0b1c6d73b3a59d07
|
| 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.15.0-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.15.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
741ec80dacc803c27aef59ea5ee25c87d5a5f46d36c109284b44c32bb57e460f
|
|
BLAKE2b-256 checksum How to use checksums |
9bff04290941285419aaac4a92c599d3e5cef91a00595480a76b114b08dcd910
|
| 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.15.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.15.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 |
c22fbdededc2104e27ebdc9675470c9a3f06dfb05cbade45bcafe3eec9dec3aa
|
|
BLAKE2b-256 checksum How to use checksums |
fea9b1b8cd94bcdc2e5b646478bb8a3c1161aae9743b2e33f032e8c5b0abe758
|
| 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.15.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.15.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 |
498ff3783e0375d060ac8c331b4f696fc3c01c10f401a8b612d66e6d65bf1105
|
|
BLAKE2b-256 checksum How to use checksums |
11e94e9a73a2bd36a9389dfdbe6b788b647e8fe07b1e0a178d4b2631a22c3018
|
| 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.15.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.15.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 |
f098abc170ad0975eb3321a5fa5e22253f5028ba4b156311dcfe36ac2073551e
|
|
BLAKE2b-256 checksum How to use checksums |
da66df62c99282788c18071d86321ae181add013488fd14c65fa6f7d785443a8
|
| 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.15.0-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.15.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
b97ed4c5744aab89b8d08b37b90893e1b67c4de66e4230da06218af5aef74ba6
|
|
BLAKE2b-256 checksum How to use checksums |
6b09f1ede861c92f072a23eaa12e22cea7ece4b5f150d94109575cbf8758f246
|
| 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.15.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.15.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 |
67ede232e3b7651c45c64bdb73161ede24fed15510294438e10b6fa316bad5c9
|
|
BLAKE2b-256 checksum How to use checksums |
6a0523d56cae54fe979f76eae8a925f5dda8d0b8b056d0923ea6aea674bc07ee
|
| 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.15.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.15.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 |
1ed7baa815f640e9476e56ab78c0a9cfab179c59c90d9db07c729b0abb1d501e
|
|
BLAKE2b-256 checksum How to use checksums |
9f7708e87e3eaeff3166086430413a68cf0423e276ba6fcdbf393ddb02cb0014
|
| 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.15.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.15.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 |
b7a676af64ba50495142fca10b9bcde6198e0f782620372712b3c3ba741d7c93
|
|
BLAKE2b-256 checksum How to use checksums |
22966911e5104ee656054706741f5d96161f7421e4b85431fc5db862ae682172
|
| 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.15.0-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.15.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
91707e189f2cf26a2401c360f84e7a23ec216c310299e7740ea9f9cb24031350
|
|
BLAKE2b-256 checksum How to use checksums |
4c1152348dccdd086673f4f879aa955f31e02d4016a1228ad8bea10f1986d1cd
|
| 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.15.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.15.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 |
5f6061ef381b2aa4b332dd5d9ff9b1bd8dbf263481f49f88541d0e49f0b5aa7e
|
|
BLAKE2b-256 checksum How to use checksums |
c009906fecdb94cd54722d019488acde6bcd8a96f861ef24742bb3046785d071
|
| 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.15.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.15.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 |
a10a63b2d269a7550b61691c270e7ead4162cbc5841beabb0832e3090896f173
|
|
BLAKE2b-256 checksum How to use checksums |
de7466179f714ae5928a2762c24fbdf2c9595f14b6c8fbcacb9ac23bdaf14f89
|
| 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.15.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.15.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 |
2f5a686f1185057eb857f0dfc52a5345d80b56f7ff9dca8ffb47d9797523744b
|
|
BLAKE2b-256 checksum How to use checksums |
735d19475e5bb127b2fe06bc41707393d8c43fc7e33ac7c4d0d56e391dc04b6b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
