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

Оркестратор TrustyAI Guardrails запускает детекторы для входных и выходных данных LLM, чтобы фильтровать или помечать контент. Он основан на проекте с открытым исходным кодом 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), для которого применяется guardrail; должно совпадать с развернутой моделью в том же namespace.
• enableBuiltInDetectors: если true, добавляется sidecar встроенного regex-детектора.
• 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-детектор

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

Конфигурация gateway по умолчанию использует placeholder 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:
            - $^                          # change this placeholder, e.g. email
    routes:
      - name: all
        detectors:
          - built-in-detector
      - name: passthrough
        detectors:

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

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

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

#Порты и роли

Когда auth включена, для портов gateway и built-in-detector требуется Bearer token.

#Аутентификация (auth включена)

В запросы к портам gateway или built-in-detector необходимо включать:

Authorization: Bearer <token>

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

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

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

# Replace <your-namespace> and optionally the ServiceAccount name (e.g. guardrails-client)
kubectl create serviceaccount -n <your-namespace> guardrails-client
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 -n <your-namespace> guardrails-client

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

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

#Справочник путей запросов

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

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

#Проверка без вызова LLM (/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 host, если он доступен) и порт built-in-detector (см. Порты и роли).

# If auth is enabled, set TOKEN. Use port 8480 (auth) or 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 на входе и выходе:

# Use orchestrator port 8432 (auth) or 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."
    }
  ]
}

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

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

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

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

# Use port 8490 (auth) or 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."
    }
  ]
}