Klientské knihovny dávkového překladu dokumentů

  • Článek

Překlad dokumentů je cloudová funkce služby Azure AI Translator, která asynchronně překládá celé dokumenty v podporovaných jazycích a různých formátech souborů. V tomto rychlém startu se naučíte používat překlad dokumentů s programovacím jazykem podle vašeho výběru k překladu zdrojového dokumentu do cílového jazyka při zachování struktury a formátování textu.

Důležité

  • Překlad dokumentů se v současné době podporuje jenom v prostředku služby Translator (jedna služba) a není součástí prostředku služeb Azure AI (více služeb).

  • Překlad dokumentů je podporován na placených úrovních. Language Studio podporuje pouze úrovně instancí S1 nebo D3. Doporučujeme vybrat standardní S1 a vyzkoušet překlad dokumentu. Podívejte se naceny služeb Azure AI – Translator.

Požadavky

Na začátek budete potřebovat:

  • Aktivní účet Azure Pokud žádné nemáte, můžete si vytvořit bezplatný účet.

  • Prostředek Translator s jednou službou (nikoli prostředek služeb Azure AI s více službami). Pokud plánujete používat funkci Překlad dokumentů s autorizací spravované identity, zvolte geografickou oblast, například USA – východ. Vyberte cenovou úroveň Standard S1 nebo D3 .

  • Účet služby Azure Blob Storage. Kontejnery vytvoříte v účtu služby Azure Blob Storage pro zdrojové a cílové soubory:

    • Zdrojový kontejner. V tomto kontejneru nahrajete soubory pro překlad (povinné).
    • Cílový kontejner. V tomto kontejneru jsou uložené přeložené soubory (povinné).

Autorizace kontejneru úložiště

Pokud chcete autorizovat přístup k prostředku Služby Translator, můžete zvolit jednu z následujících možností.

✔️ Spravovaná identita Spravovaná identita je instanční objekt, který vytvoří identitu Microsoft Entra a konkrétní oprávnění pro spravovaný prostředek Azure. Spravované identity umožňují spouštět aplikaci Translator, aniž byste museli vkládat přihlašovací údaje do kódu. Spravované identity představují bezpečnější způsob, jak udělit přístup k datům úložiště a nahradit požadavek na zahrnutí tokenů sdíleného přístupového podpisu (SAS) ke zdroji a cílovým adresám URL.

Další informace najdete v tématuSpravované identity pro překlad dokumentů.

Screenshot of managed identity flow (RBAC).

✔️ Sdílený přístupový podpis (SAS) Sdílený přístupový podpis je adresa URL, která uděluje omezený přístup po určitou dobu službě Translator. Pokud chcete použít tuto metodu, musíte pro zdrojové a cílové kontejnery vytvořit tokeny sdíleného přístupového podpisu (SAS). targetUrl Token sourceUrl sdíleného přístupového podpisu (SAS) musí obsahovat připojený jako řetězec dotazu. Token se dá přiřadit ke kontejneru nebo konkrétním objektům blob.

  • Zdrojový kontejner nebo objekt blob musí určit přístup pro čtení a seznam.
  • Cílový kontejner nebo objekt blob musí určit přístup k zápisu a seznamu.

Další informace najdete v tématuVytváření tokenů SAS.

Screenshot of a resource URI with a SAS token.

Sestavení aplikace

K dispozici je několik nástrojů pro vytváření, sestavování a spouštění aplikací Translator C#/.NET. Tady vás provedeme pomocí rozhraní příkazového řádku (CLI) nebo sady Visual Studio. Začněte výběrem jedné z následujících karet:

Nastavení projektu

V okně konzoly (například cmd, PowerShell nebo Bash) pomocí dotnet new příkazu vytvořte novou konzolovou aplikaci s názvem batch-document-translation. Tento příkaz vytvoří jednoduchý projekt "Hello World" C# s jedním zdrojovým souborem: Program.cs.

dotnet new console -n batch-document-translation

Změňte adresář na nově vytvořenou složku aplikace. Sestavte aplikaci pomocí následujícího příkazu:

dotnet build

Výstup sestavení by neměl obsahovat žádná upozornění ani chyby.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Instalace klientské knihovny

V adresáři aplikace nainstalujte klientskou knihovnu pro překlad dokumentů pro .NET:

dotnet add package Azure.AI.Translation.Document --version 1.0.0

Překlad dokumentů nebo dávkových souborů

  1. Pro tento projekt potřebujete zdrojový dokument nahraný do zdrojového kontejneru. Pro účely tohoto rychlého startu si můžete stáhnout ukázkový dokument překladu dokumentů. Zdrojový jazyk je angličtina.

  2. V adresáři projektu otevřete soubor Program.cs v preferovaném editoru nebo integrovaném vývojovém prostředí (IDE). Odstraňte existující kód včetně řádku Console.WriteLine("Hello World!").

  3. V Program.cs aplikace vytvořte proměnné pro klíč a vlastní koncový bod. Další informace najdete v tématuNačtení klíče a vlastního koncového bodu domény.

    private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";

  4. StartTranslationAsync Voláním metody spusťte operaci překladu pro jeden nebo více dokumentů v jednom kontejneru objektů blob.

  5. Chcete-li volat StartTranslationAsync, musíte inicializovat DocumentTranslationInput objekt, který obsahuje sourceUri, targetUria targetLanguageCode parametry:

    • Pro autorizaci spravované identity vytvořte tyto proměnné:

      • sourceUri. Adresa URL zdrojového kontejneru obsahujícího dokumenty, které se mají přeložit.

      • targetUri Adresa URL cílového kontejneru, do kterého se zapisují přeložené dokumenty.

      • targetLanguageCode. Kód jazyka pro přeložené dokumenty. Kódy jazyků najdete na naší stránce podpory jazyka.

        Pokud chcete najít zdrojové a cílové adresy URL, přejděte na webu Azure Portal ke svému účtu úložiště. Na levém bočním panelu v části Úložiště dat vyberte Kontejnery a následujícím postupem načtěte zdrojové dokumenty a cílový kontejner URLS.

        Source Cíl
        1. Zaškrtněte políčko vedle zdrojového kontejneru. 1. Zaškrtněte políčko vedle cílového kontejneru.
        2. V oblasti hlavního okna vyberte soubor nebo dokumenty pro překlad. 2. Vyberte tři tečky umístěné vpravo a pak zvolte Vlastnosti.
        3. Zdrojová adresa URL se nachází v horní části seznamu Vlastností. 3. Cílová adresa URL se nachází v horní části seznamu Vlastností.

    • Pro autorizaci sdíleného přístupového podpisu (SAS) vytvořte tyto proměnné.

      • sourceUri. Identifikátor URI SAS s tokenem SAS připojeným jako řetězec dotazu pro zdrojový kontejner obsahující dokumenty, které se mají přeložit.
      • targetUri Identifikátor URI SAS s tokenem SAS připojeným jako řetězec dotazu pro cílový kontejner, do kterého se zapisují přeložené dokumenty.
      • targetLanguageCode. Kód jazyka pro přeložené dokumenty. Kódy jazyků najdete na naší stránce podpory jazyka.

Ukázka kódu

Důležité

Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí použijte bezpečný způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je Azure Key Vault. Další informace najdete v tématu Zabezpečení služeb Azure AI.

Do souboru Program.cs vaší aplikace zadejte následující vzorový kód:


using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>"

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide the location of input for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

Spusťte aplikaci

Po přidání ukázky kódu do aplikace spusťte aplikaci z adresáře projektu zadáním následujícího příkazu v terminálu:

  dotnet run

Tady je fragment očekávaného výstupu:

Screenshot of the Visual Studio Code output in the terminal window.

A je to! Právě jste vytvořili program pro překlad dokumentů v kontejneru úložiště pomocí klientské knihovny .NET.

Nastavení projektu

Ujistěte se, že je nainstalovaná nejnovější verze Pythonu.

Instalace klientské knihovny

Nainstalujte nejnovější verzi klientské knihovny překladu dokumentů:

pip install azure-ai-translation-document==1.0.0

Překlad dokumentů nebo dávkových souborů

  1. Pro tento projekt potřebujete zdrojový dokument nahraný do zdrojového kontejneru. Pro účely tohoto rychlého startu si můžete stáhnout ukázkový dokument překladu dokumentů. Zdrojový jazyk je angličtina.

  2. V souboru aplikace Pythonu vytvořte proměnné pro klíč prostředku a vlastní koncový bod. Další informace najdete v tématuNačtení klíče a vlastního koncového bodu domény.

key = "<your-key>"
endpoint = "<your-custom-endpoint>"

  1. Inicializace objektu DocumentTranslationClient , který obsahuje vaše endpoint a key parametry.

  2. Zavolejte metodu begin_translation a předejte sourceUriparametr , targetUria targetLanguageCode parametry.

    • Pro autorizaci spravované identity vytvořte tyto proměnné:

      • sourceUri. Adresa URL zdrojového kontejneru obsahujícího dokumenty, které se mají přeložit.

      • targetUri Adresa URL cílového kontejneru, do kterého se zapisují přeložené dokumenty.

      • targetLanguageCode. Kód jazyka pro přeložené dokumenty. Kódy jazyků najdete na naší stránce podpory jazyka.

        Pokud chcete najít zdrojové a cílové adresy URL, přejděte na webu Azure Portal ke svému účtu úložiště. Na levém bočním panelu v části Úložiště dat vyberte Kontejnery a následujícím postupem načtěte zdrojové dokumenty a cílový kontejner URLS.

        Source Cíl
        1. Zaškrtněte políčko vedle zdrojového kontejneru. 1. Zaškrtněte políčko vedle cílového kontejneru.
        2. V oblasti hlavního okna vyberte soubor nebo dokumenty pro překlad. 2. Vyberte tři tečky umístěné vpravo a pak zvolte Vlastnosti.
        3. Zdrojová adresa URL se nachází v horní části seznamu Vlastností. 3. Cílová adresa URL se nachází v horní části seznamu Vlastností.

    • Pro autorizaci sdíleného přístupového podpisu (SAS) vytvořte tyto proměnné.

      • sourceUri. Identifikátor URI SAS s tokenem SAS připojeným jako řetězec dotazu pro zdrojový kontejner obsahující dokumenty, které se mají přeložit.
      • targetUri Identifikátor URI SAS s tokenem SAS připojeným jako řetězec dotazu pro cílový kontejner, do kterého se zapisují přeložené dokumenty.
      • targetLanguageCode. Kód jazyka pro přeložené dokumenty. Kódy jazyků najdete na naší stránce podpory jazyka.

Vzorek kódu

Důležité

Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí použijte bezpečný způsob ukládání přihlašovacích údajů a přístupu k vašim přihlašovacím údajům, jako je Azure Key Vault. Další informace najdete v tématu Zabezpečení služeb Azure AI.

Do aplikace v Pythonu zadejte následující vzorový kód:


#  import libraries
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

# create variables for your resource key, custom endpoint, sourceUrl, targetUrl, and targetLanguage
key = "<your-key>"
endpoint = "<your-custom-endpoint>"
sourceUri = "<your-container-sourceUrl>"
targetUri = "<your-container-targetUrl>"
targetLanguage = "<target-language-code>"


# initialize a new instance of the DocumentTranslationClient object to interact with the Document Translation feature
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

# include source and target locations and target language code for the begin translation operation
poller = client.begin_translation(sourceUri, targetUri, targetLanguage)
result = poller.result()

print("Status: {}".format(poller.status()))
print("Created on: {}".format(poller.details.created_on))
print("Last updated on: {}".format(poller.details.last_updated_on))
print(
    "Total number of translations on documents: {}".format(
        poller.details.documents_total_count
    )
)

print("\nOf total documents...")
print("{} failed".format(poller.details.documents_failed_count))
print("{} succeeded".format(poller.details.documents_succeeded_count))

for document in result:
    print("Document ID: {}".format(document.id))
    print("Document status: {}".format(document.status))
    if document.status == "Succeeded":
        print("Source document location: {}".format(document.source_document_url))
        print(
            "Translated document location: {}".format(document.translated_document_url)
        )
        print("Translated to language: {}\n".format(document.translated_to))
    else:
        print(
            "Error Code: {}, Message: {}\n".format(
                document.error.code, document.error.message
            )
        )

Spusťte aplikaci

Po přidání ukázky kódu do aplikace zadejte do terminálu následující příkaz:

python asynchronous-sdk.py

Tady je fragment očekávaného výstupu:

Screenshot of the Python output in the terminal window.

A je to! Právě jste vytvořili program pro překlad dokumentů v kontejneru úložiště pomocí klientské knihovny Pythonu.

Další krok

Další informace o operacích překladu dokumentů