Biblioteca cliente de Azure Document Translation para Python: versión 1.0.0

  • Artículo

La traducción de documentos de Azure Cognitive Services es un servicio en la nube que se puede usar para traducir varios y complejos documentos entre idiomas y dialectos, a la vez que se conserva la estructura original del documento y el formato de datos. Use la biblioteca cliente para traducción de documentos para:

  • Traducir numerosos archivos grandes de un contenedor de Azure Blob Storage a un contenedor de destino en el idioma que prefiera.
  • Compruebe el estado de traducción y el progreso de cada documento en la operación de traducción.
  • Aplique un modelo de traducción personalizado o glosarios para adaptar la traducción a su caso específico.

Código | fuente Paquete (PyPI) | Documentación | de referencia de APIDocumentación | del producto Muestras

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure para Python 2.7 finalizaron el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Introducción

Requisitos previos

Instalar el paquete

Instale la biblioteca cliente de Azure Document Translation para Python con pip:

pip install azure-ai-translation-document

Nota: Esta versión de la biblioteca cliente tiene como valor predeterminado la versión v1.0 del servicio.

Creación de un recurso de Traductor

La característica Traducción de documentos solo admite el acceso de un solo servicio . Para acceder al servicio, cree un recurso de Translator.

Puede crear el recurso mediante .

Opción 1:Azure Portal

Opción 2:CLI de Azure. A continuación se muestra un ejemplo de cómo puede crear un recurso de Translator mediante la 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 el cliente

Para interactuar con el servicio de características traducción de documentos, deberá crear una instancia de un cliente. Se necesita un punto de conexión y una credencial para crear una instancia del objeto de cliente.

Búsqueda del punto de conexión

Puede encontrar el punto de conexión del recurso translator mediante Azure Portal.

Tenga en cuenta que el servicio requiere un punto de conexión de dominio personalizado. Siga las instrucciones del vínculo anterior para dar formato al punto de conexión: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Obtención de la clave de API

La clave de API se puede encontrar en Azure Portal o mediante la ejecución del siguiente comando de la CLI de Azure:

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

Creación del cliente con AzureKeyCredential

Para usar una clave de API como credential parámetro, pase la clave como una cadena a una instancia 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)

Creación del cliente con una credencial de Azure Active Directory

AzureKeyCredential La autenticación se usa en los ejemplos de esta guía de introducción, pero también puede autenticarse con Azure Active Directory mediante la biblioteca azure-identity .

Para usar el tipo DefaultAzureCredential que se muestra a continuación u otros tipos de credenciales proporcionados con el SDK de Azure, instale el azure-identity paquete:

pip install azure-identity

También tendrá que registrar una nueva aplicación de AAD y conceder acceso al recurso de Translator mediante la asignación del rol a la "Cognitive Services User" entidad de servicio.

Una vez completado, establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_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
)

Conceptos clave

El servicio Traducción de documentos requiere que cargue los archivos en un contenedor de origen Azure Blob Storage y proporcione un contenedor de destino donde se puedan escribir los documentos traducidos. Puede encontrar información adicional sobre cómo configurar esta opción en la documentación del servicio:

DocumentTranslationClient

La interacción con la biblioteca cliente de traducción de documentos comienza con una instancia de .DocumentTranslationClient El cliente proporciona operaciones para:

  • Crear una operación de traducción para traducir documentos en los contenedores de origen y escribir resultados en los contenedores de destino.
  • Comprobar el estado de los documentos individuales en la operación de traducción y supervisar el progreso de cada documento.
  • Enumerar todas las operaciones de traducción pasadas y actuales.
  • Identificación de los formatos de documento y glosario admitidos.

Entrada de traducción

La entrada al begin_translation método cliente se puede proporcionar de dos maneras diferentes:

  1. Un único contenedor de origen con documentos se puede traducir a otro idioma:
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. O se pueden proporcionar varios orígenes diferentes cada uno con sus propios 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)

Nota: el target_url para cada idioma de destino debe ser único.

Para traducir documentos en una carpeta o traducir solo determinados documentos, consulte sample_begin_translation_with_filters.py. Consulte la documentación del servicio para todos los idiomas admitidos.

Operaciones de Long-Running

Las operaciones de larga duración son operaciones que constan de una solicitud inicial enviada al servicio para iniciar una operación, seguidas de sondear el servicio a intervalos para determinar si la operación se ha completado o no, y si se ha realizado correctamente, para obtener el resultado.

Los métodos que traducen documentos se modelan como operaciones de larga duración. El cliente expone un begin_<method-name> método que devuelve o DocumentTranslationLROPollerAsyncDocumentTranslationLROPoller. Los autores de llamadas deben esperar a que se complete la operación llamando result() al objeto de sondeo devuelto desde el begin_<method-name> método . A continuación se proporcionan fragmentos de código de ejemplo para ilustrar el uso de operaciones de larga duración .

Ejemplos

En la sección siguiente se proporcionan varios fragmentos de código que abarcan algunas de las tareas de traducción de documentos más comunes, entre las que se incluyen:

Traducción de los documentos

Traduzca todos los documentos del contenedor de origen al contenedor de destino. Para traducir documentos en una carpeta o traducir solo 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")

Traducción de varias entradas

Comience a traducir con documentos en varios contenedores de origen a varios contenedores de destino en distintos 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")

Enumerar las operaciones de traducción

Enumerar las operaciones de traducción enviadas para el 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 cómo usar la biblioteca cliente de traducción de documentos con Azure Storage Blob para cargar documentos, crear tokens saS para los contenedores y descargar los documentos traducidos terminados, consulte este ejemplo. Tenga en cuenta que deberá instalar la biblioteca azure-storage-blob para ejecutar este ejemplo.

Temas avanzados

En la sección siguiente se proporcionan algunas conclusiones sobre algunas características avanzadas de traducción, como glosarios y modelos de traducción personalizados.

Glosarios

Los glosarios son diccionarios específicos del dominio. Por ejemplo, si desea traducir algunos documentos relacionados con la medicina, es posible que necesite soporte técnico para las muchas palabras, terminología y expresiones en el campo médico que no puede encontrar en el diccionario de traducción estándar, o simplemente necesita traducción específica. Este es el motivo por el que la traducción de documentos proporciona compatibilidad con glosarios.

Creación de un archivo de glosario

La traducción de documentos admite glosarios en los siguientes formatos:

Tipo de archivo Extensión Descripción Muestras
Valores separados por tabulaciones/TAB .tsv, .tab Más información sobre wikipedia glossary_sample.tsv
Valores separados por comas .csv Más información sobre wikipedia glossary_sample.csv
Formato de archivo de intercambio de localización .xlf, .xliff Más información sobre wikipedia glossary_sample.xlf

Vea todos los formatos admitidos aquí.

Uso de glosarios en la traducción de documentos

Para usar glosarios con traducción de documentos, primero debe cargar el archivo de glosario en un contenedor de blobs y, a continuación, proporcionar la dirección URL de SAS al archivo como en los ejemplos de código sample_translation_with_glossaries.py.

Modelos de traducción personalizados

En lugar de usar el motor de traducción de documentos para la traducción, puede usar su propio modelo de aprendizaje profundo o automático de Azure personalizado.

Cómo crear un modelo de traducción personalizada

Para obtener más información sobre cómo crear, aprovisionar e implementar su propio modelo de traducción de Azure personalizado, siga estas instrucciones: Compilación, implementación y uso de un modelo personalizado para la traducción.

Cómo usar un modelo de traducción personalizada con traducción de documentos

Para usar un modelo de traducción personalizado con traducción de documentos, primero debe crear e implementar el modelo y, a continuación, seguir el ejemplo de código sample_translation_with_custom_model.py para usarlo con traducción de documentos.

Solución de problemas

General

La biblioteca cliente de traducción de documentos generará excepciones definidas en Azure Core.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro.

La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en INFO el nivel .

El registro de nivel detallado DEBUG , incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados , se puede habilitar en el cliente o por operación con el argumento de palabra logging_enable clave.

Consulte la documentación completa del registro del SDK con ejemplos aquí.

Configuración opcional

Los argumentos de palabra clave opcionales se pueden pasar en el nivel de cliente y por operación. En la documentación de referencia de azure-core se describen las configuraciones disponibles para los reintentos, el registro, los protocolos de transporte, etc.

Pasos siguientes

En la sección siguiente se proporcionan varios fragmentos de código que ilustran patrones comunes que se usan en la biblioteca cliente de Python de traducción de documentos. Puede encontrar más ejemplos en el directorio samples .

Más código de ejemplo

Estos ejemplos de código muestran operaciones de escenario comunes con la biblioteca cliente de Azure Document Translation.

Ejemplos asincrónicos

Esta biblioteca también incluye un conjunto completo de API asincrónicas. Para usarlos, primero debe instalar un transporte asincrónico, como aiohttp. Los clientes asincrónicos se encuentran en el azure.ai.translation.document.aio espacio de nombres .

Documentación adicional

Para obtener documentación más amplia sobre la traducción de documentos de Azure Cognitive Services, consulte la documentación de traducción de documentos en docs.microsoft.com.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.