Instalar e executar contentores de Reconhecimento de Entidades Nomeadas Personalizadas

Os contentores permitem-lhe alojar a API de Reconhecimento de Entidades Nomeadas Personalizadas na sua própria infraestrutura com o seu próprio modelo preparado. Se tiver requisitos de segurança ou governação de dados que não podem ser cumpridos ao chamar remotamente o Reconhecimento de Entidades Nomeadas Personalizadas, os contentores poderão ser uma boa opção.

Nota

• A conta gratuita está limitada a 5000 registos de texto por mês e apenas os escalões de preçoGratuito e Standard são válidos para contentores. Para obter mais informações sobre as taxas de pedidos de transação, veja Limites de dados e serviços.

Pré-requisitos

• Se não tiver uma subscrição do Azure, crie uma conta gratuita.
• Docker instalado num computador anfitrião. O Docker tem de ser configurado para permitir que os contentores se liguem e enviem dados de faturação para o Azure.
  • No Windows, o Docker também tem de ser configurado para suportar contentores do Linux.
  • Deve ter uma compreensão básica dos conceitos do Docker.
• Um recurso Language com o escalão de preço gratuito (F0) ou standard (S).
• Um modelo de Reconhecimento de Entidades Nomeadas Personalizadas, preparado e implementado

Recolher os parâmetros necessários

São necessários três parâmetros principais para todos os contentores de IA do Azure. Os Termos de Licenciamento para Software Microsoft têm de estar presentes com um valor de aceitação. Também é necessário um URI de Ponto Final e uma chave de API.

URI do ponto final

O {ENDPOINT_URI} valor está disponível na página Descrição geral do portal do Azure do recurso de serviços de IA do Azure correspondente. Aceda à página Descrição geral , paire o cursor sobre o ponto final e é apresentado um ícone Copiar para a área de transferência . Copie e utilize o ponto final sempre que necessário.

Chaves

O {API_KEY} valor é utilizado para iniciar o contentor e está disponível na página Chaves do portal do Azure do recurso de serviços do Azure AI correspondente. Aceda à página Chaves e selecione o ícone Copiar para a área de transferência .

Importante

Estas chaves de subscrição são utilizadas para aceder à sua API de serviços de IA do Azure. Não partilhe as suas chaves. Armazene-os de forma segura. Por exemplo, utilize o Azure Key Vault. Também recomendamos que volte a gerar estas chaves regularmente. Só é necessária uma chave para fazer uma chamada à API. Quando regenerar a primeira chave, pode utilizar a segunda chave para continuar a aceder ao serviço.

Requisitos e recomendações do computador anfitrião

O anfitrião é um computador baseado em x64 que executa o contentor do Docker. Pode ser um computador no local ou um serviço de alojamento do Docker no Azure, como:

• Azure Kubernetes Service.
• Azure Container Instances.
• Um cluster do Kubernetes implementado no Azure Stack. Para obter mais informações, veja Implementar o Kubernetes no Azure Stack.

A tabela seguinte descreve as especificações mínimas e recomendadas para contentores de Reconhecimento de Entidades Nomeadas Personalizadas. Cada núcleo de CPU tem de ter, pelo menos, 2,6 gigahertz (GHz) ou mais rápido. As Transações Permitidos Por Segundo (TPS) também estão listadas.

	Especificações mínimas do anfitrião	Especificações de anfitrião recomendadas	TPS Mínimo	TPS Máximo
Reconhecimento de Entidades Nomeadas Personalizadas	Memória de 1 núcleo e 2 GB	Memória de 1 núcleo e 4 GB	15	30

O núcleo e a memória da CPU correspondem às --cpus definições e --memory , que são utilizadas como parte do docker run comando .

Exportar o modelo de Reconhecimento de Entidades Nomeadas Personalizadas

Antes de continuar a executar a imagem do Docker, terá de exportar o seu próprio modelo preparado para expô-lo no seu contentor. Utilize o seguinte comando para extrair o modelo e substituir os marcadores de posição abaixo pelos seus próprios valores:

Marcador de posição	Valor	Formato ou exemplo
{API_KEY}	A chave para o recurso de Reconhecimento de Entidades Nomeadas Personalizadas. Pode encontrá-lo na página Chave e ponto final do recurso, no portal do Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI}	O ponto final para aceder à API de Reconhecimento de Entidades Nomeadas Personalizadas. Pode encontrá-lo na página Chave e ponto final do recurso, no portal do Azure.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT_NAME}	O nome do projeto que contém o modelo que pretende exportar. Pode encontrá-lo no separador Projetos no portal do Language Studio.	myProject
{TRAINED_MODEL_NAME}	O nome do modelo preparado que pretende exportar. Pode encontrar os seus modelos preparados no separador de avaliação do modelo no seu projeto no portal do Language Studio.	myTrainedModel

curl --location --request PUT '{ENDPOINT_URI}/language/authoring/analyze-text/projects/{PROJECT_NAME}/exported-models/{TRAINED_MODEL_NAME}?api-version=2023-04-15-preview' \
--header 'Ocp-Apim-Subscription-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "TrainedmodelLabel": "{TRAINED_MODEL_NAME}"
}'

Obter a imagem de contentor com docker pull

A imagem do contentor Reconhecimento de Entidades Nomeadas Personalizadas pode ser encontrada no sindicato do mcr.microsoft.com registo de contentores. Reside no azure-cognitive-services/textanalytics/ repositório e chama-se customner. O nome da imagem de contentor completamente qualificado é . mcr.microsoft.com/azure-cognitive-services/textanalytics/customner

Para utilizar a versão mais recente do contentor, pode utilizar a latest etiqueta . Também pode encontrar uma lista completa de etiquetas no MCR.

Utilize o docker pull comando para transferir uma imagem de contentor do Microsoft Container Registry.

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/customner:latest

Dica

Pode utilizar o comando docker images para listar as imagens de contentor transferidas. Por exemplo, o comando seguinte lista o ID, o repositório e a etiqueta de cada imagem de contentor transferida, formatada como uma tabela:

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

Executar o contentor com docker run

Quando o contentor estiver no computador anfitrião, utilize o comando docker run para executar os contentores. O contentor continuará a ser executado até o parar.

Importante

• Os comandos do Docker nas secções seguintes utilizam a barra anterior, \, como caráter de continuação de linha. Substitua ou remova-o com base nos requisitos do sistema operativo anfitrião.
• As Eulaopções , Billinge ApiKey têm de ser especificadas para executar o contentor; caso contrário, o contentor não será iniciado. Para obter mais informações, veja Faturação.

Para executar o contentor Reconhecimento de Entidades Nomeadas Personalizadas , execute o seguinte docker run comando. Substitua os marcadores de posição abaixo pelos seus próprios valores:

Marcador de posição	Valor	Formato ou exemplo
{API_KEY}	A chave para o recurso de Reconhecimento de Entidades Nomeadas Personalizadas. Pode encontrá-lo na página Chave e ponto final do recurso, no portal do Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI}	O ponto final para aceder à API de Reconhecimento de Entidades Nomeadas Personalizadas. Pode encontrá-lo na página Chave e ponto final do recurso, no portal do Azure.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT_NAME}	O nome do projeto que contém o modelo que pretende exportar. Pode encontrá-lo no separador Projetos no portal do Language Studio.	myProject
{LOCAL_PATH}	O caminho no qual o modelo exportado no passo anterior será transferido. Pode escolher qualquer caminho do seu agrado.	C:/custom-ner-model
{TRAINED_MODEL_NAME}	O nome do modelo preparado que pretende exportar. Pode encontrar os seus modelos preparados no separador de avaliação do modelo no seu projeto no portal do Language Studio.	myTrainedModel

docker run --rm -it -p5000:5000  --memory 4g --cpus 1 \
-v {LOCAL_PATH}:/modelPath \
mcr.microsoft.com/azure-cognitive-services/textanalytics/customner:latest \
EULA=accept \
BILLING={ENDPOINT_URI} \
APIKEY={API_KEY} \
projectName={PROJECT_NAME}
exportedModelName={TRAINED_MODEL_NAME}

Este comando:

• Executa um contentor de Reconhecimento de Entidades Nomeadas Personalizadas e transfere o modelo exportado para o caminho local especificado.
• Atribui um núcleo de CPU e 4 gigabytes (GB) de memória
• Expõe a porta TCP 5000 e aloca um pseudo-TTY para o contentor
• Remove automaticamente o contentor depois de sair. A imagem de contentor ainda está disponível no computador anfitrião.

Executar vários contentores no mesmo anfitrião

Se pretender executar vários contentores com portas expostas, certifique-se de que executa cada contentor com uma porta exposta diferente. Por exemplo, execute o primeiro contentor na porta 5000 e o segundo contentor na porta 5001.

Pode ter este contentor e um contentor de serviços do Azure AI diferente em execução no HOST em conjunto. Também pode ter vários contentores do mesmo contentor de serviços de IA do Azure em execução.

Consultar o ponto final de predição do contentor

O contentor fornece APIs de ponto final de predição de consulta com base em REST.

Utilize o anfitrião, http://localhost:5000, para APIs de contentor.

Validar que um contentor está em execução

Existem várias formas de validar que o contentor está em execução. Localize o Endereço IP externo e a porta exposta do contentor em questão e abra o seu browser favorito. Utilize os vários URLs de pedido que se seguem para validar que o contentor está em execução. Os URLs de pedido de exemplo listados aqui são http://localhost:5000, mas o contentor específico pode variar. Certifique-se de que depende do endereço IP externo do contentor e da porta exposta.

URL do Pedido	Objetivo
http://localhost:5000/	O contentor fornece uma home page.
http://localhost:5000/ready	Pedido com GET, este URL fornece uma verificação de que o contentor está pronto para aceitar uma consulta em relação ao modelo. Este pedido pode ser utilizado para pesquisas de liveness e preparação do Kubernetes.
http://localhost:5000/status	Também solicitado com GET, este URL verifica se a chave de API utilizada para iniciar o contentor é válida sem causar uma consulta de ponto final. Este pedido pode ser utilizado para pesquisas de liveness e preparação do Kubernetes.
http://localhost:5000/swagger	O contentor fornece um conjunto completo de documentação para os pontos finais e uma funcionalidade Experimentar. Com esta funcionalidade, pode introduzir as suas definições num formulário HTML baseado na Web e fazer a consulta sem ter de escrever código. Após a devolução da consulta, é fornecido um comando CURL de exemplo para demonstrar os cabeçalhos HTTP e o formato do corpo necessários.

Parar o contentor

Para encerrar o contentor, no ambiente da linha de comandos onde o contentor está em execução, selecione Ctrl+C.

Resolução de problemas

Se executar o contentor com uma montagem e registo de saída ativados, o contentor gera ficheiros de registo que são úteis para resolver problemas que ocorrem ao iniciar ou executar o contentor.

Dica

Para obter mais informações e documentação de orientação sobre a resolução de problemas, veja Perguntas mais frequentes (FAQ) sobre contentores de IA do Azure.

Faturação

Os contentores de Reconhecimento de Entidades Nomeadas Personalizadas enviam informações de faturação para o Azure através de um recurso de Reconhecimento de Entidades Nomeadas Personalizadas na sua conta do Azure.

As consultas ao contentor são faturadas no escalão de preço do recurso do Azure utilizado para o ApiKey parâmetro .

Os contentores dos serviços de IA do Azure não estão licenciados para serem executados sem estarem ligados ao ponto final de medição ou faturação. Tem de permitir que os contentores comuniquem sempre informações de faturação com o ponto final de faturação. Os contentores dos serviços de IA do Azure não enviam dados de clientes, como a imagem ou texto que está a ser analisado, para a Microsoft.

Ligar ao Azure

O contentor precisa dos valores do argumento de faturação para ser executado. Estes valores permitem que o contentor se ligue ao ponto final de faturação. O contentor comunica a utilização a cada 10 a 15 minutos. Se o contentor não se ligar ao Azure dentro do período de tempo permitido, o contentor continua a ser executado, mas não serve consultas até que o ponto final de faturação seja restaurado. A ligação é tentada 10 vezes ao mesmo intervalo de tempo de 10 a 15 minutos. Se não conseguir ligar ao ponto final de faturação nas 10 tentativas, o contentor deixa de servir pedidos. Veja as FAQ sobre o contentor dos serviços de IA do Azure para obter um exemplo das informações enviadas à Microsoft para faturação.

Argumentos de faturação

O docker run comando iniciará o contentor quando as três opções seguintes forem fornecidas com valores válidos:

Opção	Descrição
ApiKey	A chave de API do recurso dos serviços de IA do Azure que é utilizado para controlar as informações de faturação. O valor desta opção tem de ser definido como uma chave de API para o recurso aprovisionado especificado em Billing.
Billing	O ponto final do recurso dos serviços de IA do Azure que é utilizado para controlar as informações de faturação. O valor desta opção tem de ser definido como o URI do ponto final de um recurso do Azure aprovisionado.
Eula	Indica que aceitou a licença do contentor. O valor desta opção tem de ser definido para aceitar.

Resumo

Neste artigo, aprendeu conceitos e fluxos de trabalho para transferir, instalar e executar contentores de Reconhecimento de Entidades Nomeadas Personalizadas. Em resumo:

• O Reconhecimento de Entidades Nomeadas Personalizadas fornece contentores do Linux para o Docker.
• As imagens de contentor são transferidas a partir do Microsoft Container Registry (MCR).
• As imagens de contentor são executadas no Docker.
• Pode utilizar a API REST ou o SDK para chamar operações em contentores de Reconhecimento de Entidades Nomeadas Personalizadas ao especificar o URI do anfitrião do contentor.
• Tem de especificar informações de faturação ao instanciar um contentor.

Importante

Os contentores de IA do Azure não estão licenciados para serem executados sem estarem ligados ao Azure para medição. Os clientes têm de permitir que os contentores comuniquem sempre informações de faturação com o serviço de medição. Os contentores de IA do Azure não enviam dados de clientes (por exemplo, texto que está a ser analisado) para a Microsoft.

Passos seguintes

• Veja Configurar contentores para definições de configuração.