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 从 Dashboard 私有源 自动下载（需 token，
site 默认 https://ariacompute.com）到 ~/.ariacompute/models/{model} 再加载。
缓存中已有有效 bundle 时直接复用，不重复下载。
with Engine("gemma-4-e2b-it_q4", token="API_TOKEN") 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> - 都找不到 →
RuntimeError（提示安装 wheel 或设置ARIA_FFI_LIB）
源码安装（开发）
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.6.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 29.7 MB
Release files / aria_engine-1.6.4-cp313-cp313-win_amd64.whl
| Download URL | aria_engine-1.6.4-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
169e7455216753dea41e0a72056f3dec87c3ee4e2530a59c19ae58d96f8c06af
|
|
BLAKE2b-256 checksum How to use checksums |
37abea0f8a8e8c0a2e037d4a2b6f86f512ed60dbf2f76756acd9e2b1ace1ccc5
|
| 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.6.4-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.6.4-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.13 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
004fe08d21ae38eb4a2ee77cc2c2697bcc7c075b1aabdcf9dac62c7356e4b1d1
|
|
BLAKE2b-256 checksum How to use checksums |
9b6c915b2811f89d925d67473ccb87f0152eb99193758da79e9b45f0846c7701
|
| 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.6.4-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.6.4-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 |
4c8bd91589de025726e6fdbf842717ce54d25c4fbfd07128939455b28291e15d
|
|
BLAKE2b-256 checksum How to use checksums |
9a4179e24f3dcb4e1ccba8d7a21656c467af1ff0c46c44bbcc249e8e9bb39846
|
| 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.6.4-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.6.4-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
92dbdec197926cca6c99b98078b961ee2258681e5296fd30fdb02552bd0b3380
|
|
BLAKE2b-256 checksum How to use checksums |
3ae05e302d9c6806a9ce0b40bf66b0047feb03e220b185c25608e3f20798af0b
|
| 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.6.4-cp312-cp312-win_amd64.whl
| Download URL | aria_engine-1.6.4-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
59a478ecf3b0091c55977303ff7807cbf52719516789f6a2469955284b5fe6df
|
|
BLAKE2b-256 checksum How to use checksums |
01c0a400ab1d224b48343bb974595d4cbb76f2a72e737820bc66ecd373aab1df
|
| 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.6.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.6.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
b7c619d4b3f2e5b7b430f87fa1b8501edb45db131476fb8092aac725901e29a7
|
|
BLAKE2b-256 checksum How to use checksums |
06fc1fe9f520e84d8565a0b5db4f8e6d06c0415e9dccbed9268ecc9fcb5f413b
|
| 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.6.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.6.4-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 |
cca120dd97feb6560cd838c1c89d5e2b832bb052e572b3563cff5ef6ef8ae18b
|
|
BLAKE2b-256 checksum How to use checksums |
c45b5f2cc55dc31d6483dc5f16efeb25be84b7fc9a5a422b09a1330a3d70ebbe
|
| 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.6.4-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.6.4-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
32d41aac6559a6a242f94494accc2926364c0de90c52029e099607913cb6f2db
|
|
BLAKE2b-256 checksum How to use checksums |
a246cd09064944572c83c497927e5beb12f717c5106a5ddabebc3c4b6b9561bb
|
| 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.6.4-cp311-cp311-win_amd64.whl
| Download URL | aria_engine-1.6.4-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
f57ed443062ceb36ce87ca0a3a5a8e4a971c241760585f5630d7761526bf30bb
|
|
BLAKE2b-256 checksum How to use checksums |
f3b763990eb6d7f108e37f3a91a4e21692ae479c8062824c41b95f4ee6e7f87a
|
| 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.6.4-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.6.4-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
d2093682185ceaa18efae0abd040ba8ce7edb1d712b6f7c15b70c9cf1d3650db
|
|
BLAKE2b-256 checksum How to use checksums |
8ff5f6c6b0e835cdc0d1c56a7a4f4d4cf4d622791e40f9dc45847518cbee2428
|
| 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.6.4-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.6.4-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 |
e7fb0923970d914f29c188ab265449807277aefdedfe3d0509d1804681b89552
|
|
BLAKE2b-256 checksum How to use checksums |
e73762e3a92312e42678317f77ef7726e7fd0259091681c2f5b70ddab3e06d9e
|
| 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.6.4-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.6.4-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d474b7373fa7dcdd19f8ee21d9d43fe9fd93e7a828a6f685828fca7a46496abb
|
|
BLAKE2b-256 checksum How to use checksums |
c95bdafbfc90c6c8702148c774540b31784c65a71f9a7d8b6fc5d567ac861721
|
| 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.6.4-cp310-cp310-win_amd64.whl
| Download URL | aria_engine-1.6.4-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
f972b81261c2e7ed2af6d9657678a459d168aa8c623f6acae082d0923a909f30
|
|
BLAKE2b-256 checksum How to use checksums |
2b84fbd0ad14b0f60f6563b4f717870a1a3ad93f49cc6df45ae1077828a795f6
|
| 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.6.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | aria_engine-1.6.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
2d077e4cfbc6f788f7795b4378054ec8ec35c9392ae35faad9cd92dc1a44bd60
|
|
BLAKE2b-256 checksum How to use checksums |
80f7455def293c1b61d08e81a651584112b54629375b1db23008e9287e70d171
|
| 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.6.4-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | aria_engine-1.6.4-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 |
30fd6d7c21fe57c5fa7dab613df4ea55cc21385b69e84d5e858c433066aae0fe
|
|
BLAKE2b-256 checksum How to use checksums |
bf08d22914c363a5b7b3800575d40af7557df7be646d4a0be202e0e3b14405e0
|
| 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.6.4-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | aria_engine-1.6.4-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b27ea5949fc2b42c7c4a61454a2d8e88d42c39aac8edee47e5b49d1c93ebee1c
|
|
BLAKE2b-256 checksum How to use checksums |
4f9a06f8762e4cc88376586f31818b540a10e38067be5357c284d03c4f409ee4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
