Freigeben über


Verwenden einer Sperrliste

Achtung

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

Die standardmäßigen KI-Klassifizierer reichen für die meisten Anforderungen an die Inhaltsmoderation aus. Allerdings müssen Sie eventuell auf Begriffe prüfen, die spezifisch für Ihren Anwendungsfall sind. Mit Blocklisten können Sie den KI-Klassifizierern benutzerdefinierte Ausdrücke hinzufügen. Sie können Blocklisten verwenden, um nach bestimmten Begriffen oder Ausdrücken zu suchen, die Sie in Ihren Inhalten kennzeichnen möchten.

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 einen eindeutigen Namen für Ihre Ressource ein, wählen Sie Ihr Abonnement aus, und wählen Sie dann eine Ressourcengruppe, eine unterstützte Region (weitere Informationen unter Regionale Verfügbarkeit) und einen unterstützten Tarif aus. Wählen Sie dann Erstellen aus.
    • 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. Der Endpunkt und einer der Schlüssel werden verwendet, um APIs aufzurufen.
  • Installation einer der folgenden Optionen:
    • cURL für REST-API-Aufrufe
    • Installation von Python 3.x
      • Ihre Python-Installation sollte pip enthalten. Sie können überprüfen, ob pip installiert ist, indem Sie pip --version in der Befehlszeile ausführen. Installieren Sie die aktuelle Python-Version, um pip zu erhalten.
      • Wenn Sie Python verwenden, müssen Sie die Azure AI Content Safety-Clientbibliothek für Python installieren. Führen Sie in Ihrem Projektverzeichnis den Befehl pip install azure-ai-contentsafety aus.
    • .NET Runtime installiert.
      • Installation des .NET Core SDK
      • Wenn Sie .NET verwenden, müssen Sie die Azure AI Content Safety-Clientbibliothek für .NET installieren. Führen Sie in Ihrem Projektverzeichnis den Befehl dotnet add package Azure.AI.ContentSafety --prerelease aus.

Erstellen von Umgebungsvariablen

In diesem Beispiel schreiben Sie Ihre Anmeldeinformationen in Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.

Um die Umgebungsvariable für Ihren Ressourcenschlüssel und Endpunkt festzulegen, öffnen Sie ein Konsolenfenster und befolgen Sie die Anweisungen für Ihr Betriebssystem und Ihre Entwicklungsumgebung.

  • Zum Festlegen der Umgebungsvariablen CONTENT_SAFETY_KEY ersetzen Sie YOUR_CONTENT_SAFETY_KEY durch einen der Schlüssel für Ihre Ressource.
  • Zum Festlegen der Umgebungsvariablen CONTENT_SAFETY_ENDPOINT ersetzen Sie YOUR_CONTENT_SAFETY_ENDPOINT durch den Endpunkt für Ihre Ressource.

Wichtig

Wenn Sie einen API-Schlüssel verwenden, speichern Sie ihn an einer anderen Stelle sicher, z. B. in Azure Key Vault. Fügen Sie den API-Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich zugänglich.

Weitere Informationen zur Sicherheit von KI Services finden Sie unter Authentifizieren von Anforderungen an Azure KI Services.

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

Nach dem Hinzufügen der Umgebungsvariablen müssen Sie möglicherweise alle ausgeführten Programme neu starten, die die Umgebungsvariablen lesen, z. B. das Konsolenfenster.

Analysieren von Text mit einer Sperrliste

Sie können Sperrlisten für die Verwendung mit der Text-API erstellen. Die folgenden Schritte helfen Ihnen bei den ersten Schritten.

Erstellen oder Ändern einer Sperrliste

Kopieren Sie den nachstehenden cURL-Befehl in einen Text-Editor, und nehmen Sie folgende Änderungen vor:

  1. Ersetzen Sie <endpoint> durch Ihre Endpunkt-URL.
  2. Ersetzen Sie <enter_your_key_here> durch Ihren Schlüssel.
  3. Ersetzen Sie (in der URL) <your_list_name> durch einen benutzerdefinierten Namen für Ihre Liste. Ersetzen Sie außerdem den letzten Begriff der REST-URL durch denselben Namen. Zulässige Zeichen: 0–9, A-Z, a-z, - . _ ~.
  4. Ersetzen Sie optional den Wert des Felds "description" durch eine benutzerdefinierte Beschreibung.
curl --location --request PATCH '<endpoint>/contentsafety/text/blocklists/<your_list_name>?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <enter_your_key_here>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "This is a violence list"
}'

Der Antwortcode sollte 201 (neue Liste erstellt) oder 200 (vorhandene Liste aktualisiert) sein.

Hinzufügen von blocklistItems zur Liste

Hinweis

Für alle Listen gilt eine Obergrenze von insgesamt 10.000 Begriffen. Sie können in einer Anforderung maximal 100 blocklistItems hinzufügen.

Kopieren Sie den nachstehenden cURL-Befehl in einen Text-Editor, und nehmen Sie folgende Änderungen vor:

  1. Ersetzen Sie <endpoint> durch Ihre Endpunkt-URL.
  2. Ersetzen Sie <enter_your_key_here> durch Ihren Schlüssel.
  3. Ersetzen Sie <your_list_name> (in der URL) durch den Namen, den Sie im Schritt zur Listenerstellung verwendet haben.
  4. Ersetzen Sie optional den Wert des Felds "description" durch eine benutzerdefinierte Beschreibung.
  5. Ersetzen Sie den Wert des Felds "text" durch den Begriff, den Sie Ihrer Sperrliste hinzufügen möchten. Ein blocklistItems darf maximal 128 Zeichen lang sein.
curl --location --request POST '<endpoint>/contentsafety/text/blocklists/<your_list_name>:addOrUpdateBlocklistItems?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <enter_your_key_here>' \
--header 'Content-Type: application/json' \
--data-raw '"blocklistItems": [{
    "description": "string",
    "text": "bleed"
}]'

Tipp

Sie können in einem API-Aufruf mehrere blocklistItems hinzufügen. Legen Sie den Anforderungstext als JSON-Array von Datengruppen fest:

{
   "blocklistItems": [
       {
           "description": "string",
           "text": "bleed"
       },
       {
           "description": "string",
           "text": "blood"
       }
   ]
}

Der Antwortcode muss 200 sein.

{
"blocklistItems:"[
  {
  "blocklistItemId": "string",
  "description": "string",
  "text": "bleed"
  
   }
 ]
}

Hinweis

Nachdem Sie ein blockItem hinzugefügt oder bearbeitet haben, gibt es eine gewisse Verzögerung, ehe es sich auf die Textanalyse auswirkt, die normalerweise länger als fünf Minuten dauert.

Analysieren von Text mit einer Sperrliste

Kopieren Sie den nachstehenden cURL-Befehl in einen Text-Editor, und nehmen Sie folgende Änderungen vor:

  1. Ersetzen Sie <endpoint> durch Ihre Endpunkt-URL.
  2. Ersetzen Sie <enter_your_key_here> durch Ihren Schlüssel.
  3. Ersetzen Sie <your_list_name> durch den Namen, den Sie im Schritt zur Listenerstellung verwendet haben. Das Feld "blocklistNames" kann ein Array mit mehreren Listen-IDs enthalten.
  4. Ändern Sie optional den Wert von "breakByBlocklists". true gibt an, dass die Analyse sofort ohne Modellausgabe zurückkehrt, sobald eine Sperrliste gefunden wurde. false bewirkt, dass das Modell weiterhin Analysen in den Standardkategorien durchführt.
  5. Ändern Sie optional den Wert des Felds "text" in einen beliebigen Text, den Sie analysieren möchten.
curl --location --request POST '<endpoint>/contentsafety/text:analyze?api-version=2024-09-01&' \
--header 'Ocp-Apim-Subscription-Key: <enter_your_key_here>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "text": "I want to beat you till you bleed",
  "categories": [
    "Hate",
    "Sexual",
    "SelfHarm",
    "Violence"
  ],
  "blocklistNames":["<your_list_name>"],
  "haltOnBlocklistHit": false,
  "outputType": "FourSeverityLevels"
}'

Die JSON-Antwort enthält ein "blocklistMatchResults" mit allen Übereinstimmungen mit Ihrer Sperrliste. Sie meldet die Position in der Textzeichenfolge, an der die Übereinstimmung gefunden wurde.

{
  "blocklistsMatch": [
    {
      "blocklistName": "string",
      "blocklistItemId": "string",
      "blocklistItemText": "bleed"
    }
  ],
  "categoriesAnalysis": [
    {
      "category": "Hate",
      "severity": 0
    }
  ]
}

Andere Sperrlistenvorgänge

Dieser Abschnitt enthält weitere Vorgänge, die Ihnen bei der Verwaltung und Verwendung des Features „Sperrliste“ helfen.

Auflisten aller blocklistItems in einer Liste

Kopieren Sie den nachstehenden cURL-Befehl in einen Text-Editor, und nehmen Sie folgende Änderungen vor:

  1. Ersetzen Sie <endpoint> durch Ihre Endpunkt-URL.
  2. Ersetzen Sie <enter_your_key_here> durch Ihren Schlüssel.
  3. Ersetzen Sie <your_list_name> (in der Anforderungs-URL) durch den Namen, den Sie im Schritt zur Listenerstellung verwendet haben.
curl --location --request GET '<endpoint>/contentsafety/text/blocklists/<your_list_name>/blocklistItems?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <enter_your_key_here>' \
--header 'Content-Type: application/json'

Der Statuscode sollte200 sein und der Antworttext wie folgt aussehen:

{
 "values": [
  {
   "blocklistItemId": "string",
   "description": "string",
   "text": "bleed",
  }
 ]
}

Auflisten aller Sperrlisten

Kopieren Sie den nachstehenden cURL-Befehl in einen Text-Editor, und nehmen Sie folgende Änderungen vor:

  1. Ersetzen Sie <endpoint> durch Ihre Endpunkt-URL.
  2. Ersetzen Sie <enter_your_key_here> durch Ihren Schlüssel.
curl --location --request GET '<endpoint>/contentsafety/text/blocklists?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <enter_your_key_here>' \
--header 'Content-Type: application/json'

Der Statuscode sollte 200 lauten. Die JSON-Antwort sieht wie folgt aus:

"value": [
  {
    "blocklistName": "string",
    "description": "string"
  }
]

Abrufen einer Blockliste nach blocklistName

Kopieren Sie den nachstehenden cURL-Befehl in einen Text-Editor, und nehmen Sie folgende Änderungen vor:

  1. Ersetzen Sie <endpoint> durch Ihre Endpunkt-URL.
  2. Ersetzen Sie <enter_your_key_here> durch Ihren Schlüssel.
  3. Ersetzen Sie <your_list_name> (in der Anforderungs-URL) durch den Namen, den Sie im Schritt zur Listenerstellung verwendet haben.
cURL --location '<endpoint>contentsafety/text/blocklists/<your_list_name>?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <enter_your_key_here>' \
--data ''

Der Statuscode sollte 200 lauten. Die JSON-Antwort sieht wie folgt aus:

{
  "blocklistName": "string",
  "description": "string"
}

Abrufen eines blocklistItem nach blocklistName und blocklistItemId

Kopieren Sie den nachstehenden cURL-Befehl in einen Text-Editor, und nehmen Sie folgende Änderungen vor:

  1. Ersetzen Sie <endpoint> durch Ihre Endpunkt-URL.
  2. Ersetzen Sie <enter_your_key_here> durch Ihren Schlüssel.
  3. Ersetzen Sie <your_list_name> (in der Anforderungs-URL) durch den Namen, den Sie im Schritt zur Listenerstellung verwendet haben.
  4. Ersetzen Sie <your_item_id> durch den ID-Wert für das blocklistItem. Dies ist der Wert des Felds "blocklistItemId" aus den API-Aufrufen zum Hinzufügen von blocklistItem oder Abrufen aller blocklistItems.
cURL --location '<endpoint>contentsafety/text/blocklists/<your_list_name>/blocklistItems/<your_item_id>?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <enter_your_key_here>' \
--data ''

Der Statuscode sollte 200 lauten. Die JSON-Antwort sieht wie folgt aus:

{
  "blocklistItemId": "string",
  "description": "string",
  "text": "string"
}
  1. Ersetzen Sie <your_list_name> durch den Namen, den Sie im Schritt zur Listenerstellung verwendet haben.
  2. Ersetzen Sie <your_block_item_id> durch die ID des Elements, das Sie abrufen möchten.
  3. Führen Sie das Skript aus.

Entfernen Sie blocklistItems aus einer Blockliste.

Hinweis

Nachdem Sie ein Element gelöscht haben, gibt es eine gewisse Verzögerung, ehe sich der Vorgang auf die Textanalyse auswirkt, die normalerweise nicht länger als fünf Minuten dauert.

Kopieren Sie den nachstehenden cURL-Befehl in einen Text-Editor, und nehmen Sie folgende Änderungen vor:

  1. Ersetzen Sie <endpoint> durch Ihre Endpunkt-URL.
  2. Ersetzen Sie <enter_your_key_here> durch Ihren Schlüssel.
  3. Ersetzen Sie <your_list_name> (in der Anforderungs-URL) durch den Namen, den Sie im Schritt zur Listenerstellung verwendet haben.
  4. Ersetzen Sie <item_id> durch den ID-Wert für das blocklistItem. Dies ist der Wert des Felds "blocklistItemId" aus den API-Aufrufen zum Hinzufügen von blocklistItem oder Abrufen aller blocklistItems.
curl --location --request POST '<endpoint>/contentsafety/text/blocklists/<your_list_name>:removeBlocklistItems?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <enter_your_key_here>' \
--header 'Content-Type: application/json'
--data-raw '"blocklistItemIds":[
    "<item_id>"
]'

Tipp

Sie können mehrere blocklistItem in einem API-Aufruf löschen. Legen Sie den Anforderungstext als Array von blocklistItemId-Werten fest.

Der Antwortcode muss 204 sein.

Löschen einer Liste und ihres gesamten Inhalts

Hinweis

Nachdem Sie eine Liste gelöscht haben, gibt es eine gewisse Verzögerung, ehe es sich dieser Vorgang auf die Textanalyse auswirkt, die normalerweise nicht länger als fünf Minuten dauert.

Kopieren Sie den nachstehenden cURL-Befehl in einen Text-Editor, und nehmen Sie folgende Änderungen vor:

  1. Ersetzen Sie <endpoint> durch Ihre Endpunkt-URL.
  2. Ersetzen Sie <enter_your_key_here> durch Ihren Schlüssel.
  3. Ersetzen Sie <your_list_name> (in der Anforderungs-URL) durch den Namen, den Sie im Schritt zur Listenerstellung verwendet haben.
curl --location --request DELETE '<endpoint>/contentsafety/text/blocklists/<your_list_name>?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <enter_your_key_here>' \
--header 'Content-Type: application/json' \

Der Antwortcode muss 204 sein.

Nächste Schritte

Weitere Informationen zu den in dieser Anleitung verwendeten APIs finden Sie in der API-Referenzdokumentation.