> ## 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-router 运行时与 FFI

> 使用 aria-router 二进制在多个 Aria 模型包之间分发请求，或将 libaria-router_ffi 链接进你自己的服务。

`aria-router` 位于一个或多个 `aria-engine` 实例之前，根据请求元数据（模型 slug、量化等级、能力）将请求路由到正确的模型。它既可独立运行，也可嵌入 FFI 共享库。

## 安装

获取你的平台最新发布：

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

在中国站，同一接口从 Gitee 镜像提供，地址为 `https://ariacompute.cn/api/download/router-latest`。

## 配置

提供一个路由配置，列出每个后端引擎及其服务的模型：

```yaml router.yaml theme={null}
listen: 0.0.0.0:9090
backends:
  - name: gemma-e2b
    url: http://127.0.0.1:8080
    models: [gemma-4-e2b-it_q4]
  - name: qwen-e4b
    url: http://127.0.0.1:8081
    models: [qwen-3-e4b-instruct_q4]
routing:
  policy: model_slug
```

## 运行

```bash theme={null}
./aria-router --config ./router.yaml
```

随后客户端将请求发送到 `http://<host>:9090/v1/chat/completions`，并将 `model` 字段设为配置中列出的某个 slug。`aria-router` 会把请求转发到匹配的后端。

## 通过 libaria-router\_ffi 嵌入

每个发布版都会附带 `libaria-router_ffi-<platform>.{so,dylib,dll}` 与一个 C 头文件。可从任何具备 C ABI 的语言链接它。

```c router.c icon=c theme={null}
#include "aria_router.h"

int main(void) {
    AriaRouter *r = aria_router_new_from_file("./router.yaml");
    aria_router_serve(r); // 阻塞
    aria_router_free(r);
    return 0;
}
```

<Tip>
  请参阅打包的 `include/aria_router.h` 了解完整的 FFI 面：运行时重载配置、热替换后端，以及查看路由指标。
</Tip>

## 何时直接使用 aria-router 而非 aria-engine

* **单模型、单进程**：运行 `aria-engine serve`，将客户端直接指向它。
* **单主机多模型**：为每个模型运行一个 `aria-engine`，并在其前放置 `aria-router`，以便客户端按 slug 选择模型。
* **多主机、多租户**：将 `aria-router` 作为入口，并为每个后端配置健康检查与权重。