Fáze implementace

6 Fáze implementace AI aplikace

Exponát vznikal postupně v deseti fázích (devět hotových, desátá volitelná). Níže je co přesně se v každé fázi vytvářelo – od prvního hlasového kiosku až po znalostní bázi v MySQL. Chronologii s daty a laděním dokumentace najdete na stránce Historie vývoje. Tři vizuální varianty (základní SVG, animovaná postava Rive, video D-ID) sdílejí jednu konfiguraci, serverovou vrstvu a administraci.

Podrobná časová osa včetně ladění dokumentace (6. 7. 2026 – check, zabezpečení configu): Historie vývoje →

Vícejazyčný režim kiosku (hotovo)

Historie → červen 2026

Přepínač vlajek CS / EN / DE / PL / SK lokalizuje UI, STT, texty z administrace (uvítání, nápověda, omluvy) a odpovědi AI. Texty v adminu zůstávají v češtině. Podrobně: Jazyk exponátu.

Fáze 1 – Základní hlasový exponát (hotovo)

Historie vývoje → červen 2026

Cíl: funkční hlasový průvodce na dotykovém panelu bez složité grafiky – návštěvník mluví, AI odpovídá, odpověď uslyší.

Co se vytvořilo

• Základní varianta exponátu – kiosk rozhraní na celou obrazovku: overlay „Klepněte pro start“ (odemyká audio i mikrofon v prohlížeči), SVG hlava s animací úst při mluvení, stavový řádek, indikátor mikrofonu, vizualizace hlasu (wave bars).
• Hlasový vstup – rozpoznávání řeči přes Web Speech API v Chrome/Edge; jazyk STT z přepínače vlajek na kiosku (CS/EN/DE/PL/SK), záložně z voice_lang v configu; po dokončení věty automatické odeslání dotazu. Viz Jazyk exponátu.
• Serverová vrstva chatu – endpoint pro konfiguraci, chat a TTS; komunikace s Google Gemini API (generateContent); odpovědi v češtině podle system promptu.
• Přečtení odpovědi – Gemini TTS (hlasy Kore, Aoede, Puck…) nebo automatický fallback na hlas prohlížeče při výpadku TTS.
• Režim bez API klíče – místo kiosku návod k doplnění klíče (setup obrazovka).
• Administrace – webové rozhraní s heslem; ukládání do config; sekce pro texty exponátu, AI klíč, hlas, prompt.
• Omluvy při chybě API – místo technické hlášky náhodná přátelská věta; modul sdílený všemi variantami.
• Diagnostika serveru – kontrola PHP, rozšíření, zápisu konfigurace, SSL certifikátů.

Klíčová nastavení (fáze 1)

api_key, tier, model_free / model_paid, welcome_message, kiosk_hint, system_prompt, auto_speak, continuous_listen, barge_in, tts_engine, tts_voice, show_chat, test_mode. Podrobně v kapitole Administrace a konfigurace.

Fáze 2 – Varianta Rive: celá postava (hotovo)

Historie vývoje → červen 2026

Cíl: vertikální kiosk s animovanou postavou na celou výšku obrazovky, vhodný pro muzea a veřejné prostory.

Co se vytvořilo

• Samostatná varianta Rive – stejný hlasový dialog jako základní varianta, ale místo SVG hlavy canvas s Rive animací (@rive-app/canvas).
• Vertikální layout – postava zabírá většinu výšky, ovládání a stav dole; CSS optimalizované pro portrétní 9:16.
• Katalog postav – 10 přednastavených .riv souborů (asistent, maskoti, kočka, pes, mráček, chodec, lip-sync postava…); lokální soubory + CDN záloha.
• Výběr postavy (picker) – tlačítka pod postavou; volba se pamatuje v prohlížeči (localStorage); lze vypnout v administraci.
• Testovací režim – při zapnutí test_mode se pod stavem zobrazí i technická chyba API (pro instalátora); návštěvník vidí stále srozumitelnou omluvu.
• Navigace mezi variantami – přepínání základní / Rive / D-ID bez změny konfigurace.

Klíčová nastavení (fáze 2)

rive_src, rive_state_machine, rive_avatar_picker, rive_avatars (vlastní seznam postav), volitelně názvy animací rive_anim_idle, rive_anim_listen, rive_anim_speak, rive_anim_think, rive_anim_wave.

Fáze 3 – Rive stavy, omluvy teen/klasika, varianta D-ID (hotovo)

Historie vývoje → červen 2026

Cíl: živější reakce postavy na dialog; fotorealistická alternativa pro reprezentativní instalace.

Co se vytvořilo – Rive stavy

• Čtyři režimy avatara – idle (klid), poslouchá, přemýšlí (čeká na AI), mluví; synchronizace s mikrofonem a TTS.
• State Machine – automatické mapování na vstupy Rive (boolean, trigger); detekce animací podle názvu (idle, listen, talk, think, wave).
• Mimika při mluvení – pulz výrazů a opakované spouštění „mluvících“ animací (~280 ms) pro živější dojem.
• Uvítací mávnutí – jednorázová animace po startu exponátu před uvítací zprávou.

Co se vytvořilo – omluvy při chybě

• Dvě sady vět – cca 50 vět v klasickém stylu (vykání) a 50 v teen stylu (tykání, hovorově); výběr sady v administraci (gemini_error_phrase_set).
• Náhodný výběr – bez opakování stejné věty za sebou; při auto_speak se omluva i přečte hlasem.
• Vlastní seznamy – pole gemini_error_phrases_classic, gemini_error_phrases_teen nebo vlastní gemini_error_phrases.
• Strukturované chyby API – rozlišení quota, neplatný klíč, vypnuté API atd. na serveru; návštěvník vidí jen srozumitelnou větu.

Co se vytvořilo – varianta D-ID

• Samostatná varianta D-ID – fotorealistická tvář z fotografie; každá odpověď = krátké video s lip-sync.
• Tok odpovědi – text generuje Gemini (nebo později OpenAI); D-ID Talks API vyrenderuje video + hlas Microsoft neural (české hlasy Vlasta, Antonín…).
• UI – statický poster mezi odpověďmi, video při mluvení, loader „Generuji video avatara…“ (typicky 10–30 s).
• Serverový proxy – samostatný endpoint pro D-ID (config, chat, talk); klíč D-ID nikdy nejde do prohlížeče.
• Setup režim – bez AI klíče nebo bez D-ID klíče návod místo kiosku.

Klíčová nastavení (fáze 3)

gemini_error_phrase_set, did_api_key, did_source_url, did_voice_id, did_presenter_name. Náklady D-ID: D-ID – náklady.

Fáze 4 – ChatGPT (OpenAI) jako druhý provider (hotovo)

Historie vývoje → červen 2026

Cíl: možnost použít firemní OpenAI účet vedle Gemini bez přepisování exponátu.

Co se vytvořilo

• Přepínač providera – ai_provider: gemini nebo openai; chat i TTS směruje podle volby (včetně D-ID varianty).
• OpenAI chat – moduly pro volání OpenAI API; varianty modelu (Instant, Thinking, Pro, vlastní ID); reasoning effort u thinking modelů.
• OpenAI TTS – hlasy alloy, echo, fable, onyx, nova, shimmer; modely tts-1 / tts-1-hd.
• Paralelní uložení klíčů – Gemini i OpenAI klíč mohou být v konfiguraci současně; aktivní je jen zvolený provider.
• Automatický fallback modelu – při selhání primárního OpenAI modelu záložní řetězec (chat-latest, gpt-4o-mini).
• Varování v administraci – detekce špatně umístěného klíče (např. OpenAI klíč v poli Gemini).

Klíčová nastavení (fáze 4)

ai_provider, openai_api_key, openai_model_free, openai_model_paid, openai_model_variant, openai_reasoning_effort, openai_tts_model, openai_tts_voice.

Fáze 5 – Idle režim (prezentace webových stránek) (hotovo)

Historie vývoje → červen 2026 · 6. 7. – doplnění příkladů v návodu

Cíl: při nečinnosti exponát sám „vypráví“ o atrakcích – vhodné pro dlouhodobý provoz v areálu.

Co se vytvořilo

• Idle modul – sdílený JavaScript pro všechny tři varianty; po timeoutu bez interakce spustí prezentaci.
• Seznam stránek – v administraci URL atrakcí a expozic (název + adresa); typicky stránky vaší instituce nebo areálu.
• Stažení a extrakce obsahu – server stáhne HTML, vytáhne titulek, popis, otevírací dobu, stav OTEVŘENO/ZAVŘENO, zajímavosti.
• AI monolog – krátký text 2–4 věty ve zvoleném stylu; endpoint idle_narrate.
• Přehrání – TTS přes aktivní provider; u D-ID varianty záměrně ne D-ID video (úspora kreditů a času).
• Záloha bez AI – při výpadku API se přečte text sestavený přímo ze stránky.
• Ukončení idle – klepnutí, klávesa nebo řeč (≥3 znaky) vrátí běžný dialog.
• Teen styl mluvení – tykání, slang (bro, vibe…); klasický styl vyká a drží klidný tón; dědí z nastavení omluv nebo vlastní prompt.

Klíčová nastavení (fáze 5)

idle_mode_enabled, idle_timeout_seconds (výchozí 120 s), idle_page_seconds (pauza mezi stránkami), idle_pages, idle_allowed_hosts, idle_phrase_set, idle_narrator_prompt.

Fáze 6 – Využití API a statistiky v administraci (hotovo)

Historie vývoje → červen 2026 · první statistiky 2. 7. 2026

Cíl: přehled o spotřebě a stavu klíčů bez ručního logování na webech providerů.

Co se vytvořilo

• Nový layout administrace – postranní menu, sekce na celou šířku (AI & API, Exponát, Hlas, Nečinnost, Avatary, Barvy, Bezpečnost).
• Sekce „Využití API & kredity“ – nad formulářem, živá data mimo odesílání configu.
• Lokální statistiky – zápis každého chat/TTS/idle požadavku do usage-stats; dnes / tento měsíc / celkem (požadavky, tokeny, TTS znaky, odhad USD).
• Probe klíčů – test Gemini, OpenAI a D-ID klíče (OK / quota / billing / chyba); maskovaný náhled klíče.
• OpenAI náklady organizace – volitelně přes openai_admin_api_key oficiální data za 30 dní.
• Tabulka posledních požadavků – čas, provider, akce, model, tokeny, úspěch/chyba.
• Auto-refresh – lokální statistiky každých 15 s, plný refresh včetně probe každých 60 s.

Klíčová nastavení (fáze 6)

openai_admin_api_key (jen pro čtení nákladů v administraci). Plánování provozu: Náklady provozu.

Fáze 7 – Barevné motivy (hotovo)

Historie vývoje → červen 2026

Cíl: jednotný vzhled více stánků / institucí bez úpravy kódu – jen volba palety v administraci.

Co se vytvořilo

• 10 přednastavených motivů – Modrý oceán (výchozí), Smaragd, Rubín, Jantar, Fialka, Ledový cyan, Limetka, Růže, Břidlice, Měď.
• Vlastní paleta – 14 barevných tokenů (pozadí, akcenty, texty, stavy, barvy SVG avatara).
• Injekce CSS proměnných – data-theme na stránce, dynamický blok --bg, --accent, --avatar-glow…
• Jednotný vzhled – základní varianta, Rive, D-ID i administrace čtou stejný motiv z konfigurace.
• Vizuální výběr v administraci – barevné swatche a náhled motivu.

Klíčová nastavení (fáze 7)

theme_preset, theme_customize, theme_colors. Přehled motivů: Barvy a motiv.

Fáze 8 – Katalog Gemini modelů a fallback (hotovo)

Historie vývoje → červen 2026

Cíl: spolehlivý provoz i při změnách modelů u Google – automatické záložní modely a přehled v administraci.

Co se vytvořilo

• Katalog chat modelů – přehledná tabulka v administraci (free / placené, ceny, doporučení pro kiosk).
• Výchozí modely – free gemini-3.5-flash, placený gemini-2.5-pro; TTS gemini-2.5-flash-preview-tts.
• Řetězec fallbacku chatu – při nedostupnosti primárního modelu server zkouší zálohy (např. 3.5 Flash → 2.5 Flash → 3 Flash Preview → 2.5 Flash-Lite).
• Fallback TTS – při chybě nebo quota iterace přes katalog TTS modelů dle tarifu.
• Volba vlastního ID – v administraci lze zadat vlastní název modelu mimo katalog.
• Odpověď API – pole model v odpovědi chatu obsahuje skutečně použitý model (užitečné při ladění).

Klíčová nastavení (fáze 8)

model_free, model_paid, tts_model, tier. Nastavení klíče a profilů: Nastavení Gemini.

Fáze 9 – Znalostní báze exponátů v MySQL (hotovo)

Historie vývoje → 4. 7. 2026

Cíl: ověřená data o exponátech z databáze místo hádání modelu; hlasový průvodce po vlastním katalogu.

Co se vytvořilo

• MySQL katalog – hlavní expozice (idK=0) a exponáty pod sálem v jedné tabulce.
• Vytvoření tabulky z administrace + migrace schématu (AI sloupce, admin_reviewed_at) u starších instalací.
• Katalog v administraci – filtry, + Hlavní expozice / + Exponát, celá šířka obrazovky.
• AI texty – ai_short_desc, descriptionAI; náhled po řádcích, Uložit náhled do databáze nebo Přegenerovat znovu a uložit, zdroje DOVIS → Wikipedia → název (záložní zdroje).
• Tisk katalogu – texty pro hlas a bublinu podle sálu, jedno tiskové okno, tlačítko Zpět zavře okno.
• Označení uložených řádků – zelený řádek a ikona po uložení v adminu (admin_reviewed_at), včetně hromadného uložení.
• Function calling v chatu – exhibit_get, exhibit_search, exhibit_list.

Návod: Znalostní báze exponátů.

Fáze 10 – Volitelné rozšíření

Historie vývoje → plánovaná rozšíření

• Placené TTS bez fallbacku prohlížeče – vynutit pouze Gemini/OpenAI hlas (kvalitnější, ale náchylnější k tichu při výpadku).
• Vlastní Rive postava na míru – export z editoru Rive, vlastní State Machine, branding instituce (maskot, uniforma, barvy).
• HeyGen F – full-body video – realistická postava v celé výšce; není v projektu, API bez free trial, integrace pouze placený vývoj na zakázku (viz Možnosti avatara – HeyGen F).

Co všechny fáze sdílejí