Поделиться через

Начало работы: клиентские библиотеки перевода документов

  • Статья

Перевод документов — это облачная функция службы Azure AI Translator , которая асинхронно переводит целые документы на поддерживаемые языки и различные форматы файлов. В этом кратком руководстве вы узнаете, как использовать перевод документов с выбранным языком программирования для перевода исходного документа на целевой язык, сохраняя структуру и форматирование текста.

Внимание

  • Перевод документов в настоящее время поддерживается только в ресурсе Azure AI Translator (односервисный) и не включен в ресурс служба Azure AI (многосервисный).
  • Перевод документов поддерживается на платных уровнях. Language Studio поддерживает уровни конфигурации экземпляров S1 или D3. Мы рекомендуем выбрать стандартный S1, чтобы попробовать перевод документов. Смотритецены на службы Azure AI — Переводчик.
  • Выпуски общедоступной предварительной версии перевода документов предоставляют ранний доступ к функциям, которые находятся в активной разработке. Функции, подходы и процессы могут изменяться до выпуска общедоступной версии на основе отзывов пользователей.
  • Общедоступная предварительная версия клиентских библиотек перевода документов по умолчанию — REST API версии 2024-05-01.

Предварительные условия

Для начала работы вам необходимо:

  • Активная учетная запись Azure. Если ее нет, можно создать бесплатную учетную запись.

  • Односервисный ресурс Azure AI Translator (а не ресурс Azure AI с несколькими сервисами). Если вы планируете использовать функцию перевода документов с использованием авторизации управляемого удостоверения, выберите географический регион, например Восток США. Выберите стандартный план обслуживания S1 (оплата по факту использования) или планы с объёмной скидкой C2, C3, C4 или D3.

  • Учетная запись Azure для хранения Блоб-объектов. Вы создадите контейнеры в учетной записи Хранилище BLOB-объектов Azure для исходных и целевых файлов:

    • Контейнер исходных файлов. В этом контейнере вы отправляете файлы для перевода (обязательно).
    • Целевой контейнер. В этом контейнере хранятся преобразованные файлы (обязательные).

Авторизация контейнера хранилища

Вы можете выбрать один из следующих вариантов, чтобы авторизовать доступ к ресурсу Azure AI Translator.

✔️ Управляемое удостоверение. Управляемое удостоверение — это служебный принципал, который создает удостоверение Microsoft Entra и задает определенные разрешения для управляемого ресурса Azure. Управляемые удостоверения позволяют запускать приложение Azure AI Translator без необходимости внедрять учетные данные в код. Управляемые удостоверения — это более безопасный способ предоставления доступа к данным хранилища и замены требования к включению маркеров подписи общего доступа (SAS) с исходными и целевыми URL-адресами.

Чтобы узнать больше, см.раздел "Управляемые удостоверения для перевода документов".

Снимок экрана потока управляемых удостоверений (RBAC).

✔️ Подписанный маркер доступа (SAS). Подписанный URL-адрес — это URL-адрес, предоставляющий ограниченный доступ в течение указанного периода времени службе Переводчика. Чтобы использовать этот метод, необходимо создать токены совместного доступа (SAS) для исходных и целевых контейнеров. sourceUrl и targetUrl должны содержать токен SAS, добавленный в качестве строки запроса. Маркер может быть назначен вашему контейнеру или определённым блобам.

  • Исходныйконтейнер или большой двоичный объект должны назначать доступ для чтения и списка.
  • Ваш целевой контейнер или блоб должен обеспечивать доступ к записи и доступ для чтения списка.

Дополнительные сведения см. в разделе "Создание маркеров SAS".

Снимок экрана: URI ресурса с маркером SAS.

Создайте ваше приложение

Существует несколько инструментов для создания, сборки и запуска приложений Translator C#/.NET. Здесь мы рекомендуем использовать интерфейс командной строки (CLI) или Visual Studio. Выберите одну из следующих вкладок, чтобы приступить к работе:

Настройка проекта

В окне консоли (cmd, PowerShell или Bash) выполните команду dotnet new, чтобы создать консольное приложение с именем batch-document-translation. Эта команда создает простой проект "Hello World" на языке C# с одним файлом исходного кода Program.cs.

dotnet new console -n batch-document-translation

Измените каталог на созданную папку приложения. Выполните сборку приложения с помощью следующей команды:

dotnet build

Выходные данные сборки не должны содержать предупреждений или ошибок.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Установка клиентской библиотеки

В каталоге приложения установите клиентную библиотеку перевода документов для .NET:

dotnet add package Azure.AI.Translation.Document --version 2.0.0-beta

Перевод документов асинхронно

  1. Для этого проекта требуется исходный документ, отправленный в исходный контейнер. Вы можете скачать образец документа для перевода для этого краткого руководства. Исходный язык — английский.

  2. В каталоге проекта откройте файл Program.cs в предпочитаемом редакторе или интегрированной среде разработки. Удалите существующий код, включая строку Console.WriteLine("Hello World!").

  3. В Program.cs приложения создайте переменные для ключа и пользовательской конечной точки. Дополнительные сведения см. в статьеПолучите ваш ключ и конечную точку пользовательского домена.

    private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";

  4. Вызовите метод StartTranslationAsync, чтобы начать операцию перевода для одного или нескольких документов в одном контейнере BLOB.

  5. Чтобы вызватьStartTranslationAsync, необходимо инициализировать DocumentTranslationInput объект, содержащий sourceUritargetUriпараметры и targetLanguageCode параметры:

    • Для авторизации управляемого удостоверения создайте следующие переменные:

      • sourceUri. URL-адрес исходного контейнера, содержащего документы, которые необходимо преобразовать.

      • targetUri URL-адрес целевого контейнера, в который записываются переведенные документы.

      • targetLanguageCode. Код языка для переведенных документов. Коды языков можно найти на странице Поддержка языков.

        Чтобы найти исходные и целевые URL-адреса, перейдите к учетной записи хранения в портал Azure. На левой боковой панели в разделе хранилища данных выберите контейнеры и выполните следующие действия, чтобы получить исходные документы и целевой контейнер URLS.

        Оригинал Цель
        1. Установите флажок рядом с исходным контейнером 1. Установите флажок рядом с целевым контейнером.
        2. В главной области окна выберите файл или документы для перевода. 2. Выберите многоточие, расположенные справа, а затем выберите "Свойства".
        3. Исходный URL-адрес находится в верхней части списка свойств. 3. Целевой URL-адрес находится в верхней части списка свойств.

    • Для авторизации с помощью подписи общего доступа (SAS) создайте эти переменные.

      • sourceUri. URI SAS, с токеном SAS, добавленным как строка запроса, для исходного контейнера, содержащего документы, которые необходимо перевести.
      • targetUri URI SAS с маркером SAS, добавленным в виде строки запроса, для целевого контейнера, в который записываются переведенные документы.
      • targetLanguageCode. Код языка для переведенных документов. Коды языков можно найти на странице Поддержка языков.

Внимание

Обязательно удалите ключ из кода, когда завершите работу, и ни в коем случае не публикуйте его в открытом доступе. Для рабочей среды используйте безопасный способ хранения и доступа к учетным данным, например Azure Key Vault. Дополнительные сведения см. в статье "Безопасность служб искусственного интеллекта Azure".

Пример кода асинхронного перевода

Введите следующий пример кода в файл Program.cs приложения:


using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>"

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide the location of input for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    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: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

Запуск приложения

После добавления примера кода в приложение запустите приложение из каталога проекта, введя следующую команду в терминале:

  dotnet run

Ниже приведен фрагмент ожидаемых выходных данных:

Снимок экрана выходных данных Visual Studio Code в окне терминала.

Пример кода синхронного перевода

Для этого краткого руководства можно скачать образец перевода документа. Исходный язык — английский.



using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  string endpoint = "{your-document-translation-endpoint}";
  string apiKey = "{your-api-key}";
  SingleDocumentTranslationClient client = new SingleDocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

  try
  {
    string filePath = @"C:\{folder}\document.txt"
    using Stream fileStream = File.OpenRead(filePath);

    // MultipartFormFileData (string name, System.IO.Stream content, string contentType);
    var sourceDocument = new MultipartFormFileData(Path.GetFileName(filePath), fileStream, "application/vnd.openxmlformats-officedocument.wordprocessingml.document");

    DocumentTranslateContent content = new DocumentTranslateContent(sourceDocument);

    // DocumentTranslate (string targetLanguage, Azure.AI.Translation.Document.DocumentTranslateContent documentTranslateContent, string sourceLanguage = default, string category = default, bool? allowFallback = default, System.Threading.CancellationToken cancellationToken = default);
    var response = client.DocumentTranslate("de", content);

    Console.WriteLine($"Request string for translation: {requestString}");
    Console.WriteLine($"Response string after translation: {responseString}");
  }
    catch (RequestFailedException exception) {
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
  }
}

Вот и все! Вы только что создали программу для перевода документов в контейнер хранилища с помощью клиентской библиотеки .NET.

Настройка проекта

Убедитесь, что установлена последняя версия Python .

Установка клиентской библиотеки

Установите последнюю версию клиентской библиотеки перевода документов:

  pip install azure-ai-translation-document==1.0.0

Перевод пакетных файлов

  1. Для этого проекта требуется исходный документ, отправленный в исходный контейнер. Для этого краткого руководства вы можете скачать образец перевода документов. Исходный язык — английский.

  2. В файле приложения Python создайте переменные для ключа ресурса и настраиваемой конечной точки. Дополнительные сведения см. в статье"Получение вашего ключа и конечной точки вашего пользовательского домена".

key = "{your-api-key}"
endpoint = "{your-document-translation-endpoint}"

  1. Инициализация DocumentTranslationClient объекта, содержащего ваши endpoint и key параметры.

  2. begin_translation Вызовите метод и передайте параметры sourceUritargetUri, а также targetLanguageCode параметры.

    • Для авторизации управляемой идентификации создайте следующие переменные:

      • sourceUri. URL-адрес исходного контейнера, содержащего документы, которые необходимо преобразовать.

      • targetUri URL-адрес целевого контейнера, в который записываются переведенные документы.

      • targetLanguageCode. Код языка для переведенных документов. Коды языков можно найти на странице Поддержка языков.

        Чтобы найти исходные и целевые URL-адреса, перейдите к учетной записи хранения в портал Azure. На левой боковой панели в разделе хранилища данных выберите контейнеры и выполните следующие действия, чтобы получить исходные документы и целевой контейнер URLS.

        Оригинал Target
        1. Установите флажок рядом с исходным контейнером 1. Установите флажок рядом с целевым контейнером.
        2. В главной области окна выберите файл или документы для перевода. 2. Выберите многоточие, расположенные справа, а затем выберите "Свойства".
        3. Исходный URL-адрес находится в верхней части списка свойств. 3. Целевой URL-адрес находится в верхней части списка свойств.

    • Для авторизации подписей общей доступа (SAS) создайте эти переменные.

      • sourceUri. URI SAS с добавленным маркером SAS в качестве строки запроса для исходного контейнера, содержащего документы, которые необходимо перевести.
      • targetUri URI SAS с маркером SAS, добавленным в виде строки запроса, для целевого контейнера, в который записываются переведенные документы.
      • targetLanguageCode. Код языка для переведенных документов. Коды языков можно найти на странице Поддержка языков.

Пример кода асинхронного перевода

Внимание

Обязательно удалите ключ из кода, когда завершите работу, и ни в коем случае не публикуйте его в открытом доступе. Для рабочей среды используйте безопасный способ хранения и доступа к учетным данным, например Azure Key Vault. Дополнительные сведения см. в статье "Безопасность служб искусственного интеллекта Azure".

Введите следующий пример кода в приложение Python:


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

# create variables for your resource key, custom endpoint, sourceUrl, targetUrl, and targetLanguage
key = '{your-api-key}'
endpoint = '{your-document-translation-endpoint}'
sourceUri = '<your-container-sourceUrl>'
targetUri = '<your-container-targetUrl>'
targetLanguage = '<target-language-code>'


# initialize a new instance of the DocumentTranslationClient object to interact with the asynchronous Document Translation feature
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

# include source and target locations and target language code for the begin translation operation
poller = client.begin_translation(sourceUri, targetUri, targetLanguage)
result = poller.result()

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

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

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

Запуск приложения

После добавления примера кода в приложение введите следующую команду в терминале:

python asynchronous-sdk.py

Ниже приведен фрагмент ожидаемых выходных данных:

Снимок экрана: выходные данные Python в окне терминала.

Пример кода синхронного перевода

Вы можете скачать наш пример перевода документа для этого краткого руководства. Исходный язык — английский.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import SingleDocumentTranslationClient
from azure.ai.translation.document.models import DocumentTranslateContent


def sample_single_document_translation():

    # create variables for your resource api key, document translation endpoint, and target language
    key = "<your-api-key>"
    endpoint = "<your-document-translation-endpoint>"
    target_language = "{target-language-code}"

    # initialize a new instance of the SingleDocumentTranslationClient object to interact with the synchronous Document Translation feature
    client = SingleDocumentTranslationClient(endpoint, AzureKeyCredential(key))

    # absolute path to your document
    file_path = "C:/{your-file-path}/document-translation-sample.docx"
    file_name = os.path.basename(file_path)
    file_type = (
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )
    print(f"File for translation: {file_name}")

    with open(file_path, "rb") as file:
        file_contents = file.read()

    document_content = (file_name, file_contents, file_type)
    document_translate_content = DocumentTranslateContent(document=document_content)

    response_stream = client.document_translate(
        body=document_translate_content, target_language=target_language
    )
    # Save the response_stream to a file
    output_file_path = "./translated-document.docx"
    with open(output_file_path, "wb") as output_file:
        output_file.write(response_stream)
    
    print(f"Translated document saved to: {output_file_path}")


if __name__ == "__main__":
    sample_single_document_translation()

Вот и все! Вы только что создали программу для асинхронного и синхронного перевода документов с помощью клиентской библиотеки Python.

Следующий шаг

Дополнительные сведения об операциях перевода документов