Schnellstart: Benutzerdefinierte Kategorien (Standardmodus) (Vorschau)

In diesem Leitfaden erfahren Sie, wie Sie mithilfe der REST-API für benutzerdefinierte Kategorien (Standard) von Azure KI Inhaltssicherheit eigene Inhaltskategorien für Ihren Anwendungsfall erstellen und Azure KI Inhaltssicherheit so trainieren, dass diese in neuen Textinhalten erkannt werden.

Weitere Informationen zu benutzerdefinierten Kategorien finden Sie auf der Seite Konzept „Benutzerdefinierte Kategorien“. Informationen zu API-Eingabegrenzwerten finden Sie im Abschnitt Eingabeanforderungen der Übersicht.

Wichtig

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

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.

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. In diesem Leitfaden können Sie Beispieldaten verwenden. Die bereitgestellte Anmerkungsdatei enthält Textaufforderungen zu Überlebenstipps in Camping- und Wildnissituationen. Das trainierte Modell lernt, diese Art von Inhalt in neuen Textdaten zu erkennen.

Tipp

Tipps zum Erstellen ihres eigenen Datasets finden Sie in der Schrittanleitung.

1. Laden Sie die Beispieltextdatendatei aus dem GitHub-Repository herunter.
2. Laden Sie die JSONL-Datei in Ihren Blob-Container ihres Azure Storage-Kontos hoch. Kopieren Sie dann die Blob-URL an einen temporären Speicherort für die spätere Verwendung.

Wichtig

Das Speicherkonto des Benutzers ist als hierarchisches Namespace-Konto eingerichtet, das nicht von benutzerdefinierten Kategorien unterstützt werden kann. Bitte versuchen Sie stattdessen, ein reguläres Speicherkonto zu verwenden. Beispielsweise kann Ihre Blob-URL nicht in zwei Ebenen aufgeteilt werden, wie beispielsweise „example/example1/“, und sollte nur eine Ebene haben. Weitere Informationen finden Sie in der Dokumentation: Hierarchischen Azure Data Lake Storage-Namespace – Azure Storage.

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

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

Tipp

Jedes Mal, wenn Sie ihren Kategorienamen, Ihre Definition oder Beispiele ändern, wird eine neue Version erstellt. Sie können die Versionsnummer verwenden, um zu früheren Versionen zurückzukehren. Bitte merken Sie sich diese Versionsnummer, da sie in der URL für den nächsten Schritt erforderlich ist – Training benutzerdefinierter Kategorien.

API-Anforderung

Feld	Beschreibung	Beispielwert
categoryName	Der Name der Kategorie oder des Themas, auf die sich die Anforderung bezieht.	Überlebenstipps
definition	Eine kurze Beschreibung des Inhaltstyps für die Kategorie.	Textprompts zu Überlebenstipps in Camping- und Wildnissituationen
sampleBlobUrl	URL für den Zugriff auf eine JSONL-Beispieldatei mit Datenbeispielen für die Kategorie.	Verknüpfung

API-Antwort

Feld	Beschreibung	Beispielwert
categoryName	Der Name der Kategorie oder des Themas, auf den sich die Antwort bezieht.	Überlebenstipps
definition	Eine kurze Beschreibung des Inhaltstyps für die Kategorie.	Textprompts zu Überlebenstipps in Camping- und Wildnissituationen
sampleBlobUrl	URL für den Zugriff auf eine JSONL-Beispieldatei mit Datenbeispielen für die Kategorie.	Verknüpfung
sampleBlobSnapshotUrl	Snapshot-URL der JSONL-Beispieldatei, die Zugriff auf eine bestimmte Version der Daten bietet.	Snapshot-URL
version	Die Versionsnummer der Kategoriedaten.	1
createdTime	Zeitstempel, als die Kategoriedaten erstellt wurde.	2024-10-28T22:06:59.4626988Z
status	Aktueller Status der Kategoriedatenverarbeitung.	Erfolgreich

Starten Sie den Kategoriebuildprozess:

Ersetzen Sie <your_api_key> und <your_endpoint> durch Ihre eigenen Werte, und fügen Sie auch die Versionsnummer in der URL an, die Sie aus dem letzten Schritt erhalten haben. Planen Sie ausreichend Zeit für das Modelltraining ein: Die End-to-End-Ausführung des Trainings einer benutzerdefinierten Kategorie kann fünf bis zehn Stunden dauern. Planen Sie Ihre Moderationspipeline entsprechend. Nachdem Sie die Antwort erhalten haben, speichern Sie die Vorgangs-ID (genannt id) an einem temporären Speicherort. Diese ID ist erforderlich, um den Buildstatus mithilfe der Get-Status-API im nächsten Abschnitt abzurufen.

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

Feld	Beschreibung	Beispielwert
operation id	Eindeutiger Bezeichner zum Abrufen des Buildstatus	b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxx
status	Aktueller Status der Anforderung	Erfolgreich

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

API-Antwort

Feld	Beschreibung	Beispielwert
operation id	Eindeutiger Bezeichner zum Abrufen des Buildstatus	b6c69dc1-2338-484e-855b-xxxxxxxxxxxx
status	Aktueller Status der Anforderung	Erfolgreich

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_api_key> und <your_endpoint> durch Ihre eigenen Werte.

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

Feld	Beschreibung
text	Der Textinhalt oder die Nachricht, die für die Kategorieerkennung vorgesehen ist
categoryName	Der Name der Kategorie, unter der der Text erkannt werden soll
version	Versionsnummer der Kategorie

API-Antwort

Feld	Beschreibung	Beispielwert
customCategoryAnalysis	Objekt, das das Analyseergebnis für die Kategorie enthält.	—
detected	Gibt an, ob die angegebene Kategorie erkannt wurde.	false

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 Kategorie

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

Starten des Kategoriebuildprozesses

Sie können den Kategoriebuildprozess mit dem Kategorienamen und der Versionsnummer starten. Planen Sie ausreichend Zeit für das Modelltraining ein: Die End-to-End-Ausführung des Trainings einer benutzerdefinierten Kategorie kann fünf bis zehn Stunden dauern. Planen Sie Ihre Moderationspipeline entsprechend. Stellen Sie nach erhalt der Antwort sicher, dass Sie die Vorgangs-ID (genannt id) an einer beliebigen Stelle wie Ihrem Notebook speichern. Diese ID ist erforderlich, um den Buildstatus mithilfe der Funktion „get_build_status“ im nächsten Abschnitt abzurufen.

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)

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

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

Kategorien nach ihren neuesten Versionen auflisten

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)

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

Zugehöriger Inhalt

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