Създайте каталог /v1/models, съобразен с наемателите, за многомоделен API шлюз

Шлюзът не трябва да връща всеки модел, известен на всеки свързан доставчик от GET /v1/models. Трябва да върне моделите, които удостовереният ключ API е упълномощен и оперативно може да извика.

Това разграничение има значение, когато един API ключ осигурява достъп до множество доставчици на LLM. Суровото обединение на каталози нагоре по веригата може да включва модели, които са забранени от правилата на екипа, недостъпни съгласно плана на клиента, липсват здрави идентификационни данни, несъвместими с заявения API или не са внедрени в необходимия регион. Тези записи създават повредени средства за избор на модел и грешки по време на изпълнение, които откриването трябваше да предотврати.

Практическият договор е по-силен: всеки рекламиран модел трябва да премине същите проверки за допускане, които биха се прилагали за истинска заявка.

Дефинирайте какво означава „налично“

Съществуването на доставчик е само един вход. Моделът трябва да се показва в каталога по подразбиране на ключ само когато всички необходими условия са изпълнени:

• Шлюзът има конфигуриран публичен продукт за модела.
• Клиентът, екипът и ключът API имат право на този продукт.
• Приложимият търговски план позволява използването му.
• Политиката позволява модел, доставчик, регион и режим на обработка на данни.
• Съществува поне едно съвместимо внедряване или маршрут нагоре по веригата.
• Идентификационни данни за използваем доставчик са налични за този маршрут.
• Маршрутът поддържа поне една API повърхност, обявена в каталога.
• Маршрутът е оперативно готов съгласно здравната политика на шлюза.

Изразено като операция за множество:

visible_models(key) =
  configured_products
  ∩ tenant_entitlements
  ∩ team_grants
  ∩ key_grants
  ∩ commercial_rights
  ∩ policy_eligible_routes
  ∩ compatible_deployments
  ∩ operationally_ready_routes

Това е препоръка, а не твърдение относно OpenAI схемата. Стандартната схема не дефинира всички тези контроли, специфични за шлюза. Те принадлежат към контролната равнина на шлюза и компилатора на каталога.

Нормализиране на откриването на доставчик, без да го прокси

Факт: API за откриване на доставчици разкриват различни концепции. Списъкът с модели на OpenAI предоставя идентификатори и основни метаданни, но не и пълна матрица на възможностите за всяка API повърхност. Anthropic разграничава състоянията на жизнения цикъл и може да върне по-богата информация за възможностите, когато се извлича модел или псевдоним. Gemini разкрива полета като ограничения на токени и поддържани методи за генериране. Microsoft Foundry може да изисква име на внедряване в полето model и внедряването може да е несъвместимо с конкретен API дори когато основният модел съществува.

Следователно препращането на отговорите на доставчика директно не е траен дизайн. Третирайте всеки доставчик API като източник на съгласуване. Преобразувайте неговите наблюдения във вътрешен запис, след което ги комбинирайте с конфигурацията на шлюза и политиката на клиента.

Използване на каноничен каталожен запис

Полезен вътрешен запис разделя обществения договор от изпълнението нагоре по веригата:

{
  "catalog_revision": "cat_2026_11_05_0182",
  "public_model_id": "reasoning-large",
  "lifecycle": "active",
  "api_surfaces": ["chat.completions", "responses"],
  "input_modalities": ["text", "image"],
  "output_modalities": ["text"],
  "limits": {
    "context_tokens": 200000,
    "max_output_tokens": 32000
  },
  "capabilities": {
    "tools": true,
    "structured_output": true,
    "batch": false
  },
  "entitlement_profile": "advanced-reasoning",
  "routes": [
    {
      "provider": "provider-a",
      "target_type": "deployment",
      "target_id": "prod-reasoning-east",
      "region": "us-east",
      "state": "ready"
    }
  ]
}

Не излагайте target_id, препратки към идентификационни данни или вътрешно състояние на маршрутизиране през стандартната публична крайна точка. Тези полета са данни от контролната равнина. Дръжте ги на разположение за достъп до маршрута, инструменти за поддръжка и приписване на използването.

Отделни идентификатори, псевдоними и внедрявания

Идентификаторът на публичния модел е клиентски договор. Идентификационният номер на модел на доставчик идентифицира фамилия или версия на модели нагоре по веригата. Името на внедряване идентифицира обслужващ ресурс, създаден от оператор. Те не са взаимозаменяеми.

Разрешете публичен псевдоним към неизменна каталожна ревизия преди маршрутизиране. Запишете както искания идентификатор, така и разрешената цел в събитието за използване. Ако псевдонимът се промени по-късно, екипът по поддръжката все още може да възстанови кое внедряване е обработило по-ранно повикване.

Компилиране на каталога за удостоверения ключ

Компилаторът на каталога трябва да получи удостоверен принципал, а не просто ID на клиента. Един и същ наемател може да има производствени ключове, ключове за разработка, ограничени клиентски ключове и акаунти за услуги с различни предоставени модели.

Детерминирана последователност на компилиране е:

1. Заредете ревизията на неизменния основен каталог.
2. Разрешаване на членството на наемател, членството в екипа и предоставянето на конкретни ключове.
3. Прилагане на ограничения за план, география, пребиваване на данни и доставчик.
4. Премахване на маршрути без валидни идентификационни данни или съвместими внедрявания.
5. Оценете готовността на маршрута, като използвате моментната снимка на текущото състояние.
6. Обединете оцелелите маршрути в публични записи на модели.
7. Връща само API повърхности, поддържани от поне един оцелял маршрут.

Използване на семантика на пресичане, когато съществуват както екипни, така и ключови разрешения. Ключ, присвоен на ограничен екип, не трябва да възстановява по-широк достъп само защото наемателят притежава по-широк план. Това прави контрола на достъпа на AI модел за софтуерни екипи предсказуем и намалява случайното разкриване.

Поддържане на идентично поведение на списъка и извличане

GET /v1/models/{model} трябва да изпълни същия предикат за оторизация като операцията за списък. В противен случай атакуващият може да изброи скрити идентификатори чрез сравняване на успешни, забранени и ненамерени отговори.

За модел, който ключът не може да види, връща същата публична грешка, използвана за неизвестен модел. Не разкривайте дали друг наемател може да го използва, кой доставчик го хоства или кое право ще го отключи. Административните API могат да изложат по-подробни причини на оторизираните оператори.

Изрично представяне на API съвместимост

Съществуването на модел не предполага поддръжка за всяка крайна точка. Завършвания на чатове, отговори, вграждания, генериране на изображения, реално време, пакети и Anthropic Съобщенията имат различни заявки и договори за поточно предаване.

Следователно приемането на маршрут трябва да приема както модел, така и API повърхност:

admit(key, public_model_id, api_surface, request_features)

Резултатът трябва да идентифицира съвместима ревизия на каталога и един или повече допустими маршрути. Например, даден модел може да поддържа chat.completions, но не и responses, или да поддържа отговори само когато липсват вградени инструменти. Едно булево значение като supports_responses може да е недостатъчно, когато съвместимостта зависи от исканите функции.

Препоръка: публикувайте консервативни възможности. Рекламирайте функция само когато шлюзът може да я наложи в набора от отговарящи на условията маршрути или може да избере маршрут, който я поддържа детерминистично. Не правете извод за въвеждане на изображение, извикване на инструмент или структуриран изход от име на фамилия на доставчика.

Запазете SDK съвместимост при добавяне на метаданни

Поддържайте стабилни стандартните полета, очаквани от OpenAI-съвместими клиенти:

{
  "id": "reasoning-large",
  "object": "model",
  "created": 1793836800,
  "owned_by": "gateway",
  "x_gateway": {
    "catalog_revision": "cat_2026_11_05_0182",
    "lifecycle": "active",
    "api_surfaces": ["chat.completions", "responses"],
    "input_modalities": ["text", "image"],
    "availability": "available"
  }
}

Разширението с пространство от имена намалява риска от сблъсък, но някои клиенти отхвърлят неизвестните полета. Ако приложенията се нуждаят от подробни данни за избор, осигурете отделна автентифицирана крайна точка на моделна информация с версияна схема. Поддържайте /v1/models достатъчно малък за комплекти за разработване на софтуер (SDK), инструменти за команден ред и средства за избор на модели.

Изберете стабилни или филтрирани за здравето обяви

Съществуват две правила за разумна наличност.

Каталог с филтриране на изправност: скриване на модел, когато нито един маршрут в момента не е изправен. Това минимизира неуспешните обаждания, но каталозите могат да варират по време на инциденти и да обезсилят селекциите от страна на клиента.

Стабилен каталог: продължете да изброявате озаглавени продукти, докато докладвате availability: temporarily_unavailable. Това е по-лесно за инструментите за автоматизация и мигриране, но клиентите все още могат да се опитват да се обаждат, освен ако не разбират разширението.

Практическа настройка по подразбиране е да се скрият модели, които не са разгърнати, забранени, оттеглени или не отговарят на условията за идентификационни данни, като същевременно се запазят временно недостъпни модели с изричен статус за доверени клиенти. Крайната точка за минимална съвместимост може да пропусне неналични записи, ако съществуващите клиенти не могат да интерпретират метаданните за състоянието.

Прогноза: клиентите с по-богат избор на модел ще зависят все повече от метаданните за възможностите и наличността. Докато това поведение не стане като цяло надеждно, допускането на маршрут от страна на сървъра трябва да остане авторитетно.

Кеширане на компилирани каталози без обслужване на остарели разрешения

Компилирайте каталози извън пътя на заявката, където е възможно. Ключът на кеша трябва да включва поне:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Невалидност на засегнатите записи, когато членство в екип, предоставяне на модел, ценови планове, идентификационни данни на доставчик, състояние на внедряване или политика за маршрутизиране се променят. Стойностите за кратко време на живот не са заместител на събитията за отмяна: дори кратък остарял прозорец може да разкрие наскоро забранен модел.

Съгласуването на доставчика може да бъде асинхронно. По време на прекъсване на контролната равнина на доставчика, запазете последния известен каталог, запишете времето за наблюдение и предотвратете новите несигурни маршрути да станат допустими. Това поддържа списъка отзивчив, без да третира остарелите открития като доказателство, че нов маршрут е използваем.

Тествайте каталога като договор за достъп

Най-силното свойство за съответствие е просто: за всеки модел и API повърхност, върнати към ключ, приемането на маршрут трябва да бъде успешно при същия каталог и ревизия на здравето.

Добавяне на автоматизирани тестове за:

• Разрешен ключ, който вижда и извлича присвоените му модели.
• Забранен ключ, който не вижда нито записи в списъка, нито извличаеми метаданни.
• Ограниченията на екипа стесняват, вместо да разширяват достъпа до ключове.
• Внедряване само за чат не се рекламира за отговори.
• Деактивирани идентификационни данни премахват зависимите от него маршрути.
• Псевдоним, разрешаващ очакваната неизменна ревизия на каталога.
• Пенсиониран модел, изчезващ от каталога по подразбиране.
• Анулиране на кеша след предоставяне, членство или промяна на правилата.
• Неизвестни и скрити идентификатори на модели, създаващи неразличими публични грешки.
• Всяка рекламирана възможност има поне един отговарящ на условията маршрут.

Синтетичните проби могат да добавят доказателства, че даден маршрут работи, но те консумират квота, може да струват пари и не могат да покрият всяка комбинация от функции. Използвайте ги за представителни класове на маршрути и ги комбинирайте със състояние на внедряване, проверки на идентификационни данни и реално състояние на трафика.

Запишете достатъчно доказателства за обяснение на решенията

За всяка приета или отхвърлена заявка, запишете ревизията на каталога, искания публичен ID на модела, API повърхност, разрешен маршрут, договор за възможности, ревизия на правилата и структурирана причина за допускане. Избягвайте да съхранявате подканващо съдържание само за тази цел.

Последователността на внедряване е ясна: дефинирайте каноничния запис, изградете съгласуватели на доставчика, компилирайте изгледи за ключ, направете списък и извлечете споделяне на един предикат за оторизация, свържете допускането на маршрут към същата ревизия и добавете отрицателни тестове, преди да активирате кешовете. След като тези части са на мястото си, /v1/models се превръща в надежден отговор на „какво може да извика този ключ?“ а не слабо филтриран инвентар.

Свързано четене

• проектиране на слой за съвместимост на отговорите API