Share via

Azure Document Translation ügyfélkódtár Pythonhoz – 1.0.0-s verzió

  • Cikk

Az Azure Cognitive Services dokumentumfordítás egy felhőalapú szolgáltatás, amellyel több és összetett dokumentum fordítható le nyelvek és dialektusok között, miközben megőrzi az eredeti dokumentumstruktúrát és adatformátumot. A dokumentumfordítás ügyfélkódtárában a következőket használhatja:

  • Számos, nagy méretű fájlt fordíthat le egy Azure Blob Storage tárolóból egy céltárolóba a választott nyelven.
  • Ellenőrizze az egyes dokumentumok fordítási állapotát és állapotát a fordítási művelet során.
  • Egyéni fordítási modellt vagy szószedeteket alkalmazhat, hogy a fordítást az adott esethez igazíthassa.

Forráskód | Csomag (PyPI) | API-referenciadokumentáció | Termékdokumentáció | Minták

Felelősséget kizáró nyilatkozat

Az Azure SDK Python-csomagok támogatása a Python 2.7-hez 2022. január 01-én véget ért. További információkért és kérdésekért lásd: https://github.com/Azure/azure-sdk-for-python/issues/20691

Első lépések

Előfeltételek

A csomag telepítése

Telepítse a Pythonhoz készült Azure Document Translation ügyfélkódtárat a pip használatával:

pip install azure-ai-translation-document

Megjegyzés: Az ügyfélkódtár ezen verziója alapértelmezés szerint a szolgáltatás 1.0-s verziójára van bekapcsolva

Translator-erőforrás létrehozása

A Dokumentumfordítás funkció csak az egyszolgáltatásos hozzáférést támogatja. A szolgáltatás eléréséhez hozzon létre egy Translator-erőforrást.

Az erőforrást a következővel hozhatja létre:

1. lehetőség:Azure Portal

2. lehetőség:Azure CLI. Az alábbi példa bemutatja, hogyan hozhat létre Translator-erőforrást a parancssori felület használatával:

# 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

Az ügyfél hitelesítése

A Dokumentumfordítás szolgáltatás használatához létre kell hoznia egy ügyfélpéldányt. Az ügyfélobjektum példányosításához végpontra és hitelesítő adatokra van szükség.

A végpont keresése

A Translator-erőforrás végpontját az Azure Portalon találja.

Vegye figyelembe, hogy a szolgáltatáshoz egyéni tartományi végpontra van szükség. A végpont formázásához kövesse a fenti hivatkozás utasításait: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Az API-kulcs lekérése

Az API-kulcs az Azure Portalon vagy a következő Azure CLI-parancs futtatásával található meg:

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

Az ügyfél létrehozása az AzureKeyCredential használatával

Ha egy API-kulcsot szeretne paraméterként credential használni, adja át a kulcsot sztringként az AzureKeyCredential egy példányába.

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)

Az ügyfél létrehozása Azure Active Directory-hitelesítő adatokkal

AzureKeyCredential A hitelesítést az első lépések útmutatójának példáiban használjuk, de az Azure Active Directoryval is végezhet hitelesítést az azure-identity kódtár használatával.

Az alább látható DefaultAzureCredential típus vagy az Azure SDK-hoz biztosított egyéb hitelesítőadat-típusok használatához telepítse a azure-identity csomagot:

pip install azure-identity

Emellett regisztrálnia kell egy új AAD-alkalmazást, és hozzáférést kell adnia a Translator-erőforráshoz a szerepkörnek a "Cognitive Services User" szolgáltatásnévhez való hozzárendelésével.

Ha végzett, állítsa be az AAD-alkalmazás ügyfél-azonosítójának, bérlőazonosítójának és titkos ügyfélkulcsának értékeit környezeti változóként: 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
)

Fő fogalmak

A dokumentumfordítási szolgáltatáshoz fel kell töltenie a fájlokat egy Azure Blob Storage forrástárolóba, és meg kell adnia egy céltárolót, ahol a lefordított dokumentumok megírhatók. A beállítással kapcsolatos további információk a szolgáltatás dokumentációjában találhatók:

DocumentTranslationClient

A Dokumentumfordítás ügyfélkódtárral való interakció a példányával DocumentTranslationClientkezdődik. Az ügyfél a következő műveletekhez nyújt műveleteket:

  • Fordítási művelet létrehozása a forrástároló(k) dokumentumainak fordításához és az eredmények céltároló(k) írásához.
  • Az egyes dokumentumok állapotának ellenőrzése a fordítási műveletben és az egyes dokumentumok állapotának figyelése.
  • Az összes korábbi és aktuális fordítási művelet számbavétele.
  • A támogatott szószedet- és dokumentumformátumok azonosítása.

Fordítási bemenet

Az ügyfélmetódus bemenete begin_translation kétféleképpen adható meg:

  1. A dokumentumokat tartalmazó egyetlen forrástárolót más nyelvre lehet lefordítani:
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. Vagy több különböző forrás is megadható saját célokkal.
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)

Megjegyzés: az egyes célnyelvek target_url egyedinek kell lenniük.

Ha egy mappában lévő dokumentumokat szeretne lefordítani, vagy csak bizonyos dokumentumokat szeretne lefordítani, tekintse meg a sample_begin_translation_with_filters.py fájlt. Az összes támogatott nyelvhez tekintse meg a szolgáltatás dokumentációját.

Long-Running műveletek

A hosszú ideig futó műveletek olyan műveletek, amelyek egy kezdeti kérésből állnak, amelyet a szolgáltatásnak küldött egy művelet elindításához, majd a szolgáltatás időközönkénti lekérdezése annak megállapításához, hogy a művelet befejeződött vagy sikertelen volt-e, és ha sikerült, az eredmény lekéréséhez.

A dokumentumok fordítására szolgáló metódusok hosszú ideig futó műveletekként vannak modellve. Az ügyfél egy metódust begin_<method-name> tesz elérhetővé, amely egy vagy AsyncDocumentTranslationLROPollerértéket DocumentTranslationLROPoller ad vissza. A hívónak meg kell várnia a művelet befejezését a metódusból begin_<method-name> visszaadott poller objektum meghívásávalresult(). Mintakódrészleteket ad meg, amelyek hosszú ideig futó műveletek használatát szemléltetik. Példák az alábbi .

Példák

A következő szakasz számos kódrészletet tartalmaz, amelyek a leggyakoribb dokumentumfordítási feladatokat ismertetik, többek között az alábbiakat:

Dokumentumok fordítása

Fordítsa le a forrástárolóban lévő összes dokumentumot a céltárolóra. Ha egy mappában lévő dokumentumokat szeretne lefordítani, vagy csak bizonyos dokumentumokat szeretne lefordítani, tekintse meg a sample_begin_translation_with_filters.py fájlt.

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

Több bemenet fordítása

Kezdje el lefordítani a több forrástárolóban lévő dokumentumokat több céltárolóra különböző nyelveken.

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

Fordítási műveletek listázása

Az erőforráshoz elküldött fordítási műveletek számbavétele.

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

Ebből a példából megtudhatja, hogyan használhatja a Dokumentumfordítás ügyfélkódtárat az Azure Storage Blob használatával dokumentumok feltöltésére, SAS-jogkivonatok létrehozására a tárolókhoz, és hogyan töltheti le a kész lefordított dokumentumokat. Vegye figyelembe, hogy a minta futtatásához telepítenie kell az azure-storage-blob kódtárat.

Speciális témakörök

A következő szakasz betekintést nyújt néhány speciális fordítási funkcióba, például a szószedetekbe és az egyéni fordítási modellekbe.

Szószedetek

A szószedetek tartományspecifikus szótárak. Ha például bizonyos orvosi dokumentumokat szeretne lefordítani, szükség lehet a számos szó, terminológia és kifejezés támogatására az orvosi területen, amelyeket nem talál a szabványos fordítási szótárban, vagy egyszerűen csak egy adott fordításra van szüksége. Ezért támogatja a dokumentumfordítás a szószedeteket.

Szószedetfájl létrehozása

A Dokumentumfordítás a következő formátumokban támogatja a szószedeteket:

Fájltípus Kiterjesztés Leírás Példák
Tab-Separated értékek/TAB .tsv, .tab További információ a wikipédiáról glossary_sample.tsv
Comma-Separated értékek .csv További információ a wikipédiáról glossary_sample.csv
Localization Interchange File Format .xlf, .xliff További információ a wikipédiáról glossary_sample.xlf

Itt megtekintheti az összes támogatott formátumot.

Szószedetek használata a dokumentumfordításban

Ahhoz, hogy a szószedeteket dokumentumfordítással használhassa, először fel kell töltenie a szószedetfájlt egy blobtárolóba, majd meg kell adnia a fájl SAS URL-címét a sample_translation_with_glossaries.py kódmintáknak megfelelően.

Egyéni fordítási modellek

A dokumentumfordítási motor helyett használhatja saját egyéni Azure-beli gépi/mélytanulási modelljét.

Egyéni fordítási modell létrehozása

A saját egyéni Azure-beli fordítási modell létrehozásával, kiépítésével és üzembe helyezésével kapcsolatos további információkért kövesse az itt található utasításokat: Egyéni modell létrehozása, üzembe helyezése és használata fordításhoz

Egyéni fordítási modell használata dokumentumfordítással

Ahhoz, hogy egyéni fordítási modellt használhasson a Dokumentumfordítással, először létre kell hoznia és üzembe kell helyeznie a modellt, majd követnie kell a sample_translation_with_custom_model.py kódmintát a Dokumentumfordítás használatához.

Hibaelhárítás

Általános kérdések

A dokumentumfordítási ügyfélkódtár kivételeket hoz létre az Azure Core-ban.

Naplózás

Ez a kódtár a szabványos naplózási kódtárat használja a naplózáshoz.

A HTTP-munkamenetekkel (URL-címekkel, fejlécekkel stb.) kapcsolatos alapvető információk naplózása a INFO szinten történik.

A részletes DEBUG szintű naplózás, beleértve a kérés-/választörzseket és a nem végrehajtott fejléceket, engedélyezhető az ügyfélen vagy műveletenként a logging_enable kulcsszóargumentummal.

A teljes SDK-naplózási dokumentációt itt találja példákkal.

Választható konfiguráció

Az opcionális kulcsszóargumentumok az ügyfél és a művelet szintjén is átadhatók. Az Azure-Core referenciadokumentációja többek között az újrapróbálkozásokhoz, naplózáshoz, átviteli protokollokhoz elérhető konfigurációkat ismerteti.

Következő lépések

A következő szakasz számos kódrészletet tartalmaz, amely a Dokumentumfordítási Python ügyfélkódtárban használt gyakori mintákat szemlélteti. További minták a mintakönyvtárban találhatók.

További mintakód

Ezek a kódminták az Azure Document Translation ügyfélkódtárával végzett gyakori forgatókönyvműveleteket mutatják be.

Aszinkron minták

Ez a kódtár az aszinkron API-k teljes készletét is tartalmazza. A használatukhoz először telepítenie kell egy aszinkron átvitelt, például az aiohttp-t. Az aszinkron ügyfelek a azure.ai.translation.document.aio névtérben találhatók.

További dokumentáció

Az Azure Cognitive Services dokumentumfordításával kapcsolatos részletesebb dokumentációért tekintse meg a dokumentumfordítás dokumentációját docs.microsoft.com.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. Részletekért látogasson el cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.