Compartilhar via


Biblioteca de clientes REST de Segurança de Conteúdo da IA do Azure para JavaScript – versão 1.0.1

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

  • API de Análise de Texto: verifica o texto em busca de conteúdo sexual, violência, ódio e automutilação com níveis de múltipla gravidade.
  • API de Análise de Imagem: verifica imagens de conteúdo sexual, violência, ódio e automutilação com níveis de multi severidade.
  • 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 examinar os termos específicos ao seu caso de uso. Você pode criar listas de bloqueios de termos a serem usados com a API de Texto.

Confie fortemente em nossos documentos de cliente REST para usar essa biblioteca

Links de chave:

Introdução

Ambientes com suporte no momento

  • Versões lts de Node.js

Pré-requisitos

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

Instale a biblioteca de clientes REST do cliente REST de Segurança de Conteúdo da IA do Azure 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 o recurso de serviço de Segurança de Conteúdo de IA do Azure usando o portal do Azure ou 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 a AzureKeyCredential

  • Etapa 1: Obter a chave de API

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

az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"
  • Etapa 2: Criar um ContentSafetyClient com a 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 do Microsoft Entra (antigo AAD (Azure Active Directory))

  • Etapa 1: Habilitar a ID do Microsoft Entra 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 dos Serviços Cognitivos a ela.
  • Etapa 2: Defina os valores da ID do cliente, da ID do locatário e do 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, primeiro você deve npm instalar @azure/identity. Após a instalação, você pode escolher qual tipo de de credencial@azure/identity usar. Por 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);

Principais conceitos

Recursos disponíveis

Há diferentes tipos de análise disponíveis nesse serviço. A tabela a seguir descreve as APIs disponíveis no momento.

Característica Descrição
API de Análise de Texto Examina o texto para conteúdo sexual, violência, ódio e automutilação com níveis de múltipla gravidade.
API de Análise de Imagem Verifica imagens de conteúdo sexual, violência, ódio e automutilação com níveis de múltipla gravidade.
APIs de Gerenciamento de Lista de Bloqueios 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 examinar os termos específicos ao seu caso de uso. Você pode criar listas de bloqueios de termos a serem usados 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
Odiar O ó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 determinados atributos diferenciais desse grupo. Isso inclui, mas não se limita à 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 O sexual descreve conteúdo relacionado a órgãos anatômicos e genitais, relações românticas, atos retratados em termos eróticos ou afetuosos, gravidez, atos sexuais físicos, incluindo aqueles atos retratados como uma agressão ou um ato violento sexual forçado contra a vontade, prostituição, pornografia e abuso.
Violência A violência descreve o conteúdo relacionado a ações físicas destinadas a ferir, ferir, danificar ou matar alguém ou algo assim. Também inclui armas, armas e entidades relacionadas, como fabricantes, associações, legislação e similares.
Automutilação A automutilação descreve o 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-rotulada. Por exemplo, quando um exemplo de texto passa pelo modelo de moderação de texto, ele pode ser classificado 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 severidade. O nível de gravidade destina-se a indicar a gravidade das consequências de mostrar o conteúdo sinalizado.

de Texto: a versão atual do modelo de texto dá suporte ao completo de escala de severidade 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 definições de níveis de severidade de conteúdo de texto para obter detalhes.

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

Image: a versão atual do modelo de imagem dá suporte à versão aparada docompleto de escala de severidade de 0 a 7. O classificador retorna apenas as severidades 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 bloqueios de texto

Há suporte para as seguintes operações para gerenciar sua lista de bloqueios de texto:

  • Criar ou modificar uma lista de bloqueios
  • Listar todas as listas de bloqueios
  • Obter uma lista de bloqueios por blocklistName
  • Adicionar blockItems a uma lista de bloqueios
  • Remover blockItems de uma lista de bloqueios
  • Listar todos os blockItems em uma lista de bloqueios por blocklistName
  • Obter um blockItem em uma lista de bloqueios por blockItemId e blocklistName
  • Excluir uma lista de bloqueios 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 bloqueios da resposta retornada.

Exemplos

A seção a seguir fornece vários snippets 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 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);
}

Analisar 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 bloqueios de texto

Criar ou atualizar a lista de bloqueios 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 bloqueios 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 bloqueios 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 bloqueios 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

Máquina

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

Solucionando problemas

Log

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 runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

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

Próximas etapas

Documentação adicional

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

Contribuindo

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