Маршрутизация моделей: Пользовательские маппинги, приоритеты подстановочных знаков и предустановленные стратегии

Модель model, которую вы пишете в клиенте, не обязательно равна «физической модели», которую Antigravity Tools в конечном итоге запрашивает от вышестоящего провайдера. То, что делает маршрутизация моделей, просто: оно сопоставляет «стабильное внешнее имя модели» с «физической моделью, которая реально будет использоваться», и помещает результат в заголовок ответа X-Mapped-Model, чтобы вы могли подтвердить, что запрос прошёл по ожидаемому пути.

Что вы сможете сделать после изучения

• Настроить proxy.custom_mapping в UI (точное сопоставление + сопоставление с подстановками)
• Чётко объяснить, как правило было сопоставлено (точное совпадение > совпадение подстановки > сопоставление по умолчанию)
• Применить предустановленные правила одним кликом для быстрой совместимости с клиентами OpenAI/Claude
• Проверить маршрутизацию с помощью curl -i и X-Mapped-Model, чтобы найти причину «почему не маршрутизировалось как я хотел»

Ваша текущая проблема

• Вы хотите, чтобы клиент всегда писал gpt-4o, но вышестоящий провайдер должен стабильно попадать на определённую модель Gemini
• У вас есть множество версионных имён моделей (например, gpt-4-xxxx), и вы не хотите вручную добавлять маппинг каждый раз
• Вы видите, что запрос успешен, но не уверены, какая физическая модель на самом деле выполняется

Когда использовать этот подход

• Вы хотите предоставить команде «фиксированное внешнее множество моделей», экранируя изменения вышестоящих моделей
• Вы хотите унифицировать маршрутизацию множества имён моделей OpenAI/Claude к нескольким высокоэффективным моделям
• При устранении неполадок 401/429/0 token вам нужно подтвердить модель после сопоставления

🎒 Подготовка перед началом

• Вы уже смогли запустить локальный обратный прокси и успешно пройти запрос снаружи (рекомендуется сначала завершить Запуск локального обратного прокси и подключение первого клиента (/healthz + конфигурация SDK))
• Вы знаете, как использовать curl -i для просмотра заголовков ответа (в предыдущем уроке использовался X-Mapped-Model)

В этом уроке два ключевых слова

• custom_mapping — ваша «таблица пользовательских правил», ключ — имя модели, вводимое клиентом (или шаблон подстановки), значение — имя модели, которая фактически будет использоваться (источник: src/types/config.ts).
• Подстановочный знак * — используется для пакетного сопоставления имён моделей (например, gpt-4*), реализация сопоставления чувствительна к регистру (источник: src-tauri/src/proxy/common/model_mapping.rs).

Основная идея

При обработке запроса на стороне бэкенда сначала вычисляется mapped_model:

1. Сначала проверяется, есть ли в custom_mapping точное совпадение (ключ точно равен model)
2. Затем пытается совпадение подстановки: выбирается правило с «большим количеством не-* символов» (более конкретные правила имеют приоритет)
3. Если совпадений нет, идёт по системному сопоставлению по умолчанию (например, сопоставление некоторых псевдонимов моделей OpenAI/Claude с внутренними моделями)

Этот mapped_model будет записан в заголовок ответа X-Mapped-Model (как минимум, это делает обработчик OpenAI), вы можете использовать его, чтобы подтвердить «каким стало имя модели после того, как я её написал».

Семантика горячего обновления (без перезапуска)

Когда служба обратного прокси работает, фронтенд при вызове update_model_mapping немедленно запишет custom_mapping в память RwLock, а также сохранит её в персистентную конфигурацию (источник: src-tauri/src/commands/proxy.rs; src-tauri/src/proxy/server.rs).

Следуйте за мной

Шаг 1: Найдите карту «Маршрутизация моделей» на странице API Proxy

Почему Вход для настройки маршрутизации моделей находится прямо в UI; вам не нужно вручную редактировать файл конфигурации.

Откройте Antigravity Tools → страницу API Proxy, прокрутите вниз.

Вы должны увидеть: карту с заголовом примерно типа «Центр маршрутизации моделей», в правом верхнем углу две кнопки: «Применить предустановленное сопоставление» и «Сбросить сопоставление» (источник: src/pages/ApiProxy.tsx).

Шаг 2: Добавьте «точное сопоставление» (самый контролируемый)

Почему Точное сопоставление имеет наивысший приоритет, подходит для «я хочу, чтобы это конкретное имя модели попало на эту конкретную физическую модель».

В области «Добавить сопоставление»:

• Original впишите имя модели, которую вы хотите открыть снаружи, например, gpt-4o
• Target из выпадающего списка выберите целевую модель, например, gemini-3-flash

Нажмите Add.

Вы должны увидеть: в списке сопоставлений появляется gpt-4o -> gemini-3-flash, и появляется подсказка об успешном сохранении.

Шаг 3: Добавьте «сопоставление подстановки» (пакетное перекрытие)

Почему Когда у вас есть множество версионных имён моделей (например, gpt-4-turbo, gpt-4-1106-preview), с помощью подстановки можно сэкономить много повторных настроек.

Добавьте ещё одно сопоставление:

• Original: gpt-4*
• Target: gemini-3-pro-high

Вы должны увидеть: в списке появляется gpt-4* -> gemini-3-pro-high.

«Ловушка» приоритета правил

Когда gpt-4o одновременно соответствует точному правилу gpt-4o и правилу подстановки gpt-4*, бэкенд сначала пойдёт по точному совпадению (источник: src-tauri/src/proxy/common/model_mapping.rs).

Шаг 4: Примените предустановленные правила одним кликом (быстрая совместимость)

Почему Если ваша основная цель — «быстро адаптироваться к распространённым именам моделей OpenAI/Claude», предустановки помогут вам напрямую заполнить группу правил подстановок.

Нажмите «Применить предустановленное сопоставление».

Вы должны увидеть: в списке добавляются несколько правил, включая примерно следующие (источник: src/pages/ApiProxy.tsx):

{
  "gpt-4*": "gemini-3-pro-high",
  "gpt-4o*": "gemini-3-flash",
  "gpt-3.5*": "gemini-2.5-flash",
  "o1-*": "gemini-3-pro-high",
  "o3-*": "gemini-3-pro-high",
  "claude-3-5-sonnet-*": "claude-sonnet-4-5",
  "claude-3-opus-*": "claude-opus-4-5-thinking",
  "claude-opus-4-*": "claude-opus-4-5-thinking",
  "claude-haiku-*": "gemini-2.5-flash",
  "claude-3-haiku-*": "gemini-2.5-flash"
}

Шаг 5: Проверьте, работает ли маршрутизация, с помощью X-Mapped-Model

Почему Вы хотите подтвердить, что «конфигурация сохранена», и ещё больше хотите подтвердить, что «запрос действительно прошёл по этому правилу». Самый простой способ — посмотреть X-Mapped-Model.

macOS/Linux

curl -i http://127.0.0.1:8045/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "hi"}]
  }'

Windows

$resp = Invoke-WebRequest "http://127.0.0.1:8045/v1/chat/completions" -Method Post -ContentType "application/json" -Body '{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "hi"}]
}'
$resp.Headers["X-Mapped-Model"]

Вы должны увидеть: в заголовках ответа есть X-Mapped-Model: .... Если в шаге 2 вы точно сопоставили gpt-4o с gemini-3-flash, здесь должно быть видно соответствующее значение (запись заголовка ответа см. в src-tauri/src/proxy/handlers/openai.rs).

Шаг 6: Когда нужно вернуться к «чистому сопоставлению по умолчанию», сбросьте custom_mapping

Почему При устранении неполадок часто хочется сначала исключить «влияние пользовательских правил». Очистка custom_mapping — самый прямой способ отката.

Нажмите «Сбросить сопоставление».

Вы должны увидеть: список сопоставлений очищается; при последующих запросах, если не совпадают пользовательские правила, идёт по системному сопоставлению по умолчанию (источник: src/pages/ApiProxy.tsx; src-tauri/src/proxy/common/model_mapping.rs).

Контрольная точка ✅

• [ ] Вы можете добавить/удалить правила custom_mapping в UI
• [ ] Вы можете чётко объяснить, почему точные правила подавляют правила подстановки
• [ ] Вы можете прочитать X-Mapped-Model с помощью curl -i или PowerShell

Напоминания о возможных ошибках

Сценарий	Вы можете сделать (❌)	Рекомендуемый подход (✓)
Подстановка не работает	Написали GPT-4* ожидая сопоставления с gpt-4-turbo	Используйте нижний регистр gpt-4*; сопоставление подстановок на стороне бэкенда чувствительно к регистру
Две подстановки могут совпадать	Одновременно написали gpt-* и gpt-4*, не уверены, по какому правилу пойдёт	Сделайте более конкретное правило «длиннее», чтобы у него было больше не-* символов
Правила выглядят правильными, но всё ещё не изменяются	Смотрите только на тело ответа, не на заголовки ответа	Проверяйте X-Mapped-Model с помощью curl -i (это результат, явно возвращаемый бэкендом)
Два правила «одинаково конкретны»	Написали две подстановки, количество не-* символов одинаковое	Избегайте такой конфигурации; комментарий в исходном коде объясняет, что в этом случае результат зависит от порядка обхода HashMap, может быть нестабильным (источник: src-tauri/src/proxy/common/model_mapping.rs)

Краткое содержание урока

• proxy.custom_mapping — это главный вход, который вы контролируете для «внешнее имя модели → физическая модель»
• Приоритет маршрутизации на стороне бэкенда: точное совпадение > совпадение подстановки (более конкретное имеет приоритет) > сопоставление по умолчанию
• X-Mapped-Model — самый надёжный способ проверки, при устранении неполадок сначала смотрите его

Предварительный просмотр следующего урока

Следующий урок продолжит рассмотрение Управление квотами: комбинированный подход Quota Protection + Smart Warmup (соответствующая глава: advanced-quota).

---

Приложение: Ссылка на исходный код

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

Дата обновления: 2026-01-23

Функция	Путь к файлу	Номер строки
Поле конфигурации: proxy.custom_mapping (тип фронтенда)	src/types/config.ts	6-20
UI: запись/сброс/предустановки (вызов update_model_mapping)	src/pages/ApiProxy.tsx	371-475
UI: карта маршрутизации моделей (применить предустановки/сбросить сопоставления/список и форма добавления)	src/pages/ApiProxy.tsx	1762-1931
Команда бэкенда: горячее обновление и персистентизация custom_mapping	src-tauri/src/commands/proxy.rs	344-365
Состояние сервера: custom_mapping сохраняется в RwLock<HashMap<..>>	src-tauri/src/proxy/server.rs	16-53
Алгоритм маршрутизации: точный > подстановка (более конкретное имеет приоритет) > сопоставление по умолчанию	src-tauri/src/proxy/common/model_mapping.rs	180-228
Сопоставление подстановки: поддерживает несколько *, чувствительно к регистру	src-tauri/src/proxy/common/model_mapping.rs	134-178
Вычисление mapped_model в запросе (пример: обработчик OpenAI)	src-tauri/src/proxy/handlers/openai.rs	154-159
---	---	---

Ключевая функция:

• resolve_model_route(original_model, custom_mapping): главный вход маршрутизации моделей (см. src-tauri/src/proxy/common/model_mapping.rs)