Share via

Klientbibliotek för Azure-dokumentöversättning för Python – version 1.0.0

  • Artikel

Dokumentöversättning i Azure Cognitive Services är en molntjänst som kan användas för att översätta flera och komplexa dokument mellan språk och dialekter samtidigt som den ursprungliga dokumentstrukturen och dataformatet bevaras. Använd klientbiblioteket för dokumentöversättning för att:

  • Översätt många, stora filer från en Azure Blob Storage container till en målcontainer på det språk du väljer.
  • Kontrollera översättningsstatusen och förloppet för varje dokument i översättningsåtgärden.
  • Använd en anpassad översättningsmodell eller ordlistor för att skräddarsy översättningen till ditt specifika fall.

| Källkod Paket (PyPI) | API-referensdokumentation | Produktdokumentation | Prover

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 upphörde den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691

Komma igång

Förutsättningar

Installera paketet

Installera Azure Document Translation-klientbiblioteket för Python med pip:

pip install azure-ai-translation-document

Obs! Den här versionen av klientbiblioteket är som standard v1.0-versionen av tjänsten

Skapa en Translator-resurs

Funktionen Dokumentöversättning stöder endast åtkomst med en tjänst . Skapa en Translator-resurs för att få åtkomst till tjänsten.

Du kan skapa resursen med hjälp av

Alternativ 1:Azure-portalen

Alternativ 2:Azure CLI. Nedan visas ett exempel på hur du kan skapa en Translator-resurs med hjälp av 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

Autentisera klienten

För att kunna interagera med funktionstjänsten för dokumentöversättning måste du skapa en instans av en klient. En slutpunkt och autentiseringsuppgifter krävs för att instansiera klientobjektet.

Leta upp slutpunkten

Du hittar slutpunkten för din Translator-resurs med hjälp av Azure-portalen.

Observera att tjänsten kräver en anpassad domänslutpunkt. Följ anvisningarna i länken ovan för att formatera slutpunkten: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Hämta API-nyckeln

DU hittar API-nyckeln i Azure-portalen eller genom att köra följande Azure CLI-kommando:

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

Skapa klienten med AzureKeyCredential

Om du vill använda en API-nyckel som credential parameter skickar du nyckeln som en sträng till en instans av 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)

Skapa klienten med en Azure Active Directory-autentiseringsuppgift

AzureKeyCredential autentisering används i exemplen i den här komma igång-guiden, men du kan också autentisera med Azure Active Directory med hjälp av biblioteket azure-identity .

Om du vill använda typen DefaultAzureCredential som visas nedan eller andra typer av autentiseringsuppgifter som medföljer Azure SDK installerar azure-identity du paketet:

pip install azure-identity

Du måste också registrera ett nytt AAD-program och bevilja åtkomst till translator-resursen "Cognitive Services User" genom att tilldela rollen till tjänstens huvudnamn.

När det är klart anger du värdena för klient-ID, klient-ID och klienthemlighet för AAD-programmet som miljövariabler: 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
)

Viktiga begrepp

Dokumentöversättningstjänsten kräver att du laddar upp dina filer till en Azure Blob Storage källcontainer och tillhandahåller en målcontainer där de översatta dokumenten kan skrivas. Mer information om hur du konfigurerar detta finns i tjänstdokumentationen:

DocumentTranslationClient

Interaktionen med klientbiblioteket för dokumentöversättning börjar med en instans av DocumentTranslationClient. Klienten tillhandahåller åtgärder för:

  • Skapa en översättningsåtgärd för att översätta dokument i dina källcontainrar och skriva resultat till målcontainrar.
  • Kontrollera status för enskilda dokument i översättningsåtgärden och övervaka förloppet för varje dokument.
  • Räkna upp alla tidigare och aktuella översättningsåtgärder.
  • Identifiera ordliste- och dokumentformat som stöds.

Översättningsindata

Indata till begin_translation klientmetoden kan anges på två olika sätt:

  1. En container med en enda källa med dokument kan översättas till ett annat språk:
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. Eller så kan flera olika källor förses med sina egna mål.
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)

Obs! Target_url för varje målspråk måste vara unikt.

Om du vill översätta dokument under en mapp eller bara översätta vissa dokument kan du läsa sample_begin_translation_with_filters.py. Se tjänstdokumentationen för alla språk som stöds.

Long-Running åtgärder

Långvariga åtgärder är åtgärder som består av en första begäran som skickas till tjänsten för att starta en åtgärd, följt av avsökning av tjänsten med jämna mellanrum för att avgöra om åtgärden har slutförts eller misslyckats, och om den har lyckats för att få resultatet.

Metoder som översätter dokument modelleras som tidskrävande åtgärder. Klienten exponerar en begin_<method-name> metod som returnerar en DocumentTranslationLROPoller eller AsyncDocumentTranslationLROPoller. Anropare bör vänta tills åtgärden har slutförts genom att anropa result() det pollerobjekt som returneras från begin_<method-name> metoden . Exempelkodfragment tillhandahålls för att illustrera med hjälp av långvariga åtgärder nedan.

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste uppgifterna för dokumentöversättning, inklusive:

Översätta dina dokument

Översätt alla dokument i källcontainern till målcontainern. Om du vill översätta dokument under en mapp eller bara översätta vissa dokument kan du läsa 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")

Översätta flera indata

Börja översätta med dokument i flera källcontainrar till flera målcontainrar på olika språk.

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

Lista översättningsåtgärder

Räkna upp översättningsåtgärderna som skickats för resursen.

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

Information om hur du använder klientbiblioteket för dokumentöversättning med Azure Storage Blob för att ladda upp dokument, skapa SAS-token för dina containrar och ladda ned de färdiga översatta dokumenten finns i det här exemplet. Observera att du måste installera biblioteket azure-storage-blob för att köra det här exemplet.

Avancerade avsnitt

Följande avsnitt innehåller några insikter för vissa avancerade översättningsfunktioner, till exempel ordlistor och anpassade översättningsmodeller.

Ordlistor

Ordlistor är domänspecifika ordlistor. Om du till exempel vill översätta vissa medicinska relaterade dokument kan du behöva stöd för de många ord, terminologi och idiomer i det medicinska fältet som du inte kan hitta i standardöversättningsordlistan, eller så behöver du bara specifik översättning. Därför har dokumentöversättning stöd för ordlistor.

Skapa ordlistefil

Dokumentöversättning stöder ordlistor i följande format:

Filtyp Filnamnstillägg Beskrivning Exempel
Tab-Separated värden/TABB .tsv, .tab Läs mer på wikipedia glossary_sample.tsv
Comma-Separated värden .csv Läs mer på wikipedia glossary_sample.csv
Filformat för lokaliseringsutbyte .xlf, .xliff Läs mer på wikipedia glossary_sample.xlf

Visa alla format som stöds här.

Använda ordlistor i dokumentöversättning

För att kunna använda ordlistor med dokumentöversättning måste du först ladda upp ordlistefilen till en blobcontainer och sedan ange SAS-URL:en till filen som i kodexemplen sample_translation_with_glossaries.py.

Anpassade översättningsmodeller

I stället för att använda dokumentöversättningsmotorn för översättning kan du använda din egen anpassade Azure-maskin/djupinlärningsmodell.

Skapa en anpassad översättningsmodell

Mer information om hur du skapar, etablerar och distribuerar din egen anpassade Azure-översättningsmodell finns i anvisningarna här: Skapa, distribuera och använda en anpassad modell för översättning

Använda en anpassad översättningsmodell med dokumentöversättning

För att kunna använda en anpassad översättningsmodell med dokumentöversättning måste du först skapa och distribuera din modell och sedan följa kodexemplet sample_translation_with_custom_model.py som ska användas med dokumentöversättning.

Felsökning

Allmänt

Klientbiblioteket för dokumentöversättning genererar undantag som definierats i Azure Core.

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning.

Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO nivå.

Detaljerad DEBUG nivåloggning, inklusive begärande-/svarskroppar och oredigerade rubriker, kan aktiveras på klienten eller per åtgärd med nyckelordsargumentet logging_enable .

Se fullständig SDK-loggningsdokumentation med exempel här.

Valfri konfiguration

Valfria nyckelordsargument kan skickas in på klient- och åtgärdsnivå. Referensdokumentationen för azure-core beskriver tillgängliga konfigurationer för återförsök, loggning, transportprotokoll med mera.

Nästa steg

Följande avsnitt innehåller flera kodfragment som illustrerar vanliga mönster som används i Python-klientbiblioteket för dokumentöversättning. Fler exempel finns under exempelkatalogen .

Mer exempelkod

Dessa kodexempel visar vanliga scenarioåtgärder med Klientbiblioteket för Azure Document Translation.

Asynkrona exempel

Det här biblioteket innehåller också en fullständig uppsättning asynkrona API:er. Om du vill använda dem måste du först installera en asynkron transport, till exempel aiohttp. Asynkrona azure.ai.translation.document.aio klienter finns under namnområdet.

Ytterligare dokumentation

Mer omfattande dokumentation om Dokumentöversättning i Azure Cognitive Services finns i dokumentationen om dokumentöversättning på docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.