> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# aria-engine 运行时与 FFI

> 使用 aria-engine 二进制在设备端运行 Aria 模型包，或从 C、Rust、Python 或 Swift 链接 libaria-engine_ffi 以进行嵌入式推理。

`aria-engine` 在本地运行 Aria 模型包（`weight.bin` + `config.json`），用于语言、视觉与 VLA/策略推理。它既可作为独立二进制分发，也可将 FFI 共享库嵌入你的应用。

## 安装

从[下载页](/resources/downloads)获取你的平台最新发布，或以编程方式获取：

```bash theme={null}
curl -s https://ariacompute.cn/api/download/engine-latest \
  | jq -r '.assets[] | select(.name | test("linux-x86_64.tar.gz$")) | .url' \
  | xargs curl -L -o aria-engine.tar.gz
tar xf aria-engine.tar.gz
```

<Note>
  在中国站，同一接口从 Gitee 镜像。请使用 `https://ariacompute.cn/api/download/engine-latest`。
</Note>

## 获取模型包

用你的 API 密钥下载模型包，然后解包：

```bash theme={null}
curl -L -H "Authorization: Bearer bfvk-XXXXXXXXXXXXXXXX" \
  "https://ariacompute.cn/api/models/gemma-4-e2b-it/download?quant=int4&sdk=v1.0" \
  -o gemma-4-e2b-it_q4.zip
unzip gemma-4-e2b-it_q4.zip -d ./models/gemma-4-e2b-it_q4
```

模型包包含 `weight.bin`、`config.json` 以及可选的 tokenizer 附属文件。完整的布局与量化矩阵参见[模型](/concepts/models)。

## 通过 CLI 运行推理

```bash theme={null}
./aria-engine serve \
  --model ./models/gemma-4-e2b-it_q4 \
  --host 127.0.0.1 --port 8080
```

该服务在配置端口上暴露与 OpenAI 兼容的 `/v1/chat/completions` 接口。将任意 OpenAI 兼容客户端指向 `http://127.0.0.1:8080/v1` 即可。

## 通过 libaria-engine\_ffi 嵌入

每个发布版都会在 CLI 旁附带一个共享库：`libaria-engine_ffi-linux-x86_64.so`、`libaria_engine_ffi.dylib`、`aria_engine_ffi.dll`。可从 C、Rust、Python（通过 `ctypes`/`cffi`）、Swift 或任何具备 C ABI 的语言链接它。

<Tabs>
  <Tab title="C">
    ```c app.c icon=c theme={null}
    #include "aria_engine.h"

    int main(void) {
        AriaEngine *engine = aria_engine_new("./models/gemma-4-e2b-it_q4");
        char *out = aria_engine_generate(engine, "Hello, world.", 256);
        printf("%s\n", out);
        aria_engine_free_string(out);
        aria_engine_free(engine);
        return 0;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import ctypes
    lib = ctypes.CDLL("./libaria-engine_ffi-linux-x86_64.so")
    lib.aria_engine_new.restype = ctypes.c_void_p
    lib.aria_engine_generate.restype = ctypes.c_char_p
    engine = lib.aria_engine_new(b"./models/gemma-4-e2b-it_q4")
    out = lib.aria_engine_generate(engine, b"Hello, world.", 256)
    print(out.decode())
    ```
  </Tab>
</Tabs>

<Tip>
  打包的 C 头文件随发布归档一同提供，位于 `include/` 下。查阅它们可了解完整的 FFI 面：流式回调、KV 缓存管理、分词器辅助函数与清理函数。
</Tip>

## 引擎内部的模型拉取

`aria-engine` CLI 也可以直接从 Hugging Face（国际站）或 ModelScope（中国站）拉取模型。这与控制台的模型库相互独立，不消耗你的咏唱引擎钱包：

```bash theme={null}
./aria-engine pull ariacompute/gemma-4-e2b-it_q4
```