Основы Microsoft Bot Framework

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

Бот — это приложение, с которым пользователи взаимодействуют, общаясь с помощью текста, графики (карт или изображений) или речи. Сервис Azure AI Bot — это облачная платформа. Он размещает боты и делает их доступными для каналов, таких как Microsoft Teams, Facebook или Slack.

Служба Bot Framework, которая является компонентом Службы Azure AI Bot, отправляет информацию между приложением, подключенным к боту пользователя, и ботом. Каждый канал может включать дополнительные сведения в свою деятельность, которую он отправляет. Прежде чем создавать боты, важно понять, как бот использует объекты действий для взаимодействия с пользователями.

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

Схема действий

Служба Bot Framework отправляет обновление беседы, когда участник присоединяется к беседе. Например, при запуске беседы с эмулятором Bot Framework может появиться два действия обновления беседы (один для пользователя, присоединенного к беседе, и один для присоединения бота). Чтобы отличить эти действия обновления беседы, проверьте, кто включен в добавленных участников свойство действия.

Деятельность сообщения содержит информацию о беседе между сторонами. В примере эхо-бота сообщения передают простой текст, который будет отображаться в канале. Либо действие сообщения может содержать текст для озвучивания, предлагаемые действия или карты, которые нужно отображать.

Совет

В каждой платформе необходимо реализовать протокол Bot Framework, и то, как каждая платформа делает это, может немного отличаться. Например, некоторые каналы сначала отправляют действия обновления беседы, а некоторые отправляют действия обновления беседы после отправки первого действия сообщения. Канал может включать бота и пользователя в одно действие обновления беседы, а другой может отправлять два действия обновления беседы.

В этом примере бот создал и отправил активность сообщения в ответ на входящее сообщение, которое он получил. Однако бот может реагировать другими способами на полученное событие сообщения, и обычно бот реагирует на обновление беседы, отправляя сообщение с приветственным текстом. Дополнительные сведения см. в статье о том, как приветствовать пользователя.

Пакет SDK Bot Framework

Пакет SDK Bot Framework позволяет создавать боты, которые могут размещаться в службе ботов ИИ Azure. Служба определяет REST API и протокол действий для взаимодействия бота и каналов или пользователей. Пакет SDK основан на этом REST API и предоставляет абстракцию службы, чтобы сосредоточиться на логике беседы. Хотя вам не нужно понимать службу REST для использования пакета SDK, понимание некоторых его функций может оказаться полезным.

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

Примечание.

Поддержка функций, предоставляемых пакетом SDK и REST API, зависит от канала. Вы можете протестировать бота с помощью эмулятора Bot Framework, но также протестировать все функции бота на каждом канале, в котором планируется сделать бот доступным.

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

Активности

Каждое взаимодействие между пользователем (или каналом) и ботом представлено как действие. Схема действий Bot Framework определяет действия, которые можно обменивать между пользователем или каналом и ботом. Действия могут представлять человеческий текст или речь, уведомления приложения к приложению, реакции на другие сообщения и т. д.

Ходы

При общении люди обычно говорят по очереди. Как правило, бот реагирует на вводимые пользователем данные. В пакете SDK Bot Framework ход состоит из входящей активности пользователя к боту и любой активности, которую бот немедленно возвращает пользователю в ответ. Вы можете рассматривать ход как процесс, связанный с обработкой ботом полученного действия.

Например, пользователь может попросить бота выполнить определенную задачу. Бот может ответить вопросом, чтобы получить дополнительные сведения о задаче, в этот момент ход завершается. В следующем случае бот получает новое сообщение от пользователя, которое может содержать ответ на вопрос бота, или может представлять собой изменение субъекта или запрос, чтобы игнорировать первоначальный запрос для выполнения задачи.

Структура приложения Bot

Пакет SDK определяет класс бота , который обрабатывает логику беседы для приложения бота. Класс бота:

  • Распознает и интерпретирует входные данные пользователя.
  • Анализирует входные данные и выполняет соответствующие задачи.
  • Создает ответы о том, что бот делает или сделал.

Пакет SDK также определяет класс адаптера , который обрабатывает подключение к каналам. Адаптер:

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

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

Бот обладает элементами подключения и элементами рассуждения, а также абстракцией для состояния

Пакет SDK не требует использования определенного уровня приложения для отправки и получения веб-запросов. Bot Framework содержит шаблоны и примеры для ASP.NET (C#), restify (JavaScript) и aiohttp (Python). Однако вы можете использовать другой уровень приложений для приложения.

При создании бота с помощью пакета SDK вы предоставляете код для получения HTTP-трафика и перенаправит его в адаптер. Bot Framework предоставляет несколько шаблонов и примеров, которые можно использовать для разработки собственных ботов.

Внимание

Пакет SDK Bot Framework и эмулятор Bot Framework были архивированы на GitHub. Проект больше не обновляется или не поддерживается. Запросы на поддержку пакета SDK Bot Framework больше не будут обслуживаться с 31 декабря 2025 г.

Чтобы создавать агенты с помощью выбранной службы ИИ, оркестрации и знаний, рекомендуется использовать пакет SDK для агентов Microsoft 365. Пакет SDK для агентов поддерживает язык C#, JavaScript или Python. Дополнительные сведения о пакете SDK для агентов см. в aka.ms/agents. Если у вас есть существующий бот, созданный с помощью пакета SDK Bot Framework, вы можете обновить бота до пакета SDK для агентов. Ознакомьтесь с основными изменениями и обновлениями в руководстве по миграции с Bot Framework SDK на Agents SDK.

Если вы создаете агент для совместной работы в Microsoft Teams, рассмотрите возможность использования пакета SDK Teams. Он предоставляет интерфейсы API, поддержку адаптивных карт и встроенную оркестрацию ИИ для агентов, работающих в среде Teams. Дополнительные сведения см. в пакете SDK Teams (библиотека ИИ Teams).

Если вы ищете платформу агента на основе SaaS, рассмотрите microsoft Copilot Studio.

Логика бота

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

Пакет SDK предоставляет несколько различных парадигм для управления логикой бота.

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

Адаптер бота

Адаптер имеет метод процессной активности для инициирования операции.

  • Он принимает текст запроса (полезные данные запроса, переведенные в действие) и заголовок запроса в качестве аргументов.
  • Проверяет, является ли заголовок проверки подлинности допустимым.
  • Он создает объект контекста для поворота. Объект контекста содержит сведения о действии.
  • Он отправляет объект контекста через конвейер промежуточного ПО.
  • Затем он отправляет объект контекста обработчику ходов бота.

Адаптер также:

  • Форматирует и отправляет действия ответа. Эти ответы обычно представляют собой сообщения для пользователя, но также могут включать сведения, которые будут использоваться каналом пользователя напрямую.
  • Представлены другие методы, предоставляемые REST API Bot Connector, такие как обновление сообщения и удаление сообщения.
  • Перехватывает ошибки или исключения, которые иначе не перехвачены за ход.

Контекст поворота

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

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

Промежуточное программное обеспечение

Промежуточное ПО действует так же, как любое средство передачи сообщений, и состоит из линейного набора компонентов, каждый из которых выполняется в строгом порядке и получает возможность выполнить операцию над активностью. Последним этапом конвейера промежуточного программного обеспечения является обратный вызов обработчика хода в классе бота, который приложение зарегистрировало с использованием метода process activity адаптера. Промежуточное ПО реализует метод on turn, который вызывает адаптер.

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

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

Состояние бота и хранилище

Как и в других веб-приложениях, бот по сути не сохраняет состояние. Состояние в боте следует той же парадигме, что и современные веб-приложения, и пакет SDK Bot Framework предоставляет уровни хранения и абстракции управления состояниями, чтобы упростить управление состояниями.

В разделе управления состоянием описываются эти функции состояния и хранилища.

Конечная точка подключения и настройка обмена сообщениями

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

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

Сведения об HTTP

Действия поступают в бот из службы Bot Framework с помощью HTTP POST-запроса. В ответ на входящий запрос POST бот возвращает код состояния HTTP 200. Действия, отправляемые из бота в канал, отправляются отдельным POST-запросом к службе Bot Framework. В ответ на него также поступает код состояния HTTP 200.

Протокол не указывает порядок, в котором выполняются эти запросы POST и их подтверждения. Но на распространенных платформах служб HTTP такие запросы обычно являются вложенными, то есть исходящий HTTP-запрос выполняется ботом в процессе обработки входящего HTTP-запроса. Этот шаблон показан на предыдущей схеме. Поскольку имеется два последовательных HTTP-соединения, модель безопасности должна обеспечивать защиту для обоих.

Примечание.

Бот имеет 15 секунд, чтобы подтвердить вызов со статусом 200 на большинстве каналов. Если бот не отвечает в течение 15 секунд, возникает ошибка HTTP GatewayTimeout (504).

Стек обработки активности

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

Схема последовательности, иллюстрирующая обработку действия ботом.

В приведенном выше примере в ответ на действие сообщения бот отправляет другое действие сообщения, помещая в него текст из первого сообщения. Обработка начинается с поступления на веб-сервер запроса HTTP POST, в котором сведения о действии передаются в формате полезных данных JSON. Часто проекты ASP.NET используются для ботов на C#, а популярные фреймворки, такие как Express или restify, применяются для ботов на JavaScript Node.js.

Встроенный компонент пакета SDK, который называется адаптером, является ядром среды выполнения SDK. Действие передается в тексте запроса HTTP POST в формате JSON. Этот json десериализирован для создания объекта действия , который затем передается адаптеру через метод действия процесса. При получении активности адаптер создает контекст шага и вызывает промежуточное ПО.

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

Внимание

Поток, обрабатывающий главный ход бота, справляется с удалением объекта контекста после его завершения. Необходимо дождаться завершения await всех вызовов активности, чтобы первичный поток ожидал завершения сгенерированной активности, прежде чем завершить обработку и удалить контекст хода. В противном случае, если ответ (или какой-либо из его обработчиков) после длительной паузы попытается воздействовать на объект контекста, может возникнуть ошибка Контекст был удален.

Шаблоны для ботов

Необходимо выбрать уровень приложения, используемый для приложения; Однако в Bot Framework есть шаблоны и примеры для ASP.NET (C#), restify (JavaScript) и aiohttp (Python). Документация написана, предполагая, что вы используете одну из этих платформ, но пакет SDK этого от вас не требует.

Чтобы добавить шаблоны ботов в Visual Studio, скачайте и установите Bot Framework v4 SDK Templates for Visual Studio VSIX файл.

Бот — это веб-приложение, и шаблоны предоставляются для каждой языковой версии пакета SDK. Все шаблоны предоставляют реализацию и адаптер конечной точки по умолчанию. Каждый шаблон включает:

  • Подготовка ресурсов
  • Реализация конечной точки HTTP для конкретного языка, которая направляет входящие действия в адаптер.
  • Объект адаптера
  • Объект бота

Основное различие между различными типами шаблонов — в объекте бота. Шаблоны:

  • Пустой бот
    • Включает обработчик действий, который приветствует пользователя в беседе, отправив сообщение «Hello, world!» на первом этапе беседы.
  • Эхо-бот
    • Использует обработчик действий для приветствия пользователей и отзеркаливания их ввода.
  • Основной бот
    • Объединяет множество функций пакета SDK и демонстрирует рекомендации для бота.
    • Использует обработчик действий для приветствия пользователей.
    • Использует диалоговое окно компонента и дочерние диалоги для управления беседой.
    • Диалоговые окна используют функции Распознавание речи (LUIS) и QnA Maker.

Примечание.

Azure AI QnA Maker будет выведен из эксплуатации 31 марта 2025 г. С 1 октября 2022 г. вы не сможете создавать новые ресурсы или базы знаний QnA Maker. Новая версия вопроса и возможности ответа теперь доступна как часть языка искусственного интеллекта Azure.

Пользовательский ответ на вопросы, компонент языка искусственного интеллекта Azure, — это обновленная версия службы QnA Maker. Дополнительные сведения о поддержке вопросов и ответов в пакете SDK Bot Framework см. в разделе "Распознавание естественного языка".

Примечание.

Распознавание речи (LUIS) будет прекращен 1 октября 2025 года. Начиная с 1 апреля 2023 года вы не сможете создавать новые ресурсы LUIS. Новая версия распознавания речи теперь доступна как часть языка ИИ Azure.

Обработка разговорного языка (CLU) — это обновленная версия LUIS. Дополнительные сведения о поддержке распознавания речи в пакете SDK Bot Framework см. в разделе "Распознавание естественного языка".

Дополнительная информация:

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

Вам потребуется управлять ресурсами для бота, например идентификатором приложения и паролем, а также сведениями для всех подключенных служб. При развертывании бота потребуется безопасный доступ к этой информации. Чтобы избежать сложности, большинство статей пакета SDK Bot Framework не описывают, как управлять этой информацией.

Адаптеры каналов

Пакет SDK также позволяет использовать адаптеры каналов, в которых сам адаптер дополнительно выполняет задачи, которые служба соединителя Bot обычно выполняет для канала.

Пакет SDK предоставляет несколько адаптеров каналов на некоторых языках. Дополнительные адаптеры каналов доступны через репозитории Botkit и Community. Дополнительные сведения см. в таблице репозитория пакета SDK Bot Framework для каналов и адаптеров.

API подключения бота REST

Пакет Bot Framework SDK оборачивает и расширяет функциональность REST API Bot Connector. Если вы хотите понять базовые HTTP-запросы, поддерживающие пакет SDK, ознакомьтесь с проверкой подлинности соединителя и связанными статьями. Действия, которые бот отправляет и получает, соответствуют схеме действий Bot Framework Activity.

Следующие шаги

  • Last updated on