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

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

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

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

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

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

При использовании AutoConfig оператор генерирует конфигурацию orchestrator и 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 detector.
• 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 orchestrator и ConfigMap gateway с именем <orchestrator-name>-gateway-auto-config. Встроенный детектор регистрируется как built-in-detector.

#Встроенный regex 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:
            - $^                          # change this placeholder, e.g. 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 token.

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

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

Authorization: Bearer <token>

Токен должен быть действительным токеном Kubernetes ServiceAccount (или другим токеном, принимаемым auth proxy кластера) для субъекта с доступом к service (например, 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 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>.

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

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

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

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

#Автономное обнаружение (/api/v1/text/contents)

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

Используйте адрес service (изнутри кластера: <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"]}}'

Ответ: массив массивов объектов обнаружения (по одному элементу на каждый item в 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 orchestrator: детекторы для каждого запроса (/api/v2/chat/completions-detection)

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

Пример: запуск встроенного детектора с regex email для input и output:

# 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: предустановленный пайплайн (/all/v1/chat/completions)

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

Используйте адрес service и порт 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"}]}'

Если input/output проходят проверку: 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
}

Когда input вызывает обнаружение (например, 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."
    }
  ]
}