Bagikan melalui

Pustaka klien Terjemahan Dokumen Azure untuk Python - versi 1.0.0

  • Artikel

Terjemahan Dokumen Azure Cognitive Services adalah layanan cloud yang dapat digunakan untuk menerjemahkan beberapa dokumen dan kompleks di seluruh bahasa dan dialek sambil mempertahankan struktur dokumen dan format data asli. Gunakan pustaka klien untuk Terjemahan Dokumen untuk:

  • Terjemahkan banyak file besar dari kontainer Azure Blob Storage ke kontainer target dalam bahasa pilihan Anda.
  • Periksa status terjemahan dan kemajuan setiap dokumen dalam operasi terjemahan.
  • Terapkan model terjemahan kustom atau glosarium untuk menyesuaikan terjemahan dengan kasus spesifik Anda.

Kode sumber | Paket (PyPI) | Dokumentasi | referensi API Dokumentasi | produk Sampel

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi lebih lanjut dan pertanyaan, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691

Memulai

Prasyarat

Instal paketnya

Instal pustaka klien Terjemahan Dokumen Azure untuk Python dengan pip:

pip install azure-ai-translation-document

Catatan: Versi pustaka klien ini default ke versi layanan v1.0

Membuat sumber daya Penerjemah

Fitur Terjemahan Dokumen hanya mendukung akses layanan tunggal . Untuk mengakses layanan, buat sumber daya Penerjemah.

Anda dapat membuat sumber daya menggunakan

Opsi 1:Portal Microsoft Azure

Opsi 2:Azure CLI. Di bawah ini adalah contoh bagaimana Anda dapat membuat sumber daya Penerjemah menggunakan 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

Mengautentikasi klien

Untuk berinteraksi dengan layanan fitur Terjemahan Dokumen, Anda harus membuat instans klien. Titik akhir dan kredensial diperlukan untuk membuat instans objek klien.

Mencari titik akhir

Anda dapat menemukan titik akhir untuk sumber daya Penerjemah menggunakan Portal Microsoft Azure.

Perhatikan bahwa layanan memerlukan titik akhir domain kustom. Ikuti instruksi di tautan di atas untuk memformat titik akhir Anda: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Mendapatkan kunci API

Kunci API dapat ditemukan di Portal Microsoft Azure atau dengan menjalankan perintah Azure CLI berikut:

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

Membuat klien dengan AzureKeyCredential

Untuk menggunakan kunci API sebagai credential parameter, teruskan kunci sebagai string ke dalam instans 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)

Membuat klien dengan kredensial Azure Active Directory

AzureKeyCredential autentikasi digunakan dalam contoh dalam panduan memulai ini, tetapi Anda juga dapat mengautentikasi dengan Azure Active Directory menggunakan pustaka identitas azure .

Untuk menggunakan jenis DefaultAzureCredential yang ditunjukkan di bawah ini, atau jenis kredensial lain yang disediakan dengan Azure SDK, silakan instal azure-identity paket:

pip install azure-identity

Anda juga perlu mendaftarkan aplikasi AAD baru dan memberikan akses ke sumber daya Penerjemah Anda dengan menetapkan peran ke "Cognitive Services User" perwakilan layanan Anda.

Setelah selesai, atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: 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
)

Konsep utama

Layanan Terjemahan Dokumen mengharuskan Anda mengunggah file ke kontainer sumber Azure Blob Storage dan menyediakan kontainer target tempat dokumen yang diterjemahkan dapat ditulis. Informasi tambahan tentang pengaturan ini dapat ditemukan dalam dokumentasi layanan:

DocumentTranslationClient

Interaksi dengan pustaka klien Terjemahan Dokumen dimulai dengan instans DocumentTranslationClient. Klien menyediakan operasi untuk:

  • Membuat operasi terjemahan untuk menerjemahkan dokumen dalam kontainer sumber Anda dan menulis hasil kepada Anda menargetkan kontainer.
  • Memeriksa status dokumen individual dalam operasi terjemahan dan memantau kemajuan setiap dokumen.
  • Menghitung semua operasi terjemahan sebelumnya dan saat ini.
  • Mengidentifikasi format glosarium dan dokumen yang didukung.

Input Terjemahan

Input ke begin_translation metode klien dapat disediakan dengan dua cara berbeda:

  1. Kontainer sumber tunggal dengan dokumen dapat diterjemahkan ke bahasa yang berbeda:
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. Atau beberapa sumber yang berbeda dapat disediakan masing-masing dengan target mereka sendiri.
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)

Catatan: target_url untuk setiap bahasa target harus unik.

Untuk menerjemahkan dokumen di bawah folder, atau hanya menerjemahkan dokumen tertentu, lihat sample_begin_translation_with_filters.py. Lihat dokumentasi layanan untuk semua bahasa yang didukung.

Operasi Long-Running

Operasi jangka panjang adalah operasi yang terdiri dari permintaan awal yang dikirim ke layanan untuk memulai operasi, diikuti dengan polling layanan pada interval untuk menentukan apakah operasi telah selesai atau gagal, dan jika telah berhasil, untuk mendapatkan hasilnya.

Metode yang menerjemahkan dokumen dimodelkan sebagai operasi yang berjalan lama. Klien mengekspos begin_<method-name> metode yang mengembalikan DocumentTranslationLROPoller atau AsyncDocumentTranslationLROPoller. Penelepon harus menunggu operasi selesai dengan memanggil result() objek poller yang dikembalikan dari begin_<method-name> metode . Cuplikan kode sampel disediakan untuk mengilustrasikan menggunakan Contoh operasi yang berjalan lama di bawah ini.

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Terjemahan Dokumen yang paling umum, termasuk:

Menerjemahkan dokumen Anda

Terjemahkan semua dokumen dalam kontainer sumber Anda ke kontainer target. Untuk menerjemahkan dokumen di bawah folder, atau hanya menerjemahkan dokumen tertentu, lihat 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")

Menerjemahkan beberapa input

Mulai terjemahkan dengan dokumen dalam beberapa kontainer sumber ke beberapa kontainer target dalam bahasa yang berbeda.

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

Mencantumkan operasi terjemahan

Hitung operasi terjemahan yang dikirimkan untuk sumber daya.

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

Untuk melihat cara menggunakan pustaka klien Terjemahan Dokumen dengan Azure Storage Blob untuk mengunggah dokumen, membuat token SAS untuk kontainer Anda, dan mengunduh dokumen yang sudah selesai diterjemahkan, lihat sampel ini. Perhatikan bahwa Anda harus menginstal pustaka azure-storage-blob untuk menjalankan sampel ini.

Topik tingkat lanjut

Bagian berikut memberikan beberapa wawasan untuk beberapa fitur terjemahan tingkat lanjut seperti glosarium dan model terjemahan kustom.

Glosari

Glosarium adalah kamus khusus domain. Misalnya, jika Anda ingin menerjemahkan beberapa dokumen terkait medis, Anda mungkin memerlukan dukungan untuk banyak kata, terminologi, dan idiom di bidang medis yang tidak dapat Anda temukan dalam kamus terjemahan standar, atau Anda hanya memerlukan terjemahan tertentu. Inilah sebabnya mengapa Terjemahan Dokumen menyediakan dukungan untuk glosarium.

Cara Membuat File Glosarium

Document Translation mendukung glosarium dalam format berikut:

Jenis File Ekstensi Deskripsi Sampel
Tab Separated Values/TAB .tsv, .tab Baca selengkapnya di wikipedia glossary_sample.tsv
Comma Separated Values .csv Baca selengkapnya di wikipedia glossary_sample.csv
Localization Interchange File Format .xlf, .xliff Baca selengkapnya di wikipedia glossary_sample.xlf

Lihat semua format yang didukung di sini.

Cara Menggunakan Glosarium dalam Terjemahan Dokumen

Untuk menggunakan glosarium dengan Terjemahan Dokumen, Anda harus terlebih dahulu mengunggah file glosarium Anda ke kontainer blob, lalu memberikan URL SAS ke file seperti dalam sampel kode sample_translation_with_glossaries.py.

Model Terjemahan Kustom

Alih-alih menggunakan mesin Terjemahan Dokumen untuk terjemahan, Anda dapat menggunakan model pembelajaran mendalam/mesin Azure kustom Anda sendiri.

Cara Membuat Model Terjemahan Kustom

Untuk informasi selengkapnya tentang cara membuat, menyediakan, dan menyebarkan model terjemahan Azure kustom Anda sendiri, silakan ikuti instruksi di sini: Membangun, menyebarkan, dan menggunakan model kustom untuk terjemahan

Cara Menggunakan Model Terjemahan Kustom Dengan Terjemahan Dokumen

Untuk menggunakan model terjemahan kustom dengan Terjemahan Dokumen, Anda harus terlebih dahulu membuat dan menyebarkan model Anda, lalu ikuti sampel kode sample_translation_with_custom_model.py untuk digunakan dengan Terjemahan Dokumen.

Pemecahan Masalah

Umum

Pustaka klien Terjemahan Dokumen akan memunculkan pengecualian yang ditentukan di Azure Core.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan.

Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat pada INFO tingkat.

Pengelogan tingkat terperinci, termasuk isi DEBUG permintaan/respons dan header yang tidak diredaksikan , dapat diaktifkan pada klien atau per operasi dengan logging_enable argumen kata kunci.

Lihat dokumentasi pengelogan SDK lengkap dengan contoh di sini.

Konfigurasi Opsional

Argumen kata kunci opsional dapat diteruskan di tingkat klien dan per operasi. Dokumentasi referensi azure-core menjelaskan konfigurasi yang tersedia untuk percobaan ulang, pengelogan, protokol transportasi, dan banyak lagi.

Langkah berikutnya

Bagian berikut ini menyediakan beberapa cuplikan kode yang mengilustrasikan pola umum yang digunakan dalam pustaka klien Document Translation Python. Sampel lainnya dapat ditemukan di bawah direktori sampel .

Lebih banyak kode sampel

Sampel kode ini menunjukkan operasi skenario umum dengan pustaka klien Terjemahan Dokumen Azure.

Sampel asinkron

Pustaka ini juga mencakup sekumpulan API asinkron lengkap. Untuk menggunakannya, Anda harus terlebih dahulu menginstal transportasi asinkron, seperti aiohttp. Klien asinkron ditemukan di azure.ai.translation.document.aio bawah namespace.

Dokumentasi tambahan

Untuk dokumentasi yang lebih luas tentang Terjemahan Dokumen Azure Cognitive Services, lihat dokumentasi Terjemahan Dokumen di docs.microsoft.com.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.