Usar la API de categorías personalizadas (estándar)

La API de categorías personalizadas (estándar) le permite crear sus propias categorías de contenido para su caso de uso y entrenar Seguridad del contenido de Azure AI para que las detecte en contenido nuevo.

Importante

Esta característica solo está disponible en determinadas regiones de Azure. Consulte Disponibilidad de la región.

Precaución

Los datos de ejemplo de esta guía pueden incluir contenido ofensivo. Se recomienda al usuario seguir su criterio.

Requisitos previos

• Una suscripción a Azure: cree una cuenta gratuita.
• Una vez que tenga la suscripción de Azure, cree un recurso de Content Safety en Azure Portal para obtener la clave y el punto de conexión. Escriba un nombre único para el recurso, seleccione la suscripción y seleccione un grupo de recursos, región admitiday plan de tarifa admitido. Seleccione Crear.
  • El recurso tarda unos minutos en implementarse. Cuando termine, seleccione Ir al recurso. En el panel de la izquierda, en Administración de recursos, seleccione Clave y punto de conexión de la suscripción. Copiar el punto de conexión y cualquiera de los valores de clave en una ubicación temporal para su uso posterior.
• Cree también un contenedor de Azure Blob Storage donde mantendrá el archivo de anotación de entrenamiento.
• Uno de los siguientes instalados:
  • cURL para llamadas API de REST.
  • Python 3.x instalado

Preparar los datos de entrenamiento

Para entrenar una categoría personalizada, necesita datos de texto de ejemplo que representen la categoría que desea detectar. Siga estos pasos para preparar los datos de ejemplo:

1. Recopile o escriba los datos de ejemplo:

   • La calidad de los datos de ejemplo es importante para entrenar un modelo eficaz. Intente recopilar al menos 50 ejemplos positivos que representen fielmente el contenido que desea identificar. Estos ejemplos deben ser claros, variados y estar directamente relacionados con la definición de categoría.
   • No se necesitan ejemplos negativos, pero pueden mejorar la capacidad del modelo para distinguir el contenido relevante del irrelevante. Para mejorar el rendimiento, intente obtener 50 ejemplos que no estén relacionados con la definición del caso positivo. Deben ser variados, pero dentro del contexto del contenido que encontrará su modelo. Elija detenidamente los ejemplos negativos para asegurarse de que no se superponen accidentalmente con la categoría positiva.
   • Busque un equilibrio entre el número de ejemplos positivos y negativos. Un conjunto de datos desigual puede sesgar el modelo, haciendo que favorezca un tipo de clasificación en detrimento de otro, lo que puede dar lugar a una mayor tasa de falsos positivos o negativos.

2. Use un editor de texto para dar formato a los datos en un archivo .jsonl. A continuación se muestra un ejemplo del formato adecuado. Los ejemplos de categorías deben establecer isPositive en true. Los ejemplos negativos son opcionales, pero pueden mejorar el rendimiento:

   {"text": "This is the 1st sample.", "isPositive": true}
   {"text": "This is the 2nd sample.", "isPositive": true}
   {"text": "This is the 3rd sample (negative).", "isPositive": false}
   

3. Cargue el archivo .jsonl en un contenedor de blobs de la cuenta de Azure Storage. Copie la dirección URL del blob en una ubicación temporal para su uso posterior.

Conceder acceso de almacenamiento

A continuación, debe conceder acceso a los recursos de Content Safety para leer desde el recurso de Azure Storage. Habilite la identidad administrada asignada por el sistema para la instancia de Azure AI Content Safety y asigne el rol de Colaborador/propietario/lector de datos de Blob de almacenamiento a la identidad:

1. Habilite la identidad administrada para la instancia de Azure AI Content Safety.

   

2. Asigne el rol colaborador o propietario de datos de almacenamiento blob a la identidad administrada. Los roles resaltados a continuación deberían funcionar.

   

   

   

Cree y entrene una categoría personalizada

Importante

Dejar tiempo suficiente para el entrenamiento del modelo

La ejecución de un extremo a otro del entrenamiento de categorías personalizadas puede llevar entre cinco y diez horas. Planificar la canalización de moderación en consecuencia y asignar tiempo para:

• Recopilar y preparar los datos de ejemplo
• El proceso de entrenamiento
• Evaluación y ajustes del modelo

cURL

En los comandos siguientes, reemplace <your_api_key>, <your_endpoint> y otros parámetros necesarios por sus propios valores. A continuación, escriba cada comando en una ventana de terminal y ejecútelo.

Crear una nueva versión de categoría

curl -X PUT "<your_endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
        \"categoryName\": \"<your_category_name>\",
        \"definition\": \"<your_category_definition>\",
        \"sampleBlobUrl\": \"https://example.blob.core.windows.net/example-container/sample.jsonl\"
     }"

Iniciar el proceso de compilación de categoría:

Después de recibir la respuesta, almacene el id. de operación (denominado id) en una ubicación temporal. Necesita este identificador para recuperar el estado de compilación mediante la API Obtener estado.

curl -X POST "<your_endpoint>/contentsafety/text/categories/<your_category_name>:build?api-version=2024-02-15-preview&version={version}" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Obtener el estado de compilación de la categoría:

Para recuperar el estado, use el id obtenido de la respuesta anterior de la API y colóquelo en la ruta de acceso de la API siguiente.

curl -X GET "<your_endpoint>/contentsafety/text/categories/operations/<id>?api-version=2024-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Analizar texto con una categoría personalizada

Ejecute el siguiente comando para analizar el texto con la categoría personalizada. Reemplace <your_category_name> por su propio valor:

curl -X POST "<your_endpoint>/contentsafety/text:analyzeCustomCategory?api-version=2024-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
        \"text\": \"Example text to analyze\",
        \"categoryName\": \"<your_category_name>\", 
        \"version\": 1
        }"

Python

En primer lugar, debe instalar la biblioteca de Python necesaria:

pip install requests

A continuación, abra un nuevo script de Python y defina las variables necesarias con sus propios detalles de recursos de Azure:

import requests

API_KEY = '<your_api_key>'
ENDPOINT = '<your_endpoint>'

headers = {
    'Ocp-Apim-Subscription-Key': API_KEY,
    'Content-Type': 'application/json'
}

Crear una nueva versión de categoría

Puede crear una nueva categoría con el nombre de categoría, la definición y sample_blob_url, y obtendrá el número de versión generado automáticamente de esta categoría.

def create_new_category_version(category_name, definition, sample_blob_url):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-02-15-preview"
    data = {
        "categoryName": category_name,
        "definition": definition,
        "sampleBlobUrl": sample_blob_url
    }
    response = requests.put(url, headers=headers, json=data)
    return response.json()

# Replace the parameters with your own values
category_name = "DrugAbuse"
definition = "This category is related to Drug Abuse."
sample_blob_url = "https://<your-azure-storage-url>/example-container/drugsample.jsonl"

result = create_new_category_version(category_name, definition, sample_blob_url)
print(result)

Iniciar el proceso de compilación de categoría

Puede iniciar el proceso de compilación de categoría con el nombre de categoría y el número de versión.

def trigger_category_build_process(category_name, version):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}:build?api-version=2024-02-15-preview&version={version}"
    response = requests.post(url, headers=headers)
    return response.status_code

# Replace the parameters with your own values
category_name = "<your_category_name>"
version = 1

result = trigger_category_build_process(category_name, version)
print(result)

Obtener el estado de compilación de la categoría:

Para recuperar el estado, utilice el id obtenido en la respuesta anterior.

def get_build_status(id):
    url = f"{ENDPOINT}/contentsafety/text/categories/operations/{id}?api-version=2024-02-15-preview"
    response = requests.get(url, headers=headers)
    return response.status_code

# Replace the parameter with your own value
id = "your-operation-id"

result = get_build_status(id)
print(result)

Analizar texto con una categoría personalizada

Debe especificar el nombre de la categoría y el número de versión (opcional; el servicio usa el más reciente de forma predeterminada) durante la inferencia. Puede especificar varias categorías si ya están definidas.

def analyze_text_with_customized_category(text, category_name, version):
    url = f"{ENDPOINT}/contentsafety/text:analyzeCustomCategory?api-version=2024-02-15-preview"
    data = {
        "text": text,
        "categoryName": category_name,
        "version": version
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Replace the parameters with your own values
text = "Example text to analyze"
category_name = "<your_category_name>"
version = 1

result = analyze_text_with_customized_category(text, category_name, version)
print(result)

Otras operaciones de categoría personalizadas

Recuerde reemplazar los marcadores de posición siguientes por los valores reales de la clave de API, el punto de conexión y el contenido específico (nombre de categoría, definición, etc.). Estos ejemplos le ayudan a administrar las categorías personalizadas de su cuenta.

cURL

Obtener una categoría personalizada o una versión específica de ella

Reemplazar los marcadores de posición por sus propios valores y ejecutar el siguiente comando en una ventana de terminal:

curl -X GET "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Enumerar categorías de sus versiones más recientes

Reemplazar los marcadores de posición por sus propios valores y ejecutar el siguiente comando en una ventana de terminal:

curl -X GET "<endpoint>/contentsafety/text/categories?api-version=2024-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Eliminar una categoría personalizada o una versión específica de ella

Reemplazar los marcadores de posición por sus propios valores y ejecutar el siguiente comando en una ventana de terminal:

curl -X DELETE "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Python

En primer lugar, asegúrese de que ha instalado la biblioteca de Python necesaria:

pip install requests

A continuación, configure las configuraciones necesarias con sus propios detalles de recursos de IA:

import requests

API_KEY = '<your_api_key>'
ENDPOINT = '<your_endpoint>'

headers = {
    'Ocp-Apim-Subscription-Key': API_KEY,
    'Content-Type': 'application/json'
}

Obtener una categoría personalizada o una versión específica de ella

Reemplazar los marcadores de posición por sus propios valores y ejecutar el código siguiente en el script de Python:

def get_customized_category(category_name, version=None):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-02-15-preview"
    if version:
        url += f"&version={version}"
    
    response = requests.get(url, headers=headers)
    return response.json()

# Replace the parameters with your own values
category_name = "DrugAbuse"
version = 1

result = get_customized_category(category_name, version)
print(result)

Enumerar categorías de sus versiones más recientes

def list_categories_latest_versions():
    url = f"{ENDPOINT}/contentsafety/text/categories?api-version=2024-02-15-preview"
    response = requests.get(url, headers=headers)
    return response.json()

result = list_categories_latest_versions()
print(result)

Eliminar una categoría personalizada o una versión específica de ella

Reemplazar los marcadores de posición por sus propios valores y ejecutar el código siguiente en el script de Python:

def delete_customized_category(category_name, version=None):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-02-15-preview"
    if version:
        url += f"&version={version}"
    
    response = requests.delete(url, headers=headers)
    return response.status_code

# Replace the parameters with your own values
category_name = "<your_category_name>"
version = 1

result = delete_customized_category(category_name, version)
print(result)

Contenido relacionado

• Conceptos de categorías personalizadas
• Moderar contenido con seguridad de contenido