@jungtz/ai-router

統一 AI 提供者路由器 — 自由切換本地 CLI、本地模型與線上 API

支援 Node.js 與 瀏覽器 環境。

安裝

npm install @jungtz/ai-router

環境與入口

本套件提供多個入口，請依據使用環境選擇：

| 環境 | 入口 | 支援類型 | | ---------------------- | ---------------------------------------------- | --------------------- | | Node.js（含 CLI 支援） | @jungtz/ai-router / @jungtz/ai-router/node | local、cloud、cli | | 瀏覽器（無 CLI） | @jungtz/ai-router/browser | local、cloud |

⚠️ @jungtz/ai-router/browser 不支援 type: 'cli' 的 provider。若在瀏覽器環境嘗試使用 CLI 類型，會拋出明確錯誤提示。

使用方法

1. 程式庫（Node.js）

import { createRouter } from '@jungtz/ai-router'
// 或明確指定
// import { createRouter } from '@jungtz/ai-router/node';

const config = {
  providers: {
    ollama: {
      type: 'local',
      models: [{ model: 'qwen3.5:35b-a3b', description: '通義千問' }],
    },
    openai: {
      type: 'cloud',
      apiKey: 'your-api-key',
      models: [{ model: 'gpt-4o', description: 'GPT-4o' }],
    },
    'ollama-cloud': {
      type: 'cloud',
      sdk: 'openai',
      apiKey: 'your-ollama-api-key',
      baseURL: 'https://ollama.com/v1',
      models: [{ model: 'gpt-oss:120b', description: 'GPT-OSS 120B' }],
    },
    opencode: {
      type: 'cloud',
      sdk: 'openai',
      apiKey: 'your-api-key',
      baseURL: 'https://opencode.ai/zen/go/v1',
      models: [{ model: 'kimi-k2.5', description: 'Kimi K2.5' }],
    },
    'claude-cli': {
      type: 'cli',
      command: 'claude',
      models: [{ model: 'default', description: '預設' }],
    },
  },
  defaultModel: 'ollama/qwen3.5:35b-a3b',
}

const router = createRouter(config)

// 健康檢查
const health = await router.healthCheck()
if (!health.ok) {
  console.error('Provider 異常:', health.error)
}

// 發送對話
for await (const chunk of router.chat([{ role: 'user', content: '你好' }])) {
  if (chunk.type === 'error') {
    console.error('錯誤:', chunk.content)
    break
  }
  process.stdout.write(chunk.content)
}

// 切換模型
router.switchModel('opencode', 'kimi-k2.5')

// 取得所有模型
const models = router.getModels()

2. 程式庫（瀏覽器）

import { createRouter } from '@jungtz/ai-router/browser'

const config = {
  providers: {
    ollama: {
      type: 'local',
      models: [{ model: 'qwen3.5:35b-a3b' }],
    },
    openai: {
      type: 'cloud',
      apiKey: 'your-api-key',
      models: [{ model: 'gpt-4o' }],
    },
  },
  defaultModel: 'ollama/qwen3.5:35b-a3b',
}

const router = createRouter(config)
// ... 其餘用法與 Node.js 版相同

3. Express 中介軟體

import express from 'express'
import { setupExpressApp } from '@jungtz/ai-router/middleware'

const app = express()
const config = {
  /* 見上方 config 格式 */
}

setupExpressApp(app, config)
app.listen(8000)

更新 (v1.0.12+): setupExpressApp 現在是 async 函式，且支援 apiReference 選項：

await setupExpressApp(app, config, { 
  cors: true, 
  apiReference: '/reference' // 啟動 Scalar API 文件 (可自訂路徑)
})

4. CLI 工具

# 列出所有模型
ai-router list

# 列出所有 provider 詳細資訊
ai-router providers

# 切換模型
ai-router use opencode-go/kimi-k2.5

# 發送單次對話
ai-router chat "你好，請問今天天氣如何？"

# 進入互動模式
ai-router interactive

5. API 參考文件 (Scalar)

當使用伺服器模式或 Express 中介軟體時，本專案內建了 Scalar 互動式 API 文件。

• 預設路徑: /reference
• 功能:
  • 查看所有 API 端點（/models, /chat, /health）
  • 互動式測試 API 請求
  • 支援 SSE (Server-Sent Events) 串流預覽

你可以透過 apiReference 選項來設定：

• apiReference: true: 開啟文件（預設路徑 /reference）
• apiReference: '/docs': 自訂文件路徑
• apiReference: false: 關閉文件

進階：直接使用 CLI Adapter

Node.js 環境可直接操作 CLI 介面卡，獲得更細粒度的控制：

import { CLIAdapter, ALLOWED_CLI_COMMANDS } from '@jungtz/ai-router'

// 白名單內的命令可安全使用
console.log(ALLOWED_CLI_COMMANDS) // Set { 'claude', 'gemini', 'opencode', 'ollama' }

const adapter = new CLIAdapter('claude-cli', 'default')
await adapter.healthCheckCLI({ command: 'claude' })

// 即時串流生成器
for await (const chunk of adapter.streamCLIGenerator(
  { command: 'claude' },
  '你好，請幫我寫一個 Hello World'
)) {
  if (chunk.type === 'content') process.stdout.write(chunk.content)
  if (chunk.type === 'error') console.error(chunk.content)
}

配置說明

{
  "providers": {
    "ollama": {
      "type": "local",
      "models": [...]
    },
    "openai": {
      "type": "cloud",
      "apiKey": "your-api-key",
      "models": [...]
    },
    "claude-cli": {
      "type": "cli",
      "command": "claude",
      "models": [...]
    }
  },
  "defaultModel": "ollama/qwen3.5:35b-a3b"
}

簡化配置: baseURL 對於大，多數 provider 是可選的。本地 Ollama 預設 localhost:11434，Cloud SDK 會自動使用預設端點。

Provider 類型

| type | 說明 | 必要欄位 | | ------- | ------------------------------ | --------------------------------------------- | | local | Ollama 等本地模型 | baseURL（可選，默認 localhost:11434） | | cloud | OpenAI / Anthropic 等雲端 API | apiKey（可選，默認 'ai-router-no-key'）、baseURL（可選） | | cli | claude / gemini / opencode CLI | command |

關於 apiKey: 在 cloud 類型中，如果未提供 apiKey，系統會預設使用 'ai-router-no-key'。這是為了避免 Vercel AI SDK 在初始化時因缺少 Key 而崩潰。這在您使用自建 Gateway 或 Proxy（且驗證由後端處理）時非常有用。

Gateway 驗證修復: 在先前的版本中，當傳入字串模型時可能會誤觸發 Vercel AI SDK 的 GatewayAuthenticationError。自 v1.0.18 起，我們已透過物件傳遞完全阻斷了回退至 Gateway 的路徑，確保所有的請求皆會準確無誤地傳送至您設定的 baseURL。

健康檢查設定

| 選項 | 類型 | 說明 | | --------------------- | --------- | ---------------------------------------------------------------------- | | healthCheckEndpoint | string | 自訂健康檢查端點路徑，預設為 /models | | skipHealthCheck | boolean | 設為 true 可跳過健康檢查（適用於沒有標準端點的服務，如 OpenCode Go） |

自動跳過: 當 baseURL 未提供時（且 SDK 有預設值），健康檢查會自動跳過，避免連線失敗。

範例：

{
  "opencode-go": {
    "type": "cloud",
    "sdk": "openai",
    "apiKey": "your-api-key",
    "baseURL": "https://opencode.ai/zen/go/v1",
    "skipHealthCheck": true,
    "models": [{ "model": "kimi-k2.5" }]
  }
}

Cloud SDK

注意: 以下 SDK 的 baseURL 為可選欄位，SDK 會自動提供預設值。

{
  "type": "cloud",
  "sdk": "anthropic",
  "apiKey": "your-key"
}

sdk 可選值："openai"（預設）、"anthropic"、"alibaba"、"google"、"groq"、"openrouter"、"ollama"

自動 SDK 切換（v1.0.19+）: 當 sdk 設為 "ollama" 但 baseURL 以 /v1 結尾時，系統會自動切換為 openai SDK。因為 /v1 是 OpenAI-compatible 端點（使用 /v1/chat/completions），不是 Ollama 原生端點（使用 /api/chat）。

Cloud SDK

OpenAI SDK

{
  "type": "cloud",
  "sdk": "openai",
  "apiKey": "your-key"
}

Anthropic SDK

{
  "type": "cloud",
  "sdk": "anthropic",
  "apiKey": "your-key",
  "baseURL": "https://api.anthropic.com"
}

Alibaba SDK

{
  "type": "cloud",
  "sdk": "alibaba",
  "apiKey": "your-key"
}

Google SDK

{
  "type": "cloud",
  "sdk": "google",
  "apiKey": "your-key"
}

Ollama SDK（原生 Ollama API）

適用於提供 Ollama 原生端點（/api/chat、/api/tags）的服務。baseURL 結尾不能有 /v1。

{
  "type": "cloud",
  "sdk": "ollama",
  "baseURL": "https://your-ollama-server.com",
  "apiKey": "your-api-key",
  "models": [{ "model": "gpt-oss:120b", "description": "GPT-OSS 120B" }]
}

注意:

• 如果 baseURL 以 /v1 結尾，系統會自動將 SDK 切換為 openai，因為 /v1 是 OpenAI-compatible 端點，不是 Ollama 原生端點。
• sdk: 'ollama' 時，getModels() 會調用 /api/tags（Ollama Native）；sdk: 'openai' 時會調用 /v1/models（OpenAI-compatible）。

Groq SDK

{
  "type": "cloud",
  "sdk": "groq",
  "apiKey": "gsk-your-groq-api-key",
  "models": [
    { "model": "llama-3.3-70b-versatile", "description": "LLaMA 3.3 70B" }
  ]
}

OpenRouter SDK

{
  "type": "cloud",
  "sdk": "openrouter",
  "apiKey": "sk-or-v1-your-openrouter-key",
  "models": [
    { "model": "anthropic/claude-3.5-sonnet", "description": "Claude 3.5 Sonnet" }
  ]
}

createRouter(config)

建立路由器實例。

router.getModels()

取得所有可用模型列表。

router.switchModel(provider, model)

切換到指定的 provider / 模型。

router.chat(messages, options)

發送對話請求，返回 AsyncGenerator<ChatChunk>。

for await (const chunk of router.chat(messages)) {
  if (chunk.type === 'error') {
    console.error(chunk.content)
  } else {
    process.stdout.write(chunk.content)
  }
}

router.generate(messages, options)

非流式生成（一次性取得完整結果），適用於背景任務、批次處理等不需要即時顯示的場景。

const result = await router.generate([
  { role: 'user', content: '寫一段 Python 程式碼來計算費氏數列' }
])

console.log(result.text)           // 生成的文字內容
console.log(result.usage)          // Token 使用統計 { promptTokens, completionTokens, totalTokens }
console.log(result.finishReason)   // 結束原因（如 'stop'）

router.models()

models() 是 getModels() 的別名，提供更簡潔的 API 調用方式。兩者功能完全相同。

// 以下兩種寫法等價
const models = await router.getModels()
const models = await router.models()

router.getStatus()

取得當前 provider 與模型狀態。

router.healthCheck()

檢查當前 provider 的連線與登入狀態，返回 Promise<{ ok, error }>。

const result = await router.healthCheck()
if (!result.ok) {
  console.error(result.error)
}

router.getProviderDetails()

取得所有 provider 的詳細資訊，包括 API URL、認證方式、SDK 類型、模型列表等。

const details = router.getProviderDetails()
// 回傳陣列：
// [
//   {
//     name: "ollama",
//     type: "local",
//     sdk: "ollama",
//     apiURL: "http://localhost:11434",
//     authMethod: "無需認證",
//     modelSource: "/api/tags 端點",
//     modelCount: 2,
//     models: [...],
//     description: "...",
//     skipHealthCheck: false,
//     healthCheckEndpoint: null
//   },
//   ...
// ]

router.checkCLIAuth(command)

檢查 CLI 工具的登入狀態（支援 claude、gemini、opencode），未知工具自動跳過。

授權

MIT