ROUTER 运行时

ROUTER 是咏唱引擎的 OpenAI 兼容推理网关。它用三种决策器选路：语义（YAML v0.3）、内置轻量 Agent，或 afm-d（走 AFM 运行时的 System One Choice），然后在硬约束下把请求转发到共享 providers。本页讲自托管的 CLI 和 FFI。HTTP API 见 ROUTER 介绍。

安装

从下载页下载你所在平台的最新发布版。

setup、validate、serve

aria-router setup
# 可选：--template semantic|agent|afm-d
aria-router setup --status

aria-router validate

aria-router serve --bind 127.0.0.1:8899 --mgmt-bind 127.0.0.1:8090

setup 之后，默认配置写在 ~/.ariacompute/router.yml。也可以用 --config 指向仓库里的示例配置。

要用 afm-d，先启动 engine 提供 System One，再用 afm-d recipe 或 ariacompute/afm-d-auto

数据面（--bind）：POST /v1/chat/completions、GET /v1/models
管理面（--mgmt-bind）：健康检查、校验、providers、拓扑、面板

勿与 aria-engine 常用端口（8080 / 8010 / 8011）冲突。

YAML 配置

块	含义
`listeners`	数据面绑定
`providers`	模型 / `backend_refs`
`entrypoints`	虚拟模型 → `router: semantic\|agent\|afm-d` + `recipe`
`recipes`	语义 `routing.`、agent `agent.` 或 afm-d `afm-d.*`
`global`	认证 / 密钥路径（可选）

一次请求只走一个入口：

ariacompute/semantic-auto
ariacompute/agent-auto
ariacompute/afm-d-auto

afm-d 需要用 AFM_ENGINE_URL 指向已运行的 aria-engine。用 aria-router setup --template afm-d 可以生成这套配置。响应头示例：

# layer: semantic|agent|afm-d|bypass
x-aria-router-layer: semantic
x-aria-router-decision: …
x-aria-router-model: …

快速请求

# 登录 Router 控制台以创建你的 Router API Key
curl -s http://127.0.0.1:8899/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer sk-aria_your_router_api_key' \
  -d '{
    "model": "ariacompute/semantic-auto",
    "messages": [{"role": "user", "content": "please explain rust"}],
    "max_tokens": 32
  }' | jq .

语言绑定

ROUTER 的 SDK 覆盖 Rust、Python、Go、TypeScript、React Native、Flutter、Swift 和 Kotlin，都封装同一套 C ABI；另外还提供 CLI 和 FFI 动态库。

# pip install ariacompute-router
from aria_router import Router

# aria-router setup 后：加载 ~/.ariacompute/router.yml
# 进程内 init+complete 不需要 Dashboard API key。
r = Router().init()
print(r.models())
print(r.complete(
    [{"role": "user", "content": "hi"}],
    {"model": "ariacompute/semantic-auto"},
))
print(r.last_route())
r.close()

# 或连接已运行的 serve（开启 require_api_key 时需要 token）：
r = Router().connect("http://127.0.0.1:8899")
r.setup(base_url="http://127.0.0.1:8899", token="")

// go get github.com/ariacompute/router/bindings/go
package main

import (
	"fmt"
	"log"

	aria "github.com/ariacompute/router/bindings/go"
)

func main() {
	r := aria.NewRouter()
	// 空路径 → ~/.ariacompute/router.yml（需先 aria-router setup）
	if err := r.Init(""); err != nil {
		log.Fatal(err)
	}
	defer r.Close()
	models, err := r.Models()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(models)
	out, err := r.Complete(
		[]map[string]string{{"role": "user", "content": "hi"}},
		map[string]string{"model": "ariacompute/semantic-auto"},
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(out)
	route, err := r.LastRoute()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(route)

	// 或连接已运行的 serve（开启 require_api_key 时需要 token）：
	_ = r.Connect("http://127.0.0.1:8899")
	r.Setup("http://127.0.0.1:8899", "")
}

// cargo add ariacompute-router
use ariacompute_router::{Router, SetupUpdates};
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut r = Router::new();
    // 空路径 → ~/.ariacompute/router.yml（需先 aria-router setup）
    r.init("")?;
    println!("{}", r.models()?);
    println!(
        "{}",
        r.complete(
            json!([{"role": "user", "content": "hi"}]),
            json!({"model": "ariacompute/semantic-auto"}),
        )?
    );
    println!("{}", r.last_route());

    // 或连接已运行的 serve（开启 require_api_key 时需要 token）：
    r.connect("http://127.0.0.1:8899");
    r.setup(&SetupUpdates {
        base_url: Some("http://127.0.0.1:8899".into()),
        token: Some("".into()),
    })?;
    Ok(())
}

// pod 'AriaComputeRouter'
import AriaComputeRouter
import Foundation

do {
    // load(nil) → ~/.ariacompute/router.yml（Swift 关键字；映射到 aria_router_init）
    let r = try Router().load(nil)
    print(try r.models())
    print(try r.complete(
        messages: [["role": "user", "content": "hi"]],
        options: ["model": "ariacompute/semantic-auto"]
    ))
    print(r.lastRoute())
    r.close()

    // 或连接已运行的 serve（开启 require_api_key 时需要 token）：
    let c = try Router().connect("http://127.0.0.1:8899")
    c.setup(baseUrl: "http://127.0.0.1:8899", token: "")
} catch {
    fputs("\(error)\n", stderr)
}

// implementation("com.ariacompute:router:+")
import com.ariacompute.router.Router

fun main() {
    // aria-router setup 后：加载 ~/.ariacompute/router.yml
    Router().init().use { r ->
        println(r.models())
        println(
            r.complete(
                listOf(mapOf("role" to "user", "content" to "hi")),
                mapOf("model" to "ariacompute/semantic-auto"),
            ),
        )
        println(r.lastRoute())
    }

    // 或连接已运行的 serve（开启 require_api_key 时需要 token）：
    Router().connect("http://127.0.0.1:8899").use { c ->
        c.setup(baseUrl = "http://127.0.0.1:8899", token = "")
    }
}

// flutter pub add ariacompute_router
import 'package:ariacompute_router/ariacompute_router.dart';

void main() {
  // aria-router setup 后：加载 ~/.ariacompute/router.yml
  final r = AriaRouter()..init();
  print(r.models());
  print(r.complete(
    [
      {'role': 'user', 'content': 'hi'}
    ],
    {'model': 'ariacompute/semantic-auto'},
  ));
  print(r.lastRoute());
  r.close();

  // 或连接已运行的 serve（开启 require_api_key 时需要 token）：
  final c = AriaRouter()..connect('http://127.0.0.1:8899');
  c.setup(baseUrl: 'http://127.0.0.1:8899', token: '');
}

// npm install @ariacompute/router-rn
const { Router } = require("@ariacompute/router-rn");

const r = new Router().init();
console.log(r.models());
console.log(
  r.complete([{ role: "user", content: "hi" }], {
    model: "ariacompute/semantic-auto",
  }),
);
console.log(r.lastRoute());
r.close();

// 或连接已运行的 serve（开启 require_api_key 时需要 token）：
const c = new Router().connect("http://127.0.0.1:8899");
c.setup({ base_url: "http://127.0.0.1:8899", token: "" });

// npm install @ariacompute/router-ts
import { Router } from "@ariacompute/router-ts";

// aria-router setup 后：加载 ~/.ariacompute/router.yml
const r = new Router().init();
console.log(r.models());
console.log(
  r.complete([{ role: "user", content: "hi" }], {
    model: "ariacompute/semantic-auto",
  }),
);
console.log(r.lastRoute());
r.close();

// 或连接已运行的 serve（开启 require_api_key 时需要 token）：
const c = new Router().connect("http://127.0.0.1:8899");
c.setup({ base_url: "http://127.0.0.1:8899", token: "" });

何时用 aria-router，何时用 aria-engine

路由网关（OpenAI chat + 策略）：aria-router
仅类型化 System One 决策：直接调用 aria-engine 或 Ollaya

快速开始

产品

指南

SDK

资源

安装

setup、validate、serve

YAML 配置

快速请求

语言绑定

何时用 aria-router，何时用 aria-engine

​安装

​setup、validate、serve

​YAML 配置

​快速请求

​语言绑定

​何时用 aria-router，何时用 aria-engine

安装

setup、validate、serve

YAML 配置

快速请求

语言绑定

何时用 aria-router，何时用 aria-engine