Управление провайдерами¶

Провайдер описывает, какой LLM backend вы защищаете и как до него добраться. В этом разделе описано, как создавать, настраивать и обслуживать провайдеров. Концептуальное описание сущности «Провайдер» — см. Основные понятия. Здесь приведено практическое руководство по работе с провайдерами в Admin UI и через API.

Создание провайдера¶

Перейдите в раздел Провайдеры (/providers) и нажмите кнопку Создать нового провайдера. Откроется окно Создание провайдера с вкладками: Основное, Upstream (бэкенд LLM), Маршрутизация, Маппинг полей и Passthrough и события.

Вкладка «Основное»¶

Поле	Обяз.	Описание	Допустимые значения	Подробности
Название провайдера	Да	Имя провайдера	Строка 1–255 символов	Отображается в списке, логах и событиях. Рекомендуемый формат: `<провайдер>-<среда>` (например, `openai-production`, `gigachat-staging`).
Тип провайдера	Да	Назначение провайдера	`Custom`, `Guardrail`	`Custom` — обычный upstream-провайдер (Gateway проксирует запросы к LLM). `Guardrail` — режим интеграции с внешним LLM Gateway (только пайплайн безопасности, без проксирования — см. раздел ниже). Нельзя изменить после создания. Формат API/маппинга задаётся полем Mapping Preset, а discovery- и streaming-поведение — полями Discovery family / Streaming format (вкладка Маппинг полей).
Описание	Нет	Комментарий для администраторов	Текст до 1000 символов	Произвольный текст: назначение провайдера, ответственный, дата создания. Отображается только в Admin UI, не влияет на работу системы.

Вкладка «Upstream (бэкенд LLM)»¶

Поле	Обяз.	Описание	Допустимые значения	Подробности
Target Base URL	Да	URL целевого LLM backend	Валидный URL (http:// или https://)	Полный базовый URL, куда Gateway проксирует запросы после проверки. Обязателен для активации провайдера. Должен быть доступен из сети AppSec.AIGate. Не включайте путь endpoint — он указывается отдельно в API Path.
API Path	Нет	Путь к API endpoint	Строка, начинающаяся с `/`	Конкретный путь endpoint на LLM backend. Итоговый URL запроса: `Target Base URL` + `API Path`. По умолчанию `/v1/chat/completions`.
Request Timeout (мс)	Нет	Таймаут запроса к LLM	1000–600000 (по умолч. 30000)	Максимальное время ожидания ответа от LLM backend. Если LLM не ответил за это время — Gateway возвращает ошибку 504. Для моделей с длинной генерацией (o1, reasoning) рекомендуется 120000–300000 мс. Для генерации изображений — от 120000 мс.

Тип провайдера больше не определяет формат API

Раньше тип провайдера (openai, anthropic, azure, …) неявно управлял тремя вещами: маппингом запроса/ответа, обнаружением моделей (/v1/models) и разбором streaming-ответа. Это было неочевидно. Теперь каждый аспект задаётся явным полем:

формат запроса/ответа → поле Mapping Preset (любой провайдер);
обнаружение моделей → поле Discovery family;
разбор streaming → поле Streaming format.

Тип сведён к двум значениям — custom (обычный провайдер) и guardrail. OpenAI, Anthropic, Azure, GigaChat и любые другие backend'ы настраиваются как custom с соответствующим Mapping Preset; при необходимости — с переопределением Discovery family / Streaming format.

Discovery family и Streaming format (явные поля маршрутизации):

Поле	Допустимые значения	Что определяет
Discovery family	`openai_compatible`, `anthropic_native`, `unsupported`	Как обслуживается обнаружение моделей (`GET/POST /v1/models`): OpenAI-совместимый passthrough, нативный Anthropic-адаптер или `unsupported` (→ HTTP 501).
Streaming format	`openai_compatible`, `anthropic_messages`, `unsupported`	Какой парсер SSE-чанков используется при realtime-сканировании ответа: OpenAI (`choices[].delta.content`), Anthropic (`content_block_delta.text`) или `unsupported` (без чанкового сканирования, passthrough).

Оба поля автоматически подставляются из выбранного Mapping Preset (например, anthropic_messages → anthropic_native / anthropic_messages), но оператор может их переопределить. Это позволяет настроить, например, Anthropic-совместимый backend как type=custom + discovery_family=anthropic_native + streaming_format=anthropic_messages без потери discovery/streaming.

Примеры Target Base URL и API Path для популярных провайдеров:

Провайдер	Target Base URL	API Path	Итоговый URL
OpenAI	`https://api.openai.com`	`/v1/chat/completions`	`https://api.openai.com/v1/chat/completions`
Anthropic	`https://api.anthropic.com`	`/v1/messages`	`https://api.anthropic.com/v1/messages`
Azure OpenAI	`https://your-resource.openai.azure.com`	`/openai/deployments/gpt-4/chat/completions`	`https://your-resource.openai.azure.com/openai/deployments/gpt-4/chat/completions`
GigaChat	`https://gigachat.devices.sberbank.ru/api/v1`	`/chat/completions`	`https://gigachat.devices.sberbank.ru/api/v1/chat/completions`
Google Gemini	`https://generativelanguage.googleapis.com`	`/v1/models/gemini-pro:generateContent`	`https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent`
Ollama (self-hosted)	`http://ollama.internal:11434`	`/api/chat`	`http://ollama.internal:11434/api/chat`
vLLM (self-hosted)	`http://vllm.internal:8000`	`/v1/chat/completions`	`http://vllm.internal:8000/v1/chat/completions`

Совет

Если вы не уверены в правильности Target URL — выполните curl <Target Base URL><API Path> из сети AppSec.AIGate. Если получаете ответ (даже с ошибкой авторизации 401/403) — URL правильный и backend доступен.

Метод роутинга¶

Метод роутинга определяет, как Gateway выбирает провайдера для входящего запроса. Выбирается один из трёх методов на вкладке Маршрутизация при создании провайдера. Изменить метод после создания нельзя — при ошибке нужно создать нового провайдера и перепривязать профиль.

Метод 1: URL Pattern (рекомендуется для большинства случаев)

Gateway сопоставляет путь из заголовка X-Original-URI с паттерном пути. Это glob-сопоставление по сегментам пути (как в маршрутах nginx), а не регулярное выражение. Спецсимволы regex (., .*, +, ()) не поддерживаются и будут восприняты буквально — паттерн вроде /openai/.* не сматчит ни одного запроса.

Поле	Описание
URL Pattern	Паттерн пути с wildcard `` / `*` (см. таблицу синтаксиса ниже)
Priority	Приоритет (1-1000), выше число = выше приоритет

Главное правило wildcard

Одинарная * матчит ровно один сегмент пути, а не «всё, что ниже». Чтобы провайдер ловил весь API под префиксом на любой глубине (самый частый случай) — используйте ** или префикс без wildcard.

Синтаксис URL Pattern:

URL Pattern	Семантика	Пример: `/openai/v1/chat/completions`
`/openai/v1/chat/completions`	точное совпадение пути	✅ совпадёт только с ним
`/openai/**`	префикс + любая глубина	✅ (и `/openai/v1/embeddings`, и любой путь под `/openai/`)
`/openai`	префикс без wildcard, любая глубина (по границе сегмента)	✅ (то же, что `/openai/**`)
`/openai/*`	префикс + ровно один сегмент	❌ (`v1/chat/completions` — три сегмента, слишком глубоко)
`/`	catch-all — все пути	✅

Проверка идёт строго по границе сегмента: паттерн /v1 совпадёт с /v1/chat, но не с /v1beta/....

Частые ошибки — эти паттерны не сматчат ничего

Ошибочный паттерн	Почему не работает	Чем заменить
`/openai/.*`	regex не поддерживается; `.*` берётся буквально	`/openai/**`
`/openai/*` (для глубоких путей)	`*` = только один сегмент	`/openai/**`
`/v1/*/`, `/v1//`	wildcard допустим только как последний сегмент	`/v1/**`
`/openai/ch*`	частичный glob внутри сегмента не поддерживается	`/openai/**`

Шпаргалка «что я хочу → что писать»:

Цель	URL Pattern
Проксировать весь API провайдера (любые пути под префиксом)	`/openai/**` или `/openai`
Только один уровень под путём	`/v1/chat/*`
Один конкретный endpoint	`/v1/chat/completions`
Один провайдер на весь трафик (catch-all)	`/`

Пример конфигурации двух провайдеров с URL routing:

Провайдер "OpenAI":
  URL Pattern: /openai/**
  Priority: 100

Провайдер "Anthropic":
  URL Pattern: /anthropic/**
  Priority: 100

Запрос с X-Original-URI: /openai/v1/chat/completions → попадёт в "OpenAI". Запрос с X-Original-URI: /anthropic/v1/messages → попадёт в "Anthropic".

Метод 2: Host/Domain

Gateway сопоставляет заголовок Host с паттерном хоста. Поддерживает wildcard *.

Поле	Описание
Host Pattern	Паттерн хоста (wildcard: `*.openai.com`)
Priority	Приоритет (1-1000), выше число = выше приоритет

Примеры Host Pattern:

Host Pattern	Что совпадёт	Что НЕ совпадёт
`openai.company.com`	Только `openai.company.com`	`anthropic.company.com`
`*.openai.company.com`	`gpt4.openai.company.com`, `prod.openai.company.com`	`openai.company.com` (без поддомена)
`llm.company.com`	Только `llm.company.com`	`llm2.company.com`

Пример: Ваш Nginx раздаёт разные поддомены:

openai.company.com → провайдер "OpenAI" (host pattern: openai.company.com).
claude.company.com → провайдер "Anthropic" (host pattern: claude.company.com).

Метод 3: HTTP Header

Gateway ищет конкретный заголовок с конкретным значением.

Поле	Описание
Header Name	Имя HTTP заголовка (например `X-LLM-Provider`)
Header Value	Ожидаемое значение (например `openai`)
Priority	Приоритет (1-1000), выше число = выше приоритет

Пример:

Провайдер "OpenAI":
  Header Name: X-LLM-Provider
  Header Value: openai
  Priority: 100

Провайдер "Anthropic":
  Header Name: X-LLM-Provider
  Header Value: anthropic
  Priority: 100

Клиент отправляет запрос с заголовком X-LLM-Provider: openai → попадает в "OpenAI".

Разрешение конфликтов (Priority):

Если входящий запрос совпадает с несколькими провайдерами, используется провайдер с наибольшим числом Priority:

Провайдер "OpenAI Default":    URL Pattern: /openai/**         Priority: 100
Провайдер "OpenAI VIP":        URL Pattern: /openai/vip/**     Priority: 200

Запрос: /openai/vip/chat → совпадает с обоими → выбирается "OpenAI VIP" (200 > 100)
Запрос: /openai/v1/chat  → совпадает только с "OpenAI Default"

Рекомендация

Используйте URL Pattern для простых случаев, Host для мультидоменной архитектуры, Header когда клиенты управляют маршрутизацией самостоятельно.

Field Mapping (Mapping Preset)¶

Field Mapping определяет, как извлекать user prompt из запроса к LLM для анализа детекторами. Без правильного mapping Gateway не сможет извлечь текст пользователя и проанализировать его. Mapping Preset выбирается на вкладке Маппинг полей при создании провайдера. В выпадающем списке пресеты отображаются понятными названиями (например, OpenAI Chat Completions); идентификатор пресета приведён в таблице ниже.

Доступные Mapping Preset'ы:

LLM / API	Mapping Preset	Realtime-сканирование SSE-стриминга
OpenAI Chat (GPT-4, GPT-3.5)	`openai_chat_completions`	да
OpenAI Completions (legacy)	`openai_completions`	да
Azure OpenAI	`azure_openai_chat`	да
vLLM	`vllm_openai`	да
Ollama	`ollama_openai`	да
llama.cpp	`llama_cpp_openai`	да
Anthropic Claude	`anthropic_messages`	да
Sber GigaChat	`gigachat_chat`	нет (passthrough)
Yandex GPT	`yandexgpt`	нет (passthrough)
Cohere	`cohere_generate`, `cohere_chat`	нет (passthrough)
Google PaLM	`google_palm`	нет (passthrough)
Google Gemini	`google_gemini`	нет (passthrough)
HuggingFace	`huggingface_inference`	нет (passthrough)
Генерация изображений (Flux)	`flux_bfl`, `flux_openai_images`, `flux_replicate`	нет (passthrough)
NVIDIA Triton	`triton_inference`, `triton_text_generation`	нет (passthrough)
Нестандартный API	`custom_simple` + JSONPath-пути (см. ниже)	нет (passthrough)

Стриминг и realtime-сканирование

Пресеты со значением «нет (passthrough)» не поддерживают realtime-сканирование SSE-стриминга: для стримингового трафика шлюз переходит в режим passthrough (потоковые ответы проксируются без чанкового анализа). Полноценный realtime-разбор SSE доступен только для OpenAI-совместимых и Anthropic-форматов.

Полный список preset'ов — см. Mapping Presets.

Настройка Custom Mapping (для нестандартных API):

Если ваш LLM использует нестандартный формат, выберите preset Custom Simple Format (custom_simple) и укажите JSONPath-пути:

Поле	Описание	Для чего нужно
Prompt Path	Путь к тексту пользователя	Извлечение текста для детекторов
Model Path	Путь к названию модели	Логирование в событиях
System Prompt Path	Путь к system prompt	Анализ system prompt (если нужно)
Response Path	Путь к тексту ответа	Извлечение текста ответа для Response Scanning

Пример 1: Стандартный OpenAI-совместимый API

Ваш LLM принимает запросы в формате OpenAI:

{
  "model": "my-model",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Привет, как дела?"}
  ]
}

Mapping:

Prompt Path: $.messages[*].content (извлечёт текст из всех messages).
Model Path: $.model.
System Prompt Path: $.messages[?(@.role=='system')].content.
Response Path: $.choices[0].message.content.

В данном случае проще выбрать preset openai_chat_completions — он уже настроен.

Пример 2: Кастомный LLM с нестандартным форматом

Ваш LLM принимает запросы в формате:

{
  "query": "Привет, как дела?",
  "config": {
    "model_name": "internal-llm-v2",
    "temperature": 0.7
  }
}

И отвечает:

{
  "result": {
    "text": "Привет! У меня всё хорошо.",
    "tokens_used": 15
  }
}

Mapping:

Prompt Path: $.query.
Model Path: $.config.model_name.
System Prompt Path: (оставьте пустым — нет system prompt).
Response Path: $.result.text.

Пример 3: LLM с вложенными объектами

Ваш LLM принимает:

{
  "request": {
    "prompt": {
      "text": "Переведи на английский",
      "language": "ru"
    },
    "model": "translate-v1"
  }
}

Mapping:

Prompt Path: $.request.prompt.text.
Model Path: $.request.model.
Response Path: $.response.text.

Совет

Если вы не уверены в JSONPath — отправьте тестовый запрос через Gateway и проверьте логи api-gateway. При неправильном mapping в логах появится предупреждение failed to extract prompt.

Провайдер типа `guardrail`¶

Назначение. Guardrail-провайдер используется в режиме интеграции с внешним LLM Gateway (LiteLLM, Portkey). В отличие от custom-провайдеров, guardrail не проксирует запросы к LLM, а только запускает пайплайн безопасности AppSec.AIGate (детекторы → PDP). Проксированием LLM-трафика продолжает заниматься внешний Gateway.

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

Клиент уже использует LiteLLM, Portkey или аналогичный LLM Gateway и не готов менять точку входа.
Нужно применить security pipeline AppSec.AIGate к уже существующему LLM-трафику.
Подробнее: Интеграция с LiteLLM, Сценарий 5 в архитектуре.

Конфигурация:

Поле	Значение	Примечание
`type`	`guardrail`	Обязательно
`routing_method`	`header` (обычно)	Также поддерживаются `url`, `host`
`routing_config.header_name`	`X-LLM-Team`	Имя заголовка, по которому матчится
`routing_config.header_value`	`default` / `<team>`	Значение заголовка для матчинга
`target_base_url`	`null` (пустой)	Guardrail не проксирует — backend не нужен
`target_path`	`null`	То же
`priority`	`100` (по умолчанию)	Больший приоритет у более специфичных провайдеров; при равенстве — guardrail-тип побеждает LLM-провайдера

Пример provider для стандартного трафика от LiteLLM:

{
  "name": "LiteLLM Default",
  "type": "guardrail",
  "routing_method": "header",
  "routing_config": {
    "header_name": "X-LLM-Team",
    "header_value": "default",
    "priority": 100
  },
  "target_base_url": null,
  "target_path": null,
  "status": "ACTIVE"
}

Матчинг. Когда llm-gateway-adapter форвардит запрос в api-gateway, он отправляет заголовок X-LLM-Team: <team> (значение из LiteLLM metadata.team, либо default). Api-gateway находит провайдера с совпадающим header match и применяет привязанный профиль безопасности. Это позволяет разводить трафик разных команд на разные профили — достаточно создать несколько guardrail-провайдеров с разными header_value.

Привязка профиля

К guardrail-провайдеру, как и к обычному, привязывается ровно один активный профиль безопасности. Профиль определяет, какие детекторы включены и с какими порогами — Управление профилями.

Активный профиль обязателен

Для провайдера типа guardrail обязательно должен быть привязан профиль в статусе ACTIVE. Если провайдер сматчился, но активного профиля нет (например, его архивировали или забыли активировать), api-gateway отвечает HTTP 422 с кодом PROVIDER_NO_ACTIVE_PROFILE и заголовком X-LLM-Firewall-Action: BLOCKED_NO_PROFILE. Адаптер транслирует это в gateway-native блокировку ({"action":"BLOCKED"} для LiteLLM, {"verdict": false} для Portkey) — клиент видит fail-secure блок, а не открытый проход.

В отличие от провайдеров типа Custom, для которых можно включить опцию passthrough при отсутствии активного профиля (вкладка Passthrough и события — запрос идёт в LLM без инспекции, если профиль не активен), для guardrail-провайдера это поведение запрещено по дизайну: смысл guardrail-провайдера именно в обязательном прохождении пайплайна безопасности.

Жизненный цикл провайдера¶

Провайдер проходит через три состояния. Переходы между ними выполняются вручную администратором.

Жизненный цикл провайдера: DRAFT → ACTIVE → ARCHIVED

Состояние	Поведение	Когда использовать
DRAFT	Провайдер создан, но не участвует в маршрутизации. Запросы, совпадающие с его маршрутом, получат ошибку `NO_BACKEND_CONFIGURED`.	После создания — для настройки и проверки параметров до ввода в эксплуатацию.
ACTIVE	Провайдер активен. Gateway маршрутизирует запросы к его Target URL. Health check выполняется автоматически.	Рабочее состояние.
ARCHIVED	Провайдер архивирован (через удаление). Запросы не маршрутизируются. Конфигурация сохраняется для аудита. Можно реактивировать кнопкой Активировать.	При выводе LLM backend из эксплуатации, миграции на другого провайдера, или временном отключении.

Активация провайдера¶

На странице Провайдеры найдите провайдера в статусе DRAFT.
В столбце Действия нажмите кнопку Активировать.
Система проверит, что все обязательные поля заполнены (в частности, Target Base URL).
Статус изменится на ACTIVE.

Что происходит при активации: Gateway немедленно начинает принимать запросы для этого маршрута. Если к провайдеру ещё не привязан профиль безопасности — запросы будут проксироваться к LLM без проверки детекторами. Рекомендуется сначала создать и привязать профиль (шаги 3–4 из раздела Порядок настройки), а затем активировать провайдера.

Та же кнопка Активировать возвращает в работу провайдера из статуса ARCHIVED (реактивация).

Архивация провайдера¶

Отдельной кнопки архивации нет — провайдер архивируется через удаление (soft delete):

На странице Провайдеры найдите провайдера.
В столбце Действия нажмите кнопку Удалить (иконка корзины).
В диалоге подтверждения (текст: «Провайдер будет архивирован и перестанет использоваться») подтвердите действие.

Провайдер переходит в статус ARCHIVED: запись сохраняется в базе данных, кэш провайдера немедленно инвалидируется, и Gateway перестаёт сопоставлять с ним запросы. Безвозвратное удаление провайдера из базы через интерфейс не предусмотрено — архивированного провайдера можно вернуть в работу кнопкой Активировать.

Архивация при активном профиле

Если к провайдеру привязан активный профиль безопасности, удаление вернёт ошибку. Сначала архивируйте профиль на вкладке Профили, затем повторите удаление провайдера.

Мягкое удаление в продукте

Для провайдеров, профилей и контентных политик действует мягкое удаление (архивация → ARCHIVED) с сохранением записи для аудита. Безвозвратное удаление из базы применяется только к исключениям PII.

Внимание

Если архивируемый провайдер — единственный активный для определённого маршрута, все запросы по этому маршруту начнут получать ошибку NO_BACKEND_CONFIGURED. Убедитесь, что трафик перенаправлен на другой провайдер, или предупредите пользователей о плановом отключении.

Редактирование провайдера¶

Нажмите на имя провайдера в таблице или кнопку Редактировать для открытия формы редактирования.

Что можно изменить:

Поле	Можно изменить?	Примечание
Название	Да	Изменение отразится в UI, но исторические события сохранят старое имя.
Target Base URL	Да	Применяется немедленно. Все новые запросы будут направлены на новый URL.
API Path	Да	Применяется немедленно.
Request Timeout	Да	Применяется к новым запросам. Уже выполняющиеся запросы используют старый таймаут.
Описание	Да	—
Routing: URL Pattern / Host Pattern / Header Value	Да	Паттерн можно изменить, но сам метод роутинга (URL/Host/Header) изменить нельзя.
Routing: Priority	Да	Изменение приоритета может перенаправить трафик на другой провайдер. Будьте осторожны.
Mapping Preset	Да	Смена preset применяется немедленно. При неправильном preset детекторы получат пустой текст.
Custom Mapping (JSONPath)	Да	Применяется немедленно. Рекомендуется протестировать на тестовом запросе.
Тип провайдера	Нет	Нельзя изменить после создания. Нужно создать нового провайдера.
Метод роутинга (тип)	Нет	Нельзя переключить URL Pattern на Host или Header. Нужно создать нового провайдера.

Важно

Изменения в активном провайдере применяются немедленно к новым запросам. Если вам нужно безопасно мигрировать — создайте нового провайдера, настройте и протестируйте его, затем архивируйте старого.

Тестирование провайдера¶

После создания и активации провайдера рекомендуется проверить, что маршрутизация и field mapping работают корректно.

Шаг 1: Проверка маршрутизации

Отправьте тестовый запрос через Gateway и убедитесь, что он попадает к правильному провайдеру. Флаг -v выводит заголовки ответа, среди которых Gateway возвращает информацию о выбранном провайдере:

curl -v -X POST http://localhost:8085/chat \
  -H "Content-Type: application/json" \
  -H "X-Original-URI: /openai/v1/chat/completions" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Test routing"}]}' \
  2>&1 | grep -E "(HTTP/|X-Provider|X-Profile)"

Что искать в выводе:

X-Provider-ID: <uuid> — ID выбранного провайдера. Если отсутствует — маршрут не найден.
X-Profile-ID: <uuid> — ID применённого профиля. Если отсутствует — профиль не привязан.
HTTP/1.1 200 — запрос успешно проксирован к LLM.
HTTP/1.1 403 — запрос заблокирован детектором (это нормально для тестов безопасности).
HTTP/1.1 502 — LLM backend недоступен. Проверьте Target URL.

Шаг 2: Проверка field mapping

Отправьте запрос с заведомо опасным текстом (например, с PII) и проверьте, что детектор его обнаружил:

curl -s -X POST http://localhost:8085/chat \
  -H "Content-Type: application/json" \
  -H "X-Original-URI: /openai/v1/chat/completions" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Мой email: test@example.com"}]}'

Если PII Detection включён и mapping настроен правильно — на дашборде появится событие PII_DETECTED. Если события нет — mapping неправильный: Gateway не смог извлечь текст промпта.

Шаг 3: Проверка в логах

При проблемах с mapping проверьте логи API Gateway:

# В контейнере или через docker logs
grep "failed to extract prompt" /var/log/aigate/gateway.log

Наличие этого сообщения означает, что JSONPath из mapping preset не нашёл текст в теле запроса. Проверьте структуру запроса и соответствие preset.

Health Check провайдера¶

Health check — автоматическая проверка доступности LLM backend. Gateway периодически отправляет HTTP-запрос к Target URL и фиксирует результат. Результат отображается на странице Провайдеры в колонке Доступность. До первой проверки в колонке показано Неизвестно; при недоступности backend — текст ошибки соединения (например, Connection failed).

Автоматические проверки:

Система выполняет health check в фоне с настраиваемым интервалом. Конфигурация через переменные окружения:

Переменная	Значение по умолч.	Допустимый диапазон	Описание
`HEALTH_CHECK_ENABLED`	`true`	`true` / `false`	Включить автоматические фоновые проверки. При `false` — health status обновляется только при ручном запуске.
`HEALTH_CHECK_INTERVAL_SECONDS`	`60`	10–3600	Интервал между проверками. Для критичных production-провайдеров рекомендуется 30 сек. Для staging — 300 сек.
`HEALTH_CHECK_TIMEOUT_SECONDS`	`5`	1–30	Таймаут ожидания ответа от backend при health check. Если backend не ответил за это время — статус `UNHEALTHY`.
`HEALTH_CHECK_RETRIES`	`2`	0–5	Количество повторных попыток при ошибке, прежде чем установить статус `UNHEALTHY`. При 0 — одна неудачная попытка сразу даёт UNHEALTHY.

Ручная проверка:

Нажмите кнопку Проверить доступность на странице Провайдеры или выполните API-запрос:

curl -X POST "http://localhost:8001/api/v1/providers/{id}/health-check?performed_by=admin"

Результат проверки:

Статус	Условие	Что делать
HEALTHY	Backend ответил HTTP 2xx/3xx в пределах таймаута	Провайдер работает нормально.
UNHEALTHY	Ошибка соединения, таймаут, или HTTP >= 500 после всех retry	Проверьте: (1) Target URL корректен, (2) backend запущен, (3) сетевая связность и firewall, (4) backend не перегружен.
UNKNOWN	Health check ещё ни разу не выполнялся	Нажмите Check Health для первой проверки, или дождитесь автоматической.

Дополнительные поля в ответе API /api/v1/providers/{id}:

Поле	Тип	Описание	Как использовать
`health_latency_ms`	int / null	Время ответа backend в мс	Мониторинг деградации производительности. Если latency растёт — backend перегружен. Нормальные значения для облачных API: 100–500 мс. Для self-hosted: 10–100 мс.
`health_error_message`	string / null	Текст ошибки при UNHEALTHY	Содержит конкретную причину: `Connection refused`, `Timeout`, `HTTP 503 Service Unavailable`. Наведите на значок в колонке Доступность — tooltip покажет это сообщение.
`health_checked_at`	datetime / null	Время последней проверки	Если давно — возможно, health check отключён или не работает.

Типичные проблемы и решения¶

Проблема	Симптом	Причина	Решение
Запросы не маршрутизируются	HTTP 400 `NO_BACKEND_CONFIGURED`	Провайдер не найден для данного маршрута	Проверьте: (1) провайдер в статусе ACTIVE, (2) `X-Original-URI` совпадает с URL Pattern
Детекторы не срабатывают	Запросы проходят без событий	Field mapping не извлекает текст	Проверьте mapping preset. Отправьте запрос с PII — если событие `PII_DETECTED` не появилось, mapping неверный
Backend недоступен	HTTP 502 Bad Gateway	Target URL неправильный или backend не запущен	Выполните `curl <Target URL><API Path>` из сети AppSec.AIGate. Проверьте Health Check.
Таймаут	HTTP 504 Gateway Timeout	LLM отвечает дольше, чем Request Timeout	Увеличьте Request Timeout. Для reasoning-моделей (o1) — до 300000 мс.
Неправильный провайдер	Запрос попадает не к тому LLM	Конфликт маршрутов, неверный Priority	Проверьте Priority всех провайдеров с перекрывающимися маршрутами. Больший Priority побеждает.
Health check всегда UNHEALTHY	Провайдер помечен красным, но работает	Health check URL отличается от рабочего	Health check использует Target URL + API Path. Если backend требует авторизацию — health check может получать 401 (что считается ошибкой).

Управление провайдерами¶

Создание провайдера¶

Вкладка «Основное»¶

Вкладка «Upstream (бэкенд LLM)»¶

Метод роутинга¶

Field Mapping (Mapping Preset)¶

Провайдер типа guardrail¶

Жизненный цикл провайдера¶

Активация провайдера¶

Архивация провайдера¶

Редактирование провайдера¶

Тестирование провайдера¶

Health Check провайдера¶

Типичные проблемы и решения¶

Провайдер типа `guardrail`¶