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

  • Статья

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

Внимание

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

Необходимые компоненты

Для начала работы необходимы перечисленные ниже компоненты и данные.

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

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

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

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

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

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

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

Дополнительные сведения см. в разделе "Создание маркеров 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.

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

    • Для авторизации подписанного 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.1.0b1

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

  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-адрес находится в верхней части списка свойств.

    • Для авторизации подписанного 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.path.basename(file_path)
    file_type = (
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )
    print(f"File for translation: {file_name}")

    with open(file_name, "r") 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
    )
    translated_response = response_stream.decode("utf-8-sig")  # type: ignore[attr-defined]
    print(f"Translated response: {translated_response}")


if __name__ == "__main__":
    sample_single_document_translation()

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

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

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