Klientbibliotek för Azure-dokumentöversättning för Python – version 1.0.0
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
- Python 3.6 eller senare krävs för att använda det här paketet.
- Du måste ha en Azure-prenumeration och en Translator-resurs för att kunna använda det här paketet.
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:
- Konfigurera Azure Blob Storage containrar med dina dokument
- Du kan också använda ordlistor eller en anpassad modell för översättning
- Tillåt åtkomst till ditt lagringskonto med något av följande alternativ:
- Generera SAS-token till dina containrar (eller filer) med rätt behörigheter
- Skapa och använda en hanterad identitet för att bevilja åtkomst till ditt lagringskonto
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:
- 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>")
- 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.
- Klientautentisering: sample_authentication.py
- Börja översätta dokument: sample_begin_translation.py
- Översätt med flera indata: sample_translate_multiple_inputs.py
- Kontrollera status för dokument: sample_check_document_statuses.py
- Visa en lista över alla inskickade översättningsåtgärder: sample_list_translations.py
- Använd en anpassad ordlista för översättning: sample_translation_with_glossaries.py
- Använd Azure Blob Storage för att konfigurera översättningsresurser: sample_translation_with_azure_blob.py
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.
- Klientautentisering: sample_authentication_async.py
- Börja översätta dokument: sample_begin_translation_async.py
- Översätt med flera indata: sample_translate_multiple_inputs_async.py
- Kontrollera status för dokument: sample_check_document_statuses_async.py
- Visa en lista över alla inskickade översättningsåtgärder: sample_list_translations_async.py
- Använd en anpassad ordlista för översättning: sample_translation_with_glossaries_async.py
- Använd Azure Blob Storage för att konfigurera översättningsresurser: sample_translation_with_azure_blob_async.py
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.
Azure SDK for Python
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i:Skicka och visa feedback för