Pustaka klien Terjemahan Dokumen Azure untuk Python - versi 1.0.0
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
- Python 3.6 atau yang lebih baru diperlukan untuk menggunakan paket ini.
- Anda harus memiliki langganan Azure dan sumber daya Penerjemah untuk menggunakan paket ini.
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_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
)
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:
- Menyiapkan kontainer Azure Blob Storage dengan dokumen Anda
- Secara opsional terapkan glosarium atau model kustom untuk terjemahan
- Izinkan akses ke akun penyimpanan Anda dengan salah satu opsi berikut:
- Hasilkan token SAS ke kontainer (atau file) Anda dengan izin yang sesuai
- Membuat dan menggunakan identitas terkelola untuk memberikan akses ke akun penyimpanan Anda
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:
- 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>")
- 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.
- Autentikasi klien: sample_authentication.py
- Mulai menerjemahkan dokumen: sample_begin_translation.py
- Terjemahkan dengan beberapa input: sample_translate_multiple_inputs.py
- Periksa status dokumen: sample_check_document_statuses.py
- Mencantumkan semua operasi terjemahan yang dikirimkan: sample_list_translations.py
- Terapkan glosarium kustom ke terjemahan: sample_translation_with_glossaries.py
- Gunakan Azure Blob Storage untuk menyiapkan sumber daya terjemahan: sample_translation_with_azure_blob.py
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.
- Autentikasi klien: sample_authentication_async.py
- Mulai menerjemahkan dokumen: sample_begin_translation_async.py
- Terjemahkan dengan beberapa input: sample_translate_multiple_inputs_async.py
- Periksa status dokumen: sample_check_document_statuses_async.py
- Mencantumkan semua operasi terjemahan yang dikirimkan: sample_list_translations_async.py
- Terapkan glosarium kustom ke terjemahan: sample_translation_with_glossaries_async.py
- Gunakan Azure Blob Storage untuk menyiapkan sumber daya terjemahan: sample_translation_with_azure_blob_async.py
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.
Azure SDK for Python