Подробное руководство для начинающих

Существует много хороших сервисов переводчиков, однако одним из самых универсальных и простых в настройке является Microsoft Translator [1], предоставляющий вам доступ к переводчикам для множества языков с низким и высоким уровнем ресурсов бесплатно (при условии ежемесячной оплаты). пределы перевода).

В этом руководстве я расскажу, как настроить экземпляр транслятора в Azure и как написать интерфейс для подключения к нему в вашем коде с использованием лучших практик. Если вы знакомы с Azure и у вас уже есть настроенный экземпляр Translator, то посетите репозиторий проекта напрямую, чтобы получить доступ к коду.

Этот учебник будет охватывать:

  1. Настройка экземпляра переводчика Azure
  2. Отправка вашего первого запроса на перевод
  3. Очистка вашего кода и структурирование вашего проекта
  4. Рекомендации по использованию ноутбуков Jupyter
  5. Заключение

Настройка экземпляра переводчика в Azure

Создание учетной записи Azure

Первый шаг — создать учетную запись Microsoft Azure. Для этого вам потребуется:

  • Действительный адрес
  • Действующая учетная запись электронной почты
  • Действительный номер телефона
  • Действительная кредитная или дебетовая карта*

После создания учетной записи вас спросят, хотите ли вы использовать бесплатную услугу или подписку с оплатой по мере использования. Перейдите на бесплатную услугу. Вы всегда можете вернуться к подписке с оплатой по мере использования, если считаете, что она больше подходит для вас**. Azure будет агрессивно пытаться переключить вас на услугу с оплатой по мере использования, но вы всегда можете придерживаться бесплатной услуги.

*Примечание. кредитная/дебетовая карта используется для проверки вашей личности. Средства не берутся, если вы используете учетную запись бесплатного уровня.

**Примечание. Дополнительную информацию о ценах на услуги переводчика см. в Документации по ценам на услуги переводчика.

Настройка API переводчика

После входа в Azure нажмите «Создать ресурс», затем выполните поиск «переводчик». Наконец, нажмите на службу переводчика и нажмите «Создать».

Как только вы это сделаете, вы найдете страницу, для которой требуется ряд параметров:

  • Группа ресурсов: имя для сбора нескольких ресурсов, принадлежащих одному проекту. Это определяет, как вам будет выставляться счет, если вы выберете платную подписку. Назовите это что-то, что имеет отношение к вашему проекту.
  • Регион*: регион, в котором работает ваш экземпляр. Это связано с тем, как Microsoft управляет ресурсами и аварийным восстановлением. Рекомендуемый регион — Глобальный.
  • Имя: название вашей службы переводчиков. Для целей перевода это не имеет значения, но если вам нужен перевод документа, это повлияет на имя конечной точки вашего ресурса.
  • Ценовая категория*: для начала выберите бесплатную версию.

После заполнения нажмите «Создать». Azure выполнит простую проверку и перенаправит вас на другую страницу, где вы сможете подтвердить создание своего ресурса.

*Примечание. у вас не может быть нескольких экземпляров переводчика с одним и тем же регионом и ценовой категорией. Например, если у вас есть экземпляр уровня бесплатного пользования с регионом Восток США, чтобы добавить еще один бесплатный экземпляр, необходимо изменить регион.

Поиск информации о вашем ресурсе

По умолчанию Azure перенаправит вас к созданному вами ресурсу. Однако в следующий раз, когда вы войдете в систему, вам придется найти его самостоятельно. Вы можете сделать это с главной страницы, нажав на значок переводчика. Это приведет вас на страницу переводчика, где вы можете найти все свои экземпляры.

Нажав на свой экземпляр, вы перейдете на страницу экземпляра, где вы можете найти все его соответствующие конфигурации и подробности. Они станут актуальными в следующем разделе.

На данный момент вы можете использовать свой экземпляр перевода в браузере, чтобы получить представление о том, как представлен входной текст и как выглядит выходной текст:

Отправьте свой первый запрос на перевод

По умолчанию Azure предоставляет вам код по умолчанию, который вы можете скопировать, чтобы сделать свой первый запрос на перевод. Однако, если вы не знакомы с тем, как работают запросы, вам может быть трудно понять, что они делают, и, следовательно, вы не сможете эффективно использовать их в своем коде. Здесь я шаг за шагом расскажу о концепциях, связанных с отправкой вашего первого запроса на перевод.

Краткое введение в HTTP-запросы

Прежде чем писать код, стоит рассмотреть пару концепций, связанных с API перевода.

  • API имеет URL-адрес, который позволяет вам получить к нему доступ. Для Microsoft Translator это общедоступный URL-адрес:


Документация по Azure Cognitive Services Translator — краткие руководства, руководства, справочник по API — Azure…
Azure Cognitive Services Translator — это облачная служба машинного перевода, которую можно использовать для перевода текста с помощью… api.cognitive.microsofttranslator.com



  • У API есть конечные точки (это как пути в URL-адресе), на которые вы отправляете HTTP-запросы. Например, наиболее простой конечной точкой является конечная точка languages. Эта конечная точка просто возвращает все языки, которые вы можете выбрать. Это конечная точка get, поскольку она «получает» ресурсы или данные из API или ресурса.
  • Каждая конечная точка имеет параметры, которые определяют, что вы запрашиваете у конечной точки. Например, конечная точка языков имеет параметр api-version, который указывает, какую версию переводчика вы используете.

Например, полный URI для конечной точки языков, использующей версию 3.0 Microsoft API, выглядит следующим образом:

Вы можете вызвать конечную точку языков в Python, используя модуль requests:

import requests
microsoft_api_url = 'https://api.cognitive.microsofttranslator.com/languages?api-version=3.0'
resp = requests.get(microsoft_api_url)
print(resp.json())

Это отправляет HTTP-запрос к API для получения языков, доступных для версии 3.0 переводчика. На самом деле, поскольку эта конечная точка общедоступна, вы можете скопировать и вставить этот URL-адрес в свой браузер*, чтобы получить тот же результат, что и в коде:

https://api.cognitive.microsofttranslator.com/languages?api-version=3.0

*Примечание. в фоновом режиме ваш браузер отправляет запрос get на URL-адрес и возвращает вам результат.

Вы можете найти больше информации о конечных точках, доступных в официальной документации API.

Конечная точка перевода

Это конечная точка, которая позволяет нам переводить текст. В отличие от конечной точки languages, это запрос post, а не запрос get. Это означает, что вы отправляете некоторые данные для создания вывода. Вы не просто «получаете» ресурс. Вы отправляете данные как часть тела запроса. Это байты данных, которые передаются как часть вашего запроса, но они отличаются от параметров тем, что не добавляются к пути URI.

Конечная точка translate имеет следующие требования:

Параметры

  • api-version (обязательно): версия переводчика, которую вы хотите использовать.
  • to (обязательно):ISO 639–1 код(ы) языка(ов) языка(ов), на который(е) вы хотите перевести текст(ы)

Тело запроса

  • Массив текстов, которые вы хотите перевести в следующем формате: {"text": "This is a sentence I want to translate"}

В Python вы можете отправлять запросы следующим образом. Я намеренно добавил два языка перевода, чтобы показать вам, как несколько параметров с одним и тем же именем добавляются к URL-адресу запроса.

import requests
body = [{"text": "First sentence I want to translate"}, {"text": "Second sentence I want to translate"}]
api_version = "3.0"
german_iso_code = 'de'
arabic_iso_code = 'ar'
endpoint = 'translate'

url = f'https://api.cognitive.microsofttranslator.com/{endpoint}?api-version={api_version}&to={german_iso_code}&to={arabic_iso_code}'

resp = requests.post(url, json=body)

Управление доступом

Теперь, если вы запустили приведенный выше код, вы должны были получить ошибку. Это потому, что мы не можем просто запустить почтовую службу самостоятельно. Нам нужна аутентификация.

Вот почему нам нужно было создать учетную запись и экземпляр переводчика в первую очередь.

К вашему экземпляру прикреплен уникальный ключ, который позволяет Microsoft:

а) убедитесь, что отправляемый вами запрос поступает из источника с учетной записью Azure.

б) рассчитать использование вами службы для выставления счетов или ограничения*

*Примечание. помните, что в бесплатной версии, хотя вам не выставляется счет, вы можете выполнять определенное количество переводов в месяц.

Этот уникальный ключ можно передать в корпорацию Майкрософт с помощью заголовков запросов. Это ключевые концепции HTTP. Они могут сообщить серверу следующую информацию о вашем запросе:

  • IP-адрес и порт
  • Тип ожидаемых данных
  • Детали аутентификации

API переводчика требует наличия в заголовке следующих элементов:

  • Ключ подписки: это ключ проверки подлинности, который сообщает Microsoft, что вы авторизованы для использования службы. Он привязан к ресурсу переводчика, который вы создали в начале руководства.
  • Регион подписки: это регион, в котором существует ваш проект.
  • Тип контента: тип отправляемых данных.
  • Идентификатор трассировки клиента:уникальный идентификатор, идентифицирующий ваш компьютер. Подробнее об этом можно прочитать здесь.

Вы можете найти свой ключ подписки на странице проекта Azure:

На странице «Ключи и конечная точка» вы можете найти два ключа API (любой из которых можно использовать для вашей аутентификации).

Наконец, вы можете определить заголовки и добавить их в созданный выше почтовый запрос, чтобы получить успешный вывод перевода:

# code as before, new additions enclosed in ------

import requests
body = [{"text": "First sentence I want to translate"}, {"text": "Second sentence I want to translate"}]
api_version = "3.0"
german_iso_code = 'de'
arabic_iso_code = 'ar'
endpoint = 'translate'

### -----------------------------------------------------
import uuid

# YOUR PROJECT CREDENTIALS
your_key = "your_key_keep_this_a_secret"
your_project_location = "your_project_location"

# headers
headers = {
  'Ocp-Apim-Subscription-Key': your_key,
  'Ocp-Apim-Subscription-Region': your_project_location,
  # default values
  'Content-type': 'application/json',
  'X-ClientTraceId': str(uuid.uuid4())
}
### -----------------------------------------------------

url = f'https://api.cognitive.microsofttranslator.com/{endpoint}?api-version={api_version}&to={german_iso_code}&to={arabic_iso_code}'

resp = requests.post(
  url,
  headers=headers,  # add the headers
  json=body
)

Ваши API-ключи — это то, что позволяет вам использовать сервис. Они никогда не должны протекать, и рекомендуется регенерировать их каждые пару месяцев. В следующем разделе мы рассмотрим лучшие практики по снижению вероятности утечек.

Очистка кода и структурирование вашего проекта

В этом разделе рассматриваются передовые методы разработки программного обеспечения для интеграции функций Microsoft Translate API в ваш код и проекты. Мы рассмотрим:

  • Структура каталогов
  • Как скрыть учетные данные
  • Как упаковать запросы в функции и добавить базовое ведение журнала
  • Как добавить информативную документацию

Структура каталогов

При разработке приложения вы можете взаимодействовать с несколькими внешними API. Таким образом, рекомендуется хранить функциональные возможности внешних API в отдельных файлах, а затем вызывать их в основном коде приложения. Я рекомендую хранить все внешние API в подпапке с именем «external_apis» в вашем пакете, а также отдельные файлы Python, содержащие функции для вызова каждого API. Я также рекомендую добавить файл config.py в подпапку external_apis, чтобы добавить конфигурации для ваших внешних API.

Скрытие учетных данных с помощью переменных среды

Помните: вы никогда не должны раскрывать свои ключи API. Если они это сделают, немедленно регенерируйте их.

Тем не менее, они вам нужны, чтобы делать запросы на перевод. В общем, вам следует избегать (в порядке серьезности):

  • Жесткое кодирование ключа в коде. Даже если вы размещаете свой код в частном порядке, ключ всегда будет доступен в истории коммитов.
  • Печать ключа (где угодно): менее рискованно, но наличие операторов печати повышает вероятность того, что ваш ключ будет отправлен на GitHub как часть выходных данных Jupyter Notebook или сохранен в журналах сервера.
  • Сохраните свой ключ в файлах конфигурации: гораздо менее рискованно, так как случайное нажатие файлов конфигурации маловероятно, а .gitignore может сделать это практически невозможным. Тем не менее, есть еще лучший метод.

Лучший способ использовать учетные данные в коде — использовать переменные среды. Это переменные на основе сеанса, что означает, что они сохраняются только на время сеанса терминала, в котором вы запускаете свой код, что значительно сводит к минимуму человеческие ошибки.

Для этого мы можем использовать файл config.py:

import os

MICROSOFT_TRANSLATE_API_KEY = os.environ.get('MICROSOFT_TRANSLATE_API_KEY', 'default_key')

При этом по умолчанию наш ключ принимает значение «default_key». Нам нужно было бы явно установить его перед запуском любого кода с использованием терминала:

python -c "from package_name.external_apis.config import MICROSOFT_TRANSLATE_API_KEY; print(MICROSOFT_TRANSLATE_API_KEY)"

export MICROSOFT_TRANSLATE_API_KEY="your_actual_key"

python -c "from package_name.external_apis.config import MICROSOFT_TRANSLATE_API_KEY; print(MICROSOFT_TRANSLATE_API_KEY)"

Если вы хотите быть особенно осторожным, вы можете добавить дополнительные уровни абстракции к ключу API, чтобы затруднить случайное извлечение его значения. Например, вы можете создать класс Password, сохранив пароль как скрытую переменную, а затем добавив явный метод «get_password»:

import os

class Password:
  def __init__(self, password):
    self.__password = password
  
  def get_password():
    return self.__password

MICROSOFT_TRANSLATE_API_KEY_CLASS = Password(os.environ.get('MICROSOFT_TRANSLATE_API_KEY', 'default_key'))

print(MICROSOFT_TRANSLATE_API_KEY_CLASS.get_password())  # prints password
print(MICROSOFT_TRANSLATE_API_KEY_CLASS.password)  # error
print(MICROSOFT_TRANSLATE_API_KEY_CLASS.__password)  # error

Таким образом, вы вызываете метод get_password при определении headers для запроса.

Упаковка вашего кода в функции и добавление ведения журнала

Теперь, когда мы знаем основы, мы вносим некоторые улучшения:

  • Добавить все идентификаторы для Microsoft Translator API в файл config.py
"""
config.py file
"""
import os

# MICROSOFT API CONFIGS
MICROSOFT_TRANSLATE_URL = 'https://api.cognitive.microsofttranslator.com'
MICROSOFT_TRANSLATE_LOCATION = os.environ.get('MICROSOFT_TRANSLATE_LOCATION', 'default_location')
MICROSOFT_TRANSLATE_API_KEY = os.environ.get('MICROSOFT_TRANSLATE_API_KEY', 'default_key')

Здесь мы также добавили местоположение вашего экземпляра в качестве переменной среды.

  • Добавьте отдельные функции для каждой конечной точки
"""
microsoft.py file
"""

import uuid
from package_name.external_apis.config import (
  MICROSOFT_TRANSLATE_URL,
  MICROSOFT_TRANSLATE_LOCATION,
  MICROSOFT_TRANSLATE_API_KEY
)

# -- prepare headers
HEADERS = {
  'Ocp-Apim-Subscription-Key': MICROSOFT_TRANSLATE_API_KEY,
  'Ocp-Apim-Subscription-Region': MICROSOFT_TRANSLATE_LOCATION,
  'Content-type': 'application/json',
  'X-ClientTraceId': str(uuid.uuid4())
}


# -- utils
def _is_response_valid(status_code):
    if str(status_code).startswith('2'):
        return True

# -- functions for endpoints

# /languages endpoint
def get_languages(api_version='3.0'):

    # prepare url
    url = f'{MICROSOFT_TRANSLATE_URL}/languages?api-version={api_version}'

    # send request and process outputs
    resp = requests.get(url)
    status_code = resp.status_code
    if _is_response_valid(status_code):
        return resp.json(), status_code
    
    return resp.text, status_code


# /translate endpoint
def translate_text(text, target_language, source_language=None, api_version='3.0'):
    
    # send request and process outputs
    url = f'{MICROSOFT_TRANSLATE_URL}/translate?api-version={api_version}'

    # standardise target language type
    if isinstance(target_language, str):
        target_language = [target_language]
    
    # dynamically add array parameter to url
    for lang in target_language:
        url = f'{url}&to={lang}'
    
    if source_language:
        url = f'{url}&from={source_language}'
    
    # standardise text type
    if isinstance(text, str):
        text = [text]
    
    # dynamically build the request body
    body = [{'text': text_} for text_ in text]

    # send request and process outputs
    resp = requests.post(url, headers=HEADERS, json=body)
    status_code = resp.status_code

    if _is_response_valid(status_code)
        return resp.json(), status_code
    
    return resp.text, status_code
  • Добавьте журналы и документацию, используя строки документации в стиле typing и sphinx
"""
microsoft.py file
"""

import uuid
import logging
from package_name.external_apis.config import (
  MICROSOFT_TRANSLATE_URL,
  MICROSOFT_TRANSLATE_LOCATION,
  MICROSOFT_TRANSLATE_API_KEY
)

# imports for typing annotations
from typing import Optional, Union, List

# -- configure logger. Taken from official python docs
LOGGER = logging.getLogger(__name__)
LOGGER.setLevel(logging.DEBUG)
ch = logging.StreamHandler()
ch.setLevel(logging.DEBUG)
date_format = '%Y-%m-%d %H:%M:%S'
formatter = logging.Formatter('%(asctime)s:%(name)s:%(levelname)s:%(message)s', datefmt=date_format)
ch.setFormatter(formatter)
LOGGER.addHandler(ch)


# -- prepare headers
HEADERS = {
  'Ocp-Apim-Subscription-Key': MICROSOFT_TRANSLATE_API_KEY,
  'Ocp-Apim-Subscription-Region': MICROSOFT_TRANSLATE_LOCATION,
  'Content-type': 'application/json',
  'X-ClientTraceId': str(uuid.uuid4())
}


# -- utils
def _is_response_valid(status_code: int) -> Optional[bool]:
    """ Function to check response is valid or not
    
    :param status_code: status code from response
    :returns: True if valid response, None otherwise
    """
    if str(status_code).startswith('2'):
        return True

# -- functions for endpoints

# /languages endpoint
def get_languages(api_version: str = '3.0') -> tuple:
    """ get languages available from API for specific version

    :param api_version: version of API to use
    :returns: (available languages, status_code)

    """
    # prepare url
    url = f'{MICROSOFT_TRANSLATE_URL}/languages?api-version={api_version}'

    # send request and process outputs
    LOGGER.info(f'Getting languages available on api_version={api_version}')
    resp = requests.get(url)
    status_code = resp.status_code
    if _is_response_valid(status_code):
        return resp.json(), status_code

    LOGGER.error('Failed to get languages')
    return resp.text, status_code


# /translate endpoint
def translate_text(text: Union[str, List[str]], target_language: Union[str, List[str]], source_language: Optional[str] = None, api_version: str = '3.0') -> tuple:
    """translates txt using the microsoft translate API

    :param text: text to be translated. Either single or multiple (stored in a list)
    :param target_language: ISO format of target translation languages
    :param source_language: ISO format of source language. If not provided is inferred by the translator, defaults to None
    :param api_version: api version to use, defaults to "3.0"
    :return: for successful response, (status_code, [{"translations": [{"text": translated_text_1, "to": lang_1}, ...]}, ...]))        
    """
    # send request and process outputs
    url = f'{MICROSOFT_TRANSLATE_URL}/translate?api-version={api_version}'

    # standardise target language type
    if isinstance(target_language, str):
        target_language = [target_language]
    
    # dynamically add array parameter to url
    for lang in target_language:
        url = f'{url}&to={lang}'
    
    if source_language:
        url = f'{url}&from={source_language}'
    
    # standardise text type
    if isinstance(text, str):
        text = [text]
    
    # dynamically build the request body
    body = [{'text': text_} for text_ in text]

    LOGGER.info(f'Translating {len(text)} texts to {len(target_language)} languages')
    # send request and process outputs
    resp = requests.post(url, headers=HEADERS, json=body)
    status_code = resp.status_code

    if _is_response_valid(status_code)
        return resp.json(), status_code
    LOGGER.error('Failed to translate texts')
    return resp.text, status_code

Рекомендации по использованию ноутбуков Jupyter

При использовании Jupyter Notebook простой установки переменных среды в Терминале недостаточно, поскольку по умолчанию Jupyter не сможет их увидеть. Вместо этого я рекомендую следующее:

  • Добавьте «_jupyter» при настройке переменных среды в терминале, затем запустите jupyter notebook
export MICROSOFT_API_CREDENTIALS_JUPYTER='my_key'
jupyter notebook
  • Используйте пакет dot_env (возможно, вам придется установить его с помощью pip ), чтобы установить правильную переменную среды, прочитав переменную среды «_jupyter». Добавьте волшебную команду %%capture, чтобы убедиться, что переменная среды не печатается.
%%capture
import os
import json
from dotenv import load_dotenv
load_dotenv() # loads key values pairs into env
MICROSOFT_TRANSLATE_API_KEY = os.environ.get('MICROSOFT_TRANSLATE_API_KEY_JUPYTER')
%set_env MICROSOFT_TRANSLATE_API_KEY=$MICROSOFT_TRANSLATE_API_KEY

Теперь вы сможете аутентифицировать свои запросы в Microsoft в Jupyter Notebooks.

Заключительные замечания

В этой статье мы рассмотрели настройку экземпляра Microsoft Translate в Azure и его интеграцию в проекты с использованием передовых методов.

Стоит отметить, что хотя бесплатная версия очень хороша, она имеет ограничения по ресурсам (2 миллиона символов в месяц). Кажется, что это много, но заканчивается довольно быстро. Недавно я столкнулся с этим в проекте, где я использовал Translate API для увеличения данных. Кроме того, существует ограничение в 50000 символов на запрос на перевод, что означает, что вы должны быть очень осторожны при переводе больших текстов. Запрос рассчитывается следующим образом: total_chars_in_your_texts * n_languages. Поэтому в тех случаях, когда у вас есть большие тексты, имеет смысл переводить их отдельно для каждого языка или группы языков.

Я выпущу расширенное руководство по использованию Microsoft API, в котором я представлю функции для автоматической группировки текстов, чтобы вы максимально эффективно использовали максимальное количество символов. А пока вы можете найти код этой статьи здесь:



ml-utils/microsoft.py at development · namiyousef/ml-utils
Полезные функции ML util. Внесите свой вклад в разработку namiyousef/ml-utils, создав учетную запись на GitHub.github.com



Примечание автора

Если вам понравилась эта статья или вы узнали что-то новое, рассмотрите возможность получения членства по моей реферальной ссылке:



Присоединяйтесь к Medium по моей реферальной ссылке — Юсеф Нами
Прочитайте все истории Юсефа Нами (и тысяч других авторов на Medium). Ваш членский взнос напрямую поддерживает…namiyousef96.medium.com



Это дает вам неограниченный доступ ко всему Medium, а мне помогает создавать больше контента без каких-либо дополнительных затрат для вас.

Список литературы

[1] Переводчик Майкрософт. Доступно по адресу: https://www.google.com/search?q=microsoft+translator&oq=microsoft+translator&aqs=chrome.0.35i39j69i59l2j0i512l2j69i60l3.2307j0j7&sourceid=chrome&ie=UTF-8

Все изображения принадлежат автору, если не указано иное