Установка и запуск контейнеров распознавания пользовательских именованных сущностей

Контейнеры позволяют размещать пользовательский API распознавания именованных сущностей в собственной инфраструктуре с помощью собственной обученной модели. Если у вас есть требования к безопасности или управлению данными, которые не могут быть выполнены путем удаленного вызова пользовательского распознавания именованных сущностей, контейнеры могут быть хорошим вариантом.

Примечание

• Бесплатная учетная запись ограничена 5000 текстовыми записями в месяц, а для контейнеров действуют только ценовые категорииБесплатный и Стандартный. Дополнительные сведения о тарифах запросов транзакций см. в разделе Ограничения данных и услуг.

Предварительные требования

• Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure.
• Docker, установленный на главном компьютере. Docker нужно настроить таким образом, чтобы контейнеры могли подключать и отправлять данные о выставлении счетов в Azure.
  • В ОС Windows для Docker нужно также настроить поддержку контейнеров Linux.
  • Вы должны иметь базовое представление о концепциях Docker.
• A Языковой ресурс бесплатного (F0) или стандартного (S) ценового уровня.
• Обученная и развернутая пользовательская модель распознавания именованных сущностей

Сбор обязательных параметров

Для всех контейнеров ИИ Azure требуются три основных параметра. Условия лицензии на использование программного обеспечения Microsoft должны присутствовать в значении accept. Также требуются URI конечной точки и ключ API.

URI конечной точки

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

Ключи

Значение {API_KEY} используется для запуска контейнера и доступно на странице Ключи портал Azure соответствующего ресурса служб ИИ Azure. Перейдите на страницу Ключи и выберите значок Копировать в буфер обмена.

Важно!

Эти ключи подписки используются для доступа к API служб ИИ Azure. Не предоставляйте доступ к ключам другим пользователям. Храните их в безопасном месте. Например, используйте Azure Key Vault. Также рекомендуется регулярно повторно создавать эти ключи. Для вызова API необходим только один ключ. При повторном создании первого ключа второй ключ можно использовать для бесперебойного доступа к службе.

Требования к главному компьютеру и рекомендации

Узел — это 64-разрядный компьютер, на котором выполняется контейнер Docker. Это может быть компьютер в локальной среде или служба размещения Docker в Azure, включая следующие решения:

• Служба Azure Kubernetes.
• Экземпляры контейнеров Azure.
• Кластер Kubernetes, развернутый в Azure Stack. Дополнительные сведения см. в статье Развертывание Kubernetes в Azure Stack.

В следующей таблице описаны минимальные и рекомендуемые спецификации для контейнеров пользовательского распознавания именованных сущностей. Частота каждого ядра ЦП должна быть минимум 2,6 ГГц. Также указано допустимое количество транзакций в секунду (TPS).

	Минимальные спецификации узла	Рекомендуемые спецификации узла	Минимальное TPS	Максимальное TPS
Настраиваемый компонент Распознавания именованных сущностей	1 ядро, 2 ГБ памяти	1 ядро, 4 ГБ памяти	15	30

Ядро и память соответствуют параметрам --cpus и --memory, которые используются как часть команды docker run.

Экспорт пользовательской модели распознавания именованных сущностей

Прежде чем приступить к запуску образа Docker, необходимо экспортировать собственную обученную модель, чтобы предоставить ее контейнеру. Используйте следующую команду, чтобы извлечь модель и заменить заполнители ниже собственными значениями:

Заполнитель	Значение	Формат или пример
{API_KEY}	Ключ для ресурса пользовательского распознавания именованных сущностей. Он представлен на странице ресурса Ключ и конечная точка на портале Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI}	Конечная точка для доступа к ПОЛЬЗОВАТЕЛЬСКОМУ API распознавания именованных сущностей. Он представлен на странице ресурса Ключ и конечная точка на портале Azure.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT_NAME}	Имя проекта, содержащего модель, которую требуется экспортировать. Его можно найти на вкладке проектов на портале Language Studio.	myProject
{TRAINED_MODEL_NAME}	Имя обученной модели, которую требуется экспортировать. Обученные модели можно найти на вкладке оценки модели в проекте на портале Language Studio.	myTrainedModel

curl --location --request PUT '{ENDPOINT_URI}/language/authoring/analyze-text/projects/{PROJECT_NAME}/exported-models/{TRAINED_MODEL_NAME}?api-version=2023-04-15-preview' \
--header 'Ocp-Apim-Subscription-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "TrainedmodelLabel": "{TRAINED_MODEL_NAME}"
}'

Получение образа контейнера с помощью docker pull

Образ контейнера пользовательского распознавания именованных сущностей можно найти в mcr.microsoft.com синдикате реестра контейнеров. Он находится в репозитории azure-cognitive-services/textanalytics/ и называется customner. Полное имя образа контейнера — mcr.microsoft.com/azure-cognitive-services/textanalytics/customner.

Чтобы использовать последнюю версию контейнера, можно использовать latest тег . Полный список тегов также представлен в MCR.

Воспользуйтесь командой docker pull, чтобы скачать образ контейнера из реестра контейнеров Microsoft.

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/customner:latest

Совет

Используйте команду docker images, чтобы получить список скачанных образов контейнеров. Например, следующая команда возвращает таблицу со списком идентификаторов, репозиториев и тегов для каждого скачанного образа контейнера:

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

Запуск контейнера с помощью команды docker run

После добавления контейнера на главный компьютер используйте команду docker run для запуска контейнеров. После запуска контейнер продолжи работу, пока вы его не остановите.

Важно!

• В командах Docker в следующих разделах используется обратная косая черта (\) как символ продолжения строки. Замените или удалите ее в соответствии с требованиями вашей операционной системы.
• Для запуска контейнера необходимо указать параметры Eula, Billing и ApiKey. В противном случае контейнер не запустится. Дополнительные сведения см. в разделе о выставлении счетов.

Чтобы запустить контейнер Пользовательского распознавания именованных сущностей , выполните следующую docker run команду. Замените значения заполнителей ниже на собственные.

Заполнитель	Значение	Формат или пример
{API_KEY}	Ключ для ресурса пользовательского распознавания именованных сущностей. Он представлен на странице ресурса Ключ и конечная точка на портале Azure.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI}	Конечная точка для доступа к API распознавания пользовательских именованных сущностей. Он представлен на странице ресурса Ключ и конечная точка на портале Azure.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT_NAME}	Имя проекта, содержащего модель, которую требуется экспортировать. Его можно найти на вкладке проектов на портале Language Studio.	myProject
{LOCAL_PATH}	Путь, по которому будет загружена экспортируемая модель на предыдущем шаге. Вы можете выбрать любой путь по своему вкусу.	C:/custom-ner-model
{TRAINED_MODEL_NAME}	Имя обученной модели, которую требуется экспортировать. Обученные модели можно найти на вкладке оценки модели в проекте на портале Language Studio.	myTrainedModel

docker run --rm -it -p5000:5000  --memory 4g --cpus 1 \
-v {LOCAL_PATH}:/modelPath \
mcr.microsoft.com/azure-cognitive-services/textanalytics/customner:latest \
EULA=accept \
BILLING={ENDPOINT_URI} \
APIKEY={API_KEY} \
projectName={PROJECT_NAME}
exportedModelName={TRAINED_MODEL_NAME}

Команда:

• Запускает контейнер пользовательского распознавания именованных сущностей и загружает экспортированную модель по указанному локальному пути.
• выделяет одно ядро ЦП и 4 ГБ памяти;
• предоставляет TCP-порт 5000 и выделяет псевдотелетайп для контейнера;
• автоматически удаляет контейнер после завершения его работы. Образ контейнера остается доступным на главном компьютере.

Запуск нескольких контейнеров на одном узле

Если вы планируете запускать несколько контейнеров при открытых портах, обязательно назначьте каждому контейнеру отдельный открытый порт. Например, запускайте первый контейнер на порте 5000, а второй — на порте 5001.

Вы можете использовать этот контейнер и другой контейнер служб ИИ Azure, работающий на узле. Вы также можете запустить несколько контейнеров одного контейнера служб ИИ Azure.

Запрос конечной точки прогнозирования контейнера

Контейнер предоставляет интерфейсы REST API конечной точки прогнозирования запросов.

Используйте узел http://localhost:5000 для API контейнера.

Проверка состояния контейнера

Проверить это можно несколькими способами. Получите адрес и открытый порт для рассматриваемого контейнера из его параметра Внешний IP-адрес и запустите веб-браузер. Используйте приведенные ниже URL-адреса запросов, чтобы убедиться, что контейнер работает. В http://localhost:5000 приведены примеры URL-адресов запросов, однако ваш конкретный контейнер может иметь отличия. Убедитесь в правильности внешнего IP-адреса и открытого порта контейнера.

URL-адрес запроса	Назначение
http://localhost:5000/	Контейнер предоставляет домашнюю страницу.
http://localhost:5000/ready	При запросе с помощью команды GET этот URL-адрес подтверждает, что контейнер готов принять запрос к модели. Этот запрос может использоваться для проб активности и готовности Kubernetes.
http://localhost:5000/status	Этот URL-адрес, который можно также запросить с помощью GET, проверяет, действителен ли ключ API, используемый для запуска контейнера, без запроса конечной точки. Этот запрос может использоваться для проб активности и готовности Kubernetes.
http://localhost:5000/swagger	Контейнер предоставляет полный набор документации по конечным точкам и функции Попробовать. Эта функция позволяет ввести параметры в веб-форму HTML и создать запрос без необходимости писать код. После возвращения результатов запроса предоставляется пример команды CURL с примером требуемого формата HTTP-заголовков и текста.

Остановка контейнера

Чтобы завершить работу контейнера, в среде командной строки, где выполняется контейнер, нажмите комбинацию клавиш Ctrl+C.

Устранение неполадок

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

Совет

Дополнительные сведения об устранении неполадок и рекомендации см. в статье Часто задаваемые вопросы о контейнерах ИИ Azure.

Выставление счетов

Контейнеры пользовательского распознавания именованных сущностей отправляют сведения о выставлении счетов в Azure с помощью ресурса пользовательского распознавания именованных сущностей в учетной записи Azure.

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

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

Подключение к Azure

Для запуска контейнера необходимо указать значения аргументов, касающихся выставления счетов. Эти значения обеспечивают подключение контейнера к конечной точке выставления счетов. Отчеты об использовании контейнера примерно каждые 10—15 минут. Если контейнер не подключится к Azure в течение допустимого периода времени, контейнер будет продолжать работать, но не будет обслуживать запросы, пока не будет восстановлена конечная точка выставления счетов. Попытки подключения выполняются 10 раз на протяжении одинакового интервала времени (10–15 минут). Если контейнеру не удается подключиться к конечной точке выставления счетов за 10 попыток, он останавливает запросы на обслуживание. Пример информации, отправляемой корпорации Майкрософт для выставления счетов, см. в разделе Часто задаваемые вопросы о контейнере служб ИИ Azure .

Аргументы для выставления счетов

Команда docker run запустит контейнер, если указаны следующие три параметра с допустимыми значениями.

Параметр	Описание
ApiKey	Ключ API ресурса служб ИИ Azure, который используется для отслеживания сведений о выставлении счетов. Этому параметру следует присвоить значение ключа API для подготовленного ресурса, который можно получить в Billing.
Billing	Конечная точка ресурса служб ИИ Azure, которая используется для отслеживания сведений о выставлении счетов. Этому параметру следует присвоить URI конечной точки подготовленного ресурса Azure.
Eula	Указывает, что вы приняли условия лицензии для контейнера. Для этого параметра следует задать значение accept.

Сводка

В этой статье вы узнали о концепциях и рабочих процессах для скачивания, установки и запуска пользовательских контейнеров распознавания именованных сущностей. В разделе "Сводка" сделайте следующее.

• Пользовательское распознавание именованных сущностей предоставляет контейнеры Linux для Docker.
• Образы контейнеров скачиваются из Реестра контейнеров Майкрософт (MCR).
• Образы контейнеров выполняются в Docker.
• Вы можете использовать REST API или пакет SDK для вызова операций в контейнерах пользовательского распознавания именованных сущностей, указав универсальный код ресурса (URI) узла контейнера.
• При создании экземпляра контейнера нужно указать данные для выставления счетов.

Важно!

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

Дальнейшие действия

• Параметры конфигурации см. в разделе Конфигурация контейнеров.