arcships/aimux
GitHub: arcships/aimux
aimux 是一个 Rust 实现的统一 LLM 访问层，用一套 API 消除不同 AI 服务商之间的接口差异，支持 325 个 provider 和 8 种编程语言绑定。
Stars: 162 | Forks: 7
# aimux
`，因此无需更改调用处即可互换 provider。
- **全面的多模态支持** — 文本、流式传输、工具调用、embeddings、图像、
语音、转录、视频、reranking、文件。
- **配置驱动的 provider 注册表** — `provider-registry.json` 描述了
250 个 OpenAI 兼容的 provider（base URL、env var、profile
特性：top_k、tools、response_format、流式传输 usage、max_tokens 键）；
在每种语言的绑定中都有一个统一的 `provider(name, ...)` 入口。
- **快速且小巧** — Rust 核心，release profile 针对二进制文件大小进行了优化
（`lto`、`codegen-units=1`、`panic="abort"`、`strip`、`opt-level="z"`）。
- **源自同一核心的 8 种语言绑定**：Node、Python、Swift、Kotlin、Flutter、
Go、Java、C。
- **密闭测试** — 2,650 多个 cassette 重放真实的 API 响应；无需网络
或 API 密钥。
## 性能
在同一台机器、同一个 mock server 和相同的抽象层（HTTP + JSON，无编排）下，与官方 OpenAI SDK 进行了基准测试。完整结果
和方法论详见 [docs/PERF-RESULTS.md](docs/PERF-RESULTS.md)。
| | aimux | OpenAI SDK | aimux 更快 |
|---|---|---|---|
| **Node.js**（单次请求） | 0.101 ms | 1.488 ms | **14.7×** |
| **Python**（单次请求） | 0.080 ms | 0.595 ms | **7.5×** |
### 持续压力测试（2000 个请求，200 KB 上下文，50 KB 响应）
| | aimux rps | SDK rps | aimux P99 | SDK P99 | RSS 增长 |
|---|---|---|---|---|---|
| **Node.js**（32 核） | 1512 | 563¹ | 1.92 ms | 3.96 ms | +23 MB vs +103 MB |
| **Python** | 1393 | 987 | 0.94 ms | 1.37 ms | **+0 MB** vs +8 MB |
¹ 与 Vercel AI SDK 相比（非完全同等的对比 —— AISDK 为每个请求添加了 Zod 验证、
middleware 和 telemetry）。
### 为什么它很快
- **Rust 核心** — `reqwest` 连接池，无 GC，无 runtime 暂停。
- **零内存增长** — 在 2000 次请求中，Python aimux 的 RSS 没有增长哪怕一个字节；Node 也只增长了 2 MB。
- **稳定的尾部延迟** — 没有 GC 暂停意味着即使在 CPU 争用的情况下，P99 也能保持平稳；而 JS SDK 的 P99 在单核上会飙升至 12.87 ms。
- **FFI 边界开销极低** — 序列化仅在大型 payload 时约占开销的 50%；在实际的 LLM 请求中（3–10 秒），这一比例小于 0.1%。
## 架构
```
aimux/
├── aimux-core # Core abstractions: LanguageModel / Provider / Message / StreamPart
├── aimux-providers # 290+ provider implementations (250 registry-backed + native)
├── aimux-stream # SSE / NDJSON stream parsing
├── aimux-provider-utils # HTTP utilities: retry, backoff, error parsing, API-key loading
└── aimux-ffi # C ABI (opaque handle + JSON + push callback) for non-native bindings
```
```
┌─ native path ──→ aimux-core + aimux-providers (direct Rust types + async)
bindings ──┤
└─ C ABI path ──→ aimux-ffi (opaque handle + JSON + push callback)
```
## 安装
**Rust**（核心库）：
```
cargo add aimux-core aimux-providers
```
| Crate | 描述 | crates.io |
|-------|-------------|-----------|
| `aimux-core` | 核心抽象：`LanguageModel` / `Provider` / `Message` / `StreamPart` | [crates.io](https://crates.io/crates/aimux-core) |
| `aimux-providers` | 325 个 provider 实现 | [crates.io](https://crates.io/crates/aimux-providers) |
| `aimux-stream` | SSE / NDJSON 流解析 | [crates.io](https://crates.io/crates/aimux-stream) |
| `aimux-provider-utils` | HTTP 工具：重试、退避、错误解析 | [crates.io](https://crates.io/crates/aimux-provider-utils) |
| `aimux-ffi` | 用于非原生绑定的 C ABI | [crates.io](https://crates.io/crates/aimux-ffi) |
**Node.js**:
```
npm install @arcships/aimux
```
```
import { openai, generateText } from '@arcships/aimux'
const model = await openai(process.env.OPENAI_API_KEY!, 'gpt-4o')
const result = await generateText(model, 'Explain Rust ownership in one sentence.')
console.log(result.text)
```
## 快速开始
```
use aimux_core::prelude::*;
use aimux_providers::{OpenAIConfig, OpenAIProvider};
#[tokio::main]
async fn main() -> Result<(), AiMuxError> {
let provider = OpenAIProvider::new(
OpenAIConfig::new(std::env::var("OPENAI_API_KEY")?)
);
let model = provider.model("gpt-4o");
let result = generate_text(
&model,
"Explain Rust ownership in one sentence.",
GenerateTextOptions::default(),
).await?;
println!("{}", result.text);
Ok(())
}
```
## 流式传输
```
use futures::StreamExt;
let result = stream_text(
&model,
"Write a haiku about Rust.",
GenerateTextOptions::default(),
).await?;
let mut stream = result.stream;
while let Some(part) = stream.next().await {
match part? {
StreamPart::TextDelta { delta, .. } => print!("{}", delta),
StreamPart::Finish { .. } => println!("\n[done]"),
_ => {}
}
}
```
## 切换 provider
```
// OpenAI → DeepSeek: only the provider name changes (registry-backed;
// key read from the provider's env var)
use aimux_providers::{provider, provider_from_env, ProviderName};
// 推荐:类型化 ProviderName(IDE 补全 + 编译期检查)
let model = provider(ProviderName::Deepseek, None, "deepseek-chat", None)?;
// 字符串形式同样可用:
let model = provider_from_env("deepseek", "deepseek-chat", None)?;
// model usage is identical — it's all dyn LanguageModel
```
所有 250 个 OpenAI 兼容的 provider 都由注册表支持：每种绑定中都有 `provider(name, ...)`
，并具有强类型的 `ProviderName`（根据语言为 enum/union/consts）。
已弃用的各个 provider shell 类型（`XxxConfig`/`XxxProvider`）已被移除 ——
详见 [docs/API.md](docs/API.md#providers)。
## Provider 覆盖范围
| 类型 | 数量 | 示例 |
|------|:-----:|----------|
| 原生协议 | 10 | OpenAI, Anthropic, Google, Bedrock, Vertex, Azure, Cohere, Mistral, xAI, Anthropic-AWS |
| OpenAI 兼容（注册表） | 250 | Groq, Fireworks, Together, Perplexity, Ollama Cloud, DeepSeek, 阿里通义, 智谱, 百度, 腾讯, 月之暗面, SiliconFlow… |
| OpenAI 兼容（独立 + Vertex 托管） | 32 | OpenRouter, Hugging Face, Ollama, vLLM, SGLang, Llama.cpp, LiteLLM Proxy, Vertex 托管的 DeepSeek/Qwen/Llama… |
| 语音 / 转录 | 10 | ElevenLabs, Deepgram, AssemblyAI, AWS Polly, Cartesia, Hume, Gladia, RevAI, LMNT, Fal |
| 图像 / 视频 | 8 | Black Forest Labs, Replicate, Luma, Prodia, KlingAI, Recraft, Stability, RunwayML |
| Embeddings / rerank / 搜索 | 13 | Voyage, Jina, Tavily, Exa, Firecrawl, Serper, SearXNG, You.com… |
| 其他（Responses API、Bedrock/Mantle） | 2 | 通用 Responses API wrapper, Bedrock Mantle |
完整列表：[rfc/0004-provider-inventory.md](rfc/0004-provider-inventory.md)。
## 语言绑定
aimux 提供了 8 种共享同一 Rust 核心的绑定：
| 绑定 | 路径 | 工具 | 获取方式 | 原生库 |
|---------|------|------|--------|---------------|
| **Node.js** | 原生 | napi-rs v3 | `npm install @arcships/aimux` — [npm](https://www.npmjs.com/package/@arcships/aimux) | 内置于包中，无需额外操作 |
| **Python** | 原生 | PyO3 + maturin | `pip install arcships-aimux` — [PyPI](https://pypi.org/project/arcships-aimux/) | 内置于 wheel 中，无需额外操作 |
| **Go** | C ABI | cgo（静态链接） | `go get github.com/arcships/aimux/bindings/go` 然后 `go generate` | 从 [GitHub Releases](https://github.com/arcships/aimux/releases) 自动下载 `.a` |
| **Swift** | C ABI | SPM | SPM: `https://github.com/arcships/aimux` (`from: "0.2.1"`) | `libaimux_ffi.dylib` — 详见[指南](docs/api/swift.md#install) |
| **Kotlin** | C ABI | JNA | `ai.arcships:aimux-kotlin` — Maven Central（发布中） | JNA 搜索路径上的 `libaimux_ffi.so/.dylib` 或 `aimux_ffi.dll` — 详见[指南](docs/api/kotlin.md#install) |
| **Java** | C ABI | JNA | `ai.arcships:aimux-java` — Maven Central（发布中） | 同 Kotlin — 详见[指南](docs/api/java.md#install) |
| **Flutter** | C ABI | dart:ffi | pub.dev 上的 `aimux` — Flutter 插件，内置原生核心（发布者 `arcships.ai`） | iOS/Android 开箱即用，桌面端开发/测试 — 详见[指南](docs/api/flutter.md#install) |
| **C / C++** | C ABI | 直接链接 | 来自 [GitHub Releases](https://github.com/arcships/aimux/releases) 的 `.so`/`.dylib`/`.dll` + `aimux-ffi.h` | 链接即可 — 详见[指南](docs/api/c.md#install) |
详见 [bindings/README.md](bindings/README.md) 和 [API 文档](docs/API.md)。
## 测试
```
cargo test -p aimux-providers --tests
```
测试基于 cassette 回放运行 —— 无需网络和密钥。详见
[rfc/0003-test-cassette.md](rfc/0003-test-cassette.md)。
## 文档
| 文档 | 内容 |
|-----|----------|
| [docs/API.md](docs/API.md) | **API 概览** — 共享参考及相关语言指南链接 |
| [docs/api/reference.md](docs/api/reference.md) | **API 参考** — 公开类型和函数查询 |
| [docs/api/providers.md](docs/api/providers.md) | **Provider 列表** — 全部 325 个 provider 及其入口点（自动生成） |
| [docs/api/](docs/api/) | **各语言 API 指南** — Node.js、Python、Rust、Go、C/C++、Swift、Kotlin、Flutter |
| [docs/PROJECT-OVERVIEW.md](docs/PROJECT-OVERVIEW.md) | 项目概述、设计决策、基准测试 |
| [docs/PERF-RESULTS.md](docs/PERF-RESULTS.md) | 性能基准测试结果 |
| [docs/aimux-vs-aisdk-node.md](docs/aimux-vs-aisdk-node.md) | 与 Vercel AI SDK 的 Node.js DX 对比 |
| [docs/README.md](docs/README.md) | 文档索引 |
### 设计文档 (RFCs)
| RFC | 内容 |
|-----|----------|
| [0001](rfc/0001-multilang-bindings.md) | 多语言绑定（Node/Swift/Kotlin/Flutter/Python） |
| [0002](rfc/0002-provider-improvements.md) | 配置描述符与轻量级 wrapper 改进 |
| [0003](rfc/0003-test-cassette.md) | 测试 cassette 方案 |
| [0004](rfc/0004-provider-inventory.md) | 完整的 provider 清单与实现状态 |
| [0005](rfc/0005-protocol-conversion.md) | 协议转换与适配层 |
| [0006](rfc/0006-provider-development.md) | provider 最低验收标准、核心契约、测试 |
| [0007](
标签：AI, API网关, LLM, Rust, Unmanaged PE, 可视化界面, 接入层, 网络流量审计, 自动化代码审查, 通知系统