Základy rozhraní Microsoft Bot Framework

  • Článek

PLATÍ PRO: SDK v4

Robot je aplikace, se kterou uživatelé komunikují konverzačním způsobem, pomocí textu, grafiky (například karet nebo obrázků) nebo řeči. Azure AI Bot Service je cloudová platforma. Hostuje roboty a zpřístupňuje je kanálům, jako jsou Microsoft Teams, Facebook nebo Slack.

Služba Bot Framework Service, která je součástí služby Azure AI Bot Service, odesílá informace mezi aplikací připojenou k robotovi uživatele a robotem. Každý kanál může obsahovat další informace v aktivitách, které odesílají. Před vytvořením robotů je důležité pochopit, jak robot používá objekty aktivit ke komunikaci se svými uživateli.

Tento diagram znázorňuje dva typy aktivit, aktualizaci konverzací a zprávu, které se můžou vyměňovat, když uživatel komunikuje s robotem echo.

activity diagram

Služba Bot Framework Service odešle aktualizaci konverzace, když se strana připojí ke konverzaci. Například při zahájení konverzace s bot Framework Emulatorem se můžou zobrazit dvě aktivity aktualizace konverzací (jedna pro uživatele, který se připojuje ke konverzaci, a jedna pro připojení robota). Chcete-li odlišit aktivity aktualizace konverzací, zkontrolujte, kdo je součástí přidané vlastnosti členové aktivity.

Aktivita zprávy přenáší informace o konverzaci mezi stranami. V příkladu robota echo se aktivity zpráv přenášejí jednoduchý text a kanál tento text vykreslí. Případně může aktivita zprávy obsahovat text, který se má vyslovovat, navrhované akce nebo karty, které se mají zobrazit.

Tip

Je až na každém kanálu, aby implementovali protokol Bot Framework a jak to každý kanál dělá, může být trochu jiný. Některé kanály například odesílají aktivity aktualizace konverzací jako první a některé po odeslání první aktivity zprávy posílají aktivity aktualizace konverzací. Kanál může zahrnovat robota i uživatele v jedné aktivitě aktualizace konverzace, zatímco druhý může posílat dvě aktivity aktualizace konverzací.

V tomto příkladu robot vytvořil a odeslal aktivitu zprávy v reakci na příchozí aktivitu zprávy, kterou přijala. Robot ale může reagovat jinými způsoby na přijatou aktivitu zpráv a je běžné, že robot reaguje na aktivitu aktualizace konverzace odesláním aktivity zprávy s uvítací zprávou. Další informace najdete v článku o tom, jak uživatele přivítat.

Sada SDK služby Bot Framework

Sada SDK služby Bot Framework umožňuje vytvářet roboty, které je možné hostovat ve službě Azure AI Bot Service. Služba definuje rozhraní REST API a protokol aktivity pro způsob interakce robota a kanálů nebo uživatelů. Sada SDK vychází z tohoto rozhraní REST API a poskytuje abstrakci služby, abyste se mohli zaměřit na konverzační logiku. I když nepotřebujete porozumět službě REST, abyste mohli používat sadu SDK, může být užitečné porozumět některým jeho funkcím.

Roboti jsou aplikace, které mají konverzační rozhraní. Dají se použít k přesunu jednoduchých, opakujících se úkolů, jako je například rezervace večeře nebo shromažďování profilových informací, do automatizovaných systémů, které už nemusí vyžadovat přímý zásah člověka. Uživatelé komunikují s robotem prostřednictvím textu, interaktivních karet a řeči. Interakce s takovým robotem může mít podobu rychlé otázky a odpovědi, ale také sofistikovaného rozhovoru, který chytře poskytuje přístup ke službám.

Poznámka:

Podpora funkcí poskytovaných sadou SDK a rozhraním REST API se liší podle kanálu. Robota můžete otestovat pomocí bot Framework Emulatoru, ale měli byste také otestovat všechny funkce robota v každém kanálu, ve kterém chcete robota zpřístupnit.

Interakce zahrnují výměnu aktivit, které se zpracovávají střídavě.

Aktivity

Každá interakce mezi uživatelem (nebo kanálem) a robotem je reprezentována jako aktivita. Schéma aktivity služby Bot Framework definuje aktivity, které je možné vyměňovat mezi uživatelem nebo kanálem a robotem. Aktivity můžou představovat lidský text nebo řeč, oznámení aplikace-aplikace, reakce na jiné zprávy atd.

Otočí

V konverzaci lidé často mluví jednorázově a střídají mluvení. U robota obvykle reaguje na uživatelský vstup. V sadě SDK služby Bot Framework se akce skládá z příchozí aktivity uživatele do robota a jakékoli aktivity, které robot pošle uživateli jako okamžitou odpověď. Otočení si můžete představit jako zpracování přidružené k robotovi, který přijímá danou aktivitu.

Uživatel může například požádat robota, aby provedl určitou úlohu. Robot může odpovědět na otázku, aby získal další informace o úkolu, v jakém okamžiku tento krok končí. V dalším kroku robot obdrží novou zprávu od uživatele, který může obsahovat odpověď na otázku robota, nebo může představovat změnu předmětu nebo žádost o ignorování počátečního požadavku na provedení úkolu.

Struktura aplikace robota

Sada SDK definuje třídu robota, která zpracovává konverzační odůvodnění aplikace robota. Třída robota:

  • Rozpozná a interpretuje vstup uživatele.
  • Důvody týkající se vstupu a provádění relevantních úloh
  • Generuje odpovědi na to, co robot dělá nebo co udělal.

Sada SDK také definuje třídu adaptéru, která zpracovává připojení ke kanálům. Adaptér:

  • Poskytuje metodu pro zpracování požadavků od a metod pro generování požadavků do kanálu uživatele.
  • Zahrnuje kanál middlewaru, který zahrnuje zpracování mimo obslužnou rutinu otáčení robota.
  • Volá obslužnou rutinu otáčení robota a zachytává chyby, které se jinak nezpracují v obslužné rutině otáčení.

Roboti navíc často potřebují načítat a ukládat stav každé z nich. Stav se zpracovává prostřednictvím tříd úložiště, stavu robota a přístupových objektů vlastností. Sada SDK neposkytuje integrované úložiště, ale poskytuje abstrakce úložiště a několik implementací vrstvy úložiště. Téma správy stavu popisuje tyto funkce stavu a úložiště.

A bot has connectivity and reasoning elements, and an abstraction for state

Sada SDK nevyžaduje, abyste k odesílání a příjmu webových požadavků použili konkrétní aplikační vrstvu. Bot Framework obsahuje šablony a ukázky pro ASP.NET (C#), restify (JavaScript) a aiohttp (Python). Pro aplikaci ale můžete použít jinou aplikační vrstvu.

Když vytvoříte robota pomocí sady SDK, zadáte kód pro příjem provozu HTTP a jeho předání adaptéru. Bot Framework poskytuje několik šablon a ukázek, které můžete použít k vývoji vlastních robotů.

Poznámka:

Sady SDK služby Bot Framework JavaScript, C# a Python budou nadále podporovány, ale sada Java SDK se vyřazuje s konečnou dlouhodobou podporou končící v listopadu 2023. V tomto úložišti budou provedeny pouze kritické opravy zabezpečení a chyb.

Stávající roboti sestavení pomocí sady Java SDK budou i nadále fungovat.

Pro nové vytváření robotů zvažte použití Power Virtual Agents a přečtěte si o výběru správného řešení chatovacího robota.

Další informace najdete v tématu Budoucnost vytváření robotů.

Logika robota

Objekt robota obsahuje konverzační důvody nebo logiku pro otáčení a zveřejňuje obslužnou rutinu otáčení, což je metoda, která může přijímat příchozí aktivity z adaptéru robota.

Sada SDK poskytuje několik různých paradigmat pro správu logiky robota.

  • Obslužné rutiny aktivit poskytují model řízený událostmi, ve kterém jsou události typu příchozí aktivity a podtypy. Zvažte obslužnou rutinu aktivity pro roboty, kteří mají omezené krátké interakce s uživatelem.
    • Použijte obslužnou rutinu aktivity a implementujte obslužné rutiny pro každý typ aktivity nebo podtyp, na který robot rozpozná a bude reagovat.
    • Pomocí obslužné rutiny aktivity Teams můžete vytvářet roboty, kteří se můžou připojit k kanálu Teams. (Kanál Teams vyžaduje, aby robot zvládl určité chování specifické pro kanál.)
  • Knihovna dialogových oken poskytuje model založený na stavu pro správu dlouhotrvající konverzace s uživatelem.
  • Implementujte vlastní třídu robota a poskytněte vlastní logiku pro zpracování jednotlivých turnů. Podívejte se například, jak vytvořit vlastní výzvy ke shromáždění uživatelského vstupu.

Adaptér robota

Adaptér má metodu aktivity procesu pro spuštění turnu.

  • Přebírá text požadavku (datovou část požadavku, přeloženou na aktivitu) a hlavičku požadavku jako argumenty.
  • Zkontroluje, jestli je ověřovací hlavička platná.
  • Vytvoří kontextový objekt pro otáčení. Kontextový objekt obsahuje informace o aktivitě.
  • Odešle kontextový objekt prostřednictvím svého middlewarového kanálu.
  • Potom odešle kontextový objekt obslužné rutině objektu robota.

Adaptér také:

  • Formátuje a odesílá aktivity odpovědí. Tyto odpovědi jsou obvykle zprávy pro uživatele, ale mohou také obsahovat informace, které mají být využity přímo kanálem uživatele.
  • Zobrazí další metody poskytované rozhraním REST API robota Připojení oru, jako je například aktualizace zprávy a odstranění zprávy.
  • Zachytává chyby nebo výjimky, které nejsou jinak zachyceny pro otáčení.

Kontext otáčení

Objekt kontextu otáčení poskytuje informace o aktivitě, jako je odesílatel a příjemce, kanál a další data potřebná ke zpracování aktivity. Umožňuje také přidání informací během otáčení mezi různými vrstvami robota.

Kontext otáčení je jednou z nejdůležitějších abstrakcí v sadě SDK. Provádí nejen příchozí aktivitu do všech komponent middlewaru a aplikační logiky, ale také poskytuje mechanismus, kdy komponenty middlewaru a logika robota můžou odesílat odchozí aktivity.

Middleware

Middleware je podobně jako jakýkoli jiný middleware pro zasílání zpráv, který se skládá z lineární sady komponent, které se spouští v daném pořadí, a každý z nich může pracovat s aktivitou. Poslední fází kanálu middlewaru je zpětné volání obslužné rutiny turn u třídy robota, který aplikace zaregistrovala v metodě aktivity procesu adaptéru. Middleware implementuje metodu zapnutí , kterou adaptér volá.

Obslužná rutina otáčení přebírá kontext otáčení jako svůj argument, obvykle logika aplikace spuštěná uvnitř funkce obslužné rutiny turn zpracuje obsah příchozí aktivity a vygeneruje jednu nebo více aktivit v reakci a odešle tyto odchozí aktivity pomocí funkce odeslat aktivitu v kontextu turn. Volání aktivity odesílání v kontextu turn způsobí vyvolání komponent middlewaru u odchozích aktivit. Komponenty middlewaru se spouštějí před a po funkci obslužné rutiny otáčení robota. Provádění je ze své podstaty vnořené a někdy se označuje jako onion.

Téma middlewaru popisuje middleware podrobněji.

Stav robota a úložiště

Stejně jako u jiných webových aplikací je robot ze své podstaty bezstavový. Stav v robotovi se řídí stejnými paradigmaty jako moderní webové aplikace a sada SDK služby Bot Framework poskytuje abstrakce vrstvy úložiště a správy stavu, které usnadňují správu stavu.

Téma správy stavu popisuje tyto funkce stavu a úložiště.

Koncový bod zasílání zpráv a zřizování

Vaše aplikace obvykle potřebuje koncový bod REST, ve kterém budou přijímat zprávy. Bude také potřeba zřídit prostředky pro robota v souladu s platformou, kterou se rozhodnete použít.

Postupujte podle rychlého startu Vytvoření robota a otestujte jednoduchého robota echo.

Podrobnosti PROTOKOLU HTTP

Aktivity přicházejí do robota ze služby Bot Framework Service prostřednictvím požadavku HTTP POST. Robot odpoví na příchozí požadavek POST se stavovým kódem HTTP 200. Aktivity odesílané z robota do kanálu se odesílají do služby Bot Framework Service v samostatném protokolu HTTP POST. To je zase potvrzeno stavovým kódem HTTP 200.

Protokol nezadává pořadí, ve kterém se tyto požadavky POST a jejich potvrzení provádějí. Pro přizpůsobení běžným architekturám služby HTTP, obvykle jsou tyto požadavky vnořené, což znamená, že odchozí požadavek HTTP se provádí z robota v rámci rozsahu příchozího požadavku HTTP. Tento vzor je znázorněn v předchozím diagramu. Vzhledem k tomu, že zpět existují dvě různá připojení HTTP, musí model zabezpečení poskytovat obojí.

Poznámka:

Robot má 15 sekund na potvrzení hovoru se stavem 200 ve většině kanálů. Pokud robot nereaguje do 15 sekund, dojde k chybě HTTP GatewayTimeout (504).

Zásobník zpracování aktivit

Pojďme přejít k předchozímu sekvenčnímu diagramu s fokusem na příchod aktivity zprávy.

Sequence diagram illustrating how an activity is processed by a bot.

V předchozím příkladu robot odpověděl na aktivitu zprávy s jinou aktivitou zprávy obsahující stejnou textovou zprávu. Zpracování začíná požadavkem HTTP POST s informacemi o aktivitě přenesenými jako datová část JSON, která přichází na webový server. Často se ASP.NET projekty používají pro roboty jazyka C# a oblíbená architektura, jako je Express nebo restify, se používá pro roboty JavaScript Node.js.

Adaptér, integrovaná komponenta sady SDK, je jádrem modulu runtime sady SDK. Aktivita se přenáší jako JSON v těle HTTP POST. Tento JSON je deserializován k vytvoření objektu aktivity , který se pak předává adaptéru prostřednictvím jeho metody aktivity procesu . Při příjmu aktivity adaptér vytvoří kontext otáčení a zavolá middleware.

Jak už bylo zmíněno výše, kontext otáčení poskytuje robotovi mechanismus odesílání odchozích aktivit, nejčastěji v reakci na příchozí aktivitu. Kontext otáčení poskytuje metody odezvy aktivity pro odesílání, aktualizaci a odstraňování. Každá metoda odpovědi se spouští v asynchronním procesu.

Důležité

Vlákno, které zpracovává otáčení primárního robota, se zabývá likvidací kontextového objektu po jeho dokončení. Nezapomeňte všechna volání aktivit, await aby primární vlákno čekalo na vygenerovanou aktivitu před dokončením zpracování a vyřazení kontextu turnu. Jinak pokud odpověď (včetně jejích obslužných rutin) trvá nějakou významnou dobu a pokusí se jednat s kontextovým objektem, může se zobrazit chyba, že došlo k chybě.

Šablony robotů

Musíte zvolit aplikační vrstvu, která se používá pro vaši aplikaci; Bot Framework ale obsahuje šablony a ukázky pro ASP.NET (C#), restify (JavaScript) a aiohttp (Python). Dokumentace je napsaná za předpokladu, že používáte některou z těchto platforem, ale sada SDK ji nevyžaduje. Pokyny k přístupu a instalaci šablon najdete v rychlém startu k vytvoření robota .

Robot je webová aplikace a šablony jsou k dispozici pro každou jazykovou verzi sady SDK. Všechny šablony poskytují výchozí implementaci a adaptér koncového bodu. Každá šablona zahrnuje:

  • Zřizování prostředků
  • Implementace koncového bodu HTTP specifická pro jazyk, která směruje příchozí aktivity do adaptéru.
  • Objekt adaptéru
  • Objekt robota

Hlavní rozdíl mezi různými typy šablon je v objektu robota. Šablony jsou:

  • Prázdný robot
    • Obsahuje obslužnou rutinu aktivity, která vítá uživatele v konverzaci odesláním zprávy "hello world" při prvním zapnutí konverzace.
  • Echo Bot
    • Používá obslužnou rutinu aktivity k vítání uživatelů a odezvu vstupu uživatele.
  • Základní robot
    • Spojuje řadu funkcí sady SDK a demonstruje osvědčené postupy robota.
    • Používá obslužnou rutinu aktivity pro vítání uživatelů.
    • Ke správě konverzace se používá dialogové okno komponenty a podřízené dialogy.
    • V dialogových oknech se používají funkce služby Language Understanding (LUIS) a QnA Maker.

Poznámka:

Azure AI QnA Maker bude vyřazený 31. března 2025. Od 1. října 2022 nebudete moci vytvářet nové zdroje ani znalostní báze QnA Maker. Novější verze funkce pro otázky a odpovědi je teď dostupná jako součást jazyka Azure AI.

Vlastní odpověď na otázky, funkce jazyka Azure AI, je aktualizovaná verze služby QnA Maker. Další informace o podpoře otázek a odpovědí v sadě SDK služby Bot Framework najdete v tématu Principy přirozeného jazyka.

Poznámka:

Služba Language Understanding (LUIS) bude vyřazena 1. října 2025. Od 1. dubna 2023 nebudete moct vytvářet nové prostředky LUIS. Novější verze language understanding je teď dostupná jako součást jazyka Azure AI.

Konverzační jazyk understanding (CLU), funkce jazyka Azure AI, je aktualizovaná verze služby LUIS. Další informace o podpoře porozumění jazyku v sadě SDK služby Bot Framework najdete v tématu Principy přirozeného jazyka.

Další informace

Správa prostředků robota

Budete muset spravovat prostředky robota, jako je ID aplikace a heslo, a také informace o všech připojených službách. Když robota nasadíte, bude potřebovat zabezpečený přístup k tomuto informacím. Aby se zabránilo složitosti, většina článků sady SDK služby Bot Framework nepopisuje, jak tyto informace spravovat.

  • Obecné informace o zabezpečení najdete v pokynech zabezpečení služby Bot Framework.
  • Informace o správě klíčů a tajných kódů v Azure najdete v tématu o službě Azure Key Vault.

Adaptéry kanálů

Sada SDK také umožňuje používat adaptéry kanálu, ve kterých adaptér sám provádí úlohy, které by robot Připojení or Service normálně prováděl pro kanál.

Sada SDK poskytuje několik adaptérů kanálu v některých jazycích. Další adaptéry kanálů jsou k dispozici prostřednictvím úložišť Botkit a Community. Další informace najdete v tabulce kanálů a adaptérů v úložišti sady SDK služby Bot Framework.

Rozhraní REST API Připojení or robota

Sada SDK služby Bot Framework se zabalí a staví na rozhraní REST API Připojení oru. Pokud chcete porozumět základním požadavkům HTTP, které podporují sadu SDK, přečtěte si články o ověřování Připojení oru a souvisejících článcích. Aktivity, které robot odesílá a přijímá, odpovídají schématu aktivity služby Bot Framework.

Další kroky