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

Раздел Models предназначен для регистрации, настройки и мониторинга моделей искусственного интеллекта, которые будут подвергаться тестированию на безопасность.

Прежде чем запускать сканирование, необходимо зарегистрировать целевую модель в Системе, настроить API-контракт (способ взаимодействия с моделью) и убедиться, что модель доступна.

Типы моделей¶

Система поддерживает следующие типы моделей:

Тип	Код	Описание	Примеры
Большая языковая модель	`LLM`	Текстовые модели для генерации и обработки текста	GPT-4, Claude, GigaChat, YandexGPT
Компьютерное зрение	`CV`	Модели классификации и распознавания изображений	ResNet-50, VGG-16, YOLO
Мультимодальная модель	`MLLM`	Модели, работающие с несколькими типами данных	GPT-4V, Claude 3 (с изображениями)
Распознавание речи	`SPEECH`	Модели преобразования речи в текст	Whisper, DeepSpeech
Рекомендательная система	`RS`	Модели рекомендаций	Collaborative filtering
Табличные данные	`TABULAR`	Классические ML-модели	XGBoost, LightGBM

Регистрация модели¶

Для регистрации новой модели нажмите кнопку + Новая модель на странице Models. Система предлагает три способа регистрации:

Способ 1: Из провайдера¶

Самый простой способ для моделей популярных облачных провайдеров.

Рекомендуется

Используйте этот способ для моделей OpenAI, Claude, DeepSeek, GigaChat, YandexGPT и HuggingFace. Система автоматически заполнит API-эндпоинт, заголовки авторизации и формат запроса/ответа.

Шаги:

Выберите вкладку Из провайдера в мастере создания.
Выберите провайдера из списка.
Заполните обязательные поля.
Нажмите Создать модель.

Встроенные провайдеры:

Провайдер	Модели	Эндпоинт	Тип авторизации
OpenAI	gpt-4, gpt-4o, gpt-3.5-turbo	`https://api.openai.com/v1/chat/completions`	Bearer Token
Claude (Anthropic)	claude-3-5-sonnet, claude-3-opus, claude-3-haiku	`https://api.anthropic.com/v1/messages`	API Key (`x-api-key`)
DeepSeek	deepseek-chat, deepseek-coder	`https://api.deepseek.com/v1/chat/completions`	Bearer Token
GigaChat	gigachat, gigachat-pro	`https://gigachat.devices.sberbank.ru/api/v1/chat/completions`	OAuth 2.0
YandexGPT	yandexgpt, yandexgpt-lite	`https://llm.api.cloud.yandex.net/foundationModels/v1/completion`	API Key + Folder ID
HuggingFace	Inference API	`https://api-inference.huggingface.co/models/{model_name}`	Bearer Token

Поля при создании из провайдера:

Поле	Тип	Обязательное	Описание
`provider_id`	UUID	Да	Идентификатор провайдера (выбирается из списка)
`name`	string	Да	Отображаемое имя модели (например, «Мой GPT-4o»)
`model_name`	string	Да	Техническое имя модели у провайдера (например, `gpt-4o`)
`api_key`	string	Да	API-ключ для авторизации
`description`	string	Нет	Описание модели

Пример запроса через API:

POST /api/v1/providers/models/from-provider

{
    "provider_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Production GPT-4o",
    "model_name": "gpt-4o",
    "api_key": "sk-..."
}

Автоматическая настройка контракта

При создании модели из провайдера Система автоматически создаёт API-контракт с правильными настройками request_format, response_format, success_path, auth_type и auth_header_name.

Способ 2: Из шаблона¶

Подходит для моделей, совместимых с API одного из встроенных провайдеров, но размещённых на собственном сервере (например, vLLM, LM Studio, Ollama с OpenAI-совместимым API).

Шаги:

Выберите вкладку Из шаблона в мастере создания.
Выберите провайдер-шаблон (например, OpenAI).
Система загрузит конфигурацию провайдера.
Измените поле api_endpoint на адрес вашего сервера.
При необходимости отредактируйте формат запроса/ответа.
Укажите API-ключ (если требуется).
Нажмите Создать модель.

Пример запроса через API:

POST /api/v1/providers/models/from-template

{
    "name": "Internal vLLM Server",
    "description": "Self-hosted LLM with OpenAI-compatible API",
    "provider_template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "api_endpoint": "https://vllm.internal.company.com/v1/chat/completions",
    "api_key": "internal-key-123",
    "request_format": {
        "model": "{model_name}",
        "messages": "{messages}",
        "temperature": "{temperature}",
        "max_tokens": "{max_tokens}"
    },
    "response_format": {
        "success_path": "choices[0].message.content",
        "error_path": "error.message"
    },
    "auth_type": "bearer",
    "auth_header_name": "Authorization",
    "timeout_ms": 60000,
    "tags": ["internal", "openai-compatible"]
}

Способ 3: Ручная регистрация¶

Для полностью кастомных моделей с нестандартным API.

Шаги:

Выберите вкладку Вручную в мастере создания.
Заполните все поля вручную.
Настройте API-контракт.
Нажмите Создать модель.

Поля модели¶

Основные поля¶

Поле	Тип	Обязательное	Описание	Пример
`name`	string (1-255)	Да	Отображаемое имя модели	`Production GPT-4o`
`type`	enum	Да	Тип модели	`LLM`, `CV`, `MLLM`, `SPEECH`, `RS`, `TABULAR`
`modalities`	list[string]	Да	Поддерживаемые модальности	`["text"]`, `["image"]`, `["text", "image"]`
`api_endpoint`	URL	Да	Полный URL эндпоинта API модели	`https://api.openai.com/v1/chat/completions`
`api_key`	string	Условно	API-ключ для авторизации	`sk-...`
`api_key_required`	boolean	Нет	Требуется ли API-ключ (по умолчанию `true`)	`true`
`description`	string	Нет	Описание модели	`Модель для тестирования`
`version`	string (до 50)	Нет	Версия модели	`1.0`, `gpt-4o-2024-05-13`
`tags`	list[string]	Нет	Теги для категоризации	`["production", "openai"]`
`status`	enum	Нет	Статус модели	`active`, `inactive`, `archived`

Конфигурация сессий¶

Для многоходовых атак (Crescendo, PAIR, TAP) необходимо настроить конфигурацию сессий:

Stateless API (OpenAI, Claude)Stateful API (кастомные модели)

Большинство современных LLM API работают в режиме stateless: клиент передаёт полную историю сообщений в каждом запросе.

{
    "session_config": {
        "type": "stateless"
    },
    "message_format": {
        "type": "messages_array",
        "user_role": "user",
        "assistant_role": "assistant",
        "system_role": "system"
    }
}

Некоторые модели поддерживают stateful-режим: сервер хранит контекст диалога, а клиент передаёт идентификатор сессии.

{
    "session_config": {
        "type": "stateful",
        "response_session_location": {
            "type": "header",
            "path": "X-Session-Id"
        },
        "request_session_location": {
            "type": "header",
            "path": "X-Session-Id"
        },
        "cleanup": {
            "endpoint": "/session/{session_id}",
            "method": "DELETE"
        }
    }
}

Поле	Тип	Описание
`session_config.type`	`stateless` / `stateful`	Тип управления сессией
`message_format.type`	`messages_array` / `custom`	Формат передачи истории сообщений
`message_format.user_role`	string	Имя роли пользователя в массиве сообщений
`message_format.assistant_role`	string	Имя роли ассистента в массиве сообщений
`message_format.system_role`	string / null	Имя роли системного промпта
`response_session_location.type`	`header` / `body` / `cookie` / `query`	Где искать session_id в ответе
`response_session_location.path`	string	Имя заголовка / JSONPath / имя cookie / имя параметра
`request_session_location.type`	`header` / `body` / `cookie` / `query`	Куда вставлять session_id в запросе
`cleanup.endpoint`	string	URL для очистки сессии
`cleanup.method`	string	HTTP-метод для очистки (`DELETE` по умолчанию)

Кастомный system prompt (для системных моделей)¶

Для системных моделей (is_system: true) — на сегодня это модели-судьи (model_purpose: judge) — можно задать собственный системный промпт, который будет использоваться сервисом-потребителем вместо встроенного по умолчанию.

Поле	Тип	Описание
`system_prompt`	string \| null	Кастомный intro системного промпта. `null` → сервис-потребитель использует встроенный default

Ограничение

Поле system_prompt принимается только при is_system: true. Попытка задать его на обычной (тестируемой) модели отклоняется валидатором с HTTP 422.

Что именно переопределяется

На стороне LLM-Judge system_prompt заменяет только содержательную часть («что и как оценивать»). Технический блок FORMAT с тегами <reason> / <score>, по которым парсится ответ модели, всегда добавляется сервисом из кода — переопределить его через API нельзя.

API-контракт¶

API-контракт определяет, как Система взаимодействует с моделью: какой формат запроса отправлять, как разбирать ответ, какие заголовки использовать.

Важно

Без правильно настроенного API-контракта сканирование работать не будет. Контракт создаётся автоматически при регистрации из провайдера и требует ручной настройки при ручной регистрации.

Поля контракта¶

Поле	Тип	Обязательное	По умолчанию	Описание
`request_format`	JSON	Да	—	Шаблон запроса с плейсхолдерами
`request_template`	JSON	Нет	—	Дополнительный шаблон для генерации запроса
`response_format`	JSON	Да	—	Ожидаемая структура ответа
`success_path`	string	Нет	—	Dot-нотация пути к тексту ответа
`error_path`	string	Нет	—	Dot-нотация пути к сообщению об ошибке
`http_method`	string	Нет	`POST`	HTTP-метод (`POST`, `GET`, `PUT`)
`headers`	JSON	Нет	—	Дополнительные HTTP-заголовки
`timeout_ms`	int	Нет	`30000`	Таймаут запроса в миллисекундах
`auth_type`	string	Нет	—	Тип авторизации: `bearer`, `api_key`, `oauth`, `custom`
`auth_header_name`	string	Нет	`Authorization`	Имя HTTP-заголовка для авторизации
`max_retries`	int	Нет	`3`	Максимальное количество повторных попыток
`retry_delay_ms`	int	Нет	`1000`	Задержка между повторными попытками (мс)

Плейсхолдеры в шаблоне запроса¶

Шаблон request_format может содержать следующие плейсхолдеры, которые Система заменяет при отправке запроса:

Плейсхолдер	Описание
`{prompt}`	Текст промпта (для LLM-атак)
`{system_prompt}`	Системный промпт
`{messages}`	Массив сообщений для многоходовых атак
`{model_name}`	Техническое имя модели
`{temperature}`	Параметр temperature
`{max_tokens}`	Максимальное количество токенов

Пример контракта для OpenAI¶

{
    "request_format": {
        "model": "gpt-4o",
        "messages": [
            {"role": "system", "content": "{system_prompt}"},
            {"role": "user", "content": "{prompt}"}
        ],
        "temperature": 0.7,
        "max_tokens": 2048
    },
    "response_format": {
        "choices": [
            {
                "message": {
                    "role": "assistant",
                    "content": "..."
                }
            }
        ]
    },
    "success_path": "choices.0.message.content",
    "error_path": "error.message",
    "http_method": "POST",
    "headers": {
        "Content-Type": "application/json"
    },
    "auth_type": "bearer",
    "auth_header_name": "Authorization",
    "timeout_ms": 60000,
    "max_retries": 3,
    "retry_delay_ms": 1000
}

Поле success_path¶

Поле success_path задаёт путь для извлечения текста ответа модели из JSON-ответа. Используется dot-нотация:

Провайдер	success_path	Пояснение
OpenAI	`choices.0.message.content`	`response["choices"][0]["message"]["content"]`
Anthropic	`content.0.text`	`response["content"][0]["text"]`
GigaChat	`choices.0.message.content`	Совместимо с OpenAI
YandexGPT	`result.alternatives.0.message.text`	Вложенный формат
HuggingFace	`0.generated_text`	Массив результатов

Верификация модели¶

После регистрации модели необходимо убедиться, что она корректно работает. Система предоставляет три метода проверки:

Сравнение методов¶

Характеристика	Test Connection	Probe	Health Check
Назначение	Быстрая проверка связи	Глубокая диагностика	Периодический мониторинг
Контракт нужен?	Нет	Да	Нет
Что проверяет	Доступность эндпоинта	Контракт, формат, маппинг	Доступность и время отклика
Результат	Успех / Ошибка	Детальный отчёт	Статус available/unavailable
Скорость	< 5 сек	5-30 сек	< 10 сек
Когда использовать	Сразу после регистрации	Перед первым сканированием	Регулярный мониторинг

Test Connection (Тест соединения)¶

Быстрая проверка, что модель доступна по указанному URL и отвечает на запросы.

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

На странице модели нажмите кнопку Test Connection.
Опционально введите тестовый промпт (по умолчанию используется стандартный).
Укажите таймаут (по умолчанию 30 000 мс).
Нажмите Проверить.

Что проверяется:

Доступность API-эндпоинта по сети.
Корректность авторизации (API-ключ принимается).
Модель отвечает (не возвращает ошибку).
Время отклика.

API:

POST /api/v1/providers/models/{model_id}/test-connection

{
    "test_prompt": "Hello! Please respond with 'Test successful'.",
    "timeout_ms": 30000
}

Пример успешного ответа:

{
    "success": true,
    "response_time_ms": 1250,
    "http_status_code": 200,
    "response_preview": "Test successful.",
    "error": null
}

Probe (Диагностическая проба)¶

Глубокая диагностика модели с валидацией API-контракта. Probe отправляет реальный запрос и анализирует ответ по всем полям контракта.

Требование

Для запуска Probe необходимо предварительно настроить API-контракт модели. Если контракт не настроен, Система вернёт ошибку 424.

Типы проб:

Тип	Описание	Входные данные
`text`	Текстовая проба для LLM	Промпт (текст)
`image`	Проба изображением для CV	Файл изображения или file_id из Assets
`audio`	Проба аудиофайлом для ASR	Файл аудио или file_id из Assets

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

На странице модели нажмите кнопку Probe.
Выберите тип пробы.
Введите тестовый промпт (для text) или загрузите файл (для image/audio).
Укажите таймаут.
Нажмите Запустить пробу.

Что возвращает Probe:

Поле	Описание
`success`	Общий результат: успех / ошибка
`probe_type`	Тип пробы (text, image, audio)
`response_time_ms`	Время ответа модели в миллисекундах
`http_status_code`	HTTP-код ответа
`raw_request`	Отправленный запрос (снапшот)
`raw_response`	Полученный ответ (снапшот)
`extracted_text`	Извлечённый текст по `success_path`
`contract_validation`	Чеклист валидации контракта (поле за полем)
`error_category`	Категория ошибки (если есть)
`error_message`	Описание ошибки
`actionable_hint`	Конкретная рекомендация по исправлению

Категории ошибок:

Категория	Описание	Рекомендация
`network`	Эндпоинт недоступен	Проверьте URL и сетевое подключение
`authentication`	Ошибка авторизации (401/403)	Проверьте API-ключ и тип авторизации
`contract_mapping`	Ответ не соответствует `success_path`	Проверьте поле `success_path` в контракте
`model_error`	Модель вернула ошибку (4xx/5xx)	Проверьте формат запроса и параметры
`timeout`	Превышено время ожидания	Увеличьте `timeout_ms` или проверьте модель

API:

POST /api/v1/models/{model_id}/probe

Content-Type: multipart/form-data

probe_type=text
prompt=Объясни что такое нейронная сеть в одном предложении
timeout_seconds=30

Пример ответа пробы:

{
    "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
    "model_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "probe_type": "text",
    "status": "success",
    "response_time_ms": 2340,
    "http_status_code": 200,
    "extracted_text": "Нейронная сеть — это математическая модель, вдохновлённая работой биологического мозга.",
    "contract_validation": [
        {"field": "request_format", "status": "ok", "detail": "Valid JSON structure"},
        {"field": "success_path", "status": "ok", "detail": "Text extracted successfully"},
        {"field": "auth_header", "status": "ok", "detail": "Authorization header accepted"}
    ],
    "error_category": null,
    "error_message": null,
    "actionable_hint": null,
    "created_at": "2026-04-15T10:30:00Z"
}

История проб:

Система хранит последние 10 результатов проб для каждой модели. Просмотр доступен через:

GET /api/v1/models/{model_id}/probes

Health Check (Проверка здоровья)¶

Периодическая проверка доступности модели. Отличается от Test Connection и Probe тем, что обновляет внутренний статус health_check_status модели.

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

На странице модели нажмите кнопку Health Check.
Или используйте API напрямую.

API:

POST /api/v1/health/models/{model_id}/check

Результат:

{
    "model_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "available",
    "response_time_ms": 450,
    "http_status_code": 200,
    "error_message": null,
    "checked_at": "2026-04-15T10:30:00Z"
}

Статусы health_check_status:

Статус	Описание
`available`	Модель доступна и отвечает на запросы
`unavailable`	Модель не отвечает или возвращает ошибку
`stale`	Проверка давно не выполнялась (более 24 часов)

История проверок здоровья:

GET /api/v1/health/models/{model_id}/history?limit=100

Структурная валидация контракта¶

Помимо пробы, доступна структурная валидация контракта без отправки запроса к модели. Эта проверка анализирует поля контракта на корректность (наличие обязательных полей, валидность JSON, корректность путей).

GET /api/v1/models/{model_id}/contract/validate

Ответ содержит чеклист по каждому полю контракта:

[
    {"field": "request_format", "status": "ok", "detail": "Valid JSON object with placeholders"},
    {"field": "success_path", "status": "warning", "detail": "Path not validated against actual response"},
    {"field": "timeout_ms", "status": "ok", "detail": "30000ms (reasonable range)"},
    {"field": "auth_type", "status": "ok", "detail": "bearer"}
]

Жизненный цикл модели¶

Модель проходит следующие стадии:

stateDiagram-v2
    [*] --> active : Создание модели
    active --> inactive : Деактивация
    inactive --> active : Активация
    active --> archived : Архивирование (мягкое удаление)
    inactive --> archived : Архивирование
    archived --> [*] : Модель скрыта из списка

    note right of active
        Доступна для сканирования.
        Health Check выполняется.
    end note

    note right of inactive
        Не доступна для сканирования.
        Данные сохранены.
    end note

    note right of archived
        Мягкое удаление.
        Не отображается в списке.
        Может быть восстановлена администратором.
    end note

Переходы между статусами:

Действие	Из статуса	В статус	API
Деактивация	active	inactive	`PATCH /v1/models/{id}` с `{"status": "inactive"}`
Активация	inactive	active	`PATCH /v1/models/{id}` с `{"status": "active"}`
Архивирование	active / inactive	archived	`DELETE /v1/models/{id}`

Мягкое удаление

Удаление модели (DELETE /v1/models/{id}) не удаляет данные из базы, а переводит модель в статус archived. Модель перестаёт отображаться в списке по умолчанию, но может быть найдена с фильтром status=archived.

Загрузка весов модели (CV, whitebox)¶

Для проведения whitebox-атак на модели компьютерного зрения необходимо загрузить веса модели. Веса позволяют Системе вычислять градиенты и формировать состязательные примеры.

Только для CV-моделей

Загрузка весов доступна только для моделей типа CV. Для LLM и других типов эта функция не применима, так как используется blackbox-подход (атака через API).

Поддерживаемые форматы¶

Формат	Расширения	Описание	Безопасность
PyTorch	`.pt`, `.pth`	Стандартный формат PyTorch (pickle-based)	Средняя (содержит исполняемый код)
TorchScript	`.pt`	Сериализованный TorchScript	Высокая (рекомендуется)
ONNX	`.onnx`	Универсальный открытый формат	Высокая (безопасный)

Параметры при загрузке¶

Параметр	Тип	Обязательный	Описание	Пример
`weights_file`	file	Да	Файл с весами модели	`resnet50.pt`
`weights_format`	enum	Да	Формат: `pytorch`, `torchscript`, `onnx`	`torchscript`
`architecture`	string	Да	Архитектура модели	`resnet50`, `vgg16`
`num_classes`	int (>=2)	Да	Количество выходных классов	`10`, `1000`
`input_height`	int	Нет (224)	Высота входного изображения	`224`
`input_width`	int	Нет (224)	Ширина входного изображения	`224`
`input_channels`	int	Нет (3)	Число каналов (3 для RGB, 1 для grayscale)	`3`
`class_labels`	string	Нет	Метки классов через запятую	`cat,dog,bird`
`pretrained_source`	string	Нет	Источник предобучения	`imagenet`

Предустановленные веса¶

Система содержит предустановленные веса для быстрого начала работы:

Модель	Архитектура	Предобучение	Количество классов
VGG-19 ImageNet	`vgg19`	ImageNet	1000
ResNet-50 ImageNet	`resnet50`	ImageNet	1000

Загрузка весов через API¶

POST /api/v1/models/{model_id}/weights

Content-Type: multipart/form-data

weights_file=@resnet50_custom.pt
weights_format=torchscript
architecture=resnet50
num_classes=10
input_height=224
input_width=224
input_channels=3
class_labels=cat,dog,bird,car,plane,ship,truck,deer,frog,horse
pretrained_source=imagenet

Скачивание весов¶

Для скачивания загруженных весов используется механизм presigned URL:

GET /api/v1/models/{model_id}/weights/download?expiration_seconds=3600

Ответ содержит временную ссылку на скачивание:

{
    "model_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "download_url": "https://minio.internal:9000/model-weights/...",
    "expires_in_seconds": 3600
}

Редактирование модели¶

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

Откройте модель из списка на странице Models.
Нажмите кнопку Редактировать (или иконку ).
Измените необходимые поля.
Нажмите Сохранить.

Через API:

PATCH /api/v1/models/{model_id}

{
    "name": "Updated Model Name",
    "description": "Updated description",
    "api_key": "new-api-key-...",
    "tags": ["production", "updated"]
}

Частичное обновление

Метод PATCH выполняет частичное обновление — передавайте только изменённые поля. Отсутствующие поля не изменяются.

Статистика модели¶

Для каждой модели доступна статистика использования:

GET /api/v1/models/{model_id}/stats

Возвращает:

Количество проведённых сканирований.
Среднее время отклика.
Количество успешных и неуспешных вызовов API.

Устранение неполадок¶

Проблема: Модель не отвечает (Health Check = unavailable)¶

Возможные причины и решения:

Неверный URL — проверьте поле api_endpoint, убедитесь, что URL доступен из сети Системы.
Истёк API-ключ — обновите api_key через редактирование модели.
Сетевые ограничения — убедитесь, что между Системой и моделью нет файрвола или прокси, блокирующего запросы.
Модель перегружена — увеличьте timeout_ms в контракте до 60000-120000 мс.

Проблема: Probe возвращает ошибку contract_mapping¶

Причина: Поле success_path в контракте не соответствует реальной структуре ответа модели.

Решение:

Запустите Probe и изучите поле raw_response в результате.
Найдите путь к тексту ответа в JSON-структуре.
Обновите success_path в контракте.

Проблема: Ошибка авторизации (401 / 403)¶

Проверьте, что api_key корректен.
Проверьте auth_type (bearer vs api_key).
Проверьте auth_header_name (Authorization vs x-api-key).
Для GigaChat: убедитесь, что OAuth-токен актуален.

Проблема: Модель создана, но не видна в списке для сканирования¶

Проверьте статус модели — должен быть active.
Проверьте, что модель не является системной (is_system: false).
Обновите страницу.

Проблема: Загрузка весов не работает¶

Убедитесь, что модель имеет тип CV.
Проверьте формат файла (.pt, .pth или .onnx).
Убедитесь, что файл не повреждён.
Проверьте, что размер файла не превышает ограничение (настраивается администратором).