Udostępnij za pośrednictwem

Biblioteka klienta tłumaczenia dokumentów platformy Azure dla języka Python — wersja 1.0.0

  • Artykuł

Tłumaczenie dokumentów w usługach Azure Cognitive Services to usługa w chmurze, która może służyć do tłumaczenia wielu i złożonych dokumentów w różnych językach i dialektach przy zachowaniu oryginalnej struktury dokumentów i formatu danych. Użyj biblioteki klienta do tłumaczenia dokumentów, aby:

  • Przetłumacz wiele dużych plików z kontenera Azure Blob Storage na kontener docelowy w wybranym języku.
  • Sprawdź stan tłumaczenia i postęp każdego dokumentu w operacji tłumaczenia.
  • Zastosuj niestandardowy model tłumaczenia lub słowniki, aby dostosować tłumaczenie do konkretnego przypadku.

Kod | źródłowy Pakiet (PyPI) | Dokumentacja referencyjna interfejsu | API Dokumentacja | produktu Próbki

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python zestawu Azure SDK dla języka Python 2.7 została zakończona 01 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691

Wprowadzenie

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta tłumaczenia dokumentów platformy Azure dla języka Python przy użyciu narzędzia pip:

pip install azure-ai-translation-document

Uwaga: ta wersja biblioteki klienta jest domyślnie ustawiona na wersję 1.0 usługi

Tworzenie zasobu usługi Translator

Funkcja tłumaczenia dokumentów obsługuje tylko dostęp do pojedynczej usługi . Aby uzyskać dostęp do usługi, utwórz zasób usługi Translator.

Zasób można utworzyć przy użyciu polecenia

Opcja 1:Witryna Azure Portal

Opcja 2:interfejs wiersza polecenia platformy Azure. Poniżej przedstawiono przykład sposobu tworzenia zasobu usługi Translator przy użyciu interfejsu wiersza polecenia:

# 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

Uwierzytelnianie klienta

Aby móc korzystać z usługi funkcji tłumaczenia dokumentów, należy utworzyć wystąpienie klienta. Punkt końcowy i poświadczenia są niezbędne do utworzenia wystąpienia obiektu klienta.

Szukanie punktu końcowego

Punkt końcowy zasobu usługi Translator można znaleźć w witrynie Azure Portal.

Należy pamiętać, że usługa wymaga niestandardowego punktu końcowego domeny. Postępuj zgodnie z instrukcjami w powyższym linku, aby sformatować punkt końcowy: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Pobieranie klucza interfejsu API

Klucz interfejsu API można znaleźć w witrynie Azure Portal lub za pomocą następującego polecenia interfejsu wiersza polecenia platformy Azure:

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

Tworzenie klienta za pomocą elementu AzureKeyCredential

Aby użyć klucza interfejsu API jako parametru credential , przekaż klucz jako ciąg do wystąpienia obiektu 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)

Tworzenie klienta przy użyciu poświadczeń usługi Azure Active Directory

AzureKeyCredential uwierzytelnianie jest używane w przykładach w tym przewodniku wprowadzającym, ale można również uwierzytelnić się w usłudze Azure Active Directory przy użyciu biblioteki azure-identity .

Aby użyć poniższego typu DefaultAzureCredential lub innych typów poświadczeń dostarczanych z zestawem Azure SDK, zainstaluj azure-identity pakiet:

pip install azure-identity

Należy również zarejestrować nową aplikację usługi AAD i udzielić dostępu do zasobu usługi Translator, przypisując "Cognitive Services User" rolę do jednostki usługi.

Po zakończeniu ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i wpisu tajnego klienta aplikacji usługi AAD jako zmienne środowiskowe: AZURE_CLIENT_ID, , AZURE_CLIENT_SECRETAZURE_TENANT_ID.

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
)

Kluczowe pojęcia

Usługa tłumaczenia dokumentów wymaga przekazania plików do kontenera źródłowego Azure Blob Storage i udostępnienia kontenera docelowego, w którym można napisać przetłumaczone dokumenty. Dodatkowe informacje na temat konfigurowania tej funkcji można znaleźć w dokumentacji usługi:

DocumentTranslationClient

Interakcja z biblioteką klienta tłumaczenia dokumentów rozpoczyna się od wystąpienia klasy DocumentTranslationClient. Klient udostępnia operacje dla następujących elementów:

  • Tworzenie operacji tłumaczenia w celu tłumaczenia dokumentów w kontenerach źródłowych i zapisywania wyników w kontenerach docelowych.
  • Sprawdzanie stanu poszczególnych dokumentów w operacji tłumaczenia i monitorowanie postępu każdego dokumentu.
  • Wyliczanie wszystkich przeszłych i bieżących operacji tłumaczenia.
  • Identyfikowanie obsługiwanych formatów słownika i dokumentów.

Dane wejściowe tłumaczenia

begin_translation Dane wejściowe metody klienta można podać na dwa różne sposoby:

  1. Pojedynczy kontener źródłowy z dokumentami można przetłumaczyć na inny język:
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. Można też podać wiele różnych źródeł z własnymi celami.
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)

Uwaga: target_url dla każdego języka docelowego musi być unikatowa.

Aby przetłumaczyć dokumenty w folderze lub przetłumaczyć tylko niektóre dokumenty, zobacz sample_begin_translation_with_filters.py. Zapoznaj się z dokumentacją usługi dla wszystkich obsługiwanych języków.

operacje Long-Running

Długotrwałe operacje to operacje, które składają się z początkowego żądania wysłanego do usługi w celu uruchomienia operacji, a następnie sondowania usługi w odstępach czasu w celu ustalenia, czy operacja została ukończona, czy nie powiodła się, a jeśli zakończyła się pomyślnie, aby uzyskać wynik.

Metody tłumaczenia dokumentów są modelowane jako długotrwałe operacje. Klient uwidacznia metodę zwracającą begin_<method-name> obiekt DocumentTranslationLROPoller lub AsyncDocumentTranslationLROPoller. Obiekt wywołujący powinien czekać na ukończenie operacji przez wywołanie result() obiektu poller zwróconego begin_<method-name> z metody . Przykładowe fragmenty kodu są udostępniane w celu zilustrowania użycia długotrwałych operacji poniżej.

Przykłady

W poniższej sekcji przedstawiono kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań tłumaczenia dokumentów, w tym:

Tłumaczenie dokumentów

Przetłumacz wszystkie dokumenty w kontenerze źródłowym na kontener docelowy. Aby przetłumaczyć dokumenty w folderze lub przetłumaczyć tylko niektóre dokumenty, zobacz 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")

Tłumaczenie wielu danych wejściowych

Zacznij tłumaczyć dokumenty w wielu kontenerach źródłowych na wiele kontenerów docelowych w różnych językach.

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

Wyświetlanie listy operacji tłumaczenia

Wyliczanie operacji tłumaczenia przesłanych dla zasobu.

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

Aby zobaczyć, jak używać biblioteki klienta tłumaczenia dokumentów z obiektem blob usługi Azure Storage do przekazywania dokumentów, tworzenia tokenów SAS dla kontenerów i pobierania gotowych przetłumaczonych dokumentów, zobacz ten przykład. Pamiętaj, że musisz zainstalować bibliotekę azure-storage-blob , aby uruchomić ten przykład.

Tematy zaawansowane

Poniższa sekcja zawiera szczegółowe informacje dotyczące niektórych zaawansowanych funkcji tłumaczenia, takich jak słowniki i niestandardowe modele tłumaczenia.

Glosariusze

Słowniki są słownikami specyficznymi dla domeny. Jeśli na przykład chcesz przetłumaczyć niektóre dokumenty związane z medycyną, może być konieczne wsparcie dla wielu słów, terminologii i idiomów w polu medycznym, którego nie można znaleźć w standardowym słowniku tłumaczenia lub po prostu potrzebujesz konkretnego tłumaczenia. Dlatego tłumaczenie dokumentów zapewnia obsługę słowników.

Jak utworzyć plik słownika

Tłumaczenie dokumentu obsługuje słowniki w następujących formatach:

Typ pliku Rozszerzenie Opis Samples
Tab-Separated Wartości/KARTA .tsv, .tab Przeczytaj więcej na temat wikipedii glossary_sample.tsv
wartości Comma-Separated .csv Przeczytaj więcej na temat wikipedii glossary_sample.csv
Format pliku wymiany lokalizacji .xlf, .xliff Przeczytaj więcej na temat wikipedii glossary_sample.xlf

Tutaj wyświetl wszystkie obsługiwane formaty.

Jak używać słowników w tłumaczeniu dokumentów

Aby używać słowników z tłumaczeniem dokumentów, należy najpierw przekazać plik słownika do kontenera obiektów blob, a następnie podać adres URL sygnatury dostępu współdzielonego do pliku, tak jak w przykładach kodu sample_translation_with_glossaries.py.

Niestandardowe modele tłumaczenia

Zamiast używać aparatu tłumaczenia dokumentów do tłumaczenia, możesz użyć własnego niestandardowego modelu uczenia maszynowego/głębokiego platformy Azure.

Jak utworzyć niestandardowy model tłumaczenia

Aby uzyskać więcej informacji na temat tworzenia, aprowizowania i wdrażania własnego niestandardowego modelu tłumaczenia na platformie Azure, postępuj zgodnie z instrukcjami dostępnymi tutaj: Tworzenie, wdrażanie i używanie modelu niestandardowego do tłumaczenia

Jak używać niestandardowego modelu tłumaczenia z tłumaczeniem dokumentów

Aby użyć niestandardowego modelu tłumaczenia z tłumaczeniem dokumentów, należy najpierw utworzyć i wdrożyć model, a następnie postępować zgodnie z przykładowym kodem sample_translation_with_custom_model.py , aby używać go z tłumaczeniem dokumentów.

Rozwiązywanie problemów

Ogólne

Biblioteka klienta tłumaczenia dokumentów zgłosi wyjątki zdefiniowane w usłudze Azure Core.

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania.

Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na INFO poziomie.

Szczegółowe DEBUG rejestrowanie na poziomie, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie lub na operację z argumentem słowa kluczowego logging_enable .

Zobacz pełną dokumentację rejestrowania zestawu SDK z przykładami tutaj.

Konfiguracja opcjonalna

Opcjonalne argumenty słów kluczowych można przekazać na poziomie klienta i na poziomie operacji. W dokumentacji referencyjnej platformy Azure opisano dostępne konfiguracje dotyczące ponownych prób, rejestrowania, protokołów transportowych i nie tylko.

Następne kroki

Poniższa sekcja zawiera kilka fragmentów kodu ilustrujących typowe wzorce używane w bibliotece klienta języka Python tłumaczenia dokumentów. Więcej przykładów można znaleźć w katalogu samples .

Więcej przykładów kodu

Te przykłady kodu pokazują typowe operacje scenariuszy z biblioteką klienta tłumaczenia dokumentów platformy Azure.

Przykłady asynchroniczne

Ta biblioteka zawiera również kompletny zestaw asynchronicznych interfejsów API. Aby ich używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Klienci asynchroniczny znajdują się w azure.ai.translation.document.aio przestrzeni nazw.

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą tłumaczenia dokumentów w usługach Azure Cognitive Services, zobacz dokumentację tłumaczenia dokumentów w witrynie docs.microsoft.com.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.