Quickstart: Aangepaste categorieën (standaardmodus) (preview)

Volg deze handleiding om aangepaste categorieën (standaard) voor Azure AI Content Safety te gebruiken om uw eigen inhoudscategorieën voor uw use-case te maken en Azure AI Content Safety te trainen om deze te detecteren in nieuwe tekstinhoud.

Zie de conceptpagina Aangepaste categorieën voor meer informatie over aangepaste categorieën. Zie de sectie Invoervereisten van het overzicht voor API-invoerlimieten.

Belangrijk

Deze functie is alleen beschikbaar in bepaalde Azure-regio's. Zie beschikbaarheid van regio's.

Belangrijk

Voldoende tijd toestaan voor modeltraining

De end-to-end uitvoering van aangepaste categorietraining kan van ongeveer vijf uur tot tien uur duren. Plan uw beheerpijplijn dienovereenkomstig.

Vereisten

• Een Azure-abonnement - Een gratis abonnement maken
• Zodra u uw Azure-abonnement hebt, maakt u een Content Safety-resource in Azure Portal om uw sleutel en eindpunt op te halen. Voer een unieke naam in voor uw resource, selecteer uw abonnement en selecteer een resourcegroep, ondersteunde regio en ondersteunde prijscategorie. Selecteer vervolgens Maken.
  • Het implementeren van de resource duurt enkele minuten. Nadat deze is voltooid, gaat u naar de resource. Selecteer in het linkerdeelvenster onder Resourcebeheer de optie Abonnementssleutel en Eindpunt. Kopieer het eindpunt en een van de sleutelwaarden naar een tijdelijke locatie voor later gebruik.
• Maak ook een Azure Blob Storage-container waarin u uw trainingsaantekeningsbestand bewaart.
• Een van de volgende geïnstalleerd:
  • cURL voor REST API-aanroepen.
  • Python 3.x geïnstalleerd

Uw trainingsgegevens voorbereiden

Als u een aangepaste categorie wilt trainen, hebt u voorbeeldtekstgegevens nodig die de categorie vertegenwoordigen die u wilt detecteren. In deze handleiding kunt u voorbeeldgegevens gebruiken. Het verstrekte aantekeningsbestand bevat tekstprompts over overlevingsadvies in camping-/wildernissituaties. Het getrainde model leert dit type inhoud in nieuwe tekstgegevens te detecteren.

Tip

Zie de handleiding instructies voor tips over het maken van uw eigen gegevensset.

1. Download het voorbeeldgegevensbestand van de GitHub-opslagplaats.
2. Upload het JSONL-bestand naar de blobcontainer van uw Azure Storage-account. Kopieer vervolgens de blob-URL naar een tijdelijke locatie voor later gebruik.

Belangrijk

Het opslagaccount van de gebruiker is ingesteld als een hiërarchisch naamruimteaccount, dat niet kan worden ondersteund door aangepaste categorieën. Probeer in plaats daarvan een normaal opslagaccount te gebruiken. Uw blob-URL kan bijvoorbeeld niet worden gesplitst in twee lagen, zoals voorbeeld/voorbeeld1/, en mag slechts één laag hebben. Raadpleeg de documentatie voor meer informatie: Hiërarchische naamruimte van Azure Data Lake Storage - Azure Storage.

Opslagtoegang verlenen

Vervolgens moet u uw Content Safety-resource toegang geven om te lezen uit de Azure Storage-resource. Schakel door het systeem toegewezen beheerde identiteit in voor het Azure AI Content Safety-exemplaar en wijs de rol van Inzender/Eigenaar voor opslagblobgegevens toe aan de identiteit:

Belangrijk

Alleen inzender voor opslagblobgegevens of eigenaar van opslagblobgegevens zijn geldige rollen om door te gaan.

1. Schakel beheerde identiteit in voor het Azure AI Content Safety-exemplaar.

   

2. Wijs de rol van Inzender/Eigenaar voor opslagblobgegevens toe aan de beheerde identiteit. Alle rollen die hieronder zijn gemarkeerd, moeten werken.

   

   

   

Een aangepaste categorie maken en trainen

cURL

Vervang <your_api_key>in de onderstaande opdracht en <your_endpoint>andere benodigde parameters door uw eigen waarden. Voer vervolgens elke opdracht in een terminalvenster in en voer deze uit.

Nieuwe categorieversie maken

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

Tip

Telkens wanneer u de categorienaam, definitie of voorbeelden wijzigt, wordt er een nieuwe versie gemaakt. U kunt het versienummer gebruiken om terug te gaan naar eerdere versies. Onthoud dit versienummer, omdat dit vereist is in de URL voor de volgende stap: aangepaste categorieën trainen.

API-aanvraag

Veld	Beschrijving	Voorbeeldwaarde
categoryName	De naam van de categorie of het onderwerp waarop de aanvraag betrekking heeft.	overlevingsadvies
definition	Een korte beschrijving van het inhoudstype voor de categorie.	tekstprompts over overlevingsadvies in camping-/wildernissituaties
sampleBlobUrl	URL voor toegang tot een JSONL-voorbeeldbestand met gegevensvoorbeelden voor de categorie.	Koppeling

API-reactie

Veld	Beschrijving	Voorbeeldwaarde
categoryName	De naam van de categorie of het onderwerp waarop het antwoord betrekking heeft.	overlevingsadvies
definition	Een korte beschrijving van het inhoudstype voor de categorie.	tekstprompts over overlevingsadvies in camping-/wildernissituaties
sampleBlobUrl	URL voor toegang tot een JSONL-voorbeeldbestand met gegevensvoorbeelden voor de categorie.	Koppeling
sampleBlobSnapshotUrl	Momentopname-URL van het JSONL-voorbeeldbestand, dat toegang biedt tot een specifieke versie van de gegevens.	Momentopname-URL
version	Het versienummer van de categoriegegevens.	1
createdTime	Tijdstempel wanneer de categoriegegevens zijn gemaakt.	2024-10-28T22:06:59.4626988Z
status	Huidige status van de categoriegegevensverwerking.	Geslaagd

Start het buildproces van de categorie:

Vervang <your_api_key> en <your_endpoint> door uw eigen waarden en voeg ook het versienummer toe aan de URL die u hebt verkregen uit de laatste stap. Voldoende tijd voor modeltraining toestaan: de end-to-end uitvoering van aangepaste categorietraining kan van ongeveer vijf uur tot tien uur duren. Plan uw beheerpijplijn dienovereenkomstig. Nadat u het antwoord hebt ontvangen, slaat u de bewerkings-id (aangeduid als id) op een tijdelijke locatie op. Deze id is nodig voor het ophalen van de buildstatus met behulp van de GET-status-API in de volgende sectie.

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"

API-reactie

Veld	Beschrijving	Voorbeeldwaarde
operation id	Unieke id voor het ophalen van de buildstatus	b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxxxx
status	Huidige status van de aanvraag	Geslaagd

De buildstatus van de categorie ophalen:

Als u de status wilt ophalen, gebruikt u het id verkregen uit het vorige API-antwoord en plaatst u deze in het pad van de onderstaande API.

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"

API-reactie

Veld	Beschrijving	Voorbeeldwaarde
operation id	Unieke id voor het ophalen van de buildstatus	b6c69dc1-2338-484e-855b-xxxxxxxxxxxx
status	Huidige status van de aanvraag	Geslaagd

Tekst analyseren met een aangepaste categorie

Voer de volgende opdracht uit om tekst te analyseren met uw aangepaste categorie. Vervang <your_api_key> en <your_endpoint> door uw eigen waarden.

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

API-aanvraag

Veld	Beschrijving
text	De tekstinhoud of het bericht dat is bedoeld voor categoriedetectie
categoryName	De naam van de categorie waarvan de tekst moet worden gedetecteerd onder
version	Versienummer van de categorie

API-reactie

Veld	Beschrijving	Voorbeeldwaarde
customCategoryAnalysis	Object met het analyseresultaat voor de categorie.	—
detected	Geeft aan of de opgegeven categorie is gedetecteerd.	false

Python

Eerst moet u de vereiste Python-bibliotheek installeren:

pip install requests

Open vervolgens een nieuw Python-script en definieer de benodigde variabelen met uw eigen Azure-resourcegegevens:

import requests

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

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

Een nieuwe categorie maken

U kunt een nieuwe categorie maken met categorienaam, definitie en sample_blob_url en u krijgt het automatisch gegenereerde versienummer van deze categorie.

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)

Het buildproces van de categorie starten

U kunt het buildproces voor de categorie starten met de categorienaam en het versienummer. Voldoende tijd voor modeltraining toestaan: de end-to-end uitvoering van aangepaste categorietraining kan van ongeveer vijf uur tot tien uur duren. Plan uw beheerpijplijn dienovereenkomstig. Nadat u het antwoord hebt ontvangen, moet u ervoor zorgen dat u de bewerkings-id (ook wel aangeduid als id) opslaat, net zoals uw notitieblok. Deze id is nodig voor het ophalen van de buildstatus met behulp van de functie 'get_build_status' in de volgende sectie.

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)

De buildstatus van de categorie ophalen:

Als u de status wilt ophalen, gebruikt u de id verkregen uit het vorige antwoord.

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)

Tekst analyseren met een aangepaste categorie

U moet de categorienaam en het versienummer opgeven (optioneel; de service gebruikt standaard de meest recente versie) tijdens deductie. U kunt meerdere categorieën opgeven als ze al zijn gedefinieerd.

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)

Andere bewerkingen voor aangepaste categorieën

Vergeet niet om de onderstaande tijdelijke aanduidingen te vervangen door uw werkelijke waarden voor de API-sleutel, het eindpunt en specifieke inhoud (categorienaam, definitie, enzovoort). Deze voorbeelden helpen u bij het beheren van de aangepaste categorieën in uw account.

cURL

Een aangepaste categorie of een specifieke versie ervan ophalen

Vervang de tijdelijke aanduidingen door uw eigen waarden en voer de volgende opdracht uit in een terminalvenster:

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"

Categorieën van hun nieuwste versies weergeven

Vervang de tijdelijke aanduidingen door uw eigen waarden en voer de volgende opdracht uit in een terminalvenster:

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"

Een aangepaste categorie of een specifieke versie ervan verwijderen

Vervang de tijdelijke aanduidingen door uw eigen waarden en voer de volgende opdracht uit in een terminalvenster:

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"

Python

Controleer eerst of u de vereiste Python-bibliotheek hebt geïnstalleerd:

pip install requests

Stel vervolgens de benodigde configuraties in met uw eigen AI-resourcegegevens:

import requests

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

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

Een aangepaste categorie of een specifieke versie ervan ophalen

Vervang de tijdelijke aanduidingen door uw eigen waarden en voer de volgende code uit in uw Python-script:

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)

Categorieën van hun nieuwste versies weergeven

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)

Een aangepaste categorie of een specifieke versie ervan verwijderen

Vervang de tijdelijke aanduidingen door uw eigen waarden en voer de volgende code uit in uw Python-script:

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)

Gerelateerde inhoud

• Concepten van aangepaste categorieën
• Inhoud beheren met Inhoudsveiligheid