Share via

Biblioteca de clientes de tradução de documentos Azure para Python - versão 1.0.0

  • Artigo

Azure Cognitive Services Document Translation é um serviço de nuvem que pode ser usado para traduzir vários e complexos documentos através de idiomas e dialetos, preservando a estrutura original do documento e o formato de dados. Utilize a biblioteca do cliente para tradução de documentos para:

  • Traduza numerosos ficheiros grandes de um recipiente Armazenamento de Blobs do Azure para um recipiente-alvo no seu idioma de eleição.
  • Verifique o estado 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 adaptar a tradução ao seu caso específico.

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

Exclusão de Responsabilidade

O apoio aos pacotes Azure SDK Python para python 2.7 terminou em 01 de janeiro de 2022. Para mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

Instale o pacote

Instale a biblioteca de clientes de tradução de documentos Azure para Python com pip:

pip install azure-ai-translation-document

Nota: Esta versão da biblioteca do cliente está em incumprimento da versão v1.0 do serviço

Criar um recurso Tradutor

A funcionalidade de Tradução documental suporta apenas o acesso a um único serviço . Para aceder ao serviço, crie um recurso Tradutor.

Pode criar o recurso utilizando

Opção 1:Portal Azure

Opção 2:Azure CLI. Abaixo está um exemplo de como pode criar um recurso Tradutor utilizando o 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 funcionalidades de Tradução documental, terá de criar uma instância de um cliente. Um ponto final e credencial são necessários para instantaneaizar o objeto do cliente.

Olhando para o ponto final

Pode encontrar o ponto final do seu recurso Tradutor utilizando o Portal Azure.

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

Obtenha a chave API

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

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

Criar o cliente com AzureKeyCredential

Para utilizar uma chave API como credential parâmetro, passe a chave como uma corda para um exemplo de 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 Azure Ative Directory

AzureKeyCredential A autenticação é utilizada nos exemplos deste guia de arranque, mas também pode autenticar com o Azure Ative Directory utilizando a biblioteca de identidade azul .

Para utilizar o tipo DefaultAzureCredential apresentado abaixo, ou outros tipos de credenciais fornecidos com o Azure SDK, por favor instale a azure-identity embalagem:

pip install azure-identity

Também terá de registar uma nova aplicação AAD e conceder acesso ao seu recurso Tradutor atribuindo a "Cognitive Services User" função ao seu diretor de serviço.

Uma vez concluídos, decreta os valores do ID do cliente, identificação de inquilino e segredo de cliente da aplicação AAD como variáveis ambientais: 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
)

Conceitos-chave

O serviço de Tradução documental requer que faça o upload dos seus ficheiros para um recipiente de origem Armazenamento de Blobs do Azure e forneça um recipiente-alvo onde os documentos traduzidos possam ser escritos. Informações adicionais sobre a configuração desta configuração podem ser encontradas na documentação do serviço:

Transferência de DocumentosCliente

A interação com a biblioteca de clientes de tradução documental começa com um exemplo do DocumentTranslationClient. O cliente fornece operações para:

  • Criar uma operação de tradução para traduzir documentos no(s) contentor de origem e escrever resultados para o(s) contentor-alvo).
  • Verificação do estado dos documentos individuais na operação de tradução e monitorização dos progressos de cada documento.
  • Enumerando todas as operações de tradução passadas e atuais.
  • Identificação de formatos glossários e documentais suportados.

Entrada de tradução

A entrada no método do begin_translation cliente pode ser fornecida de duas maneiras diferentes:

  1. Um único recipiente de origem com documentos pode ser traduzido para uma língua 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 a cada um com os seus próprios alvos.
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)

Nota: a target_url para cada língua-alvo deve ser única.

Para traduzir documentos numa pasta, ou apenas traduzir determinados documentos, consulte sample_begin_translation_with_filters.py. Consulte a documentação de serviço para todas as línguas suportadas.

Operações Long-Running

As operações de longa duração são operações que consistem num pedido inicial enviado ao serviço para iniciar uma operação, seguida de sondagens ao serviço a intervalos para determinar se a operação foi concluída ou falhou, e se conseguiu, para obter o resultado.

Os métodos que traduzem documentos são modelados como operações de longa duração. O cliente expõe um begin_<method-name> método que devolve um DocumentTranslationLROPoller ou AsyncDocumentTranslationLROPoller. Os chamadores devem esperar que a operação esteja concluída, chamando result() o objeto poller devolvido do begin_<method-name> método. Os fragmentos de código de amostra são fornecidos para ilustrar a utilização de operações de longo prazo abaixo.

Exemplos

A secção seguinte fornece vários fragmentos de código que cobrem algumas das tarefas mais comuns de Tradução documental, incluindo:

Traduza os seus documentos

Traduza todos os documentos do seu recipiente de origem para o recipiente-alvo. Para traduzir documentos numa pasta, ou apenas traduzir 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 recipientes de origem para vários recipientes-alvo 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 submetidas 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 utilizar a biblioteca de clientes de Tradução documental com a Azure Storage Blob para carregar documentos, crie fichas SAS para os seus contentores e descarregue os documentos traduzidos acabados, consulte esta amostra. Note que terá de instalar a biblioteca azure-storage-blob para executar esta amostra.

Tópicos Avançados

A secção seguinte fornece algumas informações para algumas funcionalidades avançadas de tradução, tais como glossários e modelos de tradução personalizados.

Glossários

Glossários são dicionários específicos de domínio. Por exemplo, se quiser traduzir alguns documentos relacionados com a medicina, poderá precisar de apoio para as muitas palavras, terminologia e expressões no campo médico que não consegue encontrar no dicionário de tradução padrão, ou simplesmente precisa de tradução específica. É por isso que a Tradução documental fornece suporte para glossários.

Como criar ficheiro glossário

A Tradução documental suporta glossários nos seguintes formatos:

Tipo de Ficheiro Extensão Descrição Amostras
Tab-Separated Valores/TAB .tsv, .tab Ler mais na Wikipédia glossary_sample.tsv
Valores Comma-Separated .csv Ler mais na Wikipédia glossary_sample.csv
Formato de ficheiro de intercâmbio de localização .xlf, .xliff Ler mais na Wikipédia glossary_sample.xlf

Consulte todos os formatos suportados aqui.

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

Para utilizar glossários com tradução de documentos, primeiro tem de enviar o seu ficheiro glossário para um recipiente de bolhas e, em seguida, fornecer o URL SAS para o ficheiro como nas amostras de código sample_translation_with_glossaries.py.

Modelos de tradução personalizada

Em vez de utilizar o motor da Tradução documental para tradução, pode utilizar o seu próprio modelo de aprendizagem profunda e máquina Azure.

Como criar um modelo de tradução personalizada

Para obter mais informações sobre como criar, providenciar e implementar o seu próprio modelo de tradução Azure personalizado, siga as instruções aqui: Construa, implemente e use um modelo personalizado para tradução

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

Para utilizar um modelo de tradução personalizado com Tradução documental, primeiro é necessário criar e implementar o seu modelo, em seguida, seguir a amostra de código sample_translation_with_custom_model.py utilizar com Tradução documental.

Resolução de problemas

Geral

A biblioteca de clientes de tradução de documentos irá levantar exceções definidas no Núcleo Azure.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registar registos.

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

A registo de nível detalhado DEBUG , incluindo os órgãos de pedido/resposta e os cabeçalhos não redigidos , pode ser ativado no cliente ou por operação com o argumento da logging_enable palavra-chave.

Consulte a documentação completa do registo SDK com exemplos aqui.

Configuração opcional

Os argumentos de palavras-chave opcionais podem ser transmitidos ao cliente e ao nível por operação. A documentação de referência do núcleo azul descreve as configurações disponíveis para recaídas, registos, protocolos de transporte e muito mais.

Passos seguintes

A secção seguinte fornece vários fragmentos de código que ilustram padrões comuns usados na biblioteca do cliente de Tradução de Documentos Python. Mais amostras podem ser encontradas no diretório de amostras .

Mais código de amostra

Estas amostras de código mostram operações de cenário comum com a biblioteca de clientes de tradução de documentos Azure.

Amostras de async

Esta biblioteca também inclui um conjunto completo de APIs async. Para usá-los, primeiro deve instalar um transporte de async, como aiohttp. Os clientes async são encontrados sob o espaço de azure.ai.translation.document.aio nome.

Documentação adicional

Para documentação mais extensa sobre tradução de documentos de serviços cognitivos Azure, consulte a documentação de tradução documental sobre docs.microsoft.com.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para mais informações consulte o Código de Conduta FAQ ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.