Condividi tramite

Libreria client di Traduzione documenti di Azure per Python - versione 1.0.0

  • Articolo

Traduzione documenti di Servizi cognitivi di Azure è un servizio cloud che può essere usato per tradurre più documenti complessi tra lingue e dialetti mantenendo al tempo stesso la struttura e il formato dei dati originali del documento. Usare la raccolta client per La traduzione documenti per:

  • Tradurre numerosi file di grandi dimensioni da un contenitore Archiviazione BLOB di Azure a un contenitore di destinazione nella lingua preferita.
  • Controllare lo stato della traduzione e lo stato di avanzamento di ogni documento nell'operazione di traduzione.
  • Applicare un modello di traduzione personalizzato o glossari per adattare la traduzione al caso specifico.

Codice | sorgente Pacchetto (PyPI) | Documentazione | di riferimento sulle APIDocumentazione | del prodotto Campioni

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato il 01 gennaio 2022. Per altre informazioni e domande, fare riferimento a https://github.com/Azure/azure-sdk-for-python/issues/20691

Introduzione

Prerequisiti

Installare il pacchetto

Installare la libreria client di Traduzione documenti di Azure per Python con pip:

pip install azure-ai-translation-document

Nota: questa versione della libreria client usa per impostazione predefinita la versione 1.0 del servizio

Creare una risorsa per Translator

La funzionalità Traduzione documenti supporta solo l'accesso a servizio singolo . Per accedere al servizio, creare una risorsa Translator.

È possibile creare la risorsa usando

Opzione 1:Portale di Azure

Opzione 2:Interfaccia della riga di comando di Azure. Di seguito è riportato un esempio di come creare una risorsa Translator usando l'interfaccia della riga di comando:

# 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

Autenticare il client

Per interagire con il servizio di funzionalità Traduzione documenti, è necessario creare un'istanza di un client. Un endpoint e le credenziali sono necessari per creare un'istanza dell'oggetto client.

Ricerca dell'endpoint

È possibile trovare l'endpoint per la risorsa Traduttore usando il portale di Azure.

Si noti che il servizio richiede un endpoint di dominio personalizzato. Seguire le istruzioni nel collegamento precedente per formattare l'endpoint: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Ottenere la chiave API

La chiave API è disponibile nel portale di Azure o eseguendo il comando seguente dell'interfaccia della riga di comando di Azure:

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

Creare il client con AzureKeyCredential

Per usare una chiave API come credential parametro, passare la chiave come stringa in un'istanza di 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)

Creare il client con credenziali di Azure Active Directory

AzureKeyCredential l'autenticazione viene usata negli esempi di questa guida introduttiva, ma è anche possibile eseguire l'autenticazione con Azure Active Directory usando la libreria azure-identity .

Per usare il tipo DefaultAzureCredential illustrato di seguito o altri tipi di credenziali forniti con Azure SDK, installare il azure-identity pacchetto:

pip install azure-identity

Sarà anche necessario registrare una nuova applicazione AAD e concedere l'accesso alla risorsa Translator assegnando il ruolo all'entità "Cognitive Services User" servizio.

Al termine, impostare i valori dell'ID client, dell'ID tenant e del segreto client dell'applicazione AAD come variabili di ambiente: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_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
)

Concetti chiave

Il servizio Traduzione documenti richiede di caricare i file in un contenitore di origine Archiviazione BLOB di Azure e fornire un contenitore di destinazione in cui è possibile scrivere i documenti tradotti. Altre informazioni sulla configurazione sono disponibili nella documentazione del servizio:

DocumentTranslationClient

L'interazione con la libreria client Di traduzione documenti inizia con un'istanza DocumentTranslationClientdi . Il client fornisce operazioni per:

  • Creazione di un'operazione di traduzione per tradurre i documenti nei contenitori di origine e scrivere i risultati nei contenitori di destinazione.
  • Controllo dello stato dei singoli documenti nell'operazione di traduzione e monitoraggio dello stato di avanzamento di ogni documento.
  • Enumerazione di tutte le operazioni di traduzione passate e correnti.
  • Identificazione dei formati di glossario e documento supportati.

Input di traduzione

L'input al begin_translation metodo client può essere fornito in due modi diversi:

  1. Un singolo contenitore di origine con documenti può essere tradotto in una lingua diversa:
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. In alternativa, è possibile fornire più origini diverse ognuna con le proprie destinazioni.
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)

Nota: il target_url per ogni lingua di destinazione deve essere univoco.

Per tradurre i documenti in una cartella o tradurre solo determinati documenti, vedere sample_begin_translation_with_filters.py. Vedere la documentazione del servizio per tutte le lingue supportate.

Operazioni di Long-Running

Le operazioni a esecuzione prolungata sono operazioni costituite da una richiesta iniziale inviata al servizio per avviare un'operazione, seguita dal polling del servizio a intervalli per determinare se l'operazione è stata completata o non riuscita e, se ha avuto esito positivo, per ottenere il risultato.

I metodi che convertono i documenti vengono modellati come operazioni a esecuzione prolungata. Il client espone un begin_<method-name> metodo che restituisce un DocumentTranslationLROPoller oggetto o AsyncDocumentTranslationLROPoller. I chiamanti devono attendere il completamento dell'operazione chiamando result() sull'oggetto poller restituito dal begin_<method-name> metodo . Di seguito vengono forniti frammenti di codice di esempio per illustrare l'uso di operazioni a esecuzione prolungata

Esempio

La sezione seguente fornisce diversi frammenti di codice che illustrano alcune delle attività di traduzione documenti più comuni, tra cui:

Tradurre i documenti

Tradurre tutti i documenti nel contenitore di origine nel contenitore di destinazione. Per tradurre i documenti in una cartella o tradurre solo determinati documenti, vedere 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")

Tradurre più input

Iniziare a tradurre con documenti in più contenitori di origine in più contenitori di destinazione in lingue diverse.

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

Elencare le operazioni di traduzione

Enumerare le operazioni di conversione inviate per la risorsa.

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

Per informazioni su come usare la libreria client di Traduzione documenti con il BLOB di archiviazione di Azure per caricare documenti, creare token di firma di accesso condiviso per i contenitori e scaricare i documenti tradotti completati, vedere questo esempio. Per eseguire questo esempio, è necessario installare la libreria azure-storage-blob .

Argomenti avanzati

La sezione seguente fornisce alcune informazioni dettagliate per alcune funzionalità di traduzione avanzate, ad esempio glossari e modelli di traduzione personalizzati.

Glossari

I glossari sono dizionari specifici del dominio. Ad esempio, se si desidera tradurre alcuni documenti medici, potrebbe essere necessario il supporto per molte parole, terminologia e idiomi nel campo medico che non è possibile trovare nel dizionario di traduzione standard oppure è sufficiente una traduzione specifica. Questo è il motivo per cui La traduzione documenti fornisce supporto per i glossari.

Come creare un file di glossario

Traduzione documenti supporta i glossari nei formati seguenti:

Tipo di file Estensione Descrizione Esempi
Valori Tab-Separated/TAB .tsv, .tab Altre informazioni su wikipedia glossary_sample.tsv
valori Comma-Separated .csv Altre informazioni su wikipedia glossary_sample.csv
Formato file di interscambio di localizzazione .xlf, .xliff Altre informazioni su wikipedia glossary_sample.xlf

Visualizzare tutti i formati supportati qui.

Come usare i glossari nella traduzione dei documenti

Per usare i glossari con La traduzione documenti, è prima necessario caricare il file di glossario in un contenitore BLOB e quindi specificare l'URL della firma di accesso condiviso al file come negli esempi di codice sample_translation_with_glossaries.py.

Modelli di traduzione personalizzati

Anziché usare il motore di Traduzione documenti per la traduzione, è possibile usare un modello personalizzato di Azure machine/deep learning personalizzato.

Come creare un modello di traduzione personalizzato

Per altre informazioni su come creare, effettuare il provisioning e distribuire il proprio modello di traduzione di Azure personalizzato, seguire le istruzioni riportate di seguito: Compilare, distribuire e usare un modello personalizzato per la traduzione

Come usare un modello di traduzione personalizzata con la traduzione dei documenti

Per usare un modello di traduzione personalizzato con La traduzione documenti, è prima necessario creare e distribuire il modello, quindi seguire l'esempio di codice sample_translation_with_custom_model.py da usare con La traduzione documenti.

Risoluzione dei problemi

Generale

La raccolta client di Traduzione documenti genererà eccezioni definite in Azure Core.

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione.

Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a INFO livello.

La registrazione dettagliata DEBUG a livello, inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate , può essere abilitata nel client o per operazione con l'argomento logging_enable parola chiave.

Vedere la documentazione completa sulla registrazione sdk con esempi qui.

Configurazione facoltativa

Gli argomenti delle parole chiave facoltativi possono essere passati al client e a livello di operazione. La documentazione di riferimento di azure-core descrive le configurazioni disponibili per tentativi, registrazione, protocolli di trasporto e altro ancora.

Passaggi successivi

La sezione seguente fornisce diversi frammenti di codice che illustrano modelli comuni usati nella libreria client Python di Traduzione documenti. Altri esempi sono disponibili nella directory degli esempi .

Altro codice di esempio

Questi esempi di codice mostrano operazioni di scenario comuni con la libreria client di Traduzione documenti di Azure.

Esempi asincroni

Questa libreria include anche un set completo di API asincrone. Per usarli, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. I client asincroni vengono trovati nello azure.ai.translation.document.aio spazio dei nomi.

Documentazione aggiuntiva

Per una documentazione più completa sulla traduzione dei documenti di Servizi cognitivi di Azure, vedere la documentazione relativa alla traduzione dei documenti in docs.microsoft.com.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, visitare cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.