Compartilhar via

Biblioteca de clientes de Tradução de Documentos do Azure para Python – versão 1.0.0

  • Artigo

A Tradução de Documentos dos Serviços Cognitivos do Azure é um serviço de nuvem que pode ser usado para traduzir vários e complexos documentos entre idiomas e dialetos, preservando a estrutura original do documento e o formato de dados. Use a biblioteca de clientes para Tradução de Documentos para:

  • Traduza vários arquivos grandes de um contêiner de Armazenamento de Blobs do Azure para um contêiner de destino em seu idioma de escolha.
  • Verifique o status da tradução e o progresso de cada documento na operação de tradução.
  • Aplique um modelo de tradução personalizado ou glossários para personalizar a tradução para seu caso específico.

Código-fonte | Pacote (PyPI) | Documentação | de referência da APIDocumentação do produto | Amostras

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações e tirar dúvidas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

Instalar o pacote

Instale a biblioteca de clientes de Tradução de Documentos do Azure para Python com pip:

pip install azure-ai-translation-document

Observação: esta versão da biblioteca de clientes usa como padrão a versão v1.0 do serviço

Criar um recurso Tradutor

O recurso tradução de documento dá suporte apenas ao acesso de serviço único . Para acessar o serviço, crie um recurso de Tradutor.

Você pode criar o recurso usando

Opção 1:Portal do Azure

Opção 2:CLI do Azure. Veja abaixo um exemplo de como você pode criar um recurso de Tradutor usando a CLI:

# Create a new resource group to hold the Translator resource -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create document translation
az cognitiveservices account create \
    --name document-translation-resource \
    --custom-domain document-translation-resource \
    --resource-group my-resource-group \
    --kind TextTranslation \
    --sku S1 \
    --location westus2 \
    --yes

Autenticar o cliente

Para interagir com o serviço de recursos de Tradução de Documentos, você precisará criar uma instância de um cliente. Um ponto de extremidade e uma credencial são necessários para instanciar o objeto cliente.

Pesquisando o ponto de extremidade

Você pode encontrar o ponto de extremidade do recurso tradutor usando o Portal do Azure.

Observe que o serviço requer um ponto de extremidade de domínio personalizado. Siga as instruções no link acima para formatar seu ponto de extremidade: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Obter a chave de API

A chave de API pode ser encontrada no 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"

Criar o cliente com AzureKeyCredential

Para usar uma chave de API como parâmetro credential , passe a chave como uma cadeia de caracteres para uma instância do AzureKeyCredential.

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
document_translation_client = DocumentTranslationClient(endpoint, credential)

Criar o cliente com uma credencial do Azure Active Directory

AzureKeyCredential A autenticação é usada nos exemplos neste guia de introdução, mas você também pode autenticar com o Azure Active Directory usando a biblioteca de identidade do azure .

Para usar o tipo DefaultAzureCredential mostrado abaixo ou outros tipos de credencial fornecidos com o SDK do Azure, instale o azure-identity pacote:

pip install azure-identity

Você também precisará registrar um novo aplicativo do AAD e conceder acesso ao recurso tradutor atribuindo a "Cognitive Services User" função à entidade de serviço.

Depois de concluído, 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.

from azure.identity import DefaultAzureCredential
from azure.ai.translation.document import DocumentTranslationClient
credential = DefaultAzureCredential()

document_translation_client = DocumentTranslationClient(
    endpoint="https://<resource-name>.cognitiveservices.azure.com/",
    credential=credential
)

Principais conceitos

O serviço de Tradução de Documentos exige que você carregue seus arquivos em um contêiner de origem Armazenamento de Blobs do Azure e forneça um contêiner de destino em que os documentos traduzidos possam ser gravados. Informações adicionais sobre como configurar isso podem ser encontradas na documentação do serviço:

DocumentTranslationClient

A interação com a biblioteca de clientes de Tradução de Documentos começa com uma instância do DocumentTranslationClient. O cliente fornece operações para:

  • Criando uma operação de tradução para traduzir documentos em seus contêineres de origem e gravar resultados para os contêineres de destino.
  • Verificando o status de documentos individuais na operação de tradução e monitorando o progresso de cada documento.
  • Enumerando todas as operações de tradução passadas e atuais.
  • Identificando os formatos de glossário e documento com suporte.

Entrada de tradução

A entrada para o begin_translation método cliente pode ser fornecida de duas maneiras diferentes:

  1. Um único contêiner de origem com documentos pode ser traduzido para um idioma diferente:
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

document_translation_client = DocumentTranslationClient("<endpoint>", AzureKeyCredential("<api_key>"))
poller = document_translation_client.begin_translation("<sas_url_to_source>", "<sas_url_to_target>", "<target_language>")
  1. Ou várias fontes diferentes podem ser fornecidas cada uma com seus próprios destinos.
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget

my_input = [
    DocumentTranslationInput(
        source_url="<sas_url_to_source_A>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    ),
    DocumentTranslationInput(
        source_url="<sas_url_to_source_B>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    ),
    DocumentTranslationInput(
        source_url="<sas_url_to_source_C>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    )
]

document_translation_client = DocumentTranslationClient("<endpoint>", AzureKeyCredential("<api_key>"))
poller = document_translation_client.begin_translation(my_input)

Observação: o target_url para cada idioma de destino deve ser exclusivo.

Para traduzir documentos em uma pasta ou traduzir apenas determinados documentos, consulte sample_begin_translation_with_filters.py. Consulte a documentação do serviço para todos os idiomas com suporte.

Operações de Long-Running

Operações de execução prolongada são operações que consistem em uma solicitação inicial enviada ao serviço para iniciar uma operação, seguidas por sondar o serviço em intervalos para determinar se a operação foi concluída ou falhou e, se foi bem-sucedida, para obter o resultado.

Os métodos que convertem documentos são modelados como operações de execução prolongada. O cliente expõe um begin_<method-name> método que retorna um DocumentTranslationLROPoller ou AsyncDocumentTranslationLROPoller. Os chamadores devem aguardar a conclusão da operação chamando result() o objeto poller retornado do begin_<method-name> método . Snippets de código de exemplo são fornecidos para ilustrar o uso de operações de execução prolongada abaixo.

Exemplos

A seção a seguir fornece vários snippets de código que abrangem algumas das tarefas mais comuns de Tradução de Documentos, incluindo:

Traduzir seus documentos

Traduza todos os documentos no contêiner de origem para o contêiner de destino. Para traduzir documentos em uma pasta ou traduzir apenas determinados documentos, consulte sample_begin_translation_with_filters.py.

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
source_container_sas_url_en = "<sas-url-en>"
target_container_sas_url_es = "<sas-url-es>"

document_translation_client = DocumentTranslationClient(endpoint, credential)

poller = document_translation_client.begin_translation(source_container_sas_url_en, target_container_sas_url_es, "es")

result = poller.result()

print(f"Status: {poller.status()}")
print(f"Created on: {poller.details.created_on}")
print(f"Last updated on: {poller.details.last_updated_on}")
print(f"Total number of translations on documents: {poller.details.documents_total_count}")

print("\nOf total documents...")
print(f"{poller.details.documents_failed_count} failed")
print(f"{poller.details.documents_succeeded_count} succeeded")

for document in result:
    print(f"Document ID: {document.id}")
    print(f"Document status: {document.status}")
    if document.status == "Succeeded":
        print(f"Source document location: {document.source_document_url}")
        print(f"Translated document location: {document.translated_document_url}")
        print(f"Translated to language: {document.translated_to}\n")
    else:
        print(f"Error Code: {document.error.code}, Message: {document.error.message}\n")

Traduzir várias entradas

Comece a traduzir com documentos em vários contêineres de origem para vários contêineres de destino em diferentes idiomas.

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
source_container_sas_url_de = "<sas-url-de>"
source_container_sas_url_en = "<sas-url-en>"
target_container_sas_url_es = "<sas-url-es>"
target_container_sas_url_fr = "<sas-url-fr>"
target_container_sas_url_ar = "<sas-url-ar>"

document_translation_client = DocumentTranslationClient(endpoint, credential)

poller = document_translation_client.begin_translation(
    [
        DocumentTranslationInput(
            source_url=source_container_sas_url_en,
            targets=[
                TranslationTarget(target_url=target_container_sas_url_es, language="es"),
                TranslationTarget(target_url=target_container_sas_url_fr, language="fr"),
            ],
        ),
        DocumentTranslationInput(
            source_url=source_container_sas_url_de,
            targets=[
                TranslationTarget(target_url=target_container_sas_url_ar, language="ar"),
            ],
        )
    ]
)

result = poller.result()

for document in result:
    print(f"Document ID: {document.id}")
    print(f"Document status: {document.status}")
    if document.status == "Succeeded":
        print(f"Source document location: {document.source_document_url}")
        print(f"Translated document location: {document.translated_document_url}")
        print(f"Translated to language: {document.translated_to}\n")
    else:
        print(f"Error Code: {document.error.code}, Message: {document.error.message}\n")

Listar operações de tradução

Enumerar sobre as operações de tradução enviadas para o recurso.

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")

document_translation_client = DocumentTranslationClient(endpoint, credential)

operations = document_translation_client.list_translation_statuses()  # type: ItemPaged[TranslationStatus]

for operation in operations:
    print(f"\nID: {operation.id}")
    print(f"Status: {operation.status}")
    print(f"Created on: {operation.created_on}")
    print(f"Last updated on: {operation.last_updated_on}")
    print(f"Total number of translations on documents: {operation.documents_total_count}")
    print(f"Total number of characters charged: {operation.total_characters_charged}")

    print("Of total documents...")
    print(f"{operation.documents_failed_count} failed")
    print(f"{operation.documents_succeeded_count} succeeded")
    print(f"{operation.documents_canceled_count} canceled")

Para ver como usar a biblioteca de clientes de Tradução de Documentos com o Blob de Armazenamento do Azure para carregar documentos, crie tokens SAS para seus contêineres e baixe os documentos traduzidos concluídos, consulte este exemplo. Observe que você precisará instalar a biblioteca azure-storage-blob para executar este exemplo.

Tópicos avançados

A seção a seguir fornece alguns insights para alguns recursos avançados de tradução, como glossários e modelos de tradução personalizados.

Glossários

Glossários são dicionários específicos do domínio. Por exemplo, se você quiser traduzir alguns documentos relacionados à medicina, talvez precise de suporte para muitas palavras, terminologia e idiomas no campo médico que você não pode encontrar no dicionário de tradução padrão ou simplesmente precisa de tradução específica. É por isso que a Tradução de Documentos oferece suporte para glossários.

Como criar um arquivo de glossário

A Tradução de Documentos dá suporte a glossários nos seguintes formatos:

Tipo de arquivo Extensão Descrição Amostras
Valores separados por tabulação/TAB .tsv, .tab Leia mais sobre a wikipédia glossary_sample.tsv
Valores separados por vírgula .csv Leia mais sobre a wikipédia glossary_sample.csv
Formato de arquivo de intercâmbio de localização .xlf, .xliff Leia mais sobre a wikipédia glossary_sample.xlf

Veja todos os formatos com suporte aqui.

Como usar glossários na tradução de documentos

Para usar glossários com Tradução de Documentos, primeiro você precisa carregar seu arquivo de glossário em um contêiner de blob e, em seguida, fornecer a URL sas para o arquivo como nos exemplos de código sample_translation_with_glossaries.py.

Modelos de Tradução Personalizada

Em vez de usar o mecanismo de Tradução de Documentos para tradução, você pode usar seu próprio modelo personalizado de aprendizado de máquina/aprendizado profundo do Azure.

Como criar um modelo de tradução personalizada

Para obter mais informações sobre como criar, provisionar e implantar seu próprio modelo de tradução personalizado do Azure, siga as instruções aqui: Criar, implantar e usar um modelo personalizado para tradução

Como usar um modelo de tradução personalizada com tradução de documento

Para usar um modelo de tradução personalizada com Tradução de Documentos, primeiro você precisa criar e implantar seu modelo e, em seguida, seguir o exemplo de código sample_translation_with_custom_model.py para usar com a Tradução de Documentos.

Solução de problemas

Geral

A biblioteca de clientes de Tradução de Documentos gerará exceções definidas no Azure Core.

Log

Essa biblioteca usa a biblioteca de log padrão para registro em log.

Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no INFO nível.

O log de nível detalhado DEBUG , incluindo corpos de solicitação/resposta e cabeçalhos não redigidos , pode ser habilitado no cliente ou por operação com o logging_enable argumento de palavra-chave .

Confira a documentação completa de registro em log do SDK com exemplos aqui.

Configuração opcional

Argumentos opcionais de palavra-chave podem ser passados no nível do cliente e por operação. A documentação de referência do azure-core descreve as configurações disponíveis para repetições, registro em log, protocolos de transporte e muito mais.

Próximas etapas

A seção a seguir fornece vários snippets de código ilustrando padrões comuns usados na biblioteca de clientes do Python de Tradução de Documentos. Mais amostras podem ser encontradas no diretório de exemplos .

Mais códigos de exemplo

Esses exemplos de código mostram operações de cenário comuns com a biblioteca de clientes de Tradução de Documentos do Azure.

Exemplos assíncronos

Essa biblioteca também inclui um conjunto completo de APIs assíncronas. Para usá-los, primeiro você deve instalar um transporte assíncrono, como aiohttp. Os clientes assíncronos são encontrados no azure.ai.translation.document.aio namespace .

Documentação adicional

Para obter uma documentação mais abrangente sobre a Tradução de Documentos dos Serviços Cognitivos do Azure, consulte a documentação de Tradução de Documentos sobre docs.microsoft.com.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.