核心概念
理解 Amux 的架构
Amux 建立在三个核心概念之上：适配器（Adapters）、IR（中间表示） 和 桥接（Bridge）。理解这些概念是有效使用 Amux 的关键。
架构概览
Amux 使用一个简单但强大的模式：
您的应用（提供商格式 A）
↓
入站适配器 → 解析为 IR
↓
中间表示（统一）
↓
出站适配器 → 构建提供商格式 B
↓
提供商 API
↓
响应通过 IR 流回
↓
您的应用（提供商格式 A）1. 适配器
适配器在提供商特定格式和统一的 IR 格式之间进行转换。每个适配器有两个方向：
入站（提供商 → IR）
将提供商特定的请求解析为 IR：
// OpenAI 格式 → IR
const ir = openaiAdapter.inbound.parseRequest({
model: 'gpt-4',
messages: [{ role: 'user', content: '你好！' }]
})
// 返回：LLMRequestIR出站（IR → 提供商）
从 IR 构建提供商特定的请求：
// IR → Anthropic 格式
const anthropicRequest = anthropicAdapter.outbound.buildRequest(ir)
// 返回：{ model: 'claude-...', messages: [...], ... }适配器能力
每个适配器声明其支持的功能：
openaiAdapter.capabilities = {
streaming: true,
tools: true,
vision: true,
multimodal: true,
systemPrompt: true,
toolChoice: true,
jsonMode: true,
logprobs: true,
seed: true
}桥接使用这些能力声明来检查兼容性并警告不支持的功能。
2. 中间表示（IR）
IR 是一种统一格式，捕获所有 LLM 功能：
interface LLMRequestIR {
messages: Message[] // 对话历史
model?: string // 模型标识符
tools?: Tool[] // 可用函数
toolChoice?: ToolChoice // 工具使用控制
stream?: boolean // 启用流式传输
generation?: GenerationConfig // 温度、最大令牌数等
system?: string // 系统提示
metadata?: Record<string, any> // 附加元数据
extensions?: Record<string, any> // 提供商特定功能
}为什么需要 IR？
统一格式 - 所有提供商在内部使用相同的语言：
// OpenAI 和 Anthropic 都转换为相同的 IR
const ir1 = openaiAdapter.inbound.parseRequest(openaiRequest)
const ir2 = anthropicAdapter.inbound.parseRequest(anthropicRequest)
// 两者都生成 LLMRequestIR提供商无关 - 编写一次代码，适用于任何提供商：
function processRequest(ir: LLMRequestIR) {
// 此函数适用于任何提供商的 IR
console.log(`处理 ${ir.messages.length} 条消息`)
}可扩展 - 支持提供商特定功能：
const ir: LLMRequestIR = {
messages: [{ role: 'user', content: '你好' }],
extensions: {
// OpenAI 特定
response_format: { type: 'json_object' },
// Anthropic 特定
thinking: { type: 'enabled', budget_tokens: 1000 }
}
}3. 桥接
桥接编排转换流程：
const bridge = createBridge({
inbound: openaiAdapter, // 解析传入格式
outbound: anthropicAdapter, // 构建传出格式
config: {
apiKey: 'xxx',
baseURL: 'https://api.anthropic.com'
}
})桥接工作流
当您调用 bridge.chat() 时：
- 解析 - 入站适配器解析请求 → IR
- 验证 - 桥接验证 IR 完整性
- 检查 - 桥接检查适配器兼容性
- 构建 - 出站适配器构建提供商请求
- 调用 - 桥接调用提供商 API
- 解析 - 出站适配器解析响应 → IR
- 构建 - 入站适配器构建响应格式
- 返回 - 桥接将响应返回给您
const response = await bridge.chat({
model: 'gpt-4',
messages: [{ role: 'user', content: '你好！' }]
})
// 幕后流程：
// OpenAI 格式 → IR → Anthropic 格式 → Claude API
// Claude 响应 → IR → OpenAI 格式 → 返回给您错误处理
桥接提供统一的错误处理：
import { LLMBridgeError } from '@amux.ai/llm-bridge'
try {
const response = await bridge.chat(request)
} catch (error) {
if (error instanceof LLMBridgeError) {
console.error('错误类型：', error.type)
console.error('消息：', error.message)
console.error('可重试：', error.retryable)
// 处理特定错误类型
if (error.type === 'rate_limit') {
// 等待并重试
} else if (error.type === 'authentication') {
// 检查 API 密钥
}
}
}常见错误类型：
network- 连接问题（可重试）rate_limit- 超出速率限制（可重试）authentication- 无效的 API 密钥（不可重试）validation- 无效的请求格式（不可重试）api- 提供商 API 错误（可能可重试）
综合应用
以下是所有概念如何协同工作：
import { createBridge } from '@amux.ai/llm-bridge'
import { openaiAdapter } from '@amux.ai/adapter-openai'
import { anthropicAdapter } from '@amux.ai/adapter-anthropic'
// 1. 使用适配器创建桥接
const bridge = createBridge({
inbound: openaiAdapter, // 处理 OpenAI 格式
outbound: anthropicAdapter, // 处理 Anthropic 格式
config: {
apiKey: process.env.ANTHROPIC_API_KEY
}
})
// 2. 发送请求（OpenAI 格式）
const response = await bridge.chat({
model: 'gpt-4',
messages: [{ role: 'user', content: '你好！' }]
})
// 3. 获取响应（OpenAI 格式）
console.log(response.choices[0].message.content)
// 幕后流程：
// - openaiAdapter.inbound 转换 OpenAI → IR
// - anthropicAdapter.outbound 转换 IR → Anthropic
// - 调用 Claude API
// - anthropicAdapter.inbound 转换 Anthropic → IR
// - openaiAdapter.outbound 转换 IR → OpenAI
// - 您获得 OpenAI 格式的响应关键要点
- 适配器 处理提供商格式和 IR 之间的转换
- IR 是所有提供商都理解的通用格式
- 桥接 编排转换和 API 调用
- 转换是双向的 - 您可以控制输入和输出格式
- 错误处理在所有提供商中统一