Vytvorenie Google Gemini AI komponentu v Total.js Flowe

AI je stále veľkou témou tejto doby a každý hľadá spôsob ako by mohol zefektívniť svoju prácu s jej využitím. Preto som sa rozhodol, že pre Vás pripravím jednoduchý návod, ako si vytvoriť v aplikácií od Total.js - Flowe komponentu, práve na komunikáciu s AI. Vytvoríme si jednoduchú komponentu, do ktorej pošleme náš prompt a na výstupe dostaneme odpoveď, kde budeme používať Google Gemini AI.

Inštalácia aplikácie Flow

Inštalácia Flowu je veľmi jednoduchá a návod môžete nájsť priamo v GitHub repozitáry. V prípade potreby si pred pokračovaním pozrite video tutorial, kde krok po kroku vysvetľujem celú inštaláciu (video patrí k sérií o inštalácií Flowu pre IoT platformu, takže stačí prejsť inštaláciou a môžete sa vrátiť k tomuto blogu).

Vytvorenie nového komponentu

Po inštalácií Flowu môžeme rovno začať vytvorením nového komponentu. Preto klikneme na tlačidlo zeleného plus a vyberieme si v menu možnosť "Create component".

Ako môžete vidieť, je tu už preddefinovaná štruktúra pre Flow komponent. Pre jednoduchšie pochopenie si ju rozdelíme na niekoľko logických celkov.

Všeobecné informácie

Ako prvé môžeme vidieť všeobecné informácie, vyplníme si ich a následne ich prejdeme krok po kroku aj s vysvetlením.

    exports.id = 'geminiapi';
    exports.name = 'Gemini API';
    exports.icon = 'ti ti-google';
    exports.author = 'Pavol Danko';
    exports.version = '1';
    exports.group = 'Services';
    exports.config = { apikey: '', model: 'gemini-1.5-flash', output: 'all' };
    exports.inputs = [{ id: 'input', name: 'Input' }];
    exports.outputs = [{ id: 'output', name: 'Output' }, { id: 'error', name: 'Error' }];

Začíname definovaním id, ktoré sme nastavili ako geminiapi, táto hodnota musí byť unikátna pre každý komponent (ak by sme náhodou použili id, ktoré už patrí inému komponentu, tak by sme ho prepísali).

Ďalej máme name, kde je názov nášho komponentu. Pokračujeme s icon, author a version, kde už podľa názvu môžeme vedieť, čo znamenajú.

Pre rozdelenie komponentov v ľavom paneli v našej aplikácií Flow sa používa group, čo nám zaradí náš komponent medzi Services.

Config je veľmi dôležitý, dáta definované v tomto objekte budeme neskôr používať pri nastaveniach nášho komponentu. Sú to vlastne nastavenia, ktoré nechceme priamo natvrdo zadávať do kódu, ale budeme ich môcť meniť v konfigurácií komponentu. To nám zabezpečí, že každý komponent Google Gemini AI použitý v našom Flowstreame môže mať inú konfiguráciu. Môžeme si tu však nastaviť predvolené hodnoty. Napríkad náš apikey si necháme prázdny, model chceme byť schopný meniť. Ako predvolený nastavíme gemini-1.5-flash a output si nastavíme defaultne na all, aby sme na výstupe komponentu dostali celú odpoveď z Google Gemini AI (ak Vám to v tejto chvíli nedáva zmysel, pokračujte ďalej v čítaní, v ďalšej časti sa k tomu vrátime).

Hlavná časť komponentu

V ďalšej časti môžeme vidieť preddefinovaný kód pre časť komponentu exports.make s funkciou instance.message v jej vnútri. V našom prírpade je to všetko, čo potrebujeme pre náš komponent. Nasledujúci kód, ktorý si prejdeme je celý vložený vo funkcii instance.message.

Na konci blogu nájdete link na GitHub repozitár s kompletným kódom.

Vnútro funkcie instance.message si rozdelíme do troch častí.

var data = $.data;

if (!data) {
  $.send('error', 'Input data are missing');
  return;
}

if (!config.apikey) {
  $.send('error', 'You have to configure apikey');
  return;
}

if (data.text)
  data = data.text;

if (typeof data !== 'string') {
  $.send('error', 'Error: Wrong input format');
  return;
}

V tejto prvej časti môžeme vidieť, že sme si prichádzajúce dáta uložili do premennej data.

Následne sme si vytvorili tri podmienky, ktorými kontrolujeme, či máme všetky potrebné dáta, pre poslanie správy do Gemini API. Potrebujeme teda vstupné dáta, API kľúč a jednou podmienkou si zmeníme dáta. Ak nám prichádzajú v objekte, tak ich zmeníme na dátový typ string, ktorý budeme posielať do Gemini API. Ak sa niektorá z našich podmienok vyhodnotí ako pravdivá, tak sa pomocou funkcie $.send odošle definovaná chybová správa na error výstup nášho komponentu.

var obj = {};
obj.contents = [];

var messageParts = [];

messageParts.push({ text: data });

var content = {
  parts: messageParts
};

obj.contents.push(content);

Táto druhá časť sa zameriava len na to, aby sme si vytvorili takú štruktúru dát, ktorú si vyžaduje Google Gemini API na základe ich dokumentácie.

RESTBuilder.POST('https://generativelanguage.googleapis.com/v1beta/models/{0}:generateContent?key={1}'.format(config.model, config.apikey), obj).header('Content-Type', 'application/json').timeout(60000).callback(function (err, response) {
  if (err) {
    $.send('error', err);
    return;
  }

  if (config.output === 'text' && response && response.candidates && response.candidates.length > 0 && response.candidates[0].content && response.candidates[0].content.parts && response.candidates[0].content.parts.length > 0) {
    var textOutput = response.candidates[0].content.parts[0]?.text || '';
    $.send('output', textOutput);
  } else {
    $.send('output', response);
  }
});

Táto časť môže pôsobiť trochu komplikovane, ale v skutočnosti sa jedná len o základný RESTBuilder s metódou POST. Tu sme si následne definovali URL adresu (na základe Google Gemini API dokumentácie) s funkciou na formátovanie stringovej hodnoty, pre lepšiu čitatateľnosť URL adresy.

Následne sme pridali hlavičku s dátami, ktoré vyžaduje API. Timeout sme zvolili s väčšou hodnotou, pretože niekedy trvá dlhší čas, kým sa nám vráti odpoveď.

Ako posledný sme pridali callback, ktorý spracuje odpoveď z Google Gemini API v prípade korektnej, ale aj chybnej odpovede.

V callback funkcií môžeme vidieť dve podmienky. Prvá podmienka zachytáva chybné odpovede prichádzajúce z API volania. Druhú podmienku sme vytvorili kvôli parsovaniu odpovede z API vo formáte, aký si zvolíme (definované v config). V prípade, že chceme na výstupe komponentu len text odpovede, tak najprv zistíme, či sa odpoveď nachádza v odpovedi z API volania a následne si tento text odošleme na výstup komponentu pomocou funkcie $.send. V prípade, že si chceme poslať na výstup kompletnú odpoveď z API volania, tak pôjdeme else vetvou našej podmienky.

Nastavenia

<div class="padding">
  <div class="m">
    <ui-component name="input" path="?.apikey" config="camouflage:1;required:1">API key</ui-component>
    <div class="help"><a href="https://aistudio.google.com/app/apikey" target="_blank"><i class="ti ti-external"></i>Generate Gemini API key</a></div>
  </div>
  <div class="grid-2">
    <div class="m">
      <ui-component name="input" path="?.model" config="dirsource:gemini-pro|Gemini Pro,gemini-1.5-flash|Gemini 1.5 Flash,gemini-1.5-pro|Gemini 1.5 Pro">Gemini Model</ui-component>
    </div>
    <div class="m">
      <ui-component name="input" path="?.output" config="dirsource:all|Full response,text|Only output text">Output Type</ui-component>
    </div>
  </div>
</div>

Ako si isto spomínate na začiatku definovania komponentu sme si pridávali nastavenia do exports.config. Teraz sme teda potrebovali pripraviť pre užívateľa formulár, v ktorom si môže tieto nastavenia upraviť. Ako môžeme vidieť, jedná sa o HTML kód, ktorý sa nám zobrazí po dvojkliku na komponent vložený vo Flowe, alebo po zvolení možnosti Configure v menu.

Vytvorili sme si teda input pre API kľúč, ktorý je povinný a nastavili sme mu takisto kamufláž. Taktiež sme pridali odkaz na URL adresu, kde si užívateľ môže vytvoriť svoj API kľúč pre Google Gemini API. Potom tu máme input pre model s preddefinovanými modelmi, z ktorých si môže užívateľ vybrať (cez rozbaľovacie menu). Posledný input je pre nastavovanie výstupu (taktiež rozbaľovacie menu). Tu si užívateľ môže vybrať, či chce na výstupe komponentu dostať celú odpoveď prijatú z API volania alebo len výsledný text.

Readme

Readme predstavuje text, kde môžeme vložiť informácie o komponente pre užívateľov. Bude tak jednoduchšie pre ostatných pochopiť na čo komponent slúži a ako ho používať.

This component communicates with the Google Gemini API with text inputs and outputs.

Input:

// Object input format for Google Gemini API:
{
    text: String
}

// Or

text: String
For output, you can choose if you need the full response object from Gemini or only the extracted output text.

Google Gemini AI komponent v akcii

Teraz už môžeme prejsť k otestovaniu nášho komponentu. Na to budeme potrebovať ešte dva ďalšie komponenty, ktorými sú Trigger a Print.

V komponente Trigger zadáme správu "Hello, how are you?" a môžeme sledovať, čo sa nám vráti ako odpoveď.

V našom príklade sme použili Flow komponent s konfiguráciou, kde sme zvolili ako model Gemini 1.5 Flash a na výstupe sme chceli dostať len výsledný text odpovede.

Kompletný kód komponentu z príkladu môžete nájsť na mojom GitHube.

Záver

V tomto blogu sme si vytvorili jednoduchý Flow komponent pre komunikáciu s Google Gemini API.

Dúfam, že ste sa naučili niečo nové a rád s Vami budem zdieľať ďalšie poznatky týkajúce sa Total.js.

Video tutorial prvá časť:

Video tutorial druhá časť: