Biblioteca de clientes de tradução de documentos Azure para Python - versão 1.0.0
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
- Python 3.6 ou mais tarde é necessário para usar este pacote.
- Você deve ter uma assinatura Azure e um recurso Tradutor para usar este pacote.
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:
- Configurar recipientes Armazenamento de Blobs do Azure com os seus documentos
- Aplicar opcionalmente glossários ou um modelo personalizado para tradução
- Permitir o acesso à sua conta de armazenamento com qualquer uma das seguintes opções:
- Gerem fichas SAS nos seus contentores (ou ficheiros) com as permissões apropriadas
- Crie e use uma identidade gerida para conceder acesso à sua conta de armazenamento
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:
- 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>")
- 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.
- Autenticação do cliente: sample_authentication.py
- Comece a traduzir documentos: sample_begin_translation.py
- Traduzir com várias entradas: sample_translate_multiple_inputs.py
- Verifique o estado dos documentos: sample_check_document_statuses.py
- Listar todas as operações de tradução submetidas: sample_list_translations.py
- Aplicar um glossário habitual à tradução: sample_translation_with_glossaries.py
- Utilize Armazenamento de Blobs do Azure para criar recursos de tradução: sample_translation_with_azure_blob.py
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.
- Autenticação do cliente: sample_authentication_async.py
- Comece a traduzir documentos: sample_begin_translation_async.py
- Traduzir com várias entradas: sample_translate_multiple_inputs_async.py
- Verifique o estado dos documentos: sample_check_document_statuses_async.py
- Listar todas as operações de tradução submetidas: sample_list_translations_async.py
- Aplicar um glossário habitual à tradução: sample_translation_with_glossaries_async.py
- Utilize Armazenamento de Blobs do Azure para criar recursos de tradução: sample_translation_with_azure_blob_async.py
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.
Azure SDK for Python