Inicio rápido: Categorías personalizadas (modo estándar) (versión preliminar)

Artículo
11/03/2024

Siga esta guía para usar la API de REST de categorías personalizadas de seguridad de contenido de Azure AI (estándar) para crear sus propias categorías de contenido para su caso de uso y entrenar la seguridad del contenido de Azure AI para detectarlos en contenido de texto nuevo.

Para obtener más información sobre las categorías personalizadas, consulte la Página de concepto categorías personalizadas. Para conocer los límites de entrada de la API, consulte la sección Requisitos de entrada de la Información general.

Importante

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

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.

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. En esta guía, puede usar datos de ejemplo. El archivo de anotaciones proporcionado contiene indicaciones de texto sobre consejos de supervivencia en situaciones de acampada o en la naturaleza. El modelo entrenado aprenderá a detectar este tipo de contenido en nuevos datos de texto.

Sugerencia

Para obtener sugerencias sobre cómo crear su propio conjunto de datos, consulte la Guía paso a paso.

Descargue el archivo de datos de texto de ejemplo del repositorio de GitHub.
Cargue el archivo .jsonl en el contenedor de blobs de la cuenta de Azure Storage. A continuación, copie la dirección URL del blob en una ubicación temporal para su uso posterior.

Importante

La cuenta de almacenamiento del usuario se configura como una cuenta de espacio de nombres jerárquico, que no es compatible con categorías personalizadas. Intente usar una cuenta de almacenamiento normal en su lugar. Por ejemplo, la dirección URL del blob no se puede dividir en dos capas, como example/example1/, y solo debe tener una capa. Para más información, consulte la documentación: Espacio de nombres jerárquico de Azure Data Lake Storage: Azure Storage.

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 Seguridad del contenido de Azure AI y asigne el rol de Colaborador/propietario de datos de Storage Blob a la identidad:

Importante

Los roles Colaborador de datos de Storage Blob o Propietario de datos de Storage Blob son los únicos que permitirán continuar.

Habilite la identidad administrada para la instancia de Azure AI Content Safety.
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

cURL
Python

En el comando siguiente, 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-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
            \"categoryName\": \"survival-advice\",
            \"definition\": \"text prompts about survival advice in camping/wilderness situations\",
            \"sampleBlobUrl\": \"https://<your-azure-storage-url>/example-container/survival-advice.jsonl\"
        }"

Sugerencia

Cada vez que cambie el nombre de categoría, la definición o los ejemplos, se creará una nueva versión. Puede usar el número de versión para realizar el seguimiento hasta las versiones anteriores. Recuerde este número de versión, ya que será necesario en la dirección URL de las categorías personalizadas de entrenamiento - paso siguiente.

Solicitud API

Campo	Descripción	Valor de ejemplo
`categoryName`	Nombre de la categoría o tema al que se relaciona la solicitud.	consejos de supervivencia
`definition`	Una breve descripción del tipo de contenido de la categoría.	texto acerca de consejos de supervivencia en situaciones de acampada o en la naturaleza
`sampleBlobUrl`	Dirección URL para acceder a un archivo JSONL de muestra que contiene ejemplos de datos para la categoría.	Vínculo

Respuesta de la API

Campo	Descripción	Valor de ejemplo
`categoryName`	Nombre de la categoría o tema al que se relaciona la respuesta.	consejos de supervivencia
`definition`	Una breve descripción del tipo de contenido de la categoría.	texto acerca de consejos de supervivencia en situaciones de acampada o en la naturaleza
`sampleBlobUrl`	Dirección URL para acceder a un archivo JSONL de muestra que contiene ejemplos de datos para la categoría.	Vínculo
`sampleBlobSnapshotUrl`	Dirección URL de instantánea del archivo JSONL de muestra, que proporciona acceso a una versión específica de los datos.	Dirección URL de instantánea
`version`	Número de versión de los datos de categoría.	1
`createdTime`	Marca de tiempo cuando se crearon los datos de categoría.	2024-10-28T22:06:59.4626988Z
`status`	Estado actual del procesamiento de datos de categoría.	Correcto

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

Reemplace <your_api_key> y <your_endpoint> por sus propios valores y, además, anexe el número de versión en la dirección URL que obtuvo del último paso. 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. Después de recibir la respuesta, almacene el id. de operación (denominado id) en una ubicación temporal. Este id. será necesario para recuperar el estado de compilación mediante la API Obtener estado en la sección siguiente.

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

Respuesta de la API

Campo	Descripción	Valor de ejemplo
`operation id`	Identificador único para recuperar el estado de compilación	b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxx
`status`	Estado actual de la solicitud	Correcto

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-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

Respuesta de la API

Campo	Descripción	Valor de ejemplo
`operation id`	Identificador único para recuperar el estado de compilación	b6c69dc1-2338-484e-855b-xxxxxxxxxxxx
`status`	Estado actual de la solicitud	Correcto

Analizar texto con una categoría personalizada

Ejecute el siguiente comando para analizar el texto con la categoría personalizada. Reemplace <your_api_key> y <your_endpoint> con sus propios valores.

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

Solicitud API

Campo	Descripción
`text`	Contenido de texto o mensaje destinado a la detección de categorías
`categoryName`	Nombre de la categoría en la que se va a detectar el texto
`version`	Número de versión de la categoría

Respuesta de la API

Campo	Descripción	Valor de ejemplo
`customCategoryAnalysis`	Objeto que contiene el resultado de análisis de la categoría.	—
`detected`	Indica si se detectó la categoría especificada.	false

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'
}

Creación de una 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-09-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 = "survival-advice"
definition = "text prompts about survival advice in camping/wilderness situations"
sample_blob_url = "https://<your-azure-storage-url>/example-container/survival-advice.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. 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. Después de recibir la respuesta, asegúrese de almacenar el id. de operación (denominado id) en algún lugar como su cuaderno. Este id. será necesario para recuperar el estado de compilación mediante la función "get_build_status" en la sección siguiente.

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

# Replace the parameters with your own values
category_name = "survival-advice"
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-09-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-09-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 = "survival-advice"
version = 1

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

Otras operaciones de categorías 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
Python

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-09-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

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-09-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-09-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

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-09-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)

def list_categories_latest_versions():
    url = f"{ENDPOINT}/contentsafety/text/categories?api-version=2024-09-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-09-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)

Compartir a través de

Inicio rápido: Categorías personalizadas (modo estándar) (versión preliminar)

Requisitos previos

Preparar los datos de entrenamiento

Conceder acceso de almacenamiento

Cree y entrene una categoría personalizada

Crear una nueva versión de categoría

Solicitud API

Respuesta de la API

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

Respuesta de la API

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

Respuesta de la API

Analizar texto con una categoría personalizada

Solicitud API

Respuesta de la API

Creación de una categoría

Iniciar el proceso de compilación de categoría

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

Analizar texto con una categoría personalizada

Otras operaciones de categorías personalizadas

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

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

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

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

Comentarios

Recursos adicionales

Compartir a través de

Inicio rápido: Categorías personalizadas (modo estándar) (versión preliminar)

Requisitos previos

Preparar los datos de entrenamiento

Conceder acceso de almacenamiento

Cree y entrene una categoría personalizada

Crear una nueva versión de categoría

Solicitud API

Respuesta de la API

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

Respuesta de la API

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

Respuesta de la API

Analizar texto con una categoría personalizada

Solicitud API

Respuesta de la API

Otras operaciones de categorías personalizadas

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

Enumerar categorías de sus versiones más recientes

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

Contenido relacionado

Comentarios

Recursos adicionales