Utiliser l’API Catégories personnalisées (standard) (préversion)

L’API des catégories personnalisées (standard) vous permet de créer vos propres catégories de contenu pour votre cas d’utilisation et d’entraîner Azure AI Sécurité du Contenu 0 les détecter dans du nouveau contenu.

Important

Cette fonctionnalité est disponible uniquement dans certaines régions Azure. Consultez Disponibilité dans les régions.

Attention

Les exemples de données de ce guide peuvent contenir du contenu offensant. Ils s’adressent à des utilisateurs avertis.

Prérequis

• Un abonnement Azure - En créer un gratuitement
• Une fois que vous avez votre abonnement Azure, créez une ressource Content Safety dans le portail Azure pour obtenir votre clé et votre point de terminaison. Entrez un nom unique pour votre ressource, sélectionnez votre abonnement, puis sélectionnez un groupe de ressources, une région prise en charge et un niveau tarifaire pris en charge. Sélectionnez ensuite Créer.
  • Le déploiement de la ressource prend quelques minutes. Une fois qu’il est terminé, sélectionnez Accéder à la ressource. Dans le volet gauche, sous Gestion des ressources, sélectionnez Clé et point de terminaison de l’abonnement. Copiez le point de terminaison et l’une des valeurs clés sur un emplacement temporaire pour une utilisation ultérieure.
• Créez également un conteneur de Stockage Blob Azure dans lequel vous conservez votre fichier d’annotation d’entraînement.
• L'un des éléments suivants est installé :
  • cURL pour les appels d’API REST.
  • Python 3.x installé

Préparer vos données d’entraînement

Pour entraîner une catégorie personnalisée, vous avez besoin d’exemples de données de texte qui représentent la catégorie que vous souhaitez détecter. Suivez ces étapes pour préparer vos exemples de données :

1. Collectez ou écrivez vos exemples de données :

   • La qualité de vos exemples de données est importante pour entraîner un modèle efficace. Fixez-vous l’objectif de collecter au moins 50 exemples positifs qui représentent avec précision le contenu que vous souhaitez identifier. Ces exemples doivent être clairs, variés et directement liés à la définition de catégorie.
   • Les exemples négatifs ne sont pas obligatoires, mais ils peuvent améliorer la capacité du modèle à distinguer le contenu pertinent du contenu qui ne l’est pas. Pour améliorer les performances, fixez-vous l’objectif de 50 exemples qui ne sont pas liés à la définition positive du cas. Ceux-ci doivent être variées, mais toujours dans le contexte du contenu que votre modèle rencontrera. Choisissez soigneusement les exemples négatifs pour vous assurer qu’il n’y ait pas de chevauchement par inadvertance avec la catégorie positive.
   • Recherchez un équilibre entre le nombre d’exemples positifs et négatifs. Un jeu de données déséquilibré peut biaiser le modèle, et le pousser à favoriser un type de classification par rapport à un autre, ce qui peut entraîner un taux plus élevé de faux positifs ou négatifs.

2. Utilisez un éditeur de texte pour formater vos données dans un fichier .jsonl . Vous trouverez ci-dessous un exemple de format approprié. Les exemples de catégorie doivent définir isPositive sur true. Les exemples négatifs sont facultatifs, mais peuvent améliorer les performances :

   {"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. Chargez le fichier .jsonl dans un conteneur de Stockage Blob Azure. Copiez l’URL d’objet blob sur un emplacement temporaire pour une utilisation ultérieure.

Accorder l’accès au stockage

Ensuite, vous devez accorder à votre ressource Content Safety l’accès à la lecture à partir de la ressource Stockage Azure. Activez l’identité managée affectée par le système pour l’instance Azure AI Sécurité du Contenu et attribuez le rôle Contributeur aux données Blob du stockage/Propriétaire des données Blob du stockage à l’identité :

Important

Les rôles Contributeur aux données Blob du stockage et Propriétaire des données Blob du stockage sont les seuls rôles valides pour continuer.

1. Activez une identité managée pour l’instance Azure AI Content Safety.

   

2. Attribuez le rôle Contributeur/Propriétaire de données Blob de stockage à l’identité managée. Tous les rôles mis en évidence ci-dessous doivent fonctionner.

   

   

   

Créer et entraîner une catégorie personnalisée

Important

Laisser suffisamment de temps pour l’entraînement du modèle

L’exécution de bout en bout de l’entraînement des catégories personnalisées peut prendre entre cinq et dix heures. Planifiez votre pipeline de modération en conséquence et allouez du temps pour :

• Collecter et préparer vos exemples de données
• Commencer le processus d’entraînement
• Évaluation du modèle et ajustements

cURL

Dans les commandes ci-dessous, remplacez <your_api_key>, <your_endpoint> et d’autres paramètres nécessaires par vos propres valeurs. Entrez ensuite chaque commande dans une fenêtre de terminal et exécutez-la.

Créer une nouvelle version de catégorie

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\"
     }"

Démarrez le processus de génération de catégorie :

Après avoir reçu la réponse, stockez l’ID d’opération (appelé id) sur un emplacement temporaire. Vous avez besoin de cet ID pour récupérer l’état de build à l’aide de l’API Obtenir l’état .

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"

Obtenir l’état de la build de catégorie :

Pour récupérer l’état, utilisez l’élément id obtenu à partir de la réponse d’API précédente et placez-le dans le chemin d’accès de l’API ci-dessous.

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"

Analyser du texte avec une catégorie personnalisée

Exécutez la commande suivante pour analyser du texte avec votre catégorie personnalisée. Remplacez <your_category_name> par votre propre valeur :

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

Vous devez d’abord installer la bibliothèque Python requise :

pip install requests

Ensuite, ouvrez un nouveau script Python et définissez les variables nécessaires sur la base de vos propres détails de ressource Azure :

import requests

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

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

Créer une nouvelle version de catégorie

Vous pouvez créer une nouvelle catégorie avec le nom de catégorie, la définition et sample_blob_url, et vous obtiendrez le numéro de version généré automatiquement de cette catégorie.

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)

Démarrer le processus de génération de catégorie

Vous pouvez démarrer le processus de génération de catégorie avec le nom de la catégorie et le numéro de version.

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)

Obtenir l’état de la build de catégorie :

Pour récupérer l’état, utilisez l’élément id obtenu à partir de la réponse précédente.

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)

Analyser du texte avec une catégorie personnalisée

Vous devez spécifier le nom de la catégorie et le numéro de version (facultatif ; le service utilise la dernière par défaut) pendant l’inférence. Vous pouvez spécifier plusieurs catégories si elles sont déjà définies.

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)

Autres opérations de catégories personnalisées

N’oubliez pas de remplacer les espaces réservés ci-dessous par vos valeurs réelles pour la clé API, le point de terminaison et le contenu spécifique (nom de catégorie, définition, etc.). Ces exemples vous aident à gérer les catégories personnalisées dans votre compte.

cURL

Obtenir une catégorie personnalisée ou une version spécifique de celle-ci

Remplacez les espaces réservés par vos propres valeurs et exécutez la commande suivante dans une fenêtre 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"

Répertorier les catégories de leurs dernières versions

Remplacez les espaces réservés par vos propres valeurs et exécutez la commande suivante dans une fenêtre 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"

Supprimer une catégorie personnalisée ou une version spécifique de celle-ci

Remplacez les espaces réservés par vos propres valeurs et exécutez la commande suivante dans une fenêtre 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

Tout d’abord, assurez-vous d’avoir installé la bibliothèque Python requise :

pip install requests

Ensuite, établissez les configurations nécessaires sur la base de vos propres détails de ressource d’IA :

import requests

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

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

Obtenir une catégorie personnalisée ou une version spécifique de celle-ci

Remplacez les espaces réservés par vos propres valeurs et exécutez le code suivant dans votre script 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)

Répertorier les catégories de leurs dernières versions

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)

Supprimer une catégorie personnalisée ou une version spécifique de celle-ci

Remplacez les espaces réservés par vos propres valeurs et exécutez le code suivant dans votre script 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)

Contenu connexe

• Concepts des catégories personnalisées
• Modérer le contenu avec la Sécurité du Contenu