#TrustyAI Service (TAS)

#Overview

TrustyAI Service (TAS) собирает данные инференса модели (входные запросы и выходные ответы), сохраняет их и организует в наборы данных для анализа, включая обнаружение дрейфа и оценку смещения по сравнению с эталонным и текущим трафиком.

Основные возможности:

• Захват и хранение записей инференса.
• Организация записей по model_name и data_tag.
• Предоставление API метаданных для просмотра собранных данных.
• Настройка человекочитаемых названий столбцов для записанных полей для упрощения последующего анализа.
• Запуск обнаружения дрейфа (например, тест KS, сдвиг среднего) по сравнению с эталонным подмножеством и текущими данными в продакшене.
• Запуск метрик смещения (например, SPD и DIR) по защищённым атрибутам и результатам.

На этой странице описывается развертывание TrustyAIService, загрузка эталонных данных через POST /data/upload и живого инференса через POST /consumer/kserve/v2, регистрация метрик дрейфа и смещения через HTTP API, а также экспонирование временных рядов в Prometheus для мониторинга.

#Prerequisites

• Установлен TrustyAI Operator (см. Install TrustyAI).
• Если используется storage.format: DATABASE, требуется база данных MySQL 8.x.
• Если используется storage.format: PVC, убедитесь, что в кластере есть рабочий дефолтный StorageClass (поддерживаемый CSI драйвером) для динамического выделения томов, чтобы созданный оператором PVC мог быть привязан.

#Deploy TrustyAIService

Выберите один вариант хранения: DATABASE (MySQL) или PVC (локальное файловое хранилище на томе). Следующие два подраздела — это альтернативы, а не последовательные шаги.

#DATABASE mode

Секрет с учётными данными MySQL

Создайте секрет, содержащий ключи, необходимые для развертывания TAS при использовании storage.format: DATABASE:

apiVersion: v1
kind: Secret
metadata:
  name: <tas-name>-db-credentials
  namespace: <your-namespace>
type: Opaque
stringData:
  databaseKind: mysql
  databaseUsername: <username>
  databasePassword: <password>
  databaseService: <mysql-service-name>
  databasePort: "3306"
  databaseName: <db-name>
  # Стратегия генерации схемы базы данных, используемая TrustyAI при подключении.
  # Управляет тем, что TAS делает со схемой базы (таблицами) при запуске:
  # - none: не управлять схемой
  # - create: создать схему с нуля
  # - drop-and-create: удалить существующую схему, затем создать
  # - drop: удалить существующую схему
  # - update: обновить схему для соответствия ожидаемой модели
  # - validate: только проверить, что схема соответствует ожидаемой модели
  #
  # По умолчанию: update
  databaseGeneration: update

Примечания:

• Схема MySQL (база данных), указанная в databaseName, должна быть создана заранее. TAS не создаёт базу данных самостоятельно.
• База данных должна быть доступна из пода TAS.
• databaseGeneration контролирует, как обрабатываются изменения схемы при запуске TAS.

CR TrustyAIService

Пример:

apiVersion: trustyai.opendatahub.io/v1
kind: TrustyAIService
metadata:
  name: <tas-name>
  namespace: <your-namespace>
  annotations:
    trustyai.cpaas.io/monitor-enable: "true"
    trustyai.cpaas.io/monitor-interval: "30s"
    trustyai.cpaas.io/monitor-metric-regex: "^trustyai_.*"
spec:
  storage:
    format: DATABASE
    databaseConfigurations: <tas-name>-db-credentials
  metrics:
    schedule: "5s"
    batchSize: 5000
  replicas: 1

В режиме DATABASE поле storage.databaseConfigurations должно содержать имя созданного выше секрета с учётными данными MySQL в том же namespace, что и TrustyAIService.

Аннотации в metadata.annotations необязательны и используются для того, чтобы оператор создал ServiceMonitor для сбора метрик Prometheus (чтобы платформа могла автоматически собирать данные мониторинга).

• При установке trustyai.cpaas.io/monitor-enable: "true" оператор создаёт ServiceMonitor.
• trustyai.cpaas.io/monitor-interval и trustyai.cpaas.io/monitor-metric-regex необязательны; при отсутствии используются значения по умолчанию.

trustyai.cpaas.io/monitor-interval задаёт частоту опроса метрик Prometheus (по умолчанию 30s). trustyai.cpaas.io/monitor-metric-regex задаёт, какие имена метрик сохраняются после опроса (по умолчанию ^trustyai_.*).

Поля spec.metrics:

• schedule (обязательно): как часто TAS запускает вычисление метрик (например, каждые 5s). Значение — строка длительности.
• batchSize (необязательно): сколько записей инференса TAS включает в каждое вычисление метрик (большее значение использует больше данных за один запуск). Если не задано, оператор использует значение по умолчанию 5000.

#PVC mode

Используйте этот вариант, если storage.format — PVC (без секрета MySQL). Пример:

apiVersion: trustyai.opendatahub.io/v1
kind: TrustyAIService
metadata:
  name: <tas-name>
  namespace: <your-namespace>
spec:
  storage:
    format: PVC
    folder: /inputs
    size: 1Gi
  data:
    filename: data.csv
    format: CSV
  metrics:
    schedule: "5s"
    batchSize: 5000
  replicas: 1

В режиме PVC:

• storage.folder: путь внутри примонтированного PVC, где TAS хранит и читает данные.
• storage.size: запрашиваемый размер PVC (например, 1Gi).
• Оператор автоматически создаёт PVC с именем <tas-name>-pvc в том же namespace, что и TrustyAIService. Поскольку PVC использует дефолтный StorageClass кластера (явно storageClassName не задан), кластер должен предоставлять рабочий дефолтный StorageClass (иначе PVC может оставаться в состоянии Pending).

Когда манифест TrustyAIService для выбранного режима готов, примените его (одинаковая команда для YAML DATABASE или PVC):

kubectl apply -f <trustyai-service>.yaml -n <your-namespace>

#Verify deployment readiness

kubectl get trustyaiservices -n <your-namespace> <tas-name>

Ожидаемый status.phase — Ready.

Также проверьте поды:

kubectl get pods -n <your-namespace> -l app.kubernetes.io/instance=<tas-name>

#Access the TAS API

#Service overview and authentication

В развертывании TAS kube-rbac-proxy работает как сайдкар для обеспечения аутентификации. Оператор создаёт два сервиса в том же namespace:

• <tas-name>: маршрутизирует трафик напрямую в контейнер TAS (сырой сервис).
• <tas-name>-tls: маршрутизирует трафик через сайдкар kube-rbac-proxy; это аутентифицированная точка доступа, требующая заголовок Authorization: Bearer <token>.

#Obtain a token

Создайте ServiceAccount, Role (с правами get, create, delete на services/proxy) и RoleBinding в том же namespace, что и TrustyAIService; затем создайте токен для ServiceAccount:

# Замените <your-namespace> и при необходимости имя ServiceAccount (например, `tas-client`)
kubectl create serviceaccount -n <your-namespace> tas-client
kubectl create role -n <your-namespace> tas-client --verb=get,create,delete --resource=services/proxy
kubectl create rolebinding -n <your-namespace> tas-client --role=tas-client --serviceaccount=<your-namespace>:tas-client
kubectl create token -n <your-namespace> tas-client

Опционально можно задать длительность токена, например --duration=8760h для одного года. Последняя команда выводит токен; используйте его в заголовке Authorization: Bearer <token>.

#Bearer token and base URL

Используйте токен из предыдущего раздела как заголовок Authorization: Bearer <token> для каждого запроса к защищённому API TAS.

Выберите базовый URL (хост) для вызовов:

• Прямой сервис (без прокси-аутентификации): https://<tas-name>.<your-namespace>.svc.cluster.local
• Аутентифицированная точка (kube-rbac-proxy): https://<tas-name>-tls.<your-namespace>.svc.cluster.local — используйте этот хост, когда API требует Authorization: Bearer <token> (обычно сервис с -tls).

Например, GET /info можно отправить так:

curl -k -H "Authorization: Bearer $TOKEN" \
  "https://<tas-host>/info"

Замените <tas-host> на аутентифицированный хост (обычно URL с -tls), когда требуется заголовок.

#Data ingestion

#Training and reference data (POST /data/upload)

POST /data/upload — путь для загрузки JSON с пакетами обучающих и эталонных данных: каждый вызов содержит объединённый запрос и ответ для одной записи с data_tag, например TRAINING для эталонного подмножества. Живой инференс в продакшене загружается отдельно через POST /consumer/kserve/v2 (см. ниже).

TAS может хранить записи инференса, созданные при запуске моделей. Запись содержит:

• request: входные признаки, отправленные модели
• response: выходные данные, возвращённые моделью

Набор данных определяется по model_name и data_tag.

Подготовка подмножества набора данных

1. Выберите model_name для группировки загружаемых записей.
2. Выберите data_tag для эталонного подмножества. Для обучающих/эталонных данных используйте data_tag: TRAINING.
3. Для каждого инференса загрузите один объединённый request + response payload.

Поля тела запроса

Тело запроса должно содержать:

• model_name: идентификатор модели для группировки собранных записей
• data_tag: метка подмножества набора данных
• is_ground_truth: является ли загруженный выход эталонной меткой (установите в false, если payload содержит выходы модели, а не проверенные метки)
• request:
  • id: идентификатор инференса для этой записи
  • inputs: список входных тензоров
• response:
  • model_name: должно совпадать с model_name
  • id: должно совпадать с request.id
  • outputs: список выходных тензоров

Семантика одной записи: TAS не обучает модели; он хранит строки для мониторинга. Для data_tag: TRAINING каждая загрузка — это один эталонный образец. request содержит входные признаки, которые были бы отправлены модели (одинаковый id связывает пару). response содержит наблюдаемые выходы для этого инференса — обычно предсказания модели и любые поля результата, используемые для оценки справедливости (например, оценка одобрения и решение). Метрики дрейфа и справедливости сравнивают это эталонное подмножество с живыми данными, собранными через /consumer/kserve/v2.

Пример ниже использует небольшой набор признаков в стиле кредитного скоринга: числовые входы и поле группы (gender), а также выходы с именами predict-0 и approved.

{
  "model_name": "demo-model",
  "data_tag": "TRAINING",
  "is_ground_truth": false,
  "request": {
    "id": "training-1",
    "inputs": [
      { "name": "credit_inputs-0", "shape": [1, 1], "datatype": "FP32", "data": [21.0] },
      { "name": "credit_inputs-1", "shape": [1, 1], "datatype": "FP32", "data": [605.0] },
      { "name": "credit_inputs-2", "shape": [1, 1], "datatype": "FP32", "data": [12.0] },
      { "name": "credit_inputs-3", "shape": [1, 1], "datatype": "FP32", "data": [5.0] },
      { "name": "gender", "shape": [1, 1], "datatype": "INT64", "data": [0] }
    ]
  },
  "response": {
    "model_name": "demo-model",
    "id": "training-1",
    "outputs": [
      { "name": "predict-0", "shape": [1, 1], "datatype": "FP32", "data": [0.301] },
      { "name": "approved", "shape": [1, 1], "datatype": "INT64", "data": [0] }
    ]
  }
}

Загрузка с помощью curl

curl -k -X POST "https://<tas-host>/data/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @<training-data.json>

#Live inference data (POST /consumer/kserve/v2)

Данные инференса в реальном времени отправляются в TAS через конечную точку потребителя KServe v2. Каждый логический инференс использует два вызова POST с одинаковым корреляционным id: сначала вход модели (kind: "request"), затем выход модели (kind: "response"). Тело запроса — JSON; полезные нагрузки тензоров — это Base64-кодированные protobuf-сообщения ModelInferRequest / ModelInferResponse, определённые в KServe prediction API v2 (grpc_predict_v2.proto), а не плоский JSON тензоров, используемый /data/upload.

Поля JSON:

Пример последовательности (заполните Base64-блоки):

# Первая половина одного инференса
curl -k -X POST "https://<tas-host>/consumer/kserve/v2" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"<prediction-id>","kind":"request","modelid":"<modelId>","data":"<base64-ModelInferRequest>"}'

# Вторая половина (тот же id)
curl -k -X POST "https://<tas-host>/consumer/kserve/v2" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"<prediction-id>","kind":"response","modelid":"<modelId>","data":"<base64-ModelInferResponse>"}'

Метрики дрейфа, у которых referenceTag установлен в TRAINING, сравнивают это эталонное подмножество (из /data/upload) с органическими строками, собранными через этот путь потребителя. GET /info/tags может вывести теги, такие как TRAINING и немаркированную/органическую сторону живого потока.

#Column name mapping (POST /info/names)

После загрузки обучающих/эталонных данных через /data/upload и живого инференса через /consumer/kserve/v2, TAS может сообщить, что было записано, и сопоставить записанные имена столбцов входов/выходов с человекочитаемыми именами через POST /info/names.

Пример:

curl -k -X POST "https://<tas-host>/info/names" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "modelId": "demo-model",
  "inputMapping": {
    "credit_inputs-0": "Возраст",
    "credit_inputs-1": "Кредитный рейтинг",
    "credit_inputs-2": "Образование",
    "credit_inputs-3": "Занятость",
    "gender": "Пол"
  },
  "outputMapping": {
    "predict-0-0": "Вероятность одобрения",
    "approved-0": "Одобрено"
  }
}'

#Data drift metrics

Метрики дрейфа данных сравнивают эталонное подмножество (например, строки с тегом TRAINING из POST /data/upload) с текущими производственными данными (обычно загружаемыми через POST /consumer/kserve/v2). Регистрация, список и удаление выполняются по тому же шаблону запросов/ответов, что и другие запланированные метрики.

#Drift metric types

GET /metrics/drift/<name>/definition возвращает человекочитаемую документацию по каждой метрике.

#Register scheduled drift metrics

Используйте POST /metrics/drift/<metricName>/request с JSON телом. Общие поля:

• modelId: идентификатор набора данных (должен совпадать с загрузками / modelid в consumer).
• requestName: уникальное имя для этой запланированной задачи.
• metricName: должно совпадать с сегментом пути (kstest, meanshift, approxkstest или fouriermmd).
• batchSize: количество записей инференса, включаемых в каждое вычисление.
• referenceTag: тег эталонного подмножества (обычно TRAINING).
• fitColumns: имена входных столбцов для оценки (записанные имена полей, например имена тензоров до сопоставления через POST /info/names).

KSTest — пример:

curl -k -X POST "https://<tas-host>/metrics/drift/kstest/request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "modelId": "<modelId>",
  "requestName": "<requestName>",
  "metricName": "kstest",
  "batchSize": 20,
  "referenceTag": "TRAINING",
  "fitColumns": ["credit_inputs-0", "credit_inputs-1"]
}'

MeanShift — пример:

curl -k -X POST "https://<tas-host>/metrics/drift/meanshift/request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "modelId": "<modelId>",
  "requestName": "<requestName>",
  "metricName": "meanshift",
  "batchSize": 20,
  "referenceTag": "TRAINING",
  "fitColumns": ["credit_inputs-0", "credit_inputs-1", "credit_inputs-2", "credit_inputs-3"]
}'

ApproxKSTest — добавляет thresholdDelta и epsilon (см. GET /metrics/drift/approxkstest/definition для семантики):

curl -k -X POST "https://<tas-host>/metrics/drift/approxkstest/request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "modelId": "<modelId>",
  "requestName": "<requestName>",
  "metricName": "approxkstest",
  "batchSize": 20,
  "thresholdDelta": 0.05,
  "referenceTag": "TRAINING",
  "fitColumns": ["credit_inputs-0", "credit_inputs-1"],
  "epsilon": 0.01
}'

FourierMMD — добавляет thresholdDelta, gamma и объект parameters (см. GET /metrics/drift/fouriermmd/definition):

curl -k -X POST "https://<tas-host>/metrics/drift/fouriermmd/request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "modelId": "<modelId>",
  "requestName": "<requestName>",
  "metricName": "fouriermmd",
  "batchSize": 20,
  "thresholdDelta": 0.05,
  "referenceTag": "TRAINING",
  "fitColumns": ["credit_inputs-0", "credit_inputs-1"],
  "gamma": 1.0,
  "parameters": { "nWindow": 10, "nTest": 10, "nMode": 50, "randomSeed": 0, "sig": 1.0, "deltaStat": false, "epsilon": 0.01 }
}'

#One-shot drift requests

Для однократного запуска (не запланированного) POST /metrics/drift/kstest и POST /metrics/drift/meanshift принимают тот же формат JSON тела, что и регистрация, но без суффикса /request в пути.

#List and delete scheduled drift jobs

Список запланированных задач:

curl -k -H "Authorization: Bearer $TOKEN" \
  "https://<tas-host>/metrics/drift/kstest/requests"

Остановить задачу по requestId из ответа списка:

curl -k -X DELETE "https://<tas-host>/metrics/drift/kstest/request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "<requestId-uuid>"
}'

Замените kstest в пути на meanshift, approxkstest или fouriermmd для других типов дрейфа. GET /metrics/all/requests выводит все запланированные метрики по категориям.

#Prometheus metrics (drift)

Результаты запланированных метрик дрейфа публикуются как Micrometer gauges на GET /q/metrics, например:

• KSTest: trustyai_kstest
• MeanShift: trustyai_meanshift
• ApproxKSTest: trustyai_approxkstest
• FourierMMD: trustyai_fouriermmd

Каждая серия дрейфа содержит метки, идентифицирующие запланированную задачу и измеряемый параметр. Типичные семантические метки на trustyai_kstest / trustyai_meanshift / trustyai_approxkstest / trustyai_fouriermmd включают:

Scrape / target метки (имена зависят от кластера и настройки ServiceMonitor) часто включают namespace, pod, service, job и instance. Фактические значения для развертывания следует получать из Prometheus (например, имена меток на trustyai_kstest в UI метрик или через label_values()), а не копировать из документации — специфичные для среды идентификаторы и адреса меняются в каждом кластере.

Пример PromQL (фильтрация по одной модели и имени запроса):

trustyai_kstest{model="<modelId>", requestName="<requestName>"}

Чтобы отфильтровать по одному столбцу или признаку, добавьте матчинг по subcategory, если эта метка присутствует.

#Bias metrics

В этом разделе описывается мониторинг смещения (метрики групповой справедливости, такие как SPD и DIR) через HTTP API TAS (POST / GET / DELETE на /metrics/group/fairness/...).

#SPD and DIR

TAS предоставляет две связанные метрики групповой справедливости по одному и тому же защищённому атрибуту и результату:

Обе метрики используют одинаковые поля запроса (protectedAttribute, outcomeName, favorableOutcome и т.д.). HTTP путь и metricName различают SPD (spd) и DIR (dir).

#Register scheduled bias metrics

Создайте периодический запрос метрики смещения для развернутого набора данных модели, вызвав:

• POST /metrics/group/fairness/spd/request (Statistical Parity Difference, SPD)
• POST /metrics/group/fairness/dir/request (Disparate Impact Ratio, DIR)

Пример (SPD):

curl -k -X POST "https://<tas-host>/metrics/group/fairness/spd/request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "<modelId>",
    "requestName": "<requestName>",
    "metricName": "spd",
    "batchSize": 20,
    "protectedAttribute": "<protectedAttribute>",
    "privilegedAttribute": <privilegedValue>,
    "unprivilegedAttribute": <unprivilegedValue>,
    "outcomeName": "<outcomeName>",
    "favorableOutcome": <favorableOutcome>
  }'

Поля запроса SPD:

• modelId: идентификатор набора данных модели, для которого вычисляется метрика (должен совпадать с набором/моделью, используемой в загрузках).
• requestName: уникальное имя для этого запланированного запроса метрики (используется для различения периодических задач).
• metricName: имя типа метрики; для этого эндпоинта используйте spd.
• batchSize: количество записей инференса, включаемых при вычислении запланированной метрики.
• protectedAttribute: признак (после сопоставления имён, если используется), определяющий сравниваемые группы.
• privilegedAttribute: значение protectedAttribute, представляющее привилегированную группу.
• unprivilegedAttribute: значение protectedAttribute, представляющее непривилегированную группу.
• outcomeName: поле результата, оцениваемое на справедливость (например, исход классификации).
• favorableOutcome: значение outcomeName, считающееся благоприятным исходом.

Для DIR используйте тот же JSON с "metricName": "dir" и вызовите POST /metrics/group/fairness/dir/request. GET /metrics/group/fairness/dir/definition описывает метрику текстово.

#List and delete scheduled bias jobs

Чтобы остановить периодический расчёт, выведите список задач, затем отправьте requestId из ответа на соответствующий URL удаления:

Пример (SPD):

curl -k -H "Authorization: Bearer $TOKEN" \
  "https://<tas-host>/metrics/group/fairness/spd/requests"

curl -k -X DELETE "https://<tas-host>/metrics/group/fairness/spd/request" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "<requestId-uuid>"
  }'

Используйте тот же JSON с requestId для URL удаления .../dir/request для задач DIR.

#Prometheus metrics (bias)

TAS экспонирует метрики Prometheus на /q/metrics. TrustyAI Operator создаёт ServiceMonitor, который сохраняет метрики, связанные со смещением (по умолчанию серии, соответствующие trustyai_(spd|dir).*).

Базовые имена метрик:

• SPD (Statistical Parity Difference): trustyai_spd
• DIR (Disparate Impact Ratio): trustyai_dir

Каждая серия содержит метки, идентифицирующие запланированный расчёт и его конфигурацию справедливости. Типичные семантические метки на trustyai_spd / trustyai_dir включают:

Scrape / target метки (имена зависят от кластера и настройки ServiceMonitor) часто включают namespace, pod, service, job и instance.

Пример: выбрать SPD для одной модели и одного имени запланированного запроса:

trustyai_spd{model="demo-credit-model-1774142686-91294", requestName="demo-spd-1774142686-91294"}

Пример: последнее значение за окно (согласуйте интервал с интервалом опроса):

max_over_time(trustyai_spd{model="<modelId>", requestName="<requestName>"}[15m])

Аналогичные фильтры меток применимы к trustyai_dir, когда зарегистрирована запланированная задача DIR.