#AI Guardrails для безопасности LLM

TrustyAI Guardrails Orchestrator запускает детекторы на входных и выходных данных LLM для фильтрации или пометки контента. Он основан на open-source проекте FMS-Guardrails. TrustyAI Operator предоставляет CRD GuardrailsOrchestrator для его развертывания и управления.

В этом документе рассматривается только развертывание с помощью AutoConfig и встроенный детектор на основе regex.

#Предварительные требования

• Установлен TrustyAI Operator (см. Install TrustyAI).
• LLM развернут как InferenceService в целевом namespace.

#Развертывание с AutoConfig

С AutoConfig оператор генерирует конфигурацию оркестратора и gateway из ресурсов в namespace; для базовой настройки не требуются ручные ConfigMap.

Создайте кастомный ресурс GuardrailsOrchestrator с включённым autoConfig, встроенным детектором и gateway:

apiVersion: trustyai.opendatahub.io/v1alpha1
kind: GuardrailsOrchestrator
metadata:
  name: guardrails-orchestrator
  namespace: <your-namespace>
  # Optional: enable auth for routes (Bearer token required)
  annotations:
    security.opendatahub.io/enable-auth: "false"
spec:
  autoConfig:
    inferenceServiceToGuardrail: <inference-service-name>
  enableBuiltInDetectors: true
  enableGuardrailsGateway: true
  replicas: 1

• inferenceServiceToGuardrail: имя InferenceService (LLM) для защиты; должно совпадать с развернутой моделью в том же namespace.
• enableBuiltInDetectors: при true добавляется встроенный детектор на основе regex в sidecar.
• enableGuardrailsGateway: при true gateway открывает предустановленные маршруты (например, /all/v1/chat/completions).

#Статус ресурса

Ресурс имеет подресурс status. status.phase может принимать значения Progressing, Ready или Error. При использовании AutoConfig status.autoConfigState содержит имена сгенерированных ConfigMap (generatedConfigMap, generatedGatewayConfigMap), обнаруженные сервисы и message. Трафик следует направлять только после status.phase == Ready и готовности соответствующего Deployment.

Оператор создаёт ConfigMap оркестратора и ConfigMap gateway с именем <orchestrator-name>-gateway-auto-config. Встроенный детектор регистрируется как built-in-detector.

#Встроенный детектор на основе regex

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

Конфигурация gateway по умолчанию использует заглушку regex ($^). Чтобы включить конкретный алгоритм (например, email), отредактируйте ConfigMap и установите detector_params.regex в имя алгоритма (например, - email).

#Структура ConfigMap gateway

Имя ConfigMap: <orchestrator-name>-gateway-auto-config. Пример:

apiVersion: v1
kind: ConfigMap
metadata:
  name: guardrails-orchestrator-gateway-auto-config
  namespace: <your-namespace>
data:
  config.yaml: |
    orchestrator:
      host: "localhost"
      port: 8032
    detectors:
      - name: built-in-detector
        input: true
        output: true
        detector_params:
          regex:
            - $^                          # замените эту заглушку, например, на email
    routes:
      - name: all
        detectors:
          - built-in-detector
      - name: passthrough
        detectors:

Измените regex под built-in-detector на нужный алгоритм (например, - email). После обновления дождитесь готовности Deployment.

#Порты сервиса и справка по API

Guardrails Orchestrator доступен через Service с именем <orchestrator-name>-service. Номера портов зависят от того, включена ли аутентификация (аннотация security.opendatahub.io/enable-auth: "true" на GuardrailsOrchestrator).

#Порты и роли

При включённой аутентификации для портов gateway и built-in-detector требуется Bearer токен.

#Аутентификация (auth enabled)

Запросы к портам gateway или built-in-detector должны содержать:

Authorization: Bearer <token>

Токен должен быть валидным Kubernetes ServiceAccount токеном (или другим токеном, принимаемым прокси аутентификации кластера) для субъекта с доступом к сервису (например, services/proxy). Неавторизованные запросы получают 401/403.

Как получить токен

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

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

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

Клиенты внутри кластера могут использовать проецируемый volume с токеном ServiceAccount как Bearer токен.

#Справка по путям запросов

Другие маршруты gateway (например, /<preset-name>/v1/chat/completions) определены в ConfigMap gateway в разделе routes.

#Использование API и примеры

#Отдельное обнаружение (/api/v1/text/contents)

Запустите встроенный детектор regex на тексте без вызова LLM. Используйте порт built-in-detector (8080 или 8480). Тело запроса: contents (список строк), detector_params (например, regex: ["email"]).

Используйте адрес сервиса (внутри кластера: <orchestrator-name>-service.<your-namespace>.svc.cluster.local; снаружи: хост Ingress, если открыт) и порт built-in-detector (см. Порты и роли).

# Если включена аутентификация, задайте TOKEN. Используйте порт 8480 (auth) или 8080 (no auth).
curl -k -s -X POST "https://<service-address>:8480/api/v1/text/contents" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"contents":["hello, my email is test@example.com"],"detector_params":{"regex":["email"]}}'

Ответ: массив (по одному элементу на каждый элемент contents) массивов объектов обнаружения. Каждый объект содержит start, end, text, detection (например, EmailAddress), detection_type (например, pii) и score.

[
  [
    {
      "detection": "EmailAddress",
      "detection_type": "pii",
      "end": 35,
      "score": 1.0,
      "start": 19,
      "text": "test@example.com"
    }
  ]
]

#API оркестратора: детекторы на запрос (/api/v2/chat/completions-detection)

Используйте порт orchestrator (8032 или 8432), когда вызывающий должен выбирать, какие детекторы запускать для каждого запроса. Тело запроса: model, messages и опционально detectors (например, input / output с параметрами детектора).

Пример: запустить встроенный детектор с regex email на входных и выходных данных:

# Используйте порт оркестратора 8432 (auth) или 8032 (no auth).
curl -k -s -X POST "https://<service-address>:8432/api/v2/chat/completions-detection" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "model": "<inference-service-name>",
    "messages": [{"content": "my email is test@example.com", "role": "user"}],
    "detectors": {
      "input":  { "built-in-detector": { "regex": ["email"] } },
      "output": { "built-in-detector": { "regex": ["email"] } }
    }
  }'

Если детектор находит совпадение во входных данных (например, email), в ответе присутствуют detections и warnings, а choices пуст:

{
  "id": "0c339dbab9ab45f59e6bf052d4fd78c6",
  "object": "",
  "created": 1773118440,
  "model": "......",
  "choices": [],
  "usage": {
    "prompt_tokens": 0,
    "total_tokens": 0,
    "completion_tokens": 0
  },
  "detections": {
    "input": [
      {
        "message_index": 0,
        "results": [
          {
            "start": 12,
            "end": 28,
            "text": "test@example.com",
            "detection": "EmailAddress",
            "detection_type": "pii",
            "detector_id": "built-in-detector",
            "score": 1.0
          }
        ]
      }
    ]
  },
  "warnings": [
    {
      "type": "UNSUITABLE_INPUT",
      "message": "Unsuitable input detected. Please check the detected entities on your input and try again with the unsuitable input removed."
    }
  ]
}

Формат ответа совпадает с ответом gateway для чата: choices, detections, warnings. Если не нужны детекторы, опустите detectors для обычного чат-комплишена без детекции.

#API gateway: предустановленный пайплайн (/all/v1/chat/completions)

Используйте порт gateway (8090 или 8490) для чата с фиксированным пайплайном детекторов (определённым в ConfigMap gateway). Тело запроса: model, messages (OpenAI-стиль). Для выбора детекторов на запрос используйте API оркестратора.

Используйте адрес сервиса и порт gateway (см. Порты и роли).

# Используйте порт 8490 (auth) или 8090 (no auth).
curl -k -s -X POST "https://<service-address>:8490/all/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"model":"<inference-service-name>","messages":[{"content":"my email is test@example.com","role":"user"}]}'

Если входные/выходные данные проходят проверку: detections и warnings равны null, choices содержит ответ модели:

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "......",
        "role": "assistant"
      }
    }
  ],
  "created": 1773109415,
  "detections": null,
  "id": "chatcmpl-6d190200e68646bba140fa584ce5c301",
  "model": "......",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 28,
    "prompt_tokens": 30,
    "total_tokens": 58
  },
  "warnings": null
}

Если входные данные вызывают детекцию (например, PII): detections и warnings установлены, choices пуст:

{
  "choices": [],
  "created": 1773109609,
  "detections": {
    "input": [
      {
        "message_index": 0,
        "results": [
          {
            "detection": "EmailAddress",
            "detection_type": "pii",
            "detector_id": "built-in-detector",
            "end": 28,
            "score": 1.0,
            "start": 12,
            "text": "test@example.com"
          }
        ]
      }
    ],
    "output": null
  },
  "id": "24dcf55e14344b4bbc760944eb6c1630",
  "model": "......",
  "object": "",
  "usage": {
    "completion_tokens": 0,
    "prompt_tokens": 0,
    "total_tokens": 0
  },
  "warnings": [
    {
      "type": "UNSUITABLE_INPUT",
      "message": "Unsuitable input detected. Please check the detected entities on your input and try again with the unsuitable input removed."
    }
  ]
}