Azure Document Translation-Clientbibliothek für Python– Version 1.0.0

Artikel
04/05/2023

Die Azure Cognitive Services-Dokumentübersetzung ist ein Clouddienst, mit dem mehrere und komplexe Dokumente in sprachen- und dialektübergreifend übersetzt werden können, wobei die ursprüngliche Dokumentstruktur und das Ursprüngliche Datenformat beibehalten werden. Verwenden Sie die Clientbibliothek für die Dokumentübersetzung für Folgendes:

Übersetzen Sie zahlreiche große Dateien aus einem Azure Blob Storage Container in einen Zielcontainer in der Sprache Ihrer Wahl.
Überprüfen Sie den Übersetzungsstatus und den Fortschritt der einzelnen Dokumente im Übersetzungsvorgang.
Wenden Sie ein benutzerdefiniertes Übersetzungsmodell oder Glossare an, um die Übersetzung an Ihren spezifischen Fall anzupassen.

Quellcode | Paket (PyPI) | API-Referenzdokumentation | Produktdokumentation | Proben

Haftungsausschluss

Die Unterstützung von Azure SDK-Python-Paketen für Python 2.7 endet am 01. Januar 2022. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.

Erste Schritte

Voraussetzungen

Für die Verwendung dieses Pakets ist Python 3.6 oder höher erforderlich.
Sie benötigen ein Azure-Abonnement und eine Translator-Ressource , um dieses Paket verwenden zu können.

Installieren des Pakets

Installieren Sie die Clientbibliothek für die Azure-Dokumentübersetzung für Python mit pip:

pip install azure-ai-translation-document

Hinweis: Diese Version der Clientbibliothek ist standardmäßig die Version v1.0 des Diensts.

Erstellen einer Translator-Ressource

Die Dokumentübersetzungsfunktion unterstützt nur den Einzeldienstzugriff . Um auf den Dienst zuzugreifen, erstellen Sie eine Translator-Ressource.

Sie können die Ressource mit

Option 1:Azure-Portal

Option 2:Azure CLI. Im Folgenden finden Sie ein Beispiel dafür, wie Sie eine Translator-Ressource mithilfe der CLI erstellen können:

# 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

Authentifizieren des Clients

Um mit dem Featuredienst dokumentübersetzung zu interagieren, müssen Sie eine Instanz eines Clients erstellen. Ein Endpunkt und Anmeldeinformationen sind erforderlich, um das Clientobjekt zu instanziieren.

Nachschlagen des Endpunkts

Sie finden den Endpunkt für Ihre Translator-Ressource im Azure-Portal.

Beachten Sie, dass für den Dienst ein benutzerdefinierter Domänenendpunkt erforderlich ist. Befolgen Sie die Anweisungen im obigen Link, um Ihren Endpunkt zu formatieren: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Abrufen des API-Schlüssels

Den API-Schlüssel finden Sie im Azure-Portal oder durch Ausführen des folgenden Azure CLI-Befehls:

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

Erstellen des Clients mit AzureKeyCredential

Um einen API-Schlüssel als credential Parameter zu verwenden, übergeben Sie den Schlüssel als Zeichenfolge an eine Instanz von 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)

Erstellen des Clients mit Azure Active Directory-Anmeldeinformationen

AzureKeyCredential Die Authentifizierung wird in den Beispielen in diesem Leitfaden zu den ersten Schritten verwendet, Aber Sie können sich auch mithilfe der Azure-Identity-Bibliothek bei Azure Active Directory authentifizieren.

Um den unten gezeigten DefaultAzureCredential-Typ oder andere Anmeldeinformationstypen zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie das azure-identity Paket:

pip install azure-identity

Sie müssen auch eine neue AAD-Anwendung registrieren und Zugriff auf Ihre Translator-Ressource gewähren, indem Sie die "Cognitive Services User" Rolle Ihrem Dienstprinzipal zuweisen.

Legen Sie nach Abschluss des Vorgangs die Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: 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
)

Wichtige Begriffe

Der Dokumentübersetzungsdienst erfordert, dass Sie Ihre Dateien in einen Azure Blob Storage Quellcontainer hochladen und einen Zielcontainer bereitstellen, in dem die übersetzten Dokumente geschrieben werden können. Weitere Informationen zum Einrichten finden Sie in der Dienstdokumentation:

Einrichten von Azure Blob Storage Containern mit Ihren Dokumenten
Wenden Sie optional Glossare oder ein benutzerdefiniertes Modell für die Übersetzung an.
Lassen Sie den Zugriff auf Ihr Speicherkonto mit einer der folgenden Optionen zu:
- Generieren von SAS-Token für Ihre Container (oder Dateien) mit den entsprechenden Berechtigungen
- Erstellen und Verwenden einer verwalteten Identität zum Gewähren des Zugriffs auf Ihr Speicherkonto

DocumentTranslationClient

Die Interaktion mit der Dokumentübersetzungs-Clientbibliothek beginnt mit einer Instanz von DocumentTranslationClient. Der Client stellt Vorgänge für Folgendes bereit:

Erstellen eines Übersetzungsvorgangs, um Dokumente in Ihren Quellcontainern zu übersetzen und Ergebnisse in Ihre Zielcontainer zu schreiben.
Überprüfen des Status einzelner Dokumente im Übersetzungsvorgang und Überwachen des Fortschritts jedes Dokuments.
Aufzählen aller vergangenen und aktuellen Übersetzungsvorgänge.
Identifizieren unterstützter Glossar- und Dokumentformate.

Übersetzungseingabe

Eingaben für die begin_translation Clientmethode können auf zwei verschiedene Arten bereitgestellt werden:

Ein einzelner Quellcontainer mit Dokumenten kann in eine andere Sprache übersetzt werden:

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

Oder mehrere verschiedene Quellen können jeweils mit eigenen Zielen bereitgestellt werden.

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)

Hinweis: Die target_url für jede Zielsprache muss eindeutig sein.

Informationen zum Übersetzen von Dokumenten in einem Ordner oder nur zum Übersetzen bestimmter Dokumente finden Sie unter sample_begin_translation_with_filters.py. Informationen zu allen unterstützten Sprachen finden Sie in der Dienstdokumentation.

Long-Running Vorgänge

Vorgänge mit langer Ausführungsdauer sind Vorgänge, die aus einer anfänglichen Anforderung bestehen, die an den Dienst gesendet wird, um einen Vorgang zu starten, gefolgt von der Abfrage des Diensts in Intervallen, um festzustellen, ob der Vorgang abgeschlossen oder fehlgeschlagen ist, und ob er erfolgreich war, um das Ergebnis zu erhalten.

Methoden, die Dokumente übersetzen, werden als Vorgänge mit langer Ausführungsdauer modelliert. Der Client macht eine begin_<method-name> Methode verfügbar, die ein DocumentTranslationLROPoller oder AsyncDocumentTranslationLROPollerzurückgibt. Aufrufer sollten warten, bis der Vorgang abgeschlossen ist, indem sie für das Von der begin_<method-name> -Methode zurückgegebene Poller-Objekt aufrufenresult(). Beispielcodeausschnitte werden bereitgestellt, um die Verwendung von Vorgängen mit langer Ausführungszeit zu veranschaulichen unten.

Beispiele

Der folgende Abschnitt enthält mehrere Codeausschnitte, die einige der gängigsten Aufgaben der Dokumentübersetzung abdecken, einschließlich:

Übersetzen Ihrer Dokumente
Übersetzen mehrerer Eingaben
Auflisten von Übersetzungsvorgängen

Übersetzen Ihrer Dokumente

Übersetzen Sie alle Dokumente in Ihrem Quellcontainer in den Zielcontainer. Informationen zum Übersetzen von Dokumenten in einem Ordner oder nur zum Übersetzen bestimmter Dokumente finden Sie unter 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")

Übersetzen mehrerer Eingaben

Beginnen Sie mit der Übersetzung von Dokumenten in mehreren Quellcontainern in mehrere Zielcontainer in verschiedenen Sprachen.

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

Auflisten von Übersetzungsvorgängen

Auflisten der für die Ressource übermittelten Übersetzungsvorgänge.

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

In diesem Beispiel erfahren Sie, wie Sie mithilfe der Clientbibliothek für die Dokumentübersetzung mit Azure Storage Blob Dokumente hochladen, SAS-Token für Ihre Container erstellen und die fertigen übersetzten Dokumente herunterladen. Beachten Sie, dass Sie die azure-storage-blob-Bibliothek installieren müssen, um dieses Beispiel auszuführen.

Weiterführende Themen

Der folgende Abschnitt enthält einige Erkenntnisse zu einigen erweiterten Übersetzungsfeatures, z. B. Glossare und benutzerdefinierte Übersetzungsmodelle.

Glossare

Glossare sind domänenspezifische Wörterbücher. Wenn Sie beispielsweise einige medizinbezogene Dokumente übersetzen möchten, benötigen Sie möglicherweise Unterstützung für die vielen Wörter, Terminologie und Ausdrücke im medizinischen Bereich, die Sie im Standardübersetzungswörterbuch nicht finden können, oder Sie benötigen einfach eine spezifische Übersetzung. Aus diesem Grund bietet die Dokumentübersetzung Unterstützung für Glossare.

Erstellen einer Glossardatei

Die Dokumentübersetzung unterstützt Glossare in den folgenden Formaten:

Dateityp	Erweiterung	Beschreibung	Beispiele
Durch Tabstopp getrennte Werte	.tsv, .tab	Lesen Sie mehr auf wikipedia	glossary_sample.tsv
Durch Trennzeichen getrennte Datei	.csv	Weitere Informationen finden Sie unter wikipedia	glossary_sample.csv
Localization Interchange File Format	XLF, XLIFF	Weitere Informationen finden Sie unter wikipedia	glossary_sample.xlf

Sehen Sie sich hier alle unterstützten Formate an.

Verwenden von Glossaren in der Dokumentübersetzung

Um Glossare mit der Dokumentübersetzung verwenden zu können, müssen Sie zuerst Ihre Glossardatei in einen Blobcontainer hochladen und dann die SAS-URL für die Datei angeben, wie in den Codebeispielen sample_translation_with_glossaries.py.

Benutzerdefinierte Übersetzungsmodelle

Anstatt die Engine der Dokumentübersetzung für die Übersetzung zu verwenden, können Sie Ihr eigenes benutzerdefiniertes Azure Machine/Deep Learning-Modell verwenden.

Erstellen eines benutzerdefinierten Übersetzungsmodells

Weitere Informationen zum Erstellen, Bereitstellen und Bereitstellen eines eigenen benutzerdefinierten Azure-Übersetzungsmodells finden Sie in den Anweisungen hier: Erstellen, Bereitstellen und Verwenden eines benutzerdefinierten Modells für die Übersetzung

Verwenden eines benutzerdefinierten Übersetzungsmodells mit der Dokumentübersetzung

Um ein benutzerdefiniertes Übersetzungsmodell mit der Dokumentübersetzung zu verwenden, müssen Sie zunächst Ihr Modell erstellen und bereitstellen. Folgen Sie dann dem Codebeispiel sample_translation_with_custom_model.py zur Verwendung mit der Dokumentübersetzung.

Problembehandlung

Allgemein

Die Dokumentübersetzungsclientbibliothek löst die in Azure Core definierten Ausnahmen aus.

Protokollierung

Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung.

Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf Ebene INFO protokolliert.

Die detaillierte DEBUG Protokollierung auf Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf dem Client oder pro Vorgang mit dem logging_enable Schlüsselwortargument aktiviert werden.

Sehen Sie sich die vollständige SDK-Protokollierungsdokumentation mit Beispielen hier an.

Optionale Konfiguration

Optionale Schlüsselwortargumente können auf Client- und Vorgangsebene übergeben werden. Die azure-core-Referenzdokumentation beschreibt verfügbare Konfigurationen für Wiederholungen, Protokollierung, Transportprotokolle und vieles mehr.

Nächste Schritte

Der folgende Abschnitt enthält mehrere Codeausschnitte, die gängige Muster veranschaulichen, die in der Python-Clientbibliothek für die Dokumentübersetzung verwendet werden. Weitere Beispiele finden Sie im Verzeichnis samples .

Weiterer Beispielcode

Diese Codebeispiele zeigen häufige Szenariovorgänge mit der Azure Document Translation-Clientbibliothek.

Clientauthentifizierung: sample_authentication.py
Beginnen Sie mit der Übersetzung von Dokumenten: sample_begin_translation.py
Übersetzen mit mehreren Eingaben: sample_translate_multiple_inputs.py
Überprüfen Sie den Status von Dokumenten: sample_check_document_statuses.py
Auflisten aller übermittelten Übersetzungsvorgänge: sample_list_translations.py
Anwenden eines benutzerdefinierten Glossars auf die Übersetzung: sample_translation_with_glossaries.py
Verwenden Sie Azure Blob Storage, um Übersetzungsressourcen einzurichten: sample_translation_with_azure_blob.py

Asynchrone Beispiele

Diese Bibliothek enthält auch einen vollständigen Satz von asynchronen APIs. Um sie zu verwenden, müssen Sie zuerst einen asynchronen Transport installieren, z. B. aiohttp. Asynchrone Clients befinden sich unter dem azure.ai.translation.document.aio Namespace.

Clientauthentifizierung: sample_authentication_async.py
Beginnen Sie mit der Übersetzung von Dokumenten: sample_begin_translation_async.py
Übersetzen mit mehreren Eingaben: sample_translate_multiple_inputs_async.py
Überprüfen Sie den Status von Dokumenten: sample_check_document_statuses_async.py
Auflisten aller übermittelten Übersetzungsvorgänge: sample_list_translations_async.py
Anwenden eines benutzerdefinierten Glossars auf die Übersetzung: sample_translation_with_glossaries_async.py
Verwenden Sie Azure Blob Storage, um Übersetzungsressourcen einzurichten: sample_translation_with_azure_blob_async.py

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zur Azure Cognitive Services-Dokumentübersetzung finden Sie in der Dokumentation zur Dokumentübersetzung auf docs.microsoft.com.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Freigeben über