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:
- código-fonte
- do NPM (pacote)
- documentação de referência da API
- exemplos de
Introdução
Ambientes com suporte no momento
- Versões lts de Node.js
Pré-requisitos
- Você precisa de uma assinatura do Azure para usar esse pacote.
- Um recurso de Segurança de Conteúdo de IA do Azure, se não houver recurso existente, você poderá criar um novo.
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.
Azure SDK for JavaScript