Biblioteca de cliente REST do Azure AI Content Safety para JavaScript - versão 1.0.1

2025-02-22

de Segurança de Conteúdo de IA do Azure deteta conteúdo prejudicial gerado pelo usuário e gerado por IA em aplicativos e serviços. A Segurança de Conteúdo inclui APIs de texto e imagem que permitem detetar material prejudicial.

API de análise de texto: verifica o texto em busca de conteúdo sexual, violência, ódio e automutilação com vários níveis de gravidade.
API de análise de imagens: verifica imagens em busca de conteúdo sexual, violência, ódio e automutilação com vários níveis de gravidade.
APIs de gerenciamento de lista de bloqueio de texto: os classificadores de IA padrão são suficientes para a maioria das necessidades de segurança de conteúdo; no entanto, talvez seja necessário verificar os termos específicos do seu caso de uso. Você pode criar listas de bloqueio de termos para usar com a API de texto.

Por favor, confie muito em nossos documentos de cliente REST para usar esta biblioteca

Ligações principais:

Primeiros passos

Ambientes atualmente suportados

Versões LTS do Node.js

Pré-requisitos

Você precisa de um de assinatura do Azure para usar este pacote.
Um recurso de Segurança de Conteúdo da IA do Azure, se nenhum recurso existente, você poderá criar um novo.

Instalar o pacote `@azure-rest/ai-content-safety`

Instale a biblioteca de cliente REST do cliente REST do Azure AI Content Safety para JavaScript com npm:

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

Criar e autenticar um `ContentSafetyClient`

Obter o ponto de extremidade

Você pode encontrar o ponto de extremidade para seu recurso de serviço de Segurança de Conteúdo do Azure AI usando o do Portal do Azure ou da CLI do Azure :

# 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"

Criar um ContentSafetyClient com AzureKeyCredential

Etapa 1: Obter a chave da API

A chave da API pode ser encontrada no do Portal do Azure ou executando o seguinte comando da CLI do Azure:

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

Etapa 2: Criar um ContentSafetyClient com AzureKeyCredential

Para usar uma chave de API como o parâmetro credential, passe a chave como uma cadeia de caracteres para uma instância 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);

Criar um ContentSafetyClient com a credencial de token Microsoft Entra ID (anteriormente Azure Ative Directory (AAD))

Etapa 1: Habilitar o Microsoft Entra ID para seu recurso Consulte este documento de autenticação dos Serviços Cognitivos Autenticar com o Microsoft Entra ID. para as etapas para habilitar o AAD para seu recurso.

As principais etapas são:
- Crie um recurso com um subdomínio personalizado.
- Crie a Entidade de Serviço e atribua a função de Usuário de Serviços Cognitivos a ela.
Etapa 2: Defina os valores do ID do cliente, ID do locatário e segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET

Para autenticar com o AAD, você deve primeiro npm instalar @azure/identity. Após a configuração, você pode escolher qual tipo de credencial de @azure/identity usar. Como exemplo, DefaultAzureCredential pode ser usado para autenticar o cliente.

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

Conceitos-chave

Funcionalidades disponíveis

Existem diferentes tipos de análise disponíveis a partir deste serviço. A tabela a seguir descreve as APIs atualmente disponíveis.

Funcionalidade	Descrição
API de Análise de Texto	Analisa o texto em busca de conteúdo sexual, violência, ódio e automutilação com vários níveis de gravidade.
API de análise de imagem	Analisa imagens em busca de conteúdo sexual, violência, ódio e automutilação com vários níveis de gravidade.
APIs de gerenciamento de lista de bloqueio de texto	Os classificadores de IA padrão são suficientes para a maioria das necessidades de segurança de conteúdo. No entanto, talvez seja necessário verificar se há termos específicos para o seu caso de uso. Você pode criar listas de bloqueio de termos para usar com a API de texto.

Categorias de danos

A Segurança de Conteúdo reconhece quatro categorias distintas de conteúdo censurável.

Categoria	Descrição
Ódio	Ódio refere-se a qualquer conteúdo que ataque ou use linguagem pejorativa ou discriminatória em referência a uma pessoa ou grupo de identidade com base em certos atributos diferenciadores desse grupo. Isso inclui, mas não está limitado a, raça, etnia, nacionalidade, identidade e expressão de gênero, orientação sexual, religião, status de imigração, status de habilidade, aparência pessoal e tamanho do corpo.
Sexual	Sexual descreve conteúdo relacionado a órgãos anatômicos e genitais, relacionamentos românticos, atos retratados em termos eróticos ou afetivos, gravidez, atos sexuais físicos – incluindo aqueles retratados como uma agressão ou um ato sexual violento forçado contra a vontade –, prostituição, pornografia e abuso.
Violência	A violência descreve conteúdo relacionado a ações físicas destinadas a ferir, ferir, danificar ou matar alguém ou algo. Também inclui armas, armas e entidades relacionadas, como fabricantes, associações, legislação e similares.
Automutilação	Automutilação descreve conteúdo relacionado a ações físicas destinadas a ferir, ferir ou danificar propositalmente o corpo ou se matar.

A classificação pode ser multi-labeled. Por exemplo, quando uma amostra de texto passa pelo modelo de moderação de texto, ela pode ser classificada como Conteúdo sexual e Violência.

Níveis de severidade

Cada categoria de dano que o serviço aplica também vem com uma classificação de nível de gravidade. O nível de severidade destina-se a indicar a gravidade das consequências de mostrar o conteúdo sinalizado.

Text: A versão atual do modelo de texto suporta a escala de gravidade de 0 a 7 . Por padrão, a resposta produzirá 4 valores: 0, 2, 4 e 6. Cada dois níveis adjacentes são mapeados para um único nível. Os usuários podem usar "outputType" na solicitação e defini-lo como "EightSeverityLevels" para obter 8 valores na saída: 0,1,2,3,4,5,6,7. Você pode consultar texto, conteúdo, níveis de gravidade, definições para obter detalhes.

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

Image: A versão atual do modelo de imagem suporta a versão cortada da escala de gravidade completa de 0 a 7. O classificador só devolve as gravidades 0, 2, 4 e 6; Cada dois níveis adjacentes são mapeados para um único nível. Você pode consultar definições de níveis de severidade de conteúdo de imagem para obter detalhes.

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

Gerenciamento de lista de bloqueio de texto

As seguintes operações são suportadas para gerenciar sua lista de bloqueio de texto:

Criar ou modificar uma lista de bloqueio
Listar todas as listas de bloqueio
Obter uma lista de bloqueio por blocklistName
Adicionar blockItems a uma lista de bloqueio
Remover blockItems de uma lista de bloqueio
Listar todos os blockItems em uma lista de bloqueio por blocklistName
Obter um blockItem em uma lista de bloqueio por blockItemId e blocklistName
Excluir uma lista de bloqueio e todos os seus blockItems

Você pode definir as listas de bloqueio que deseja usar ao analisar o texto e, em seguida, obter o resultado da correspondência da lista de bloqueio da resposta retornada.

Exemplos

A seção a seguir fornece vários trechos de código que abrangem algumas das tarefas mais comuns do serviço de Segurança de Conteúdo em TypeScript e JavaScript, incluindo:

Analisar texto
Analisar de imagem
Gerenciar lista de bloqueio de texto

Analisar texto

Analisar texto sem listas de bloqueio

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

Analisar texto com listas de bloqueio

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

Analise a imagem

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

Gerenciar lista de bloqueio de texto

Criar ou atualizar lista de bloqueio de texto

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

Listar listas de bloqueio de texto

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

Obter lista de bloqueio de texto

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

Excluir lista de bloqueio de texto

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

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

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

Obter blockItem

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

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

Solução de problemas

Registo

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, você pode consultar os documentos do pacote @azure/logger.

Próximos passos

Documentação adicional

Para obter documentação mais abrangente sobre a Segurança de Conteúdo do Azure, consulte o de Segurança de Conteúdo do Azure AI no learn.microsoft.com.

Contribuição

Se você quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.