Delen via

Azure Document Translation-clientbibliotheek voor Python - versie 1.0.0

  • Artikel

Azure Cognitive Services-documentvertaling is een cloudservice die kan worden gebruikt voor het vertalen van meerdere en complexe documenten in talen en dialecten met behoud van de oorspronkelijke documentstructuur en gegevensindeling. Gebruik de clientbibliotheek voor documentvertaling voor het volgende:

  • Vertaal talrijke, grote bestanden van een Azure Blob Storage container naar een doelcontainer in de taal van uw keuze.
  • Controleer de vertaalstatus en voortgang van elk document in de vertaalbewerking.
  • Pas een aangepast vertaalmodel of woordenlijsten toe om de vertaling aan uw specifieke geval aan te passen.

Broncode | Pakket (PyPI) | API-referentiedocumentatie | Productdocumentatie | Monsters

Disclaimer

Ondersteuning voor Azure SDK Python-pakketten voor Python 2.7 is beëindigd op 1 januari 2022. Voor meer informatie en vragen raadpleegt u https://github.com/Azure/azure-sdk-for-python/issues/20691

Aan de slag

Vereisten

Het pakket installeren

Installeer de Azure Document Translation-clientbibliotheek voor Python met pip:

pip install azure-ai-translation-document

Opmerking: deze versie van de clientbibliotheek is standaard ingesteld op de versie v1.0 van de service

Een Translator-resource maken

De functie Documentvertaling biedt alleen ondersteuning voor toegang met één service . Maak een Translator-resource om toegang te krijgen tot de service.

U kunt de resource maken met behulp van

Optie 1:Azure Portal

Optie 2:Azure CLI. Hieronder ziet u een voorbeeld van hoe u een Translator-resource kunt maken met behulp van de 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

De client verifiëren

Als u wilt communiceren met de functieservice Documentvertaling, moet u een exemplaar van een client maken. Er zijn een eindpunt en referenties nodig om het clientobject te instantiëren.

Het eindpunt opzoeken

U kunt het eindpunt voor uw Translator-resource vinden met behulp van Azure Portal.

Houd er rekening mee dat voor de service een aangepast domeineindpunt is vereist. Volg de instructies in de bovenstaande koppeling om uw eindpunt te formatteren: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

De API-sleutel ophalen

U vindt de API-sleutel in Azure Portal of door de volgende Azure CLI-opdracht uit te voeren:

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

De client maken met AzureKeyCredential

Als u een API-sleutel als credential parameter wilt gebruiken, geeft u de sleutel door als een tekenreeks aan een exemplaar van 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)

De client maken met een Azure Active Directory-referentie

AzureKeyCredential verificatie wordt gebruikt in de voorbeelden in deze introductiehandleiding, maar u kunt zich ook verifiëren met Azure Active Directory met behulp van de azure-identity-bibliotheek .

Als u het hieronder weergegeven Type DefaultAzureCredential of andere referentietypen wilt gebruiken die worden geleverd met de Azure SDK, installeert u het azure-identity pakket:

pip install azure-identity

U moet ook een nieuwe AAD-toepassing registreren en toegang verlenen tot uw Translator-resource door de "Cognitive Services User" rol toe te wijzen aan uw service-principal.

Wanneer dit is voltooid, stelt u de waarden van de client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: 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
)

Belangrijkste concepten

Voor de documentvertalingsservice moet u uw bestanden uploaden naar een Azure Blob Storage broncontainer en een doelcontainer opgeven waarin de vertaalde documenten kunnen worden geschreven. Aanvullende informatie over het instellen hiervan vindt u in de servicedocumentatie:

DocumentTranslationClient

Interactie met de clientbibliotheek documentvertaling begint met een exemplaar van de DocumentTranslationClient. De client biedt bewerkingen voor:

  • Een vertaalbewerking maken om documenten in uw broncontainer(s) te vertalen en resultaten naar uw doelcontainer(s) te schrijven.
  • De status van afzonderlijke documenten in de vertaalbewerking controleren en de voortgang van elk document bijhouden.
  • Alle eerdere en huidige vertaalbewerkingen opsommen.
  • Ondersteunde woordenlijst- en documentindelingen identificeren.

Vertaalinvoer

Invoer voor de begin_translation clientmethode kan op twee verschillende manieren worden geleverd:

  1. Eén broncontainer met documenten kan worden vertaald in een andere taal:
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. Of meerdere verschillende bronnen kunnen worden voorzien van elk hun eigen doelen.
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)

Opmerking: de target_url voor elke doeltaal moet uniek zijn.

Als u documenten onder een map wilt vertalen of alleen bepaalde documenten wilt vertalen, raadpleegt u sample_begin_translation_with_filters.py. Raadpleeg de servicedocumentatie voor alle ondersteunde talen.

Long-Running bewerkingen

Langlopende bewerkingen zijn bewerkingen die bestaan uit een initiële aanvraag die naar de service wordt verzonden om een bewerking te starten, gevolgd door het pollen van de service met intervallen om te bepalen of de bewerking is voltooid of mislukt, en of deze is geslaagd, om het resultaat te verkrijgen.

Methoden voor het vertalen van documenten worden gemodelleerd als langlopende bewerkingen. De client maakt een begin_<method-name> methode beschikbaar die een DocumentTranslationLROPoller of AsyncDocumentTranslationLROPollerretourneert. Aanroepers moeten wachten tot de bewerking is voltooid door het poller-object aan te roepen result() dat is geretourneerd door de begin_<method-name> methode. Voorbeeldcodefragmenten worden gegeven ter illustratie van het gebruik van langlopende bewerkingen hieronder.

Voorbeelden

De volgende sectie bevat verschillende codefragmenten voor enkele van de meest voorkomende taken voor documentvertaling, waaronder:

Uw documenten vertalen

Vertaal alle documenten in de broncontainer naar de doelcontainer. Als u documenten onder een map wilt vertalen of alleen bepaalde documenten wilt vertalen, raadpleegt u 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")

Meerdere invoer vertalen

Begin met het vertalen van documenten in meerdere broncontainers naar meerdere doelcontainers in verschillende talen.

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

Vertaalbewerkingen weergeven

Inventariseer de vertaalbewerkingen die voor de resource zijn ingediend.

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

Zie dit voorbeeld voor meer informatie over het gebruik van de documentomzettingsclientbibliotheek met Azure Storage Blob om documenten te uploaden, SAS-tokens voor uw containers te maken en de voltooide vertaalde documenten te downloaden. Houd er rekening mee dat u de bibliotheek azure-storage-blob moet installeren om dit voorbeeld uit te voeren.

Geavanceerde onderwerpen

De volgende sectie biedt enkele inzichten voor een aantal geavanceerde vertaalfuncties, zoals woordenlijsten en aangepaste vertaalmodellen.

Glossaria

Woordenlijsten zijn domeinspecifieke woordenlijsten. Als u bijvoorbeeld bepaalde medische documenten wilt vertalen, hebt u mogelijk ondersteuning nodig voor de vele woorden, terminologie en idiomen op medisch gebied die u niet kunt vinden in de standaardvertalingswoordenlijst, of u hebt gewoon een specifieke vertaling nodig. Daarom biedt Document Translation ondersteuning voor woordenlijsten.

Woordenlijstbestand maken

Documentvertaling ondersteunt woordenlijsten in de volgende indelingen:

Bestandstype Extensie Beschrijving Voorbeelden
Tab-Separated waarden/TAB .tsv, .tab Lees meer op wikipedia glossary_sample.tsv
waarden Comma-Separated .csv Lees meer op wikipedia glossary_sample.csv
Localization Interchange File Format .xlf, .xliff Lees meer op wikipedia glossary_sample.xlf

Bekijk hier alle ondersteunde indelingen.

Woordenlijsten gebruiken in documentvertaling

Als u woordenlijsten wilt gebruiken met documentvertaling, moet u eerst het woordenlijstbestand uploaden naar een blobcontainer en vervolgens de SAS-URL naar het bestand opgeven, zoals in de codevoorbeelden sample_translation_with_glossaries.py.

Aangepaste vertaalmodellen

In plaats van de engine van documentvertaling te gebruiken voor vertaling, kunt u uw eigen aangepaste Azure-machine-/deep learning-model gebruiken.

Een aangepast vertaalmodel maken

Volg de instructies hier voor meer informatie over het maken, inrichten en implementeren van uw eigen aangepaste Azure-vertaalmodel: Een aangepast model bouwen, implementeren en gebruiken voor vertaling

Een aangepast vertaalmodel gebruiken met documentvertaling

Als u een aangepast vertaalmodel wilt gebruiken met documentvertaling, moet u eerst uw model maken en implementeren. Volg vervolgens het codevoorbeeld sample_translation_with_custom_model.py voor gebruik met documentvertaling.

Problemen oplossen

Algemeen

De clientbibliotheek documentvertaling genereert uitzonderingen die zijn gedefinieerd in Azure Core.

Logboekregistratie

Deze bibliotheek maakt gebruik van de standaardbibliotheek voor logboekregistratie voor logboekregistratie.

Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO niveau.

Gedetailleerde DEBUG logboekregistratie op niveau, inclusief aanvraag-/antwoordteksten en niet-bewerkte headers, kan worden ingeschakeld op de client of per bewerking met het logging_enable trefwoordargument.

Bekijk hier de volledige documentatie voor SDK-logboekregistratie met voorbeelden.

Optionele configuratie

Optionele trefwoordargumenten kunnen worden doorgegeven op het niveau van de client en per bewerking. In de naslagdocumentatie van Azure Core worden de beschikbare configuraties beschreven voor nieuwe pogingen, logboekregistratie, transportprotocollen en meer.

Volgende stappen

De volgende sectie bevat verschillende codefragmenten die algemene patronen illustreren die worden gebruikt in de Python-clientbibliotheek voor documentomzetting. Meer voorbeelden vindt u in de map voorbeelden .

Meer voorbeeldcode

Deze codevoorbeelden tonen algemene scenariobewerkingen met de Azure Document Translation-clientbibliotheek.

Asynchrone voorbeelden

Deze bibliotheek bevat ook een volledige set asynchrone API's. Als u deze wilt gebruiken, moet u eerst een asynchroon transport installeren, zoals aiohttp. Asynchrone clients bevinden zich onder de azure.ai.translation.document.aio naamruimte.

Aanvullende documentatie

Zie de documentatie over documentvertaling van Azure Cognitive Services op docs.microsoft.com voor uitgebreidere documentatie over Azure Cognitive Services-documentvertaling .

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.