Verwenden der API für benutzerdefinierte Kategorien (Standard) (Vorschau)

Mit der API für benutzerdefinierte Kategorien (Standard) können Sie eigene Inhaltskategorien für Ihren Anwendungsfall erstellen und Azure KI Inhaltssicherheit trainieren, um sie in neuen Inhalten zu erkennen.

Wichtig

Dieses Feature ist nur in bestimmten Azure-Regionen verfügbar. Weitere Informationen finden Sie unter Regionale Verfügbarkeit.

Achtung

Die Beispieldaten in diesem Leitfaden können anstößige Inhalte enthalten. Wir raten zu umsichtigem Vorgehen.

Voraussetzungen

• Azure-Abonnement: Kostenloses Azure-Konto
• Sobald Sie über ein Azure-Abonnement verfügen, können Sie im Azure-Portal eine Content Safety-Ressource erstellen, um Ihren Schlüssel und Endpunkt abzurufen. Geben Sie für Ihre Ressource einen eindeutigen Namen ein. Wählen Sie Ihr Abonnement aus, und wählen Sie dann eine Ressourcengruppe, eine unterstützte Region und einen unterstützten Tarif. Klicken Sie anschließend auf Erstellen.
  • Die Bereitstellung der Ressource dauert einige Minuten. Wählen Sie im Anschluss Zu Ressource wechseln aus. Wählen Sie im linken Bereich unter Ressourcenverwaltung die Option Abonnementschlüssel und Endpunkt aus. Kopieren Sie den Endpunkt und einen der Schlüsselwerte an einen temporären Speicherort für die spätere Verwendung.
• Erstellen Sie außerdem einen Azure Blob Storage-Container, in dem Sie Ihre Trainingsanmerkungsdatei beibehalten.
• Installation einer der folgenden Optionen:
  • cURL für REST-API-Aufrufe
  • Installation von Python 3.x

Vorbereiten Ihrer Trainingsdaten

Zum Trainieren einer benutzerdefinierten Kategorie benötigen Sie Beispieltextdaten, die die Kategorie darstellen, die erkannt werden soll. Führen Sie die folgenden Schritte aus, um Ihre Beispieldaten vorzubereiten.

1. Sammeln oder Schreiben von Beispieldaten:

   • Die Qualität Ihrer Beispieldaten ist wichtig für das Training eines effektiven Modells. Zielen Sie darauf ab, mindestens 50 Positivbeispiele zu sammeln, die die zu identifizierenden Inhalte genau darstellen. Diese Beispiele sollten klar und abwechslungsreich sein und direkt mit der Kategoriedefinition zusammenhängen.
   • Negativbeispiele sind nicht erforderlich, können aber die Fähigkeit des Modells, relevante Inhalte von irrelevanten Inhalten zu unterscheiden, verbessern. Um die Leistung zu verbessern, sollten Sie 50 Beispiele auswählen, die nicht mit der Definition der positiven Fälle zusammenhängen. Diese sollten abwechslungsreich sein, aber immer noch im Zusammenhang mit dem Inhalt stehen, auf den Ihr Modell stoßen wird. Wählen Sie die Negativbeispiele sorgfältig aus, um sicherzustellen, dass sie nicht versehentlich mit der positiven Kategorie überlappen.
   • Bemühen Sie sich um ein Gleichgewicht zwischen der Anzahl positiver und negativer Beispiele. Ein ungleichmäßiges Dataset kann das Modell beeinträchtigen, was dazu führt, dass eine Art der Klassifizierung gegenüber einer anderen bevorzugt wird, was wiederum zu einer höheren Rate falsch positiver oder negativer Ergebnisse führen kann.

2. Verwenden Sie einen Text-Editor, um Ihre Daten in eine JSONL-Datei zu formatieren. Unten sehen Sie ein Beispiel für das entsprechende Format. Kategoriebeispiele sollten isPositive auf true festlegen. Negativbeispiele sind optional, können aber die Leistung verbessern:

   {"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. Laden Sie die JSONL-Datei in einen Blob-Container eines Azure Storage-Kontos hoch. Kopieren Sie die Blob-URL an einen temporären Speicherort für die spätere Verwendung.

Gewähren des Speicherzugriffs

Als Nächstes müssen Sie Ihrer Content Safety-Ressource Zugriff gewähren, um Daten aus der Azure Storage-Ressource lesen zu können. Aktivieren Sie die systemseitig zugewiesene verwaltete Identität für die Azure KI Inhaltssicherheit-Instanz, und weisen Sie der Identität die Rolle Mitwirkender/Besitzer von Speicherblobdaten zu:

Wichtig

Nur Speicherblobdaten-Mitwirkender oder Speicherblobdaten-Besitzer sind gültige Rollen, um fortzufahren.

1. Aktivieren Sie die verwaltete Identität für die Azure KI Content Safety-Instanz.

   

2. Weisen Sie der verwalteten Identität die Rolle Mitwirkender an/Besitzer von Storage-Blobdaten zu. Alle nachstehend hervorgehobenen Rollen sollten funktionieren.

   

   

   

Erstellen und Trainieren einer benutzerdefinierten Kategorie

Wichtig

Ausreichend Zeit für das Modelltraining einplanen

Die End-to-End-Ausführung des Trainings einer benutzerdefinierten Kategorie kann fünf bis zehn Stunden dauern. Planen Sie Ihre Moderationspipeline entsprechend, und planen Sie Zeit für Folgendes ein:

• Sammeln und Vorbereiten der Beispieldaten
• Trainingsprozess
• Modellauswertung und Anpassungen

cURL

Ersetzen Sie in den folgenden Befehlen <your_api_key>, <your_endpoint> und andere erforderliche Parameter durch Ihre eigenen Werte. Geben Sie dann jeden Befehl in ein Terminalfenster ein, und führen Sie ihn aus.

Erstellen einer neuen Kategorieversion

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

Starten Sie den Kategoriebuildprozess:

Nachdem Sie die Antwort erhalten haben, speichern Sie die Vorgangs-ID (genannt id) in einer temporären Datei. Sie benötigen diese ID, um den Buildstatus mithilfe der Get-Status-API abzurufen.

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"

Abrufen des Kategoriebuildstatus:

Um den Status abzurufen, verwenden Sie die id aus der vorherigen API-Antwort, und platzieren Sie sie im Pfad der folgenden API.

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"

Analysieren von Text mit einer benutzerdefinierten Kategorie

Führen Sie den folgenden Befehl aus, um Text mit Ihrer benutzerdefinierten Kategorie zu analysieren. Ersetzen Sie <your_category_name> durch Ihren eigenen Wert:

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

Zunächst müssen Sie die erforderliche Python-Bibliothek installieren:

pip install requests

Öffnen Sie dann ein neues Python-Skript, und definieren Sie die erforderlichen Variablen mit Ihren eigenen Azure-Ressourcendetails:

import requests

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

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

Erstellen einer neuen Kategorieversion

Sie können eine neue Kategorie mit Kategoriename, Definition und sample_blob_url erstellen, und Sie erhalten die automatisch generierte Versionsnummer dieser Kategorie.

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)

Starten des Kategoriebuildprozesses

Sie können den Kategoriebuildprozess mit dem Kategorienamen und der Versionsnummer starten.

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)

Abrufen des Kategoriebuildstatus:

Um den Status abzurufen, verwenden Sie die id aus der vorherigen Antwort.

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)

Analysieren von Text mit einer benutzerdefinierten Kategorie

Sie müssen den Kategorienamen und die Versionsnummer (optional; der Dienst verwendet standardmäßig die neueste) während des Rückschlusses angeben. Sie können mehrere Kategorien angeben, wenn sie bereits definiert sind.

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)

Andere Vorgänge für benutzerdefinierte Kategorien

Denken Sie daran, die unten aufgeführten Platzhalter durch Ihre tatsächlichen Werte für den API-Schlüssel, Endpunkt und bestimmte Inhalte (Kategoriename, Definition usw.) zu ersetzen. Diese Beispiele helfen Ihnen, die benutzerdefinierten Kategorien in Ihrem Konto zu verwalten.

cURL

Abrufen einer benutzerdefinierten Kategorie oder einer bestimmten Version davon

Ersetzen Sie die Platzhalter durch Ihre eigenen Werte, und führen Sie den folgenden Befehl in einem Terminalfenster aus:

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"

Kategorien nach ihren neuesten Versionen auflisten

Ersetzen Sie die Platzhalter durch Ihre eigenen Werte, und führen Sie den folgenden Befehl in einem Terminalfenster aus:

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"

Löschen einer benutzerdefinierten Kategorie oder einer bestimmten Version davon

Ersetzen Sie die Platzhalter durch Ihre eigenen Werte, und führen Sie den folgenden Befehl in einem Terminalfenster aus:

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

Stellen Sie zunächst sicher, dass Sie die erforderliche Python-Bibliothek installiert haben:

pip install requests

Richten Sie dann die erforderlichen Konfigurationen mit Ihren eigenen AI-Ressourcendetails ein:

import requests

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

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

Abrufen einer benutzerdefinierten Kategorie oder einer bestimmten Version davon

Ersetzen Sie die Platzhalter durch Ihre eigenen Werte, und führen Sie den folgenden Code in Ihrem Python-Skript aus:

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)

Kategorien nach ihren neuesten Versionen auflisten

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)

Löschen einer benutzerdefinierten Kategorie oder einer bestimmten Version davon

Ersetzen Sie die Platzhalter durch Ihre eigenen Werte, und führen Sie den folgenden Code in Ihrem Python-Skript aus:

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)

Zugehöriger Inhalt

• Konzepte für benutzerdefinierte Kategorien
• Moderieren von Inhalten mit Inhaltssicherheit