Démarrage rapide : Catégories personnalisées (mode standard) (préversion)

Article
11/05/2024

Suivez ce guide pour utiliser les catégories personnalisées (standard) de l’API REST Azure AI Sécurité du Contenu afin de créer vos propres catégories de contenu pour votre cas d’utilisation et d’entraîner Azure AI Sécurité du Contenu à les détecter dans le nouveau contenu texte.

Pour plus d’informations sur les catégories personnalisées, consultez la page des concepts des catégories personnalisées. Pour connaître les limites d’entrée de l’API, consultez la section Exigences pour les entrées de la Vue d’ensemble.

Important

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

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.

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. Dans ce guide, vous pouvez utiliser des exemples de données. Le fichier d’annotation fourni contient des invites de texte sur les conseils de survie dans des situations de camping/en pleine nature sauvage. Le modèle entraîné apprend à détecter ce type de contenu dans de nouvelles données de texte.

Conseil

Pour obtenir des conseils sur la création de votre propre jeu de données, consultez le guide pratique.

Téléchargez l’exemple de fichier de données de texte à partir du référentiel GitHub.
Chargez le fichier .jsonl dans votre conteneur de Stockage Blob Azure. Copiez ensuite l’URL d’objet blob sur un emplacement temporaire pour une utilisation ultérieure.

Important

Le compte de stockage de l’utilisateur est configuré en tant que compte d’espace de noms hiérarchique, lequel ne peut pas être pris en charge par les catégories personnalisées. Essayez plutôt d’utiliser un compte de stockage standard. Par exemple, votre URL de blob ne peut pas être divisée en deux couches, comme exemple/exemple1/, elle ne doit avoir qu’une seule couche. Pour plus d’informations, reportez-vous à la documentation : Espace de noms hiérarchique Azure Data Lake Storage – Stockage Azure.

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 de contributeur/propriétaire des données Blob du stockage à l’identité :

Important

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

Activez une identité managée pour l’instance Azure AI Content Safety.
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

cURL
Python

Dans la commande 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-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\"
        }"

Conseil

Chaque fois que vous modifiez le nom, la définition ou les exemples de votre catégorie, une nouvelle version est créée. Vous pouvez utiliser le numéro de version pour revenir aux versions précédentes. N’oubliez pas ce numéro de version, car il sera nécessaire dans l’URL à l’étape suivante : catégories personnalisées d’entraînement.

Demande API

Champ	Description	Exemple de valeur
`categoryName`	Nom de la catégorie ou de la rubrique à laquelle la demande est liée.	survival-advice
`definition`	Brève description du type de contenu pour la catégorie.	invites de texte sur les conseils de survie dans les situations de camping ou dans la nature
`sampleBlobUrl`	URL permettant d’accéder à un exemple de fichier JSONL contenant des exemples de données pour la catégorie.	Lien

Réponse de l’API

Champ	Description	Exemple de valeur
`categoryName`	Nom de la catégorie ou de la rubrique à laquelle la réponse est liée.	survival-advice
`definition`	Brève description du type de contenu pour la catégorie.	invites de texte sur les conseils de survie dans les situations de camping ou dans la nature
`sampleBlobUrl`	URL permettant d’accéder à un exemple de fichier JSONL contenant des exemples de données pour la catégorie.	Lien
`sampleBlobSnapshotUrl`	URL d’instantané de l’exemple de fichier JSONL, qui fournit l’accès à une version spécifique des données.	URL d’instantané
`version`	Numéro de version des données de catégorie.	1
`createdTime`	Horodatage lorsque les données de catégorie ont été créées.	2024-10-28T22:06:59.4626988Z
`status`	État actuel du traitement des données de catégorie.	Réussi

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

Remplacez <your_api_key> et <your_endpoint> par vos propres valeurs, puis ajoutez le numéro de version dans l’URL que vous avez obtenue à la dernière étape. Prévoyez suffisamment de temps pour l’entraînement du modèle : l’exécution de bout en bout de l’entraînement de catégorie personnalisée peut prendre environ cinq heures à dix heures. Planifiez votre pipeline de modération en conséquence. Après avoir reçu la réponse, stockez l’ID d’opération (appelé id) sur un emplacement temporaire. Cet ID sera nécessaire pour récupérer l’état de la build à l’aide de l’API Obtenir l’état dans la section suivante.

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"

Réponse de l’API

Champ	Description	Exemple de valeur
`operation id`	Identificateur unique pour récupérer l’état de la build	b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxx
`status`	État actuel de la demande	Réussi

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

Réponse de l’API

Champ	Description	Exemple de valeur
`operation id`	Identificateur unique pour récupérer l’état de la build	b6c69dc1-2338-484e-855b-xxxxxxxxxxxx
`status`	État actuel de la demande	Réussi

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_api_key> et <your_endpoint> par vos propres valeurs.

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

Demande API

Champ	Description
`text`	Contenu texte ou message destiné à la détection de catégorie
`categoryName`	Nom de la catégorie dans laquelle le texte doit être détecté
`version`	Numéro de version de la catégorie

Réponse de l’API

Champ	Description	Exemple de valeur
`customCategoryAnalysis`	Objet contenant le résultat d’analyse de la catégorie.	—
`detected`	Indique si la catégorie spécifiée a été détectée.	false

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

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. Prévoyez suffisamment de temps pour l’entraînement du modèle : l’exécution de bout en bout de l’entraînement de catégorie personnalisée peut prendre environ cinq heures à dix heures. Planifiez votre pipeline de modération en conséquence. Après avoir reçu la réponse, assurez-vous de stocker l’ID d’opération (appelé id) sur un emplacement comme votre bloc-notes. Cet ID sera nécessaire pour récupérer l’état de la build à l’aide de la fonction « get_build_status » dans la section suivante.

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)

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

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

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
Python

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

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

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

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

Partager via

Démarrage rapide : Catégories personnalisées (mode standard) (préversion)

Prérequis

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

Accorder l’accès au stockage

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

Créer une nouvelle version de catégorie

Demande API

Réponse de l’API

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

Réponse de l’API

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

Réponse de l’API

Analyser du texte avec une catégorie personnalisée

Demande API

Réponse de l’API

Créer une catégorie

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

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

Analyser du texte avec une catégorie personnalisée

Autres opérations de catégories personnalisées

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

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

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

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

Commentaires

Ressources supplémentaires

Partager via

Démarrage rapide : Catégories personnalisées (mode standard) (préversion)

Prérequis

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

Accorder l’accès au stockage

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

Créer une nouvelle version de catégorie

Demande API

Réponse de l’API

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

Réponse de l’API

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

Réponse de l’API

Analyser du texte avec une catégorie personnalisée

Demande API

Réponse de l’API

Autres opérations de catégories personnalisées

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

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

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

Contenu connexe

Commentaires

Ressources supplémentaires