Biblioteca cliente de traducción de documentos de Azure Cognitive Services para .NET, versión 1.0.0

Artículo
04/27/2023

La traducción de documentos de Azure Cognitive Services es un servicio en la nube que traduce documentos a y desde 90 idiomas y dialectos, a la vez que conserva la estructura del documento y el formato de datos. Use la biblioteca cliente para traducción de documentos para:

Traduzca 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 (NuGet) | Documentación | de referencia de API | Documentación del producto Muestras

Introducción

Instalar el paquete

Instale la biblioteca cliente de Traducción de documentos de Azure para .NET con NuGet:

dotnet add package Azure.AI.Translation.Document

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

Requisitos previos

Una suscripción de Azure.
Un recurso de Translator existente.

Creación de un recurso de Traductor

La traducción de documentos solo admite el acceso de un solo servicio . Para acceder al servicio, cree un recurso de Translator.

Puede crear cualquiera de los recursos 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 <your-resource-name> --location <location>

# Create Translator
az cognitiveservices account create \
    --name <your-resource-name> \
    --custom-domain <your-resource-name> \
    --resource-group <your-resource-group-name> \
    --kind TextTranslation \
    --sku S1 \
    --location <location> \
    --yes

Para obtener más información sobre cómo crear el recurso o cómo obtener la información de ubicación, consulte aquí.

Autenticar el cliente

Para interactuar con el servicio de traducción de documentos, deberá crear una instancia de la clase DocumentTranslationClient . Necesitará un punto de conexión y una clave de API o TokenCredential para crear una instancia de un objeto de cliente. Para más información sobre la autenticación con Cognitive Services, consulte Autenticación de solicitudes en Azure Cognitive Services.

Búsqueda del punto de conexión

Para la traducción de documentos, deberá usar un punto de conexión de Custom Domain con el nombre del recurso translator.

Obtención de la clave de API

Puede obtener la API key información del recurso translator en Azure Portal.

Como alternativa, use el fragmento de código de la CLI de Azure siguiente para obtener la clave de API del recurso translator.

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Creación de DocumentTranslationClient con credencial de clave de API

Una vez que tenga el valor de la clave de API, cree un AzureKeyCredential. Esto le permitirá actualizar la clave de API sin crear un nuevo cliente.

Con el valor del punto de conexión y un AzureKeyCredential, puede crear DocumentTranslationClient:

string endpoint = "<Document Translator Resource Endpoint>";
string apiKey = "<Document Translator Resource API Key>";
var client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

Creación de DocumentTranslationClient con credenciales de Azure Active Directory

La autenticación de clave de API de cliente se usa en la mayoría de los ejemplos de esta guía de introducción, pero también puede autenticarse con Azure Active Directory mediante la biblioteca de identidades de Azure. Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de AAD.

Cree un subdominio personalizado para el recurso con el fin de usar este tipo de autenticación.

Para usar el proveedor DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el paquete Azure.Identity:

dotnet add package Azure.Identity

También deberá 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.

Establezca los valores de client ID, tenant IDy client secret de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

string endpoint = "<Document Translator Resource Endpoint>";
var client = new DocumentTranslationClient(new Uri(endpoint), new DefaultAzureCredential());

Conceptos clave

El servicio de 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. Los tokens de SAS para los contenedores (o archivos) se usan para acceder a los documentos y crear los documentos traducidos en el contenedor de destino. Puede encontrar información adicional sobre cómo configurar esta opción en la documentación del servicio:

Configure Azure Blob Storage contenedores con los documentos.
Opcionalmente, aplique glosarios o un modelo personalizado para la traducción.
Genere tokens de SAS en los contenedores (o archivos) con los permisos adecuados.

DocumentTranslationClient

Es DocumentTranslationClient la interfaz principal para los desarrolladores que usan la biblioteca cliente de traducción de documentos. Proporciona métodos sincrónicos y asincrónicos para realizar las siguientes operaciones:

Crear una operación de traducción para traducir documentos en los contenedores de origen y escribir resultados en los contenedores de destino.
Enumerar todas las operaciones de traducción pasadas y actuales.
Identificación de los formatos de documento y glosario admitidos.

Entrada de traducción

Para iniciar una operación de traducción, debe crear una instancia o una lista de DocumentTranslationInput.

Una única dirección URL de origen a documentos se puede traducir a muchos idiomas diferentes:

Uri sourceSasUri = new Uri("<source SAS URI>");
Uri frenchTargetSasUri = new Uri("<french target SAS URI>");
var input = new DocumentTranslationInput(sourceSasUri, frenchTargetSasUri, "fr");

O se pueden proporcionar varios orígenes diferentes cada uno con sus propios destinos.

Uri arabicTargetSasUri = new Uri("<arabic target SAS URI>");
Uri spanishTargetSasUri = new Uri("<spanish target SAS URI>");
Uri source1SasUri = new Uri("<source1 SAS URI>");
Uri source2SasUri = new Uri("<source2 SAS URI>");

var inputs = new List<DocumentTranslationInput>
{
    new DocumentTranslationInput(source1SasUri, spanishTargetSasUri, "es"),
    new DocumentTranslationInput(
        source: new TranslationSource(source2SasUri),
        targets: new List<TranslationTarget>
        {
            new TranslationTarget(frenchTargetSasUri, "fr"),
            new TranslationTarget(arabicTargetSasUri, "ar")
        }),
};

Tenga en cuenta que los documentos escritos en un contenedor de destino deben tener nombres únicos. Por lo tanto, no se puede traducir un contenedor de origen en un contenedor de destino dos veces o tener orígenes con los mismos documentos traducidos en el mismo contenedor de destino.

Operaciones de Long-Running

La traducción de documentos se implementa como una operación de larga duración. Las operaciones de larga duración constan de una solicitud inicial enviada al servicio para iniciar una operación, seguida de sondear el servicio a intervalos para determinar si la operación se ha completado correctamente o no.

Para las operaciones de larga duración en el SDK de Azure, el cliente expone un Start<operation-name> método que devuelve un PageableOperation<T>. Puede usar el método WaitForCompletionAsync() de extensión para esperar a que se complete la operación y obtener su resultado. A continuación se proporciona un fragmento de código de ejemplo para ilustrar el uso de operaciones de larga duración.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Ejemplos

En la sección siguiente se proporcionan varios fragmentos de código con el clientcreado anteriormente y se tratan las funciones principales de la traducción de documentos. Nota: proporciona DocumentTranslationClient métodos sincrónicos y asincrónicos.

Ejemplos asincrónicos

Iniciar la traducción de forma asincrónica
Historial de operaciones de forma asincrónica
Varias entradas de forma asincrónica

Ejemplos de sincronización

Nota: proporciona DocumentTranslationClient métodos sincrónicos y asincrónicos.

Iniciar traducción

Iniciar la traducción de forma asincrónica

Inicie una operación de traducción para traducir documentos en el contenedor de origen y escribir los archivos traducidos en el contenedor de destino. DocumentTranslationOperation permite sondear el estado de la operación de traducción y obtener el estado de los documentos individuales.

Uri sourceUri = new Uri("<source SAS URI>");
Uri targetUri = new Uri("<target SAS URI>");
var input = new DocumentTranslationInput(sourceUri, targetUri, "es");

DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

await operation.WaitForCompletionAsync();

Console.WriteLine($"  Status: {operation.Status}");
Console.WriteLine($"  Created on: {operation.CreatedOn}");
Console.WriteLine($"  Last modified: {operation.LastModified}");
Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

await foreach (DocumentStatusResult document in operation.Value)
{
    Console.WriteLine($"Document with Id: {document.Id}");
    Console.WriteLine($"  Status:{document.Status}");
    if (document.Status == DocumentTranslationStatus.Succeeded)
    {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language code: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
    }
    else
    {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
    }
}

Obtener el historial de operaciones de forma asincrónica

Obtenga el historial de operaciones de traducción enviadas de los últimos 7 días. El parámetro options se puede omitir si el usuario desea devolver todas las operaciones enviadas.

int operationsCount = 0;
int totalDocs = 0;
int docsCanceled = 0;
int docsSucceeded = 0;
int docsFailed = 0;

DateTimeOffset lastWeekTimestamp = DateTimeOffset.Now.AddDays(-7);

var options = new GetTranslationStatusesOptions
{
    CreatedAfter = lastWeekTimestamp
};

await foreach (TranslationStatusResult translationStatus in client.GetTranslationStatusesAsync(options))
{
    if (translationStatus.Status == DocumentTranslationStatus.NotStarted ||
        translationStatus.Status == DocumentTranslationStatus.Running)
    {
        DocumentTranslationOperation operation = new DocumentTranslationOperation(translationStatus.Id, client);
        await operation.WaitForCompletionAsync();
    }

    operationsCount++;
    totalDocs += translationStatus.DocumentsTotal;
    docsCanceled += translationStatus.DocumentsCanceled;
    docsSucceeded += translationStatus.DocumentsSucceeded;
    docsFailed += translationStatus.DocumentsFailed;
}

Console.WriteLine($"# of operations: {operationsCount}");
Console.WriteLine($"Total Documents: {totalDocs}");
Console.WriteLine($"Succeeded Document: {docsSucceeded}");
Console.WriteLine($"Failed Document: {docsFailed}");
Console.WriteLine($"Canceled Documents: {docsCanceled}");

Iniciar traducción con varias entradas de forma asincrónica

Inicie una operación de traducción para traducir documentos en varios contenedores de origen a varios contenedores de destino en distintos idiomas. DocumentTranslationOperation permite sondear el estado de la operación de traducción y obtener el estado de los documentos individuales.

Uri source1SasUri = new Uri("<source1 SAS URI>");
Uri source2SasUri = new Uri("<source2 SAS URI>");
Uri frenchTargetSasUri = new Uri("<french target SAS URI>");
Uri arabicTargetSasUri = new Uri("<arabic target SAS URI>");
Uri spanishTargetSasUri = new Uri("<spanish target SAS URI>");
Uri frenchGlossarySasUri = new Uri("<french glossary SAS URI>");

var glossaryFormat = "TSV";

var input1 = new DocumentTranslationInput(source1SasUri, frenchTargetSasUri, "fr", new TranslationGlossary(frenchGlossarySasUri, glossaryFormat));
input1.AddTarget(spanishTargetSasUri, "es");

var input2 = new DocumentTranslationInput(source2SasUri, arabicTargetSasUri, "ar");
input2.AddTarget(frenchTargetSasUri, "fr", new TranslationGlossary(frenchGlossarySasUri, glossaryFormat));

var inputs = new List<DocumentTranslationInput>()
    {
        input1,
        input2
    };

DocumentTranslationOperation operation = await client.StartTranslationAsync(inputs);

await operation.WaitForCompletionAsync();

await foreach (DocumentStatusResult document in operation.GetValuesAsync())
{
    Console.WriteLine($"Document with Id: {document.Id}");
    Console.WriteLine($"  Status:{document.Status}");
    if (document.Status == DocumentTranslationStatus.Succeeded)
    {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language code: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
    }
    else
    {
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
    }
}

Iniciar traducción

Uri sourceUri = new Uri("<source SAS URI>");
Uri targetUri = new Uri("<target SAS URI>");
var input = new DocumentTranslationInput(sourceUri, targetUri, "es");

DocumentTranslationOperation operation = client.StartTranslation(input);

TimeSpan pollingInterval = new(1000);

while (true)
{
    operation.UpdateStatus();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    if (operation.HasCompleted)
    {
        break;
    }
    else
    {
        if (operation.GetRawResponse().Headers.TryGetValue("Retry-After", out string value))
        {
            pollingInterval = TimeSpan.FromSeconds(Convert.ToInt32(value));
        }
        Thread.Sleep(pollingInterval);
    }
}

foreach (DocumentStatusResult document in operation.GetValues())
{
    Console.WriteLine($"Document with Id: {document.Id}");
    Console.WriteLine($"  Status:{document.Status}");
    if (document.Status == DocumentTranslationStatus.Succeeded)
    {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language code: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
    }
    else
    {
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
    }
}

Solución de problemas

General

Al interactuar con la biblioteca cliente de traducción de documentos de Cognitive Services mediante el SDK de .NET, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de la API REST .

Por ejemplo, si envía una solicitud con una lista de destinos vacía, se devuelve un 400 error, que indica "Solicitud incorrecta".

var invalidInput = new DocumentTranslationInput(new TranslationSource(new Uri(endpoint)), new List<TranslationTarget>());

try
{
    DocumentTranslationOperation operation = client.StartTranslation(invalidInput);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Observará que se registra información adicional, como el identificador de solicitud de cliente de la operación.

Message:
    Azure.RequestFailedException: Service request failed.
    Status: 400 (Bad Request)

Content:
    {"error":{"code":"InvalidRequest","message":"No translation target found.","target":"TargetInput","innerError":{"code":"NoTranslationTargetFound","message":"No translation target found."}}}

Headers:
    Transfer-Encoding: chunked
    X-RequestId: REDACTED
    Content-Type: application/json; charset=utf-8
    Set-Cookie: REDACTED
    X-Powered-By: REDACTED
    apim-request-id: REDACTED
    Strict-Transport-Security: REDACTED
    x-content-type-options: REDACTED
    Date: Mon, 22 Mar 2021 11:54:58 GMT

Configuración del registro de la consola

La manera más sencilla de ver los registros es habilitar el registro de la consola. Para crear un agente de escucha de registro del SDK de Azure que genere mensajes en la consola, use el método AzureEventSourceListener.CreateConsoleLogger.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Para más información sobre otros mecanismos de registro, consulte aquí.

Pasos siguientes

Los ejemplos que muestran cómo usar la biblioteca de traducción de documentos de Cognitive Services están disponibles en este repositorio de GitHub.

Ejemplos avanzados

Contribuir

Consulte la CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.

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.

Impresiones

Share via