События
Присоединение к вызову ИИ Навыков
8 апр., 15 - 28 мая, 07
Отточите свои навыки ИИ и введите подметки, чтобы выиграть бесплатный экзамен сертификации
Зарегистрируйтесь!Примечание
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Перевод документов — это облачная функция службы Azure AI Translator . API перевода документов можно использовать для асинхронного перевода целых документов на поддерживаемых языках и различных форматах файлов, сохраняя структуру исходного документа и форматирование текста. В этом руководстве вы узнаете, как использовать API перевода документов с выбранным языком программирования и REST API HTTP.
Примечание
Перевод документов поддерживается в стандартном плане обслуживания S1 (оплата по мере использования) и планах с объемными скидками C2, C3, C4 и D3. Смотрите цены на услуги ИИ Azure — Переводчик.
Чтобы начать, вам нужно:
Активная учетная запись Azure. Если у вас нет учетной записи, вы можете создать бесплатную учетную запись.
Учетная запись хранения BLOB-объектов Azure. Кроме того, необходимо создать контейнеры в учетной записи Хранилище BLOB-объектов Azure для исходных и целевых файлов:
- Контейнер исходных файлов. В этом контейнере вы отправляете файлы для перевода (обязательно).
- Целевой контейнер. В этом контейнере хранятся преобразованные файлы (обязательные).
Ресурс Переводчика:
Заполните поля сведений о проекте и экземпляре "Переводчик" следующим образом:
Подписка. Выберите одну из доступных подписок Azure.
Группа ресурсов. Вы можете создать новую группу ресурсов или добавить ресурс в существующую группу ресурсов, которая использует одинаковый жизненный цикл, разрешения и политики.
Область ресурсов. Выберите Глобальный, если для вашего бизнеса или приложения не требуется конкретный регион. Если вы планируете использовать управляемое удостоверение, назначаемое системой, для проверки подлинности, выберите географический регион, например западная часть США.
Имя. Введите имя, выбранное для ресурса. Выбранное вами имя должно быть уникальным в Azure.
Примечание
Для перевода документов требуется конечная точка личного домена. Значение, введенное в поле "Имя", — это параметр имени личного домена для конечной точки.
Ценовая категория. Перевод документов не поддерживается на уровне "Бесплатный". Чтобы попробовать службу, выберите "Стандартный" S1.
Выберите Review + Create.
Проверьте условия обслуживания и щелкните Создать, чтобы развернуть ресурс.
После успешного развертывания ресурса выберите "Перейти к ресурсу ", чтобы получить ключ и конечную точку.
- Для запросов к службе Переводчика требуется ключ только для чтения и настраиваемая конечная точка для проверки подлинности доступа. Конечная точка настраиваемого домена — это URL-адрес, отформатированный с именем вашего ресурса, именем узла и подкаталогами Переводчика и доступный в портале Azure.
Если вы создали новый ресурс, после его развертывания нажмите кнопку "Перейти к ресурсу". Если у вас есть ресурс перевода документа, перейдите непосредственно на страницу ресурсов.
На левой границе в разделе Управление ресурсами выберите Ключи и конечная точка.
Скопируйте и вставьте
keyиdocument translation endpointв удобное место, например, в Microsoft Notepad. Для вызова API необходим только один ключ.Вы вставляете
keyиdocument translation endpointв примеры кода для проверки подлинности вашего запроса в службе перевода документов.
Для запросов к службе переводчика требуется ключ, доступный только для чтения, для проверки подлинности доступа.
- Если вы создали новый ресурс, после его развертывания нажмите кнопку "Перейти к ресурсу". Если у вас есть ресурс перевода документа, перейдите непосредственно на страницу ресурсов.
- На левой границе в разделе Управление ресурсами выберите Ключи и конечная точка.
- Скопируйте и вставьте ключ в удобное место, например в Блокнот Microsoft.
- Вставьте его в пример кода, чтобы пройти проверку подлинности запроса в службе перевода документов.
Необходимо создать контейнеры в учетной записи в Хранилище BLOB-объектов Azure для исходных и целевых файлов.
- Контейнер исходных файлов. В этом контейнере вы отправляете файлы для перевода (обязательно).
- Целевой контейнер. В этом контейнере хранятся преобразованные файлы (обязательные).
Примечание
Перевод документов поддерживает глоссарии в виде блобов в контейнерах назначения (а не в отдельных контейнерах глоссария). Если вы хотите включить пользовательский глоссарий, добавьте его в целевой контейнер и включите glossaryUrl его в запрос. Если языковая пара перевода отсутствует в глоссарии, глоссарий не применяется.
См. статью Перевод документов с использованием пользовательского глоссария.
Параметры sourceUrl, targetUrl и необязательный glossaryUrl должны содержать маркер SAS (маркер совместного доступа), добавленный как строка запроса. Маркер может быть назначен вашему контейнеру или определённым BLOB-объектам.
См.Создание маркеров SAS для обработки перевода документов.
- Исходный контейнер или блоб должны предоставлять доступ для чтения и к списку.
- Целевойконтейнер или большой двоичный объект должен назначать доступ к записи и списку.
- Ваш глоссарий должен предоставлять доступ на чтение и доступ к списку.
Совет
- При переводе нескольких файлов (BLOB-объектов) в рамках операции делегируйте SAS доступ на уровне контейнера.
- При переводе одного файла (BLOB) в операции делегируйте доступ SAS на уровне BLOB.
- В качестве альтернативы маркерам SAS можно использовать назначаемое системой управляемое удостоверение для проверки подлинности.
Запрос асинхронного пакетного перевода отправляется в конечную точку службы Переводчика через запрос POST. При успешном выполнении метод POST возвращает 202 Accepted код ответа, а служба создает пакетный запрос. Переведенные документы перечислены в предназначенном контейнере.
Подробные сведения об ограничениях запросов службы Azure AI Translator см. в разделе"Ограничения запросов на перевод документов".
В каждый запрос API перевода документов включены следующие заголовки.
| Заголовок HTTP | Описание |
|---|---|
| Ocp-Apim-Subscription-Key | Обязательно. Это значение является ключом Azure для ресурса "Переводчик" или "Службы искусственного интеллекта Azure". |
| Тип контента | Обязательно: Указывает тип содержимого полезной нагрузки. Допустимые значения: application/json или charset = UTF-8. |
- URL-адрес запроса POST — POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches. - Текст запроса POST представляет собой объект JSON с именем
inputs. - Объект
inputsсодержит адреса контейнеровsourceURLиtargetURLдля пар исходного и целевого языков. -
prefixиsuffix— это строки с учетом регистра, используемые для фильтрации документов в исходном пути для перевода. Полеprefixчасто используется для обозначения вложенных папок для перевода. Полеsuffixчаще всего используется для указания расширений файлов. - Значение поля
glossaries(необязательно) применяется при переводе документа. - Параметр
targetUrlдля каждого целевого языка должен быть уникальным.
Примечание
Если файл с тем же именем уже существует в назначении, задание завершается ошибкой.
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
- Укажите
"storageType": "File". - Если для проверки подлинности не используется управляемое удостоверение, назначаемое системой, убедитесь, что вы создали исходный URL-адрес и маркеры SAS для конкретного большого двоичного объекта или документа (а не для контейнера).
- Убедитесь, что вы указали целевое имя файла в рамках целевого URL-адреса, хотя маркер SAS по-прежнему предназначен для контейнера.
- Этот пример запроса возвращает один документ, переведенный на два целевых языка.
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
Примечание
- Эта функция является необязательной и должна быть включена для каждого запроса на перевод.
- Включение этой функции приведет к дополнительным затратам в зависимости от использования. Дополнительные сведения см. в статьео ценах на Azure AI Vision
- Эта функция в настоящее время доступна только через API пакетного перевода документов.
- Поддерживается только формат файла
.docx. - Для использования этой функции требуется ресурс Служб искусственного интеллекта Azure (а не автономный ресурс Переводчика).
Использование необязательного
translateTextWithinImageпараметра вoptionsполе- Тип данных: Логический (
trueилиfalse) - Логическое значение по умолчанию .
falseУстановите параметрtrue, чтобы включить перевод текста изображения.
- Тип данных: Логический (
Сведения о ответе. Если эта функция включена, в ответ включается дополнительная информация об обработке изображений.
totalImageScansSucceeded. Количество успешно переведенных сканирований изображений.totalImageScansFailed. Количество сканирований изображений, которые не удалось обработать.
- Создание проекта
- Замените Program.cs примером кода C#.
- Задайте значения параметров конечной точки, ключа и URL-адреса контейнера в файле Program.cs.
- Добавьте пакет Newtonsoft.Json с помощью .NET CLI для обработки данных JSON.
- Запустите программу из каталога проекта.
Важно!
В примерах кода вставьте URL-адрес вашей подписи общего доступа (SAS) в указанных местах. Обязательно удалите URL-адрес SAS из кода, когда завершите работу, и ни в коем случае не публикуйте его в открытом доступе. Для рабочей среды используйте безопасный способ хранения и доступа к учетным данным, например управляемое удостоверение Azure. Для получения дополнительной информации см. раздел безопасность хранилища Azure.
В зависимости от операции может потребоваться обновить следующие поля:
endpointbasePathkeysourceURLtargetURLglossaryURLid(идентификатор задания)
- Вы можете найти задание
idв значении URL-адресаOperation-Locationв заголовке ответа метода POSTstart-batch-translation. Буквенно-цифровой строкой, следующей за/document/параметром, является заданиеidоперации:
| Заголовок ответа | URL-адрес ответа |
|---|---|
| Операция-Местоположение | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date} |
- Вы также можете использовать запрос get-translations-status, чтобы получить список заданийперевода и их
idсостояний.
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-key}";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");
static async Task Main(string[] args)
{
using HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
StringContent content = new StringContent(json, Encoding.UTF8, "application/json");
request.Method = HttpMethod.Post;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine();
Console.WriteLine($"Response Headers:");
Console.WriteLine(response.Headers);
}
else
Console.Write("Error");
}
}
}
Список поддерживаемых форматов файлов. В случае успеха этот метод возвращает код ответа 200 OK.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Получите текущее состояние одного задания и сводку по всем заданиям в запросе на перевод документов. В случае успеха этот метод возвращает код ответа 200 OK.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
}
Получение состояния конкретного документа в запросе на перевод документов. В случае успеха этот метод возвращает код ответа 200 OK.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Отмена обрабатываемого задания или задания, поставленного в очередь. Отменяются только документы, для которых не запущен перевод.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
| Код состояния HTTP | Описание | Возможная причина |
|---|---|---|
| 200 | OK | Запрос выполнен успешно. |
| 400 | ошибка запроса | Обязательный параметр отсутствует, пустой или его значение равно нулю. Или переданное либо обязательному, либо необязательному параметру значение является недопустимым. Распространенной проблемой является слишком длинный заголовок. |
| 401 | Не авторизовано | Запрос не авторизован. Убедитесь, что ваш ключ или токен валидны и находятся в правильном регионе. |
| 429 | Слишком много запросов | Вы превысили квоту или частоту запросов, разрешенных для вашей подписки. |
| 502 | Недопустимый шлюз | Проблема с сетью или сервером. Также может указывать недопустимые заголовки. |