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

Клиентская библиотека перевода документов Azure для Python версии 1.0.0

  • Статья

Перевод документов Azure Cognitive Services — это облачная служба, которую можно использовать для перевода нескольких сложных документов на разных языках и диалектах с сохранением исходной структуры документа и формата данных. Используйте клиентную библиотеку для перевода документов, чтобы:

  • Преобразование большого количества больших файлов из контейнера Хранилище BLOB-объектов Azure в целевой контейнер на выбранном языке.
  • Проверьте состояние перевода и ход выполнения каждого документа в операции перевода.
  • Примените пользовательскую модель перевода или глоссарии, чтобы адаптировать перевод к конкретному варианту.

Исходный код | Пакет (PyPI) | Справочная документация по | API Документация по продукту | Образцы

Заявление об отказе

Поддержка пакетов Python пакета Azure SDK для Python 2.7 завершилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Начало работы

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

  • Для использования этого пакета требуется Python 3.6 или более поздней версии.
  • Для использования этого пакета необходимо иметь подписку Azure и ресурс Переводчика .

Установка пакета

Установите клиентую библиотеку перевода документов Azure для Python с помощью pip:

pip install azure-ai-translation-document

Примечание. Эта версия клиентской библиотеки по умолчанию использует версию 1.0 службы.

Создание ресурса Переводчика

Функция перевода документов поддерживает доступ только к одной службе . Чтобы получить доступ к службе, создайте ресурс Переводчика.

Ресурс можно создать с помощью

Вариант 1.Портал Azure

Вариант 2.Azure 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

Аутентификация клиента

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

Поиск конечной точки

Конечную точку для ресурса Переводчика можно найти на портале Azure.

Обратите внимание, что службе требуется конечная точка личного домена. Следуйте инструкциям по приведенной выше ссылке, чтобы отформатировать конечную точку: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Получение ключа API

Ключ API можно найти на портале Azure или с помощью следующей команды Azure CLI:

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

Создание клиента с помощью AzureKeyCredential

Чтобы использовать ключ API в credential качестве параметра, передайте ключ в виде строки в экземпляр 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)

Создание клиента с учетными данными Azure Active Directory

AzureKeyCredential Проверка подлинности используется в примерах в этом руководстве по началу работы, но вы также можете пройти проверку подлинности в Azure Active Directory с помощью библиотеки azure-identity .

Чтобы использовать тип DefaultAzureCredential, показанный ниже, или другие типы учетных данных, предоставляемые пакетом azure-identity SDK Для Azure, установите пакет :

pip install azure-identity

Вам также потребуется зарегистрировать новое приложение AAD и предоставить доступ к ресурсу Переводчика, назначив "Cognitive Services User" роль субъекту-службе.

После завершения задайте значения идентификатора клиента, идентификатора клиента и секрета клиента приложения AAD в качестве переменных среды: 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
)

Основные понятия

Служба перевода документов требует отправки файлов в Хранилище BLOB-объектов Azure исходный контейнер и предоставления целевого контейнера, в который можно записать переведенные документы. Дополнительные сведения о настройке см. в документации по службе:

DocumentTranslationClient

Взаимодействие с клиентской библиотекой перевода документов начинается с экземпляра DocumentTranslationClient. Клиент предоставляет операции для:

  • Создание операции перевода для перевода документов в исходных контейнерах и записи результатов в целевые контейнеры.
  • Проверка состояния отдельных документов в операции перевода и отслеживание хода выполнения каждого документа.
  • Перечисление всех прошлых и текущих операций перевода.
  • Определение поддерживаемых форматов глоссария и документов.

Перевод входных данных

Входные данные для begin_translation метода клиента можно предоставить двумя разными способами:

  1. Один исходный контейнер с документами можно перевести на другой язык:
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. Для каждого из них можно предоставить несколько разных источников с собственными целевыми объектами.
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)

Примечание. target_url для каждого целевого языка должны быть уникальными.

Сведения о переводе документов в папке или только определенных документов см. в разделе sample_begin_translation_with_filters.py. См. документацию по службам для всех поддерживаемых языков.

Операции Long-Running

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

Методы, которые преобразуют документы, моделироваются как длительные операции. Клиент предоставляет метод, возвращающий begin_<method-name>DocumentTranslationLROPoller или AsyncDocumentTranslationLROPoller. Вызывающие объекты должны дождаться завершения операции путем вызова result() в объекте опроса, возвращенном методом begin_<method-name> . Примеры фрагментов кода приведены для демонстрации использования длительных операций ниже.

Примеры

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

Перевод документов

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

Перевод нескольких входных данных

Начните перевод документов из нескольких исходных контейнеров в несколько целевых контейнеров на разных языках.

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")

Перечисление операций перевода

Перечисление операций перевода, отправленных для ресурса.

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")

Сведения об использовании клиентской библиотеки перевода документов с большим двоичным объектом службы хранилища Azure для отправки документов, создании маркеров SAS для контейнеров и скачивании готовых переведенных документов см. в этом примере. Обратите внимание, что для запуска этого примера необходимо установить библиотеку azure-storage-blob .

Дополнительные разделы

В следующем разделе приведены некоторые аналитические сведения о некоторых расширенных функциях перевода, таких как глоссарии и пользовательские модели перевода.

Глоссарии

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

Создание файла глоссария

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

Тип файла Расширение Описание Примеры
Значения с разделением знаками табуляции (TAB) .tsv, .tab Дополнительные сведения см. в википедии glossary_sample.tsv
Значения с разделителями-запятыми .csv Подробнее в Википедии glossary_sample.csv
Localization Interchange File Format (формат обмена локализуемыми данными) .xlf, .xliff Подробнее в Википедии glossary_sample.xlf

Просмотрите все поддерживаемые форматы здесь.

Использование глоссариев при переводе документов

Чтобы использовать глоссарии с переводом документов, необходимо сначала отправить файл глоссария в контейнер больших двоичных объектов, а затем указать URL-адрес SAS для файла, как показано в примерах кода sample_translation_with_glossaries.py.

Пользовательские модели перевода

Вместо перевода документов можно использовать собственную пользовательскую модель машинного и глубокого обучения Azure.

Создание пользовательской модели перевода

Дополнительные сведения о создании, подготовке и развертывании собственной пользовательской модели перевода Azure см. в статье Создание, развертывание и использование пользовательской модели для перевода.

Использование пользовательской модели перевода с переводом документов

Чтобы использовать пользовательскую модель перевода с переводом документов, сначала необходимо создать и развернуть модель, а затем следуйте примеру кода sample_translation_with_custom_model.py для использования с переводом документов.

Устранение неполадок

Общие сведения

Клиентская библиотека перевода документов вызывает исключения, определенные в Azure Core.

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала.

Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на INFO уровне.

Подробное DEBUG ведение журнала на уровне, включая тексты запросов и ответов и нередактированные заголовки, можно включить на клиенте или на операцию с помощью аргумента ключевого logging_enable слова .

См. полную документацию по ведению журнала пакета SDK с примерами здесь.

Дополнительная настройка

Необязательные аргументы ключевого слова можно передать на уровне клиента и на уровне операций. В справочной документации azure-Core описаны доступные конфигурации для повторных попыток, ведения журнала, транспортных протоколов и многого другого.

Дальнейшие действия

В следующем разделе представлено несколько фрагментов кода, иллюстрирующих распространенные шаблоны, используемые в клиентской библиотеке Python перевода документов. Дополнительные примеры можно найти в каталоге примеров .

Больше примеров кода

В этих примерах кода показаны распространенные операции сценария с клиентской библиотекой перевода документов Azure.

Асинхронные примеры

Эта библиотека также включает полный набор асинхронных API. Чтобы использовать их, необходимо сначала установить асинхронный транспорт, например aiohttp. Асинхронные клиенты находятся в azure.ai.translation.document.aio пространстве имен.

Дополнительная документация

Более подробную документацию по переводу документов Azure Cognitive Services см. в документации по переводу документов на docs.microsoft.com.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см . на странице cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.