Aracılığıyla paylaş

Python için Azure Belge Çevirisi istemci kitaplığı - sürüm 1.0.0

  • Makale

Azure Bilişsel Hizmetler Belge Çevirisi, özgün belge yapısını ve veri biçimini korurken birden çok ve karmaşık belgeyi diller ve diyalektler arasında çevirmek için kullanılabilen bir bulut hizmetidir. Belge Çevirisi için istemci kitaplığını kullanarak:

  • bir Azure Blob Depolama kapsayıcısından seçtiğiniz dilde bir hedef kapsayıcıya çok sayıda büyük dosya çevirin.
  • Çeviri işlemindeki her belgenin çeviri durumunu ve ilerleme durumunu denetleyin.
  • Çeviriyi özel durumunuzla uyarlamak için özel bir çeviri modeli veya sözlükler uygulayın.

Kaynak kodu | Paket (PyPI) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Bildirim

Python 2.7 için Azure SDK Python paketleri desteği 01 Ocak 2022'de sona erdi. Daha fazla bilgi ve soru için lütfen https://github.com/Azure/azure-sdk-for-python/issues/20691

Başlarken

Önkoşullar

Paketi yükleme

Pip ile Python için Azure Belge Çevirisi istemci kitaplığını yükleyin:

pip install azure-ai-translation-document

Not: İstemci kitaplığının bu sürümü varsayılan olarak hizmetin v1.0 sürümünü kullanır

Translator kaynağı oluşturma

Belge Çevirisi özelliği yalnızca tek hizmetli erişimi destekler. Hizmete erişmek için bir Translator kaynağı oluşturun.

Kaynağı oluşturmak için

Seçenek 1:Azure Portal

Seçenek 2:Azure CLI. Aşağıda, CLI kullanarak Translator kaynağını nasıl oluşturabileceğinize ilişkin bir örnek verilmiştir:

# 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

İstemcinin kimliğini doğrulama

Belge Çevirisi özellik hizmetiyle etkileşim kurmak için bir istemci örneği oluşturmanız gerekir. İstemci nesnesinin örneğini oluşturmak için bir uç nokta ve kimlik bilgisi gereklidir.

Uç noktayı arama

Translator kaynağınızın uç noktasını Azure Portal'ı kullanarak bulabilirsiniz.

Hizmetin özel bir etki alanı uç noktası gerektirdiğini unutmayın. Uç noktanızı biçimlendirmek için yukarıdaki bağlantıdaki yönergeleri izleyin: https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

API anahtarını alma

API anahtarı Azure Portal'da veya aşağıdaki Azure CLI komutunu çalıştırarak bulunabilir:

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

AzureKeyCredential ile istemci oluşturma

Parametre olarak credentialbir API anahtarı kullanmak için anahtarı dize olarak AzureKeyCredential örneğine geçirin.

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)

Azure Active Directory kimlik bilgileriyle istemci oluşturma

AzureKeyCredential kimlik doğrulaması bu başlangıç kılavuzundaki örneklerde kullanılır, ancak azure-identity kitaplığını kullanarak Azure Active Directory ile kimlik doğrulaması da yapabilirsiniz.

Aşağıda gösterilen DefaultAzureCredential türünü veya Azure SDK ile sağlanan diğer kimlik bilgileri türlerini kullanmak için lütfen paketi yükleyin azure-identity :

pip install azure-identity

Ayrıca yeni bir AAD uygulaması kaydetmeniz ve rolü hizmet sorumlunuza atayarak "Cognitive Services User" Translator kaynağınıza erişim vermeniz gerekir.

Tamamlandıktan sonra, AAD uygulamasının istemci kimliği, kiracı kimliği ve istemci gizli dizisi değerlerini ortam değişkenleri olarak ayarlayın: 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
)

Önemli kavramlar

Belge Çevirisi hizmeti, dosyalarınızı bir Azure Blob Depolama kaynak kapsayıcısına yüklemenizi ve çevrilen belgelerin yazıldığı bir hedef kapsayıcı sağlamanızı gerektirir. Bunu ayarlama hakkında ek bilgileri hizmet belgelerinde bulabilirsiniz:

DocumentTranslationClient

Belge Çevirisi istemci kitaplığıyla etkileşim, bir örneğiyle DocumentTranslationClientbaşlar. İstemci şu işlemler için işlemler sağlar:

  • Kaynak kapsayıcılarınızdaki belgeleri çevirmek ve sonuçları hedef kapsayıcılara yazmak için çeviri işlemi oluşturma.
  • Çeviri işleminde tek tek belgelerin durumunu denetleme ve her belgenin ilerleme durumunu izleme.
  • Tüm geçmiş ve geçerli çeviri işlemleri numaralandırılıyor.
  • Desteklenen sözlük ve belge biçimlerini tanımlama.

Çeviri Girişi

İstemci yöntemine begin_translation giriş iki farklı yolla sağlanabilir:

  1. Belgeler içeren tek bir kaynak kapsayıcı farklı bir dile çevrilebilir:
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. Ya da her birine kendi hedefleri olan birden çok farklı kaynak sağlanabilir.
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)

Not: Her hedef dilin target_url benzersiz olmalıdır.

Bir klasörün altındaki belgeleri çevirmek veya yalnızca belirli belgeleri çevirmek için bkz. sample_begin_translation_with_filters.py. Desteklenen tüm diller için hizmet belgelerine bakın.

Long-Running İşlemleri

Uzun süre çalışan işlemler, bir işlemi başlatmak için hizmete gönderilen ilk isteklerden oluşan ve ardından işlemin tamamlanıp tamamlanmadığını ve başarılı olup olmadığını belirlemek için hizmeti aralıklarla yoklayarak sonucu almak için gerçekleştirilen işlemlerdir.

Belgeleri çeviren yöntemler, uzun süre çalışan işlemler olarak modellenir. İstemci, veya AsyncDocumentTranslationLROPollerdöndüren bir begin_<method-name>DocumentTranslationLROPoller yöntemi kullanıma sunar. Çağıranların yönteminden döndürülen poller nesnesini çağırarak result() işlemin tamamlanmasını beklemesi begin_<method-name> gerekir. Örnek kod parçacıkları, aşağıda uzun süre çalışan işlemlerin kullanılmasını göstermek için

Örnekler

Aşağıdaki bölümde, aşağıdakiler de dahil olmak üzere en yaygın Belge Çevirisi görevlerinden bazılarını kapsayan çeşitli kod parçacıkları sağlanır:

Belgelerinizi çevirme

Kaynak kapsayıcınızdaki tüm belgeleri hedef kapsayıcıya çevirin. Bir klasörün altındaki belgeleri çevirmek veya yalnızca belirli belgeleri çevirmek için bkz. 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")

Birden çok girişi çevirme

Birden çok kaynak kapsayıcıdaki belgelerle farklı dillerdeki birden çok hedef kapsayıcıya çevirmeye başlayın.

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

Çeviri işlemlerini listeleme

Kaynak için gönderilen çeviri işlemlerini numaralandırın.

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

Belgeleri karşıya yüklemek, kapsayıcılarınız için SAS belirteçleri oluşturmak ve tamamlanmış çevrilmiş belgeleri indirmek üzere Azure Depolama Blobu ile Belge Çevirisi istemci kitaplığının nasıl kullanılacağını görmek için bu örne bakın. Bu örneği çalıştırmak için azure-storage-blob kitaplığını yüklemeniz gerektiğini unutmayın.

İleri Düzey Konular

Aşağıdaki bölümde sözlükler ve özel çeviri modelleri gibi bazı gelişmiş çeviri özelliklerine yönelik bazı içgörüler sağlanmaktadır.

Sözlükler

Sözlükler etki alanına özgü sözlüklerdir. Örneğin, tıbbile ilgili bazı belgeleri çevirmek istiyorsanız, standart çeviri sözlüğünde bulamadığınız tıp alanındaki birçok sözcük, terminoloji ve deyim için desteğe ihtiyacınız olabilir veya yalnızca belirli bir çeviriye ihtiyacınız olabilir. Bu nedenle Belge Çevirisi sözlükler için destek sağlar.

Sözlük Dosyası Oluşturma

Belge Çevirisi aşağıdaki biçimlerde sözlükleri destekler:

Dosya Türü Uzantı Açıklama Örnekler
Tab-Separated Değerleri/SEKME .tsv, .tab Wikipedia'da daha fazla bilgi edinin glossary_sample.tsv
Comma-Separated Değerleri .csv Wikipedia'da daha fazla bilgi edinin glossary_sample.csv
Yerelleştirme Değişim Dosyası Biçimi .xlf, .xliff Wikipedia'da daha fazla bilgi edinin glossary_sample.xlf

Desteklenen tüm biçimleri burada görüntüleyin.

Belge Çevirisinde Sözlükleri Kullanma

Sözlükleri Belge Çevirisi ile kullanmak için önce sözlük dosyanızı bir blob kapsayıcısına yüklemeniz ve ardından sample_translation_with_glossaries.py kod örneklerinde olduğu gibi dosyanın SAS URL'sini sağlamanız gerekir.

Özel Çeviri Modelleri

Çeviri için Belge Çevirisi'nin altyapısını kullanmak yerine kendi özel Azure makinenizi/derin öğrenme modelinizi kullanabilirsiniz.

Özel Çeviri Modeli Oluşturma

Kendi özel Azure çeviri modelinizi oluşturma, sağlama ve dağıtma hakkında daha fazla bilgi için lütfen buradaki yönergeleri izleyin: Çeviri için özel model oluşturma, dağıtma ve kullanma

Belge Çevirisi ile Özel Çeviri Modeli Kullanma

Belge Çevirisi ile özel çeviri modeli kullanmak için önce modelinizi oluşturup dağıtmanız, ardından Belge Çevirisi ile kullanmak üzere sample_translation_with_custom_model.py kod örneğini izlemeniz gerekir.

Sorun giderme

Genel

Belge Çevirisi istemci kitaplığı , Azure Core'da tanımlanan özel durumları tetikler.

Günlüğe Kaydetme

Bu kitaplık, günlüğe kaydetme için standart günlük kitaplığını kullanır.

HTTP oturumlarıyla ilgili temel bilgiler (URL'ler, üst bilgiler vb.) düzeyinde günlüğe kaydedilir INFO .

İstek/yanıt gövdeleri ve işlenmemiş üst bilgiler de dahil olmak üzere ayrıntılı DEBUG düzey günlüğe kaydetme, istemcide veya anahtar sözcük bağımsız değişkeniyle logging_enable işlem başına etkinleştirilebilir.

Burada örneklerin bulunduğu tam SDK günlük belgelerine bakın.

İsteğe Bağlı Yapılandırma

İsteğe bağlı anahtar sözcük bağımsız değişkenleri istemcide ve işlem düzeyinde geçirilebilir. Azure-core başvuru belgelerinde yeniden denemeler, günlüğe kaydetme, aktarım protokolleri ve daha fazlası için kullanılabilir yapılandırmalar açıklanmaktadır.

Sonraki adımlar

Aşağıdaki bölümde, Belge Çevirisi Python istemci kitaplığında kullanılan yaygın desenleri gösteren çeşitli kod parçacıkları sağlanır. Samples dizininde daha fazla örnek bulunabilir.

Daha fazla örnek kod

Bu kod örnekleri, Azure Belge Çevirisi istemci kitaplığıyla yaygın senaryo işlemlerini gösterir.

Zaman uyumsuz örnekler

Bu kitaplık ayrıca tam bir zaman uyumsuz API kümesi içerir. Bunları kullanmak için önce aiohttp gibi bir zaman uyumsuz aktarım yüklemeniz gerekir. Zaman uyumsuz istemciler ad alanının azure.ai.translation.document.aio altında bulunur.

Diğer belgeler

Azure Bilişsel Hizmetler Belge Çevirisi hakkında daha kapsamlı belgeler için docs.microsoft.com belge çevirisi belgelerine bakın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için cla.microsoft.com adresini ziyaret edin.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .