Sdílet prostřednictvím

Klientská knihovna azure Document Translation pro Python – verze 1.0.0

  • Článek

Překlad dokumentů Azure Cognitive Services je cloudová služba, kterou je možné použít k překladu několika složitých dokumentů napříč jazyky a dialekty při zachování původní struktury dokumentů a formátu dat. Pomocí klientské knihovny pro překlad dokumentů můžete:

  • Přeložte velké soubory z kontejneru Azure Blob Storage do cílového kontejneru ve vašem jazyce.
  • Zkontrolujte stav a průběh překladu jednotlivých dokumentů v operaci překladu.
  • Použití vlastního modelu překladu nebo glosáře k přizpůsobení překladu konkrétnímu případu

Zdrojový kód | Balíček (PyPI) | Referenční dokumentace k | rozhraní API Dokumentace k | produktu Vzorky

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete na https://github.com/Azure/azure-sdk-for-python/issues/20691

Začínáme

Požadavky

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Document Translation pro Python pomocí pipu:

pip install azure-ai-translation-document

Poznámka: Tato verze klientské knihovny má výchozí verzi služby v1.0.

Vytvoření prostředku Služby Translator

Funkce překladu dokumentů podporuje přístup jenom s jednou službou . Pokud chcete získat přístup ke službě, vytvořte prostředek Translator.

Prostředek můžete vytvořit pomocí

Možnost 1:Azure Portal

Možnost 2:Azure CLI Níže je příklad vytvoření prostředku Služby Translator pomocí rozhraní příkazového řádku:

# 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

Ověření klienta

Abyste mohli pracovat se službou funkcí překladu dokumentů, budete muset vytvořit instanci klienta. Koncový bod a přihlašovací údaje jsou nezbytné k vytvoření instance objektu klienta.

Vyhledání koncového bodu

Koncový bod pro prostředek Služby Translator najdete na webu Azure Portal.

Všimněte si, že služba vyžaduje vlastní koncový bod domény. Postupujte podle pokynů na výše uvedeném odkazu a naformátujte koncový bod: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Získání klíče rozhraní API

Klíč rozhraní API najdete na webu Azure Portal nebo spuštěním následujícího příkazu Azure CLI:

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

Vytvoření klienta pomocí AzureKeyCredential

Pokud chcete jako credential parametr použít klíč rozhraní API, předejte klíč jako řetězec do instance 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)

Vytvoření klienta s přihlašovacími údaji Azure Active Directory

AzureKeyCredential ověřování se používá v příkladech v této příručce Začínáme, ale můžete se také ověřit pomocí azure Active Directory pomocí knihovny azure-identity .

Pokud chcete použít níže uvedený typ DefaultAzureCredential nebo jiné typy přihlašovacích údajů poskytované se sadou Azure SDK, nainstalujte azure-identity balíček:

pip install azure-identity

Budete také muset zaregistrovat novou aplikaci AAD a udělit přístup k vašemu "Cognitive Services User" prostředku Translator přiřazením role k instančnímu objektu.

Po dokončení nastavte hodnoty ID klienta, ID tenanta a tajného klíče klienta aplikace AAD jako proměnné prostředí: 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
)

Klíčové koncepty

Služba překladu dokumentů vyžaduje, abyste nahráli soubory do zdrojového kontejneru Azure Blob Storage a poskytli cílový kontejner, do kterého lze přeložené dokumenty zapisovat. Další informace o tomto nastavení najdete v dokumentaci ke službě:

DocumentTranslationClient

Interakce s klientskou knihovnou překladu dokumentů začíná instancí objektu DocumentTranslationClient. Klient poskytuje operace pro:

  • Vytvoření operace překladu pro překlad dokumentů ve zdrojových kontejnerech a zápis výsledků do cílových kontejnerů
  • Kontrola stavu jednotlivých dokumentů v operaci překladu a sledování průběhu jednotlivých dokumentů
  • Výčet všech minulých a aktuálních operací překladu
  • Identifikace podporovaných formátů glosáře a dokumentů

Vstup překladu

Vstup do begin_translation metody klienta lze poskytnout dvěma různými způsoby:

  1. Jeden zdrojový kontejner s dokumenty je možné přeložit do jiného jazyka:
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. Nebo je možné poskytnout více různých zdrojů s vlastními cíli.
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)

Poznámka: target_url pro každý cílový jazyk musí být jedinečný.

Pokud chcete přeložit dokumenty ve složce nebo jenom některé dokumenty, přečtěte si článek sample_begin_translation_with_filters.py. Všechny podporované jazyky najdete v dokumentaci ke službě.

operace Long-Running

Dlouhotrvající operace jsou operace, které se skládají z počátečního požadavku odeslaného službě na spuštění operace a následného dotazování služby v intervalech, aby se zjistilo, jestli se operace dokončila nebo selhala, a pokud byla úspěšná, aby se získal výsledek.

Metody, které překládají dokumenty, se modelují jako dlouhotrvající operace. Klient zveřejňuje metodu begin_<method-name> , která vrací DocumentTranslationLROPoller nebo AsyncDocumentTranslationLROPoller. Volající by měli počkat na dokončení operace voláním result() objektu poller vráceného begin_<method-name> z metody. Ukázkové fragmenty kódu jsou k dispozici pro ilustraci použití dlouhotrvajících operací níže.

Příklady

Následující část obsahuje několik fragmentů kódu, které pokrývají některé nejběžnější úlohy překladu dokumentů, mezi které patří:

Překlad dokumentů

Přeložte všechny dokumenty ve zdrojovém kontejneru do cílového kontejneru. Pokud chcete přeložit dokumenty ve složce nebo jenom některé dokumenty, přečtěte si článek 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")

Překlad více vstupů

Začněte překládat dokumenty v několika zdrojových kontejnerech do několika cílových kontejnerů v různých jazycích.

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

Operace překladu seznamu

Zadejte výčet operací překladu odeslaných pro prostředek.

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

Pokud chcete zjistit, jak používat klientskou knihovnu překladu dokumentů s objektem blob služby Azure Storage k nahrávání dokumentů, vytváření tokenů SAS pro kontejnery a stažení dokončených přeložených dokumentů, podívejte se na tuto ukázku. Upozorňujeme, že ke spuštění této ukázky budete muset nainstalovat knihovnu azure-storage-blob .

Pokročilá témata

Následující část obsahuje přehled některých pokročilých funkcí překladu, jako jsou glosáře a vlastní modely překladu.

Glosáře

Glosáře jsou slovníky specifické pro doménu. Pokud například chcete přeložit některé lékařské dokumenty, možná budete potřebovat podporu pro mnoho slov, terminologie a idiomů v lékařské oblasti, které nemůžete najít ve standardním překladovém slovníku, nebo prostě potřebujete konkrétní překlad. Proto překlad dokumentů podporuje glosáře.

Vytvoření souboru glosáře

Překlad dokumentů podporuje glosáře v následujících formátech:

Typ souboru Linka Popis ukázky
Tab-Separated Hodnoty/TAB .tsv, .tab Další informace najdete na wikipedii. glossary_sample.tsv
Comma-Separated hodnoty .csv Další informace najdete na wikipedii. glossary_sample.csv
Formát souboru Localization Interchange .xlf, .xliff Další informace najdete na wikipedii. glossary_sample.xlf

Tady si můžete prohlédnout všechny podporované formáty.

Jak používat glosáře v překladu dokumentů

Pokud chcete používat glosáře s překladem dokumentů, musíte nejdřív nahrát soubor glosáře do kontejneru objektů blob a pak k souboru zadat adresu URL SAS jako v ukázkách kódu sample_translation_with_glossaries.py.

Vlastní modely překladu

Místo toho, abyste k překladu použili modul překladu dokumentů, můžete použít vlastní model strojového/hlubokého učení Azure.

Vytvoření vlastního modelu překladu

Další informace o tom, jak vytvořit, zřídit a nasadit vlastní model překladu Azure, najdete v následujících pokynech: Sestavení, nasazení a použití vlastního modelu pro překlad.

Použití vlastního modelu překladu s překladem dokumentů

Pokud chcete použít vlastní model překladu s překladem dokumentů, musíte nejprve vytvořit a nasadit model a pak postupovat podle ukázkového kódu sample_translation_with_custom_model.py , který použijete s překladem dokumentů.

Poradce při potížích

Obecné

Klientská knihovna pro překlad dokumentů vyvolá výjimky definované v Azure Core.

protokolování

Tato knihovna používá pro protokolování standardní knihovnu protokolování .

Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na INFO úrovni.

Protokolování podrobných DEBUG úrovní, včetně těl požadavků/odpovědí a nereagovaných hlaviček, je možné povolit u klienta nebo pro jednotlivé operace pomocí argumentu klíčového logging_enable slova.

Kompletní dokumentaci k protokolování sady SDK s příklady najdete tady.

Volitelná konfigurace

Volitelné argumenty klíčových slov je možné předat na úrovni klienta a na úrovni jednotlivých operací. Referenční dokumentace azure-core popisuje dostupné konfigurace pro opakování, protokolování, přenosové protokoly a další.

Další kroky

Následující část obsahuje několik fragmentů kódu, které ilustrují běžné vzory používané v klientské knihovně Pythonu pro překlad dokumentů. Další ukázky najdete v adresáři samples .

Další ukázkový kód

Tyto ukázky kódu ukazují běžné operace scénářů s klientskou knihovnou překladu dokumentů Azure.

Asynchronní ukázky

Tato knihovna také obsahuje kompletní sadu asynchronních rozhraní API. Abyste je mohli používat, musíte nejprve nainstalovat asynchronní přenos, například aiohttp. Asynchronní klienti se nacházejí v azure.ai.translation.document.aio oboru názvů.

Další dokumentace

Rozsáhlejší dokumentaci k překladu dokumentů služby Azure Cognitive Services najdete v dokumentaci k překladu dokumentů na docs.microsoft.com.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete na cla.microsoft.com.

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.