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.

Benutzerdefinierte Kategorien (Standardmodus) (Vorschau) – Benutzerflow

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.

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/survival-advice?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.

Abrufen einer neuen Kategorieversion

curl -X PUT "<your_endpoint>/contentsafety/text/categories/survival-advice?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\"
        }"

Starten Sie den Kategoriebuildprozess:

Ersetzen Sie <your_api_key> und <your_endpoint> durch Ihre eigenen Werte, und fügen Sie auch die Versionsnummer 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"

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"

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

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)

Zugehöriger Inhalt

• Informationen zu anderen Vorgängen für benutzerdefinierte Kategorien finden Sie in der Schrittanleitung.
• Konzepte für benutzerdefinierte Kategorien
• Moderieren von Inhalten mit Inhaltssicherheit