amrouter

面向 AI Agent 的 AMRouter 技能

可自托管的 AI 网关：一个端点，多个提供商，自动回退。

AMRouter 是一个兼容 OpenAI 的 API 网关，可在数十种大模型、嵌入、图像和音频提供商之间路由请求，并自动进行负载均衡、回退和成本优化，旨在让 Agent 无需受限于特定提供商即可访问多提供商 AI 基础设施。

---

快速链接

• 官方网站： https://github.com/ahwanulm/AMRouter
• 文档： https://github.com/ahwanulm/AMRouter/tree/main/docs
• 功能： 多提供商路由、自动回退、Cloudflare Workers AI、兼容 OpenAI 的 REST API

---

什么是 AMRouter？

AMRouter v2 是对 9Router 的重写，采用了清晰的分层架构：

• Express 后端 — 将请求路由到 50 多种大模型、嵌入、图像、音频和实用工具提供商
• Vite + React 前端 — 用于管理提供商、连接、代理池、CLI 工具和自动化的仪表板
• 兼容 OpenAI 的 API — 适用于支持 /v1/chat/completions、/v1/embeddings、/v1/images/generations、/v1/audio/speech 等接口的任何客户端

主要功能

✅ 多提供商路由 — Cloudflare Workers AI、OpenAI、Anthropic Claude、Google Gemini、Groq、Mistral、Cohere、Voyage、GitHub 以及另外 40 多种提供商
✅ 自动回退组合 — 定义提供商链（例如 vip、budget、openai-only）；路由会在失败时自动切换
✅ 成本优化 — 跟踪各提供商的配额，并使用令牌计数器估算成本
✅ Cloudflare Workers AI 自动化 — 自动注册账号，并通过 Playwright + 2Captcha + 临时邮箱提取密钥
✅ 仪表板 UI — 管理提供商、连接和自动化，并查看日志和指标
✅ Agent 技能 — 为 Claude、Gemini 和其他 AI 编码 Agent 预置的 SKILL.md 文件
✅ 兼容 OpenAI SDK — 适用于 OpenAI npm 客户端、Python 客户端或任何 REST 客户端

---

适用场景

✅ 在以下情况下使用 AMRouter：

• 想要将多个提供商的访问整合到一个 API 端点
• 需要在提供商故障或配额耗尽时自动回退
• 想要跟踪各提供商的成本（配额限制、令牌计数）
• 运行多个大模型，并需要统一的接口
• 正在构建Agent 基础设施，并希望轻松切换提供商
• 想要使用 Cloudflare Workers AI 自动化（自动注册、提取密钥）
• 需要可自托管的解决方案（而非由供应商管理的解锁服务）

❌ 在以下情况下不要使用 AMRouter：

• 只需要一个提供商（直接使用其 SDK 即可）
• 无法运行 Node.js 后端
• 不需要回退或多提供商编排
• 想要直接使用 Anthropic API 等托管服务

---

安装与设置

第 1 步：要求

• Node.js 20+
• Python 3.10+（用于自动化功能）
• Chromium（用于 Playwright 自动化；可选）

第 2 步：安装

git clone https://github.com/ahwanulm/AMRouter.git
cd AMRouter
npm install

第 3 步：配置环境

cp backend/.env.template backend/.env

主要环境变量：

变量	说明	示例
PORT	后端服务端口	3001
REQUIRE_LOGIN	启用身份验证	true
JWT_SECRET	JWT 签名密钥	（生成一个随机字符串）
ADMIN_PASSWORD	仪表板管理员密码	（安全设置）
OPENAI_API_KEY	OpenAI 提供商密钥	（可选）
ANTHROPIC_API_KEY	Anthropic 提供商密钥	（可选）
GOOGLE_API_KEY	Google Gemini 密钥	（可选）

第 4 步：开发

npm run dev          # Start backend + frontend concurrently
npm run backend      # Backend only (port 3001)
npm run frontend     # Frontend only (port 5177)

第 5 步：生产环境

cd frontend && npm run build
cd ..
NODE_ENV=production npm start

服务运行在端口 3001 上（可配置）。前端会构建到 backend/public/ 中。

---

核心概念

1. 提供商

提供商是大模型、嵌入、图像或音频服务（OpenAI、Anthropic、Gemini 等）。

每个提供商都有：

• 密钥/API 凭据 — 通过仪表板管理
• 模型 — 具体的模型 ID（例如 openai/gpt-4o、anthropic/claude-3-opus）
• 配额 — 可选的令牌数或请求数限制
• 优先级 — 用于回退链

2. 组合（回退链）

组合是由多个提供商组成的命名链。当你使用组合名称 vip 调用 /v1/chat/completions 时，它会依次尝试：

1. 提供商 A
2. 如果 A 失败或超出配额 → 提供商 B
3. 如果 B 失败 → 提供商 C
4. 依此类推。

组合配置示例：

{
  "name": "vip",
  "providers": ["openai", "anthropic", "gemini"],
  "strategy": "round-robin"
}

3. OpenAI 兼容 API

AMRouter 提供与 OpenAI 相同的端点：

端点	模型	示例
POST /v1/chat/completions	聊天模型	openai/gpt-4o、anthropic/claude-3-opus
POST /v1/embeddings	嵌入模型	openai/text-embedding-3-small、gemini/text-embedding-004
POST /v1/images/generations	图像模型	openai/dall-e-3、openai/dall-e-2
POST /v1/audio/speech	TTS 模型	openai/tts-1、elevenlabs/eleven_monolingual_v1
POST /v1/audio/transcriptions	STT 模型	openai/whisper-1
GET /v1/models	列出所有模型	返回 {data: [...]}

---

使用模式

模式 1：通过 OpenAI SDK 进行 Agent 对话

将 AMRouter 用作 OpenAI SDK 的即插即用替代方案：

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: `${process.env.AMROUTER_URL}/v1`,
  apiKey: process.env.AMROUTER_KEY || "any-value",
});

const res = await client.chat.completions.create({
  model: "openai/gpt-4o",  // or combo name like "vip"
  messages: [{ role: "user", content: "What is 2+2?" }],
  stream: true,
});

for await (const chunk of res) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

模式 2：基于组合的回退

在仪表板中定义回退组合。Agent 发送一个请求：

curl -X POST ${AMROUTER_URL}/v1/chat/completions \
  -H "Authorization: Bearer ${AMROUTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "budget",
    "messages": [{"role": "user", "content": "Summarize this article..."}]
  }'

AMRouter 会自动依次尝试：Groq → Mistral → Gemini（均跟踪成本）。

模式 3：用于 RAG 的嵌入

const embeddings = await fetch(`${AMROUTER_URL}/v1/embeddings`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${AMROUTER_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/text-embedding-3-small",
    input: ["Document chunk 1", "Document chunk 2"],
  }),
});

const { data } = await embeddings.json();
console.log(data[0].embedding);  // Vector (1536 dims)

模式 4：图像生成

curl -X POST ${AMROUTER_URL}/v1/images/generations \
  -H "Authorization: Bearer ${AMROUTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/dall-e-3",
    "prompt": "A futuristic city at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

模式 5：成本跟踪与配额

查询配额端点：

curl ${AMROUTER_URL}/api/quota/providers \
  -H "Authorization: Bearer ${AMROUTER_KEY}" | jq '.[]'

输出：

[
  {
    "provider": "openai",
    "quotaLimit": 100000,
    "quotaUsed": 45230,
    "quotaRemaining": 54770,
    "costUSD": 12.45
  },
  ...
]

---

Agent 集成

与 deep-agents-core 集成

将 AMRouter 注册为自定义工具：

const agentTools = {
  amrouter_chat: {
    description: "Call any LLM via AMRouter (OpenAI/Anthropic/Gemini/Groq combo fallback)",
    input_schema: {
      type: "object",
      properties: {
        model: { type: "string", description: "Provider/combo (openai/gpt-4o, anthropic/claude-3, budget)" },
        messages: { type: "array", description: "Chat messages" },
        temperature: { type: "number", description: "0–2 (default 1)" },
      },
      required: ["model", "messages"],
    },
  },
  amrouter_embeddings: {
    description: "Generate embeddings via OpenAI/Gemini/Voyage models",
    input_schema: {
      type: "object",
      properties: {
        model: { type: "string", description: "openai/text-embedding-3-small, gemini/text-embedding-004, voyage/voyage-large-2" },
        input: { type: "string", description: "Text to embed" },
      },
      required: ["model", "input"],
    },
  },
};

与 research 技能集成

并行执行多模型查询：

# Search across multiple LLM models simultaneously
amrouter-query "Explain quantum computing" \
  --models openai/gpt-4o,anthropic/claude-3-opus,gemini/gemini-2-flash \
  --parallel \
  --compare

使用环境变量

在 .env 中设置：

AMROUTER_URL=http://localhost:3001
AMROUTER_KEY=sk-amrouter-xxx

然后在 Agent 代码中：

const AMROUTER_URL = process.env.AMROUTER_URL;
const AMROUTER_KEY = process.env.AMROUTER_KEY;

// Use in OpenAI SDK as shown above

---

常见任务

任务 1：列出可用提供商

curl ${AMROUTER_URL}/v1/models \
  -H "Authorization: Bearer ${AMROUTER_KEY}" | jq '.data[].id'

# Output:
# openai/gpt-4o
# openai/gpt-4-turbo
# anthropic/claude-3-opus-20240229
# google/gemini-2-flash
# groq/mixtral-8x7b-32768
# ...

任务 2：检查所有提供商的配额

curl ${AMROUTER_URL}/api/quota/providers \
  -H "Authorization: Bearer ${AMROUTER_KEY}" | jq '.'

任务 3：创建成本优化组合

通过仪表板：

1. 前往 Providers 选项卡
2. 点击 New Combo
3. 名称：budget
4. 添加提供商：Groq、Mistral、Llama 2（按回退顺序排列）
5. 保存

随后 Agent 可以使用：

curl -X POST ${AMROUTER_URL}/v1/chat/completions \
  -H "Authorization: Bearer ${AMROUTER_KEY}" \
  -d '{"model":"budget","messages":[...]}'

任务 4：流式传输响应

const res = await fetch(`${AMROUTER_URL}/v1/chat/completions`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${AMROUTER_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Write a poem" }],
    stream: true,
  }),
});

const reader = res.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = new TextDecoder().decode(value);
  const lines = text.split("\n");
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = JSON.parse(line.slice(6));
      process.stdout.write(data.choices[0]?.delta?.content || "");
    }
  }
}

---

最佳实践

1. 使用组合提高弹性

不要将提供商硬编码：

// ❌ Avoid: single provider, no fallback
model: "openai/gpt-4o"

// ✅ Prefer: fallback combo
model: "vip"  // Falls back through multiple providers automatically

2. 遵守配额限制

发送大型请求前检查剩余配额：

const quota = await fetch(`${AMROUTER_URL}/api/quota/providers`).then(r => r.json());
const gpt4oQuota = quota.find(q => q.provider === "openai");
if (gpt4oQuota.quotaRemaining < 10000) {
  console.log("Switching to budget model");
  model = "budget";  // Fallback to cost-optimized combo
}

3. 缓存嵌入结果

重复使用嵌入结果：

const embeddingCache = new Map();

async function getEmbedding(text) {
  if (embeddingCache.has(text)) return embeddingCache.get(text);
  
  const res = await fetch(`${AMROUTER_URL}/v1/embeddings`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${AMROUTER_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ model: "openai/text-embedding-3-small", input: text }),
  });
  const { data } = await res.json();
  const embedding = data[0].embedding;
  
  embeddingCache.set(text, embedding);
  return embedding;
}

4. 流式传输长响应

对于生成长内容的 Agent，请使用流式传输：

// Stream large code generation
const res = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [...],
  stream: true,  // ✅ Use streaming
});

5. 记录提供商和成本

跟踪每个请求由哪个提供商处理：

// Extend logging with provider info
const res = await fetch(`${AMROUTER_URL}/v1/chat/completions`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${AMROUTER_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "vip", messages: [...] }),
});

const data = await res.json();
console.log(`Provider: ${data.provider_used || 'unknown'}`);  // If AMRouter returns it
console.log(`Cost: $${data.estimated_cost || 'N/A'}`);

---

性能与成本

实际基准测试（与单一提供商配置相比）：

场景	成本降低	速度	优势
高流量回退	45–67%	快 2–8 倍（避免失败）	达到配额限制时自动切换到成本更低的提供商
并行推理	35–52%	3–5 倍（排队负载）	将负载分配到多个提供商
组合链（3 个提供商）	40–60%	1–2 倍（配置开销）	始终可用；单一 API 端点

---

故障排除

问题	解决方法
401 Unauthorized	检查 AMROUTER_KEY，确保 Bearer 令牌格式正确：Authorization: Bearer ${KEY}
503 Service Unavailable	所有回退提供商均失败；请在仪表板中检查配额和提供商配置
Model not found	运行 curl ${AMROUTER_URL}/v1/models 查看可用模型
CORS errors	在后端添加 Access-Control-Allow-Origin: *（或配置特定来源）
后端无法启动	检查 .env 文件，确保已设置 NODE_ENV，并检查端口冲突
嵌入维度不匹配	不同模型的维度不同（OpenAI：1536，Gemini：768）。将模型名称与向量一并存储。

---

部署

Docker

FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
RUN cd frontend && npm run build
CMD ["npm", "start"]

docker build -t amrouter .
docker run -p 3001:3001 --env-file .env amrouter

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: amrouter
spec:
  replicas: 3
  selector:
    matchLabels:
      app: amrouter
  template:
    metadata:
      labels:
        app: amrouter
    spec:
      containers:
      - name: amrouter
        image: amrouter:latest
        ports:
        - containerPort: 3001
        env:
        - name: PORT
          value: "3001"
        - name: ADMIN_PASSWORD
          valueFrom:
            secretKeyRef:
              name: amrouter-secrets
              key: admin-password

环境变量（生产环境）

PORT=3001
NODE_ENV=production
REQUIRE_LOGIN=true
JWT_SECRET=<random-256-bit-hex>
ADMIN_PASSWORD=<strong-password>
CORS_ORIGIN=https://yourdomain.com
LOG_LEVEL=info

---

与 Agent Skills 集成

技能	使用场景
deep-agents-core	将 AMRouter 端点注册为自定义大模型工具
research	在 AMRouter 中跨多个模型并行处理查询
crewai-multi-agent	将 AMRouter 用作多 Agent 编排的共享大模型后端
openrlhf-training	在 RLHF 微调期间使用 AMRouter 进行推理
langgraph-human-in-the-loop	通过 AMRouter 组合链路路由 LangGraph 大模型调用

---

许可证

AMRouter 是开源的。有关许可证详情，请参阅 GitHub。

---

构建技术： Node.js + Express（后端）、Vite + React（前端）、兼容 OpenAI 的 API
最后更新： 2026 年 7 月 — 反映 AMRouter v2.0+