Azure AI Content Safety REST-clientbibliotheek voor JavaScript - versie 1.0.1

Azure AI Content Safety detecteert schadelijke door de gebruiker gegenereerde en DOOR AI gegenereerde inhoud in toepassingen en services. Content Safety bevat tekst- en afbeeldings-API's waarmee u materiaal kunt detecteren dat schadelijk is.

• Api voor tekstanalyse: scant tekst op seksuele inhoud, geweld, haat en zelfschadiging met niveaus met meerdere ernstniveaus.
• Afbeeldingsanalyse-API: scant afbeeldingen op seksuele inhoud, geweld, haat en zelfschadiging met niveaus met meerdere ernstniveaus.
• Text Blocklist Management API's: de standaard AI-classificaties zijn voldoende voor de meeste behoeften aan inhoudsveiligheid; Mogelijk moet u echter scherm maken voor termen die specifiek zijn voor uw use-case. U kunt blokkeringslijsten maken voor gebruik met de Text-API.

Vertrouw sterk op onze REST-clientdocumenten om deze bibliotheek te gebruiken

Sleutelkoppelingen:

• broncode
• Package (NPM)
• API-referentiedocumentatie
• voorbeelden

Slag

Momenteel ondersteunde omgevingen

• LTS-versies van Node.js

Voorwaarden

• U hebt een Azure-abonnement nodig om dit pakket te kunnen gebruiken.
• Een Azure AI Content Safety-resource, als er geen bestaande resource is, kunt u een nieuwemaken.

Het @azure-rest/ai-content-safety-pakket installeren

Installeer de AZURE AI Content Safety REST-clientbibliotheek voor REST-client voor JavaScript met npm:

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

Een ContentSafetyClient maken en verifiëren

Het eindpunt ophalen

U vindt het eindpunt voor uw Azure AI Content Safety-serviceresource met behulp van de Azure Portal of 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"

Een ContentSafetyClient maken met AzureKeyCredential

• Stap 1: de API-sleutel ophalen

De API-sleutel vindt u in de Azure Portal- of door de volgende Azure CLI opdracht uit te voeren:

az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"

• Stap 2: Een ContentSafetyClient maken met AzureKeyCredential

Als u een API-sleutel wilt gebruiken als de parameter credential, geeft u de sleutel als een tekenreeks door aan een exemplaar van 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);

Een ContentSafetyClient maken met Microsoft Entra ID -tokenreferenties (voorheen Azure Active Directory (AAD))

• Stap 1: Schakel Microsoft Entra-id voor uw resource in. Raadpleeg dit Cognitive Services-verificatiedocument Verifiëren met Microsoft Entra ID. voor de stappen voor het inschakelen van AAD voor uw resource.

  De belangrijkste stappen zijn:

  • Een resource maken met een aangepast subdomein.
  • Maak een service-principal en wijs de rol Cognitive Services-gebruiker eraan toe.

• Stap 2: Stel de waarden van de client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Als u wilt verifiëren met AAD, moet u eerst npm@azure/identityinstalleren. Na de installatie kunt u kiezen welk type referentie uit @azure/identity te gebruiken. Als voorbeeld kan DefaultAzureCredential- worden gebruikt om de client te verifiëren.

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

Sleutelbegrippen

Beschikbare functies

Er zijn verschillende soorten analyse beschikbaar vanuit deze service. In de volgende tabel worden de momenteel beschikbare API's beschreven.

Gelaatstrek	Beschrijving
Tekstanalyse-API	Scant tekst op seksuele inhoud, geweld, haat en zelfschadiging met niveaus met meerdere ernstniveaus.
Afbeeldingsanalyse-API	Scant afbeeldingen op seksuele inhoud, geweld, haat en zelfbeschadiging met meerdere ernstniveaus.
Text Blocklist Management API's	De standaard AI-classificaties zijn voldoende voor de meeste behoeften op het gebied van inhoudsveiligheid. Het is echter mogelijk dat u moet screenen op termen die specifiek zijn voor uw use-case. U kunt blokkeringslijsten maken voor gebruik met de Text-API.

Categorieën schade

Inhoudsveiligheid herkent vier verschillende categorieën aantootgevende inhoud.

Categorie	Beschrijving
Haten	Haat verwijst naar inhoud die een pejoratieve of discriminerende taal aanvalt of gebruikt in verwijzing naar een persoon of identiteitsgroep op basis van bepaalde differentiërende kenmerken van die groep. Dit omvat maar is niet beperkt tot ras, etniciteit, nationaliteit, genderidentiteit en expressie, seksuele geaardheid, religie, immigratiestatus, vaardigheidsstatus, persoonlijk uiterlijk en lichaamsgrootte.
Seksueel	Seksuele beschrijving van inhoud met betrekking tot anatomische organen en geslachtsdelen, romantische relaties, handelingen die worden weergegeven in erotische of genegenheidsvoorwaarden, zwangerschap, fysieke seksuele handelingen, waaronder die handelingen die worden weergegeven als een aanval of een gedwongen seksuele gewelddadige daad tegen de wil van één, prostitutie, pornografie en misbruik.
Geweld	Geweld beschrijft inhoud met betrekking tot fysieke acties die bedoeld zijn om iemand of iets te kwetsen, verwonden, beschadigen of doden. Het omvat ook wapens, wapens en gerelateerde entiteiten, zoals fabrikanten, verenigingen, wetgeving en soortgelijke.
Zelfschade	Zelfschade beschrijft inhoud met betrekking tot fysieke acties die zijn bedoeld om opzettelijk pijn te doen, verwonden of beschadigen van het lichaam of om zichzelf te doden.

Classificatie kan meerdere labels hebben. Wanneer een tekstvoorbeeld bijvoorbeeld het model voor tekstbeheer doorloopt, kan het worden geclassificeerd als seksuele inhoud en geweld.

Ernstniveaus

Elke schadecategorie die de service toepast, wordt ook geleverd met een classificatie op ernstniveau. Het ernstniveau is bedoeld om de ernst aan te geven van de gevolgen van het weergeven van de gemarkeerde inhoud.

Text: de huidige versie van het tekstmodel ondersteunt de volledige ernstschaal van 0-7. Het antwoord levert standaard 4 waarden op: 0, 2, 4 en 6. Elke twee aangrenzende niveaus worden toegewezen aan één niveau. Gebruikers kunnen 'outputType' in aanvraag gebruiken en instellen als 'EightSeverityLevels' om 8 waarden in uitvoer op te halen: 0,1,2,3,4,5,6,7. U kunt definities van ernstniveaus voor tekstinhoud raadplegen voor meer informatie.

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

Image: de huidige versie van het installatiekopiemodel ondersteunt de bijgesneden versie van de volledige ernstschaal van 0-7. De classificatie retourneert alleen ernst 0, 2, 4 en 6; elke twee aangrenzende niveaus worden toegewezen aan één niveau. Raadpleeg definities van ernstniveaus voor afbeeldingsinhoud voor meer informatie.

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

Beheer van blokkeringslijsten voor tekst

De volgende bewerkingen worden ondersteund voor het beheren van uw tekstblokkeringslijst:

• Een blokkeringslijst maken of wijzigen
• Alle blokkeringen weergeven
• Een blokkeringslijst ophalen op blocklistName
• BlockItems toevoegen aan een blokkeringslijst
• BlockItems verwijderen uit een blokkeringslijst
• Alle blockItems in een bloklijst weergeven op blocklistName
• Een blockItem ophalen in een blocklist door blockItemId en blocklistName
• Een blokkeringslijst en alle bijbehorende blockItems verwijderen

U kunt de blokkeringslijsten instellen die u wilt gebruiken bij het analyseren van tekst. Vervolgens kunt u het resultaat van de bloklijstovereenkomst ophalen uit het geretourneerde antwoord.

Voorbeelden

De volgende sectie bevat verschillende codefragmenten die betrekking hebben op enkele van de meest voorkomende Servicetaken voor Inhoudsveiligheid in zowel TypeScript- als JavaScript-, waaronder:

• Tekst analyseren
• Afbeelding analyseren
• Tekstbloklijst beheren

Tekst analyseren

Tekst analyseren zonder bloklijsten

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,
  );
}

Tekst analyseren met bloklijsten

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

Afbeelding analyseren

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,
  );
}

Tekstbloklijst beheren

Tekstbloklijst maken of bijwerken

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

Lijst met bloklijsten voor tekst

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,
    );
  }
}

Tekstbloklijst ophalen

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

Tekstbloklijst verwijderen

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

BlockItems toevoegen

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,
    );
  }
}

Lijst met 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 ophalen

TypeScript

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

BlockItems verwijderen

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

Probleemoplossing

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

Volgende stappen

Aanvullende documentatie

Zie de Azure AI Content Safety- op learn.microsoft.com voor uitgebreidere documentatie over Azure Content Safety.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.