Imágenes de pantalla

Model Armor examina las imágenes independientes y las imágenes incorporadas en documentos de texto enriquecido compatibles en las instrucciones y respuestas para ayudar a proteger tus aplicaciones de IA generativa de los riesgos incorporados en las imágenes.

Model Armor filtra las imágenes con los siguientes métodos:

Especificaciones y limitaciones

Ten en cuenta las siguientes especificaciones y limitaciones cuando uses Model Armor para filtrar imágenes:

  • Formatos de imagen admitidos: Model Armor analiza imágenes independientes en formatos JPEG, PNG y BMP. También extrae y analiza las imágenes incorporadas de los archivos de texto enriquecido compatibles.
  • Límites de tamaño: Cada imagen independiente debe tener un tamaño de 4 MB o menos. Los archivos de texto enriquecido deben tener un tamaño total de 4 MB o menos, y contener un máximo de 5 imágenes incorporadas. Si se supera cualquiera de estos límites, Model Armor omitirá el análisis de todo el archivo. Para obtener más información, consulta Límite del sistema para el tamaño de los archivos y Imágenes incorporadas en la pantalla en los documentos.
  • Instrucciones independientes: Cuando llamas a los métodos SanitizeUserPrompt y SanitizeModelResponse con imágenes independientes, Model Armor verifica una sola imagen por solicitud. No se admite la detección de varias imágenes independientes en una sola solicitud. Además, Model Armor no admite instrucciones independientes que combinen texto e imágenes en una sola solicitud. Sin embargo, puedes revisar documentos de texto enriquecido que contengan texto e imágenes habilitando las modalidades de texto y de imagen.
  • Desidentificación: Cuando configuras una plantilla de desidentificación de Sensitive Data Protection, Model Armor oculta texto o imágenes independientes, no ambos. La desidentificación no se admite para los documentos de texto enriquecido cuando se selecciona la modalidad de imagen (MODALITY_IMAGE). Para obtener más información, consulta Oculta datos sensibles en imágenes independientes y Revisa imágenes incorporadas en documentos.
  • Transmisión: Los métodos de transmisión de Model Armor solo admiten entradas de texto y no admiten imágenes ni archivos.
  • Integraciones compatibles: Puedes filtrar imágenes llamando a la API de REST de Model Armor directamente o a través de la integración de Gemini Enterprise. Todas las demás integraciones de Model Armor analizan y limpian solo texto. Para obtener más información, consulta Modalidades compatibles.
  • Disponibilidad regional: La detección de imágenes solo se admite en multirregiones específicas. Si envías una instrucción que contiene una imagen a un extremo en el que Model Armor no admite el filtrado de imágenes, el campo invocationResult de la respuesta indica FAILURE. Para obtener una lista de las ubicaciones que admiten la detección de imágenes, consulta Funciones compatibles por región.

Cálculo de tokens y precios de las imágenes

Model Armor usa un modelo de precios unificado basado en tokens en el que los tokens de imagen se facturan con la misma tarifa que los tokens de texto.

No se te facturará cuando Model Armor rechace o ignore una entrada antes del procesamiento del filtro, como entradas vacías o archivos e imágenes que superen los límites de tamaño de archivo o de imagen incorporada. Sin embargo, si una entrada pasa la validación inicial, se te facturarán los tokens calculados, incluso en los siguientes casos:

  • Se omiten todos los detectores: Se omiten algunos o todos los filtros (detectores) configurados y se devuelve EXECUTION_SKIPPED (por ejemplo, cuando los detectores no pueden analizar una carga útil de imagen dentro del límite de 4 MB o cuando se omite un filtro para una modalidad).
  • Archivos que no son de imagen unidos con el tipo de datos de bytes IMAGE: Se envía un archivo que no es de imagen (como un documento ZIP, CSV o de Microsoft Word) con byteDataType establecido en IMAGE (hasta 4 MB). Model Armor factura la solicitud con el cálculo de tokens de imagen independiente, aunque los filtros devuelvan EXECUTION_SKIPPED.

Model Armor calcula los tokens para imágenes y documentos según el tipo de entrada y las modalidades configuradas:

  • Imágenes independientes: Model Armor convierte cada imagen procesada (hasta 4 MB) en tokens con un recuento base de 5,000 tokens por imagen, más 1,000 tokens por megabyte (MB) de tamaño de imagen. Cuando calcula los tokens basados en el tamaño, Model Armor redondea el tamaño de la imagen al siguiente MB entero:

    Tokens por imagen = 5,000 + (1,000 × tamaño de la imagen en MB, redondeado al siguiente MB entero)

    El texto extraído de una imagen a través de OCR se incluye en el cálculo de tokens de imagen y no genera cargos por tokens de texto independientes.

  • Documentos de texto enriquecido: El cálculo de tokens depende de las modalidades configuradas en tu plantilla:

    • Modalidad de texto (MODALITY_TEXT): Model Armor calcula los tokens a partir del texto extraído del documento (alrededor de 4 caracteres por token). Las imágenes incorporadas no se extraen ni se facturan.
    • Modalidad de imagen (MODALITY_IMAGE): Model Armor calcula los tokens de forma individual para cada imagen incorporada procesada con la fórmula de tokens de imagen. No se factura el texto del documento.
    • Modalidades de texto e imagen (MODALITY_TEXT y MODALITY_IMAGE): Model Armor calcula el recuento total de tokens como la suma de los tokens del texto del documento extraído y los tokens de cada imagen incorporada procesada.

En la siguiente tabla, se muestran ejemplos de cómo Model Armor calcula los tokens para las imágenes procesadas:

Tamaño de la imagen Tamaño redondeado para el cálculo Cálculo de tokens Tokens totales
500 KB 1 MB 5,000 + (1 × 1,000) 6,000 tokens
1.9 MB 2 MB 5,000 + (2 × 1,000) 7,000 tokens
4 MB 4 MB 5,000 + (4 × 1,000) 9,000 tokens

Antes de comenzar

Antes de filtrar imágenes, completa los siguientes requisitos previos:

Crea o actualiza una plantilla con la modalidad de imagen habilitada

Cuando creas o actualizas una plantilla, selecciona la modalidad para incluir MODALITY_IMAGE (Imagen o Todo en la consola de Google Cloud , o "modalities": ["MODALITY_IMAGE", "MODALITY_TEXT"] en templateMetadata cuando usas la API de REST). Si no especificas una modalidad, dejas el campo modalities vacío o especificas solo MODALITY_TEXT, Model Armor analiza solo texto y devuelve EXECUTION_SKIPPED para los filtros que analizan la modalidad omitida.

Obtén los permisos necesarios

Asegúrate de tener los roles de Identity and Access Management necesarios para limpiar los mensajes y las respuestas (como roles/modelarmor.user) y, si usas el modo avanzado de Sensitive Data Protection en todos los proyectos, otorga los roles de DLP necesarios al agente de servicio de Model Armor. Para obtener instrucciones, consulta Obtén los permisos necesarios.

Cómo limpiar imágenes independientes

Para filtrar una imagen independiente en una instrucción del usuario o una respuesta del modelo, establece el campo byteDataType en IMAGE y proporciona la imagen codificada en Base64 en un formato compatible (JPEG, PNG o BMP) en el campo byteData.

Usa el siguiente comando para limpiar una instrucción que contiene una imagen:

curl -X POST \
    -d "$(jq -n \
    --arg data "$(base64 -w 0 -i IMAGE)" \
    '{userPromptData: {byteItem: {byteDataType: "IMAGE", byteData: $data}}}')" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto que contiene la plantilla.
  • LOCATION: Es la ubicación de la plantilla.
  • TEMPLATE_ID: Es el ID de una plantilla que está configurada para analizar imágenes (MODALITY_IMAGE).
  • IMAGE: Es la ruta de acceso al archivo de imagen en un formato compatible.

La respuesta es similar a lo que se muestra a continuación:

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "MATCH_FOUND",
          "confidenceLevel": "HIGH"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "MATCH_FOUND"
          }
        }
      }
    }
  }
}

Oculta datos sensibles en imágenes independientes

Cuando usas el modo avanzado de Sensitive Data Protection, Model Armor oculta los hallazgos sensibles en imágenes independientes si configuras tu plantilla de Model Armor con una plantilla de inspección de Sensitive Data Protection y una plantilla de desidentificación de Sensitive Data Protection. Asegúrate de configurar la redacción de imágenes en la plantilla de desidentificación. Para obtener más información sobre cómo configurar Sensitive Data Protection en Model Armor, consulta Establece la configuración de Sensitive Data Protection. Para obtener información sobre las limitaciones de desidentificación, consulta Especificaciones y limitaciones y Imágenes incorporadas en la pantalla en documentos.

En el siguiente ejemplo, se muestra la configuración del filtro con la ocultación de Sensitive Data Protection habilitada:

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate": "projects/PROJECT_ID/locations/LOCATION/inspectTemplates/INSPECT_TEMPLATE_ID",
        "deidentifyTemplate": "projects/PROJECT_ID/locations/LOCATION/deidentifyTemplates/DEIDENTIFY_TEMPLATE_ID"
      }
    }
  }
}

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto que contiene las plantillas de Sensitive Data Protection.
  • LOCATION: Es la ubicación de las plantillas.
  • INSPECT_TEMPLATE_ID: Es el ID de la plantilla de inspección.
  • DEIDENTIFY_TEMPLATE_ID: Es el ID de la plantilla de desidentificación.

Cuando limpias una imagen independiente con una plantilla que tiene habilitada la ocultación de imágenes, la respuesta incluye la imagen ocultada y las coordenadas del cuadro delimitador para cada hallazgo:

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "invocationResult": "SUCCESS",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "redactResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "MATCH_FOUND",
            "redactedImage": "[REDACTED_IMAGE]",
            "findings": [
              {
                "infoType": "EMAIL_ADDRESS",
                "likelihood": "LIKELY",
                "location": {
                  "contentLocations": [
                    {
                      "imageFindingLocation": {
                        "boundingBoxes": {
                          "top": 16,
                          "left": 121,
                          "width": 620,
                          "height": 90
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }
}

Analiza las imágenes incorporadas en los documentos

Cuando habilitas la modalidad de imagen (MODALITY_IMAGE) en tu plantilla y limpias un documento de texto enriquecido (PDF, WORD_DOCUMENT, EXCEL_DOCUMENT o POWERPOINT_DOCUMENT), Model Armor extrae y revisa automáticamente hasta 5 imágenes incorporadas en el documento. Si habilitas MODALITY_TEXT y MODALITY_IMAGE, Model Armor analiza el texto del documento y las imágenes incorporadas.

Ya sea que habilites solo MODALITY_IMAGE o MODALITY_IMAGE y MODALITY_TEXT, Model Armor omite el análisis de todo el documento, incluidos el texto y las imágenes incorporadas, sin análisis parcial. Devuelve EXECUTION_SKIPPED para todos los filtros configurados, incluida la inspección, y un filterMatchState general de NO_MATCH_FOUND en los siguientes casos:

  • El documento supera el límite de tamaño de archivo de 4 MB o el límite de 5 imágenes.
  • Se configura una plantilla de desidentificación de Sensitive Data Protection. Para inspeccionar documentos de texto enriquecido cuando la modalidad de imagen está habilitada, configura solo una plantilla de inspección sin una plantilla de desidentificación.

Para ver muestras de código que ilustran cómo enviar instrucciones basadas en archivos con REST y bibliotecas cliente, consulta Instrucciones basadas en archivos.

Inspección parcial de archivos

Model Armor devuelve un resultado parcial (invocationResult: PARTIAL) solo a nivel del filtro (detector) en todo el archivo, en lugar de por imagen:

  • Falla por imagen (se omite todo el archivo): Si algunas imágenes incorporadas en un archivo se analizan correctamente, pero una o más imágenes del archivo no se pueden extraer o analizar, Model Armor omite todo el archivo. Muestra executionState: EXECUTION_SKIPPED para todos los filtros configurados y un filterMatchState general de NO_MATCH_FOUND.
  • Falla a nivel del detector (resultado parcial): Si algunos filtros configurados se aplican correctamente en todo el archivo, mientras que uno o más filtros se omiten para todo el archivo (por ejemplo, debido a un tiempo de espera del detector), Model Armor devuelve un resultado parcial con los siguientes campos:
    • Resultado de la invocación: El campo invocationResult se establece en PARTIAL (en lugar de SUCCESS), lo que indica que se omitieron uno o más filtros configurados para el archivo, mientras que otros filtros completaron la inspección.
    • Estado de ejecución del filtro: Son los filtros que se omitieron para el informe de archivos executionState: EXECUTION_SKIPPED. Filtros que completaron la inspección en el informe de archivos executionState: EXECUTION_SUCCESS.
    • Estado de coincidencia: El campo filterMatchState refleja los hallazgos de los filtros que completaron la inspección. Si algún filtro completado detecta un incumplimiento, filterMatchState se establece en MATCH_FOUND. Si los filtros completados no detectan incumplimientos, filterMatchState se establece en NO_MATCH_FOUND.

Consideraciones de seguridad con la inspección parcial

Desde el punto de vista de la seguridad, un valor invocationResult de PARTIAL indica que uno o más filtros configurados no pudieron evaluar el archivo. Es posible que las posibles amenazas de seguridad o los incumplimientos de política a los que se dirigen los filtros omitidos sigan presentes en el archivo.

De forma predeterminada, si los filtros que completaron la inspección no detectan incumplimientos de política, filterMatchState es NO_MATCH_FOUND. Si tu aplicación requiere que todos los filtros configurados completen la inspección antes de permitir que las instrucciones lleguen a un modelo de IA, inspecciona el campo invocationResult en la respuesta. Si el valor es PARTIAL, configura la lógica de tu aplicación para que controle la solicitud según la tolerancia al riesgo de tu organización, como rechazar la instrucción o enrutarla para una revisión secundaria.

Ejemplo de respuesta de inspección parcial

En el siguiente ejemplo, se muestra una respuesta en la que se omitió el filtro de material de abuso sexual infantil (CSAM) para el archivo, mientras que otros filtros configurados completaron la inspección. Model Armor devuelve un invocationResult de PARTIAL, un estado EXECUTION_SKIPPED para el filtro de CSAM y EXECUTION_SUCCESS para los filtros restantes:

{
  "sanitizationResult": {
    "filterMatchState": "NO_MATCH_FOUND",
    "invocationResult": "PARTIAL",
    "filterResults": {
      "csam": {
        "csamFilterFilterResult": {
          "executionState": "EXECUTION_SKIPPED",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "pi_and_jailbreak": {
        "piAndJailbreakFilterResult": {
          "executionState": "EXECUTION_SUCCESS",
          "matchState": "NO_MATCH_FOUND"
        }
      },
      "sdp": {
        "sdpFilterResult": {
          "inspectResult": {
            "executionState": "EXECUTION_SUCCESS",
            "matchState": "NO_MATCH_FOUND"
          }
        }
      }
    }
  }
}

¿Qué sigue?