feat: support client-driven model selection in ai-proxy-multi via `models` request body field

オープン
  • 何か問題がありますか？
#13,083 コメント 3 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 2 日以内に返信

まだ誰も着手していません。

  • #13084 @kjprice による — マージされずにクローズ

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
45/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
静か
技術スタック
lua
領域
api, backend-api-design

調査の方向性

まず ai-proxy-multi.lua と、その access-phase におけるインスタンス選択フローを読みます。upstream への転送前にリクエストボディと設定済みインスタンスがどのように処理されるかを追跡し、opt-in の順序、文字列およびオブジェクトのマッチング、マッチしないエントリ、モデルの除去、フォールバック動作に対するテストを定義します。デフォルトでは引き続きサーバー主導であり、有効化されたルートではクライアントの優先設定が尊重されれば完了です。

索引モデルが issue の本文から書いたものです。

説明

feature-request

Description

Currently, ai-proxy-multi selects AI instances entirely server-side via configured priority, weight, and fallback_strategy. The client has no way to influence which model or provider handles their request, or in what order fallbacks should be attempted.

This proposal adds support for a models field in the request body, allowing clients to specify their preferred model ordering while the gateway retains full control over authentication, rate limiting, and provider configuration.

Proposed API

Clients include a models array in the chat completions request body. Each element can be:

Object form (full control):

{
  "messages": [{"role": "user", "content": "Hello"}],
  "models": [
    {"provider": "anthropic", "model": "claude-sonnet-4-20250514"},
    {"provider": "openai", "model": "gpt-4o"}
  ]
}

String shorthand (just model names, matched against configured instances):

{
  "messages": [{"role": "user", "content": "Hello"}],
  "models": ["claude-sonnet-4-20250514", "gpt-4o"]
}

Mixed:

{
  "messages": [{"role": "user", "content": "Hello"}],
  "models": [
    {"provider": "anthropic", "model": "claude-sonnet-4-20250514"},
    "gpt-4o"
  ]
}

Behavior

  1. The models array defines the client's preferred instance ordering (first element = highest priority).
  2. Each entry is matched against the route's configured ai-proxy-multi instances by model name and optionally provider.
  3. String entries match by model name only. Object entries can match by provider + model for disambiguation (e.g., two providers serving the same model).
  4. Unmatched entries are ignored (the client cannot introduce providers/models not configured on the route).
  5. Configured instances not referenced in models are appended after the client's preferred list, in their original priority order.
  6. The existing fallback_strategy still applies — if the top-priority instance fails, the plugin falls back through the client-specified order, then server-configured instances.
  7. Auth, rate limiting, and all other instance config remain server-controlled.

Configuration

A new optional boolean on the plugin config to opt-in:

plugins:
  ai-proxy-multi:
    allow_client_model_preference: true   # default: false
    instances:
      - name: anthropic-primary
        provider: anthropic
        options:
          model: claude-sonnet-4-20250514
        # ...
      - name: openai-fallback
        provider: openai
        options:
          model: gpt-4o
        # ...

When allow_client_model_preference is false (default), the models field is stripped from the request body and instance ordering is purely server-driven. This ensures backward compatibility.

Use Case

We're building an LLM proxy gateway where multiple teams consume AI services through a shared gateway. Different clients have different model preferences:

  • Team A prefers Claude with GPT-4o fallback
  • Team B prefers GPT-4o with Claude fallback
  • The gateway team manages auth keys, rate limits, and provider configs centrally

Today this requires separate routes per team/preference. With client-driven model selection, a single route handles all teams while respecting their preferences.

Implementation Notes

  • The matching logic would live in ai-proxy-multi.lua, executed before instance selection in the access phase.
  • The models field should be stripped from the request body before forwarding to the upstream provider (providers don't recognize it).
  • String matching should be case-sensitive to match provider model naming conventions.
  • When using chash balancer, client preference should take precedence over hash-based selection.

I'm happy to submit a PR for this feature if the approach looks good.

主要言語
Lua
スター
17.3k
フォーク
3k
平均マージ
4日 14時間
マージ済み PR（30日）
73

環境構築

Codespaces で開く

このプロジェクトの開発コンテナを、あなたの GitHub アカウントでブラウザ上に起動します。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

apache/apisix のほかの issue

apache/apisix の issue をすべて見る

似ている issue

Lua の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。