Freigeben über


Rest-Clientbibliothek für Azure AI Content Safety für JavaScript – Version 1.0.1

Azure AI Content Safety erkennt schädliche, vom Benutzer generierte und KI generierte Inhalte in Anwendungen und Diensten. Die Inhaltssicherheit enthält Text- und Bild-APIs, mit denen Sie Material erkennen können, das schädlich ist.

  • Textanalyse-API: Überprüft Text auf sexuelle Inhalte, Gewalt, Hass und Selbstschäden mit mehreren Schweregraden.
  • Bildanalyse-API: Überprüft Bilder auf sexuelle Inhalte, Gewalt, Hass und Selbstschäden mit mehreren Schweregraden.
  • Textblocklistenverwaltungs-APIs: Die standardmäßigen KI-Klassifizierer sind für die meisten Anforderungen an die Inhaltssicherheit ausreichend; Möglicherweise müssen Sie jedoch nach Begriffen suchen, die für Ihren Anwendungsfall spezifisch sind. Sie können Blocklisten von Ausdrücken erstellen, die mit der Text-API verwendet werden sollen.

Verlassen Sie sich auf unsere REST-Clientdokumente, um diese Bibliothek

Wichtige Links:

Erste Schritte

Derzeit unterstützte Umgebungen

  • LTS-Versionen von Node.js

Voraussetzungen

Installieren des @azure-rest/ai-content-safety-Pakets

Installieren Sie die Rest-Client-REST-Clientbibliothek für Azure AI Content Safety für JavaScript mit npm:

npm install @azure-rest/ai-content-safety

Erstellen und Authentifizieren einer ContentSafetyClient

Abrufen des Endpunkts

Sie finden den Endpunkt für Ihre Azure AI Content Safety-Dienstressource mithilfe des Azure Portal oder Azure CLI:

# Get the endpoint for the Azure AI Content Safety service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"

Erstellen eines ContentSafetyClient mit AzureKeyCredential

  • Schritt 1: Abrufen des API-Schlüssels

Der API-Schlüssel befindet sich im Azure Portal oder führen Sie den folgenden befehl Azure CLI aus:

az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"
  • Schritt 2: Erstellen eines ContentSafetyClient mit AzureKeyCredential

Um einen API-Schlüssel als credential-Parameter zu verwenden, übergeben Sie den Schlüssel als Zeichenfolge an eine Instanz von AzureKeyCredential.

import { AzureKeyCredential } from "@azure/core-auth";
import ContentSafetyClient from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const key = "<api_key>";
const credential = new AzureKeyCredential(key);
const client = ContentSafetyClient(endpoint, credential);

Erstellen eines ContentSafetyClient mit Microsoft Entra ID (ehemals Azure Active Directory (AAD))-Tokenanmeldeinformationen

  • Schritt 1: Microsoft Entra ID für Ihre Ressource aktivieren Bitte lesen Sie dieses Dokument zur Authentifizierung von Cognitive Services Authentifizieren mit Microsoft Entra ID. für die Schritte zum Aktivieren von AAD für Ihre Ressource.

    Die wichtigsten Schritte sind:

    • Erstellen Sie eine Ressource mit einer benutzerdefinierten Unterdomäne.
    • Erstellen Sie Dienstprinzipal, und weisen Sie ihr die Rolle "Cognitive Services User" zu.
  • Schritt 2: Festlegen der Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Um sich bei AAD zu authentifizieren, müssen Sie zuerst npm@azure/identityinstallieren. Nach dem Setup können Sie auswählen, welche Art von Anmeldeinformationen von @azure/identity verwendet werden soll. Beispielsweise können DefaultAzureCredential- zum Authentifizieren des Clients verwendet werden.

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

Schlüsselkonzepte

Verfügbare Features

Es gibt verschiedene Arten von Analysen, die von diesem Dienst zur Verfügung stehen. In der folgenden Tabelle werden die derzeit verfügbaren APIs beschrieben.

Merkmal Beschreibung
Textanalyse-API Überprüft Text auf sexuelle Inhalte, Gewalt, Hass und Selbstschäden mit mehreren Schweregraden.
Bildanalyse-API Sucht Bilder nach sexuellen Inhalten, Gewalt, Hass und Selbstschäden mit mehreren Schweregraden.
Textblocklistenverwaltungs-APIs Die standardmäßigen KI-Klassifizierer sind für die meisten Anforderungen an die Inhaltssicherheit ausreichend. Möglicherweise müssen Sie jedoch nach Begriffen suchen, die für Ihren Anwendungsfall spezifisch sind. Sie können Blocklisten von Ausdrücken erstellen, die mit der Text-API verwendet werden sollen.

Kategorien schaden

Die Inhaltssicherheit erkennt vier verschiedene Kategorien von widerspruchsfähigen Inhalten an.

Kategorie Beschreibung
Hass Hass bezieht sich auf inhalte, die auf bestimmte Unterscheidungsattribute dieser Gruppe basierend auf bestimmten Unterscheidungsattributen dieser Gruppe angreifen oder eine diskriminierende oder diskriminierende Sprache verwenden. Dazu gehören unter anderem rasse, ethnische Zugehörigkeit, Nationalität, Geschlechtsidentität und Ausdruck, sexuelle Orientierung, Religion, Einwanderungsstatus, Status der Fähigkeit, persönliche Erscheinung und Körpergröße.
Sexuell Sexual beschreibt Inhalte im Zusammenhang mit anatomischen Organen und Genitalien, romantische Beziehungen, Handlungen, die in erotischen oder liebevollen Begriffen dargestellt werden, Schwangerschaft, körperliche sexuelle Handlungen – einschließlich der Handlungen, die als Angriff oder erzwungener sexueller Gewalt gegen den Willen eines Menschen dargestellt werden – Die Prostitution, Pornografie und Missbrauch.
Gewalt Gewalt beschreibt Inhalte im Zusammenhang mit körperlichen Handlungen, die dazu bestimmt sind, jemanden oder etwas zu verletzen, zu verletzen, zu schädigen oder zu töten. Sie umfasst auch Waffen, Waffen und verwandte Einrichtungen wie Hersteller, Verbände, Rechtsvorschriften und ähnliche.
Selbstschäden Selbstschäden beschreiben Inhalte im Zusammenhang mit körperlichen Handlungen, die beabsichtigt sind, zu verletzen, zu verletzen oder den Körper zu schädigen oder sich selbst zu töten.

Die Klassifizierung kann mit mehreren Bezeichnungen versehen werden. Wenn beispielsweise ein Textbeispiel das Textmoderationsmodell durchläuft, könnte es sowohl als sexueller Inhalt als auch als Gewalt klassifiziert werden.

Schweregrad

Jede Schadenkategorie, die der Dienst anwendet, enthält auch eine Bewertung auf Schweregrad. Der Schweregrad soll den Schweregrad der Folgen der Anzeige des gekennzeichneten Inhalts angeben.

Text-: Die aktuelle Version des Textmodells unterstützt die vollständige Schweregrad 0 bis 7. Standardmäßig gibt die Antwort 4 Werte aus: 0, 2, 4 und 6. Jeder zwei angrenzenden Ebenen wird einer einzelnen Ebene zugeordnet. Benutzer können "outputType" in der Anforderung verwenden und als "EightSeverityLevels" festlegen, um 8 Werte in der Ausgabe abzurufen: 0,1,2,3,4,5,6,7. Ausführliche Informationen finden Sie in Definitionen für textinhaltsschweregradige Ebenen.

  • [0,1] -> 0
  • [2,3] -> 2
  • [4,5] -> 4
  • [6,7] -> 6

Image-: Die aktuelle Version des Bildmodells unterstützt die gekürzte Version der vollständigen Schweregradskala 0 bis 7. Der Klassifizierer gibt nur schweregrade 0, 2, 4 und 6 zurück. jeder zwei angrenzenden Ebenen wird einer einzelnen Ebene zugeordnet. Weitere Informationen finden Sie in Definitionen für bildinhaltsschweregradige Ebenen.

  • [0,1] -> 0
  • [2,3] -> 2
  • [4,5] -> 4
  • [6,7] -> 6

Verwaltung von Textblocklisten

Folgende Vorgänge werden unterstützt, um Ihre Textblockliste zu verwalten:

  • Erstellen oder Ändern einer Blockliste
  • Alle Blocklisten auflisten
  • Abrufen einer Blockliste nach blocklistName
  • Hinzufügen von BlockItems zu einer Blockliste
  • Entfernen von BlockItems aus einer Blockliste
  • Auflisten aller blockItems in einer Blockliste nach blocklistName
  • Abrufen eines BlockItem in einer Blockliste durch blockItemId und blocklistName
  • Löschen einer Blockliste und aller zugehörigen BlockItems

Sie können die Blocklisten festlegen, die Sie beim Analysieren von Text verwenden möchten, und dann können Sie das Ergebnis der Blocklistenzuordnung aus der zurückgegebenen Antwort abrufen.

Beispiele

Der folgende Abschnitt enthält mehrere Codeausschnitte, die einige der am häufigsten verwendeten Aufgaben des Inhaltssicherheitsdiensts in TypeScript- und JavaScript-umfassen:

Analysieren von Text

Analysieren von Text ohne Blocklisten

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const text = "This is a sample text";
const analyzeTextOption = { text: text };
const analyzeTextParameters = { body: analyzeTextOption };

const result = await client.path("/text:analyze").post(analyzeTextParameters);

if (isUnexpected(result)) {
  throw result;
}

for (let i = 0; i < result.body.categoriesAnalysis.length; i++) {
  const textCategoriesAnalysisOutput = result.body.categoriesAnalysis[i];
  console.log(
    textCategoriesAnalysisOutput.category,
    " severity: ",
    textCategoriesAnalysisOutput.severity,
  );
}

Analysieren von Text mit Blocklisten

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, {
  CreateOrUpdateTextBlocklistParameters,
  isUnexpected,
} from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

async function createOrUpdateTextBlocklist() {
  const blocklistName = "TestBlocklist";
  const blocklistDescription = "Test blocklist management.";
  const createOrUpdateTextBlocklistParameters: CreateOrUpdateTextBlocklistParameters = {
    contentType: "application/merge-patch+json",
    body: {
      description: blocklistDescription,
    },
  };

  const result = await client
    .path("/text/blocklists/{blocklistName}", blocklistName)
    .patch(createOrUpdateTextBlocklistParameters);

  if (isUnexpected(result)) {
    throw result;
  }

  console.log(
    "Blocklist created or updated: Name",
    result.body.blocklistName,
    ", Description: ",
    result.body.description,
  );
}

async function addBlockItems() {
  const blocklistName = "TestBlocklist";
  const blockItemText1 = "sample";
  const blockItemText2 = "text";
  const addOrUpdateBlocklistItemsParameters = {
    body: {
      blocklistItems: [
        {
          description: "Test block item 1",
          text: blockItemText1,
        },
        {
          description: "Test block item 2",
          text: blockItemText2,
        },
      ],
    },
  };

  const result = await client
    .path("/text/blocklists/{blocklistName}:addOrUpdateBlocklistItems", blocklistName)
    .post(addOrUpdateBlocklistItemsParameters);

  if (isUnexpected(result)) {
    throw result;
  }

  console.log("Block items added: ");
  if (result.body.blocklistItems) {
    for (const blockItem of result.body.blocklistItems) {
      console.log(
        "BlockItemId: ",
        blockItem.blocklistItemId,
        ", Text: ",
        blockItem.text,
        ", Description: ",
        blockItem.description,
      );
    }
  }
}

async function analyzeTextWithBlocklists() {
  const blocklistName = "TestBlocklist";
  const inputText = "This is a sample to test text with blocklist.";
  const analyzeTextParameters = {
    body: {
      text: inputText,
      blocklistNames: [blocklistName],
      haltOnBlocklistHit: false,
    },
  };

  const result = await client.path("/text:analyze").post(analyzeTextParameters);

  if (isUnexpected(result)) {
    throw result;
  }

  console.log("Blocklist match results: ");
  if (result.body.blocklistsMatch) {
    for (const blocklistMatchResult of result.body.blocklistsMatch) {
      console.log(
        "BlocklistName: ",
        blocklistMatchResult.blocklistName,
        ", BlockItemId: ",
        blocklistMatchResult.blocklistItemId,
        ", BlockItemText: ",
        blocklistMatchResult.blocklistItemText,
      );
    }
  }
}

try {
  await createOrUpdateTextBlocklist();
  await addBlockItems();
  await analyzeTextWithBlocklists();
} catch (err) {
  console.error("The sample encountered an error:", err);
}

Bild analysieren

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";
import { readFileSync } from "node:fs";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const image_path = "./samples-dev/example-data/image.png";

const imageBuffer = readFileSync(image_path);
const base64Image = imageBuffer.toString("base64");
const analyzeImageOption = { image: { content: base64Image } };
const analyzeImageParameters = { body: analyzeImageOption };

const result = await client.path("/image:analyze").post(analyzeImageParameters);

if (isUnexpected(result)) {
  throw result;
}

for (let i = 0; i < result.body.categoriesAnalysis.length; i++) {
  const imageCategoriesAnalysisOutput = result.body.categoriesAnalysis[i];
  console.log(
    imageCategoriesAnalysisOutput.category,
    " severity: ",
    imageCategoriesAnalysisOutput.severity,
  );
}

Verwalten der Textblockliste

Erstellen oder Aktualisieren der Textblockliste

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, {
  CreateOrUpdateTextBlocklistParameters,
  isUnexpected,
} from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";
const blocklistDescription = "Test blocklist management.";
const createOrUpdateTextBlocklistParameters: CreateOrUpdateTextBlocklistParameters = {
  contentType: "application/merge-patch+json",
  body: {
    description: blocklistDescription,
  },
};

const result = await client
  .path("/text/blocklists/{blocklistName}", blocklistName)
  .patch(createOrUpdateTextBlocklistParameters);

if (isUnexpected(result)) {
  throw result;
}

console.log(
  "Blocklist created or updated: Name",
  result.body.blocklistName,
  ", Description: ",
  result.body.description,
);

Listentextblocklisten

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const result = await client.path("/text/blocklists").get();

if (isUnexpected(result)) {
  throw result;
}

console.log("List blocklists: ");
if (result.body.value) {
  for (const blocklist of result.body.value) {
    console.log(
      "BlocklistName: ",
      blocklist.blocklistName,
      ", Description: ",
      blocklist.description,
    );
  }
}

Textblockliste abrufen

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";

const result = await client.path("/text/blocklists/{blocklistName}", blocklistName).get();

if (isUnexpected(result)) {
  throw result;
}

console.log("Get blocklist: ");
console.log("Name: ", result.body.blocklistName, ", Description: ", result.body.description);

Textblockliste löschen

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";

const result = await client.path("/text/blocklists/{blocklistName}", blocklistName).delete();

if (isUnexpected(result)) {
  throw result;
}

console.log("Deleted blocklist: ", blocklistName);

Hinzufügen von BlockItems

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";
const blockItemText1 = "sample";
const blockItemText2 = "text";
const addOrUpdateBlocklistItemsParameters = {
  body: {
    blocklistItems: [
      {
        description: "Test block item 1",
        text: blockItemText1,
      },
      {
        description: "Test block item 2",
        text: blockItemText2,
      },
    ],
  },
};

const result = await client
  .path("/text/blocklists/{blocklistName}:addOrUpdateBlocklistItems", blocklistName)
  .post(addOrUpdateBlocklistItemsParameters);

if (isUnexpected(result)) {
  throw result;
}

console.log("Block items added: ");
if (result.body.blocklistItems) {
  for (const blockItem of result.body.blocklistItems) {
    console.log(
      "BlockItemId: ",
      blockItem.blocklistItemId,
      ", Text: ",
      blockItem.text,
      ", Description: ",
      blockItem.description,
    );
  }
}

Auflisten von BlockItems

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";

const result = await client
  .path("/text/blocklists/{blocklistName}/blocklistItems", blocklistName)
  .get();

if (isUnexpected(result)) {
  throw result;
}

console.log("List block items: ");
if (result.body.value) {
  for (const blockItem of result.body.value) {
    console.log(
      "BlockItemId: ",
      blockItem.blocklistItemId,
      ", Text: ",
      blockItem.text,
      ", Description: ",
      blockItem.description,
    );
  }
}

BlockItem abrufen

Maschinenschrift

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blockItemId = "<blockItemId>";
const blocklistName = "TestBlocklist";

const blockItem = await client
  .path(
    "/text/blocklists/{blocklistName}/blocklistItems/{blocklistItemId}",
    blocklistName,
    blockItemId,
  )
  .get();

if (isUnexpected(blockItem)) {
  throw blockItem;
}

console.log("Get blockitem: ");
console.log(
  "BlockItemId: ",
  blockItem.body.blocklistItemId,
  ", Text: ",
  blockItem.body.text,
  ", Description: ",
  blockItem.body.description,
);

Entfernen von blockItems

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blockItemId = "<blockItemId>";
const blocklistName = "TestBlocklist";
const blockItemText = "sample";

const removeBlocklistItemsParameters = {
  body: {
    blocklistItemIds: [blockItemId],
  },
};
const removeBlockItem = await client
  .path("/text/blocklists/{blocklistName}:removeBlocklistItems", blocklistName)
  .post(removeBlocklistItemsParameters);

if (isUnexpected(removeBlockItem)) {
  throw removeBlockItem;
}

console.log("Removed blockItem: ", blockItemText);

Fehlerbehebung

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Zusätzliche Dokumentation

Ausführlichere Dokumentation zu Azure Content Safety finden Sie in der Azure AI Content Safety zu learn.microsoft.com.

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.