[AI] AI gateway milestones

[Alanxtl]

https://jimmysong.io/blog/ai-gateway-in-depth/

Step1: 基础

• 1. 基础 AI 协议支持 (SSE/HTTP) [AI] feat: Compatible with http/sse protocol #657
• 2. Streamable HTTP (doc/pr) Add streamable http #674
• 3. Token 用量获取 [AI] feat: implementation of token calculation filter #659

Step2: 兼容

• 1. 面向密钥的负载均衡 [AI] AI gateway milestones #696 (comment)
• 2. 密钥的健康性检测 feat(ai-gateway): enhance API key handling and health check logic for endpoints #731 [AI] AI gateway milestones #696 (comment)
• 3. fallback策略 [AI] feat: Implement LLM proxy filter with retry and fallback mechanisms #685 feat(ai-gateway): rewrite llmproxy strategy, extract retry policy into a configurable strategy #692
• 4. retry策略 [AI] feat: Implement LLM proxy filter with retry and fallback mechanisms #685 feat(ai-gateway): rewrite llmproxy strategy, extract retry policy into a configurable strategy #692
• 5. LLM 供应商的兼容 [AI] feat: Add a new field "LLMMeta" for endpoint, simpilify the use of llm endpoint #678(需持续适配)
• 6. OpenAI 请求适配层 [AI] AI gateway milestones #696 (comment)
• 7. LLM服务发现 (Nacos 注册中心)

Step3: 完善

• 1. AI 可观测性 feat(ai-gateway): enhance upstream request tracking and metrics reporting #733
  • Token 用量
  • 响应时间
• 2. 响应合规性和请求合规性
• 3. 日志
• 4. 更智能的路由

[Alanxtl]

Pixiu AI 网关将输入统一为openai格式，通过一个适配器filter转换成对应的供应商的格式

graph TD
    subgraph "客户端 (Client)"
        UserRequest("👤 用户/客户端")
    end

    subgraph "AI 网关 (AI Gateway)"
        A["入口: 接收标准OpenAI格式请求"]
        B{"选择对应的适配器"}
        
        subgraph "适配层 (Adapter Layer)"
            C1["适配器: OpenAI (透传)"]
            C2["适配器: Anthropic Claude"]
            C3["适配器: Google Gemini"]
            C4["适配器: ...更多"]
        end

        A --> B
        B -- "model: 'gpt-4o'" --> C1
        B -- "model: 'claude-3-opus-20240229'" --> C2
        B -- "model: 'gemini-1.5-pro'" --> C3
    end

    subgraph "LLM 供应商 (LLM Providers)"
        D1[☁️ OpenAI API]
        D2[☁️ Anthropic API]
        D3[☁️ Google AI API]
    end

    C1 --> D1
    C2 --> D2
    C3 --> D3

    %% --- 转换过程示例 (Conversion Example) ---
    subgraph "转换示例: OpenAI -> Anthropic"
        direction LR
        Input("输入请求 (OpenAI 格式): 
        POST /v1/chat/completions 
        { 
        'model': 'claude-3-opus-20240229', 
        'messages': [ 
        { 'role': 'system', 'content': '你是一个乐于助人的助手。' }, 
        { 'role': 'user', 'content': '你好，克劳德！' } ], 
        'max_tokens': 1024 }"
        )

        Output("输出请求 (Anthropic 格式): 
        POST /v1/messages 
        { 
        'model': 'claude-3-opus-20240229', 
        'system': '你是一个乐于助人的助手。', 
        'messages': [ 
        { 'role': 'user', 'content': '你好，克劳德！' } ], 
        'max_tokens': 1024 }"
        )
        
        Input -- "通过 Claude 适配器处理" --> Output
    end

    UserRequest --> A
    
    %% Styling
    style A fill:#D6EAF8,stroke:#3498DB
    style B fill:#E8DAEF,stroke:#8E44AD
    style C2 fill:#D5F5E3,stroke:#2ECC71
    style Input fill:#FEF9E7,stroke:#F1C40F
    style Output fill:#FDEDEC,stroke:#E74C3C
    style C2 fill:#D5F5E3,stroke:#2ECC71
    style A fill:#D6EAF8,stroke:#3498DB
    style B fill:#E8DAEF,stroke:#8E44AD
    style Output fill:#FDEDEC,stroke:#E74C3C

Loading

[AlexStocks]

可以更新下 task list，把 nacos 支持也加进去

[Alanxtl]

API密钥的健康探测

对于密钥数组中的某个密钥，若触发了failover则视为该密钥不健康，对于不健康的密钥在下次请求的时候不会使用它发送请求，待超时机制过后重新探测其健康性

[Alanxtl]

LLM cluster endpoint 层级的设计

现在的代码用的是方案2，但是我越来越觉得方案1要好（工作量要少很多，并且逻辑更加清晰）

---

方案一：一个 Endpoint 对应一个 API Key

这种设计将一个 apikey 视为一个 Endpoint。

# 方案一：原子化的 Endpoint
clusters:
  - name: "chat"
    lb_policy: "round_robin" # 假设是轮询
    endpoints:
      - id: 1
        provider: "deepseek"
        api_key: "key-1" 
      - id: 2
        provider: "deepseek"
        api_key: "key-2"
      - id: 3
        provider: "openai"
        api_key: "key-3"

优势 (Pros)

1. 逻辑简单且统一：负载均衡、健康探测、熔断、统计等所有核心功能，都围绕 Endpoint 这个唯一的对象。实现非常干净，每个 Endpoint 的状态（健康/不健康）是独立的。
2. 充分复用现有设施：正如你所说，如果你的系统已经将 Endpoint 作为最小单元，那么几乎不需要改动核心的调度逻辑。这大大降低了开发成本和风险。
3. 故障隔离清晰：key-1 对应的 endpoint-1 挂了，负载均衡器会清晰地将其从池中移除，完全不影响 endpoint-2。责任非常明确。

劣势 (Cons)

1. 配置繁琐且冗余：这是最大的问题。如果要给 DeepSeek 添加 10 个 Key，用户必须复制粘贴 10 次 endpoint 块，并修改 id 和 key。这不仅麻烦，还容易出错。
2. 从属关系不清晰：在配置文件中，endpoint-1 和 endpoint-2 看起来是两个完全独立的实体，但实际上它们都属于同一个 provider (DeepSeek)。这种逻辑上的分组关系丢失了，不利于人类理解。

---

方案二：一个 Endpoint 对应多个 API Key

这种设计将一个供应商视为一个 Endpoint，apikey是更小的一个层级。

# 方案二：分组的 Endpoint
clusters:
  - name: "chat"
    lb_policy: "round_robin" # 这个策略现在只作用于 Endpoint 列表 并不作用于api_keys列表
    endpoints:
      - id: 1
        provider: "deepseek"
        api_keys: # 一个 key 列表
          - name: "apikey-1"
            key: "key-1"
          - name: "apikey-2"
            key: "key-2"

优势 (Pros)

1. 配置直观且优雅：从属关系一目了然。用户可以清晰地看到 "DeepSeek" 这个服务下配置了两个 Key。添加或删除 Key 也非常方便，只需在 api_keys 数组中操作即可。

劣势 (Cons)

1. 核心逻辑需要重构/重写：这是致命的缺点。
   • 二级负载均衡：cluster 层的 lb_policy 将请求分发到 endpoint-1。然后呢？endpoint-1 内部必须有自己的逻辑来决定本次请求是用 key-1 还是 key-2。你需要实现一个 "Endpoint 内的 Key 负载均衡器"。
   • 健康探测粒度问题：如果使用 key-1 的请求失败（例如 QPS 超限），你不能将整个 endpoint-1 标记为不健康，因为 key-2 可能还是好的。你需要将健康状态维护在更细的 api_key 粒度上。这意味着你的健康探测和熔断机制需要重写，以支持这种父子关系。
   • 代码重复：本质上，你把原本在 cluster 层的调度逻辑，在 endpoint 内部又实现了一遍，导致了逻辑复杂化和代码重复。

[AlexStocks]

这还用说，当然方案一好呀，配置这都不算啥事，核心逻辑清晰才算好

[Alanxtl]

ai-gateway observability grafana demonstrate