Bibliothèque de client REST Azure AI Content Safety pour JavaScript - version 1.0.1

Azure AI Content Safety détecte le contenu généré par l’utilisateur et généré par l’IA dangereux dans les applications et les services. La sécurité du contenu inclut des API de texte et d’image qui vous permettent de détecter des éléments dangereux.

• API Analyse de texte : analyse le texte du contenu sexuel, de la violence, de la haine et du mal à des niveaux de gravité multiples.
• API Analyse d’images : analyse les images de contenu sexuel, de violence, de haine et d’auto-préjudice avec des niveaux de gravité multiples.
• API de gestion des listes de blocs de texte : les classifieurs IA par défaut sont suffisants pour la plupart des besoins en matière de sécurité du contenu ; toutefois, vous devrez peut-être rechercher des termes spécifiques à votre cas d’usage. Vous pouvez créer des listes de blocs de termes à utiliser avec l’API Texte.

S’il vous plaît s’appuyer fortement sur nos documents clients REST pour utiliser cette bibliothèque

Liens clés :

• code source
• package (NPM)
• Documentation de référence de l’API
• Exemples

Commencer

Environnements actuellement pris en charge

• Versions LTS de Node.js

Conditions préalables

• Vous avez besoin d’un abonnement Azure pour utiliser ce package.
• Une ressource Azure AI Content Safety, si aucune ressource existante n’est existante, vous pouvez créer une ressource.

Installer le package @azure-rest/ai-content-safety

Installez la bibliothèque de client REST rest azure AI Content Safety pour JavaScript avec npm:

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

Créer et authentifier un ContentSafetyClient

Obtenir le point de terminaison

Vous trouverez le point de terminaison de votre ressource de service Azure AI Content Safety à l’aide du du portail Azure ou 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"

Créer un ContentSafetyClient avec AzureKeyCredential

• Étape 1 : Obtenir la clé API

Vous trouverez la clé API dans portail Azure ou en exécutant la commande azure CLI suivante :

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

• Étape 2 : Créer un ContentSafetyClient avec AzureKeyCredential

Pour utiliser une clé API comme paramètre credential, passez la clé en tant que chaîne dans une instance de 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);

Créer un ContentSafetyClient avec les informations d’identification du jeton Microsoft Entra (anciennement Azure Active Directory (AAD))

• Étape 1 : Activez l’ID Microsoft Entra pour votre ressource Veuillez consulter ce document d’authentification Cognitive Services Authentifier avec l’ID Microsoft Entra. pour connaître les étapes permettant d’activer AAD pour votre ressource.

  Les étapes principales sont les suivantes :

  • Créez une ressource avec un sous-domaine personnalisé.
  • Créez le principal de service et attribuez-lui un rôle d’utilisateur Cognitive Services.

• Étape 2 : Définir les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Pour vous authentifier auprès d’AAD, vous devez d’abord npm installer @azure/identity. Après l’installation, vous pouvez choisir le type d’informations d’identification de @azure/identity à utiliser. Par exemple, DefaultAzureCredential pouvez être utilisé pour authentifier le client.

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

Concepts clés

Fonctionnalités disponibles

Il existe différents types d’analyse disponibles à partir de ce service. Le tableau suivant décrit les API actuellement disponibles.

Catégories de préjudices

Content Safety reconnaît quatre catégories distinctes de contenu répréhensible.

La classification peut être étiquetée à plusieurs étiquettes. Par exemple, lorsqu’un exemple de texte passe par le modèle de modération du texte, il peut être classé comme contenu sexuel et violence.

Niveaux de gravité

Chaque catégorie de préjudice que le service applique est également fournie avec une évaluation de niveau de gravité. Le niveau de gravité est destiné à indiquer la gravité des conséquences de l’affichage du contenu marqué.

texte : la version actuelle du modèle de texte prend en charge l’échelle de gravité complète de 0 à 7. Par défaut, la réponse génère 4 valeurs : 0, 2, 4 et 6. Chaque deux niveaux adjacents sont mappés à un seul niveau. Les utilisateurs peuvent utiliser « outputType » dans la requête et le définir comme « EightSeverityLevels » pour obtenir 8 valeurs dans la sortie : 0,1,2,3,4,5,6,7. Vous pouvez faire référence définitions de niveaux de gravité de contenu texte pour plus d’informations.

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

Image: la version actuelle du modèle d’image prend en charge la version rogné de l’échelle de gravité complète de 0 à 7. Le classifieur retourne uniquement les gravités 0, 2, 4 et 6 ; chacun des deux niveaux adjacents est mappé à un seul niveau. Vous pouvez faire référence définitions de niveaux de gravité de contenu d’image pour plus d’informations.

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

Gestion de la liste de blocs de texte

Les opérations suivantes sont prises en charge pour gérer votre liste de blocs de texte :

• Créer ou modifier une liste de blocs
• Répertorier toutes les listes de blocs
• Obtenir une liste de blocs par blocklistName
• Ajouter des blockItems à une liste de blocs
• Supprimer des blockItems d’une liste de blocs
• Répertorier tous les blockItems dans une liste de blocs par blocklistName
• Obtenir un blockItem dans une liste de blocs par blockItemId et blocklistName
• Supprimer une liste de blocs et tous ses blockItems

Vous pouvez définir les listes de blocs que vous souhaitez utiliser lors de l’analyse du texte, puis obtenir le résultat de la correspondance de liste de blocs à partir de la réponse retournée.

Exemples

La section suivante fournit plusieurs extraits de code couvrant certaines des tâches de service de sécurité du contenu les plus courantes dans typeScript et JavaScript, notamment :

• Analyser le texte
• Analyser l’image
• Gérer la liste de blocs de texte

Analyser du texte

Analyser du texte sans listes de blocs

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

Analyser du texte avec des listes de blocs

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

Analyser l’image

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

Gérer la liste de blocs de texte

Créer ou mettre à jour une liste de blocs de texte

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

Lister les listes de blocs de texte

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

Obtenir la liste de blocs de texte

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

Supprimer la liste de blocs de texte

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

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

Répertorier les 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,
    );
  }
}

Get blockItem

Tapuscrit

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

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

Dépannage

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentation du package@azure/enregistreur d’événements.

Étapes suivantes

Documentation supplémentaire

Pour obtenir une documentation plus complète sur Azure Content Safety, consultez la Azure AI Content Safety sur learn.microsoft.com.

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.