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
- Sie benötigen ein Azure-Abonnement, um dieses Paket zu verwenden.
- Eine Azure AI Content Safety Ressource, wenn keine vorhandene Ressource vorhanden ist, könnten Sie eine neueerstellen.
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/identity
installieren. 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 info
fest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel
im @azure/logger
aktiviert 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.
Azure SDK for JavaScript