Автономна архітектура Hybrid RAG: браузерний векторний пошук, Generative UI та Next.js 16 SSG
Повний архітектурний розбір платформи yusupovartur.com: проєктування Hybrid RAG-асистента за 5 мс (Okapi BM25 + Дамерау-Левенштейн + косинусна подібність), багатоходової пам'яті діалогу, віджетів Generative UI та 213+ статичних маршрутів Next.js 16 без витрат на векторні БД.

1. Резюме для керівників (Executive Summary): Антипатерн хмарних векторних БД
Протягом останніх двох років індустрія просувала єдину догму: *щоб створити AI-асистента на базі RAG, обов'язково потрібна підписка на Pinecone, Weaviate або Qdrant, окремий мікросервіс ембедингів і мережеві запити на кожне повідомлення користувача.*
Для корпоративних систем із мільйонами юридичних чи медичних документів це виправдано. Проте для інженерних портфоліо, порталів документації та продуктових баз знань обсягом до 10 000 документів це архітектурний надлишок:
- Податок на затримку (Latency Tax): Кожен мережевий запит до зовнішньої векторної БД додає 150-400 мс затримки ще до початку генерації відповіді.
- Фінансовий податок (Cost Tax): Керовані векторні бази коштують $70-$250 на місяць у базових тарифах просто за зберігання індексу.
- Точка відмови (Single Point of Failure): Якщо зовнішній сервіс недоступний або вичерпано ліміт токенів, асистент на сайті повністю перестає працювати.
Проєктуючи флагманську платформу Next.js 16 & Hybrid RAG Portfolio Platform (`yusupovartur.com`), ми створили автономний рушій Hybrid RAG, який працює одночасно на Vercel Edge та безпосередньо в браузері, індексуючи 71 кейс проєктів та 9 інженерних статей трьома мовами (EN, UA, ES) менш ніж за 5 мс із нульовими щомісячними витратами на бази даних.
2. Ключові архітектурні рішення (ADR)
| Архітектурне рішення | Розглянута альтернатива | Чому обрано цей шлях (Аналіз компромісів) |
|---|---|---|
| In-Memory індекс під час збірки (Okapi BM25 + прекомпільовані вектори) | Хмарна векторна БД (Pinecone / Qdrant) | Усуває 150-400 мс мережевої затримки та $70+/міс абонплати. Уся база знань (80+ чанків) пакується в лінивий чанк (22.1 КБ gzip). |
| Дворежимне виконання (`/api/chat` стрімінг + автономний клієнтський фолбек) | Лише серверний LLM-ендпоінт | На yusupovartur.com відповіді стрімляться через POST /api/chat. При втраті мережі, перевищенні лімітів або роботі на статичному хостингу клієнт миттєво синтезує точну відповідь локально без екранів помилок. |
| Детермінований класифікатор 7 інтентів (`detectQueryIntent`) | Маршрутизація лише через LLM | Класифікує запит за < 0.2 мс у 7 категорій (project-aspect, blog, service, profile, contact, methodology, general), щоб активний проєкт не перехоплював загальні питання про ціни чи контакти. |
| Оркестрація Generative UI всередині чату | Звичайні текстові відповіді Markdown | Динамічно монтує інтерактивні React 19 компоненти (ProjectToolCard, StackComparisonCard, ProjectEstimateCalculatorCard, ContactActionCard) прямо в повідомлення бота. |
| Єдиний реєстр даних `projectRegistry` (Single Source of Truth) | Дублювання JSON / окрема CMS | Один суворо типізований реєстр TypeScript одночасно живить generateStaticParams (240+ SSG-сторінок), мікророзмітку Schema.org, файл llms-full.txt та внутрішню базу знань RAG. |
22.1 КБ gzip).yusupovartur.com відповіді стрімляться через POST /api/chat. При втраті мережі, перевищенні лімітів або роботі на статичному хостингу клієнт миттєво синтезує точну відповідь локально без екранів помилок.project-aspect, blog, service, profile, contact, methodology, general), щоб активний проєкт не перехоплював загальні питання про ціни чи контакти.ProjectToolCard, StackComparisonCard, ProjectEstimateCalculatorCard, ContactActionCard) прямо в повідомлення бота.generateStaticParams (240+ SSG-сторінок), мікророзмітку Schema.org, файл llms-full.txt та внутрішню базу знань RAG.3. Ключові механізми: як платформа працює під капотом
Механізм 1: Триетапний гібридний пайплайн ранжування (Okapi BM25 + Дамерау-Левенштейн + Косинусна подібність)
Чистий векторний пошук часто помиляється на точних назвах версій (Next.js 16 проти Next.js 14) або власних назвах продуктів (IT-Magic, Unitrition, Fullstack AI Lab). І навпаки, звичайний пошук за підрядком не розуміє концептуальних питань на кшталт *«Як ви оптимізуєте швидкість завантаження на мобільних?»*.
Наш ретривер у src/lib/ai/rag.ts поєднує три математичні сигнали для кожного документа d та запиту Q:
FinalScore(d, Q) = (w_bm25 * BM25(d, Q)) + (w_sem * CosineSimilarity(q, d)) + FieldBoost(d, Q) + ContextBoost(d)Запит нормалізується через foldForSearch(), очищується від стоп-слів англійської, української та іспанської мов і розширюється через граф доменних синонімів (expandTokens()). Якщо токен не знайдено напряму, алгоритм відстані Дамерау-Левенштейна (distance <= 1 для коротких слів, <= 2 для довших термінів) виправляє друкарські помилки на льоту (наприклад, зіставляє wpskilz із wpskills).
Кожен фрагмент оцінюється за зворотною частотою документа (IDF) із нормалізацією довжини тексту відносно середньої довжини по базі (avgDocLength):
const idf = Math.log(1 + (totalDocs - docFreq + 0.5) / (docFreq + 0.5))
const tfNorm = (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (docLength / avgDocLength)))
bm25Score += idf * tfNormБагатовимірні вектори порівнюються через нормалізований скалярний добуток (calculateCosineSimilarity). Якщо відвідувач відкрив чат зі сторінки конкретного проєкту (Active Case Study: IT-Magic), чанки з currentProjectSlug отримують детермінований бонус +18.0 для прицільної точності відповіді.
Механізм 2: Багатоходова пам'ять діалогу та захист від повторів (Conversational State Machine)
Типова проблема простих RAG-ботів - втрата контексту на уточнюючих питаннях (*«А який там був стек?»*, *«Які виклики вирішили?»*) або повторення одного й того самого оглядового абзацу.
У src/lib/ai/rag.ts реалізовано детермінований кінцевий автомат діалогу:
Якщо поточна репліка не містить назви проєкту, рушій сканує options.history у зворотному хронологічному порядку, знаходить активний проєкт або статтю блогу з попередніх повідомлень і автоматично закріплює їх у верхній плашці контексту.
Синтезатор визначає, який саме зріз проєкту цікавить користувача: Стек (technologies), Архітектура (architecture.rows), Виклики та рішення (challenges / solutions), Метрики (detailMetrics) чи Посилання (liveUrl / githubUrl), і видає саме потрібну інженерну секцію.
Усі поставлені питання фіксуються в answeredQuestions, завдяки чому getContextualFollowUps() динамічно пропонує лише нові, ще не розглянуті аспекти проєкту.
Механізм 3: Оркестрація Generative UI всередині потоку чату
Замість того щоб повертати лише суцільний текст, ChatModal.tsx аналізує інтент запиту паралельно з відповіддю RAG і вбудовує живі інтерактивні компоненти React 19 прямо всередину бульбашки повідомлення асистента:
- `ProjectToolCard` (`getRelevantProjectCards`): Візуальні картки знайдених кейсів із WebP-прев'ю, категорією, топ-4 технологіями та кнопками переходу до повного кейсу або живого сайту.
- `StackComparisonCard` (`isStackComparisonQuery`): Активується при запитах *«Next.js чи WordPress»* або *«Який стек обрати?»*. Відображає інтерактивну таблицю з перемиканням вкладок (TCO, швидкість запуску, Core Web Vitals, сценарії використання) для Next.js 16, Headless WP та Custom PHP.
- `ProjectEstimateCalculatorCard` (`isEstimateOrCalculatorQuery`): Інтерактивний калькулятор термінів та фаз розробки, де клієнт може прямо в чаті змінювати тип продукту, масштаб і наявність AI-модулів.
- `ContactActionCard` (`isHireOrContactQuery`): Картка прямого зв'язку з клієнтським розшифруванням Base64-контактів (Email, WhatsApp, Telegram, LinkedIn) та завантаженням CV у PDF.
Механізм 4: Синхронізація з Next.js 16 App Router (213+ SSG-маршрутів) та GEO (llms.txt)
Оскільки ця стаття є головним архітектурним розбором платформи `yusupovartur.com`, важливо показати, як веб-платформа та AI-асистент працюють від єдиного джерела даних:
Під час збірки generateStaticParams() обходить усі 71 проєкт та 9 статей блогу для локалей ['en', 'ua', 'es'], попередньо генеруючи понад 240 статичних HTML-сторінок на Vercel Edge Network.
Кожен маршрут автоматично формує локалізовані мета-теги, канонічні hreflang-посилання та граф JSON-LD (Person, CreativeWork, TechArticle, BreadcrumbList).
Для того щоб зовнішні нейропошуковики (ChatGPT Search, Perplexity, Claude, Google AI Overviews) цитували точні інженерні факти про портфоліо Артура Юсупова, у корені домену опубліковані структуровані файли за стандартом llms.txt 2026 року.
4. Інженерний глосарій: пояснення кожного терміна простими словами
- Hybrid RAG (Retrieval-Augmented Generation):
- *Що це:* Поєднання точного ключового пошуку (Okapi BM25) із семантичним пошуком за векторними ембедингами (Cosine Similarity) перед формуванням відповіді AI.
- *Чому це важливо:* Повністю виключає галюцинації та гарантує 100% точність у назвах проєктів, метриках і версіях технологій.
- Okapi BM25 (Best Matching 25):
- *Що це:* Ймовірнісна формула ранжування пошукових систем, яка оцінює релевантність документа за частотою рідкісних ключових слів із поправкою на довжину тексту.
- *Чому це важливо:* Гарантує, що специфічні терміни (
WPGraphQL,useSyncExternalStore,IT-Magic) миттєво піднімають потрібний кейс на перше місце. - Відстань Дамерау-Левенштейна (Damerau-Levenshtein Distance):
- *Що це:* Алгоритм вимірювання схожості рядків, який рахує мінімальну кількість вставок, видалень, замін або переставлень сусідніх символів для перетворення одного слова на інше.
- *Чому це важливо:* Забезпечує стійкість пошуку та AI-асистента до людських одруківок без сторонніх серверів.
- Косинусна подібність (Cosine Similarity):
- *Що це:* Математичне обчислення косинуса кута між двома багатовимірними векторами для вимірювання близькості змісту незалежно від довжини тексту.
- *Чому це важливо:* Дозволяє асистенту розуміти суть запитання англійською, українською та іспанською мовами менш ніж за 2 мс.
- Generative UI:
- *Що це:* Патерн проєктування AI-інтерфейсів, де асистент відповідає не лише текстом, а й динамічним рендерингом інтерактивних віджетів (калькуляторів, таблиць порівняння, карток проєктів) прямо в діалозі.
- *Чому це важливо:* Перетворює чат-бота на повноцінний інструмент B2B-конверсії та кваліфікації замовлень.
5. Ешелонована архітектура безпеки (Defense-in-Depth)
Публікація повного розбору архітектури yusupovartur.com є абсолютно безпечною, оскільки захист базується на суворих серверних і клієнтських бар'єрах, а не на приховуванні назв технологій:
Ендпоінт POST /api/chat обмежує частоту запитів (15 запитів на годину з одного IP) через Upstash Redis у продакшені та in-memory LRU-сховище з жорстким лімітом у 5 000 записів, що унеможливлює переповнення оперативної пам'яті під час бот-атак.
Усі вхідні повідомлення обмежуються за довжиною (до 600 символів) та очищуються від інструкцій перезапису системного промпту (ignore previous instructions, system:, <|im_start|>).
Ключі API (OPENAI_API_KEY) зберігаються виключно в зашифрованих серверних змінних оточення Vercel. Браузер отримує лише публічні кейси портфоліо та математичні функції ранжування.
Особистий email, телефон, WhatsApp та Telegram ніколи не рендеряться у відкритому HTML або SSR-відповіді - вони декодуються з Base64 виключно під час явної дії користувача в браузері.
Де ця архітектура працює у моєму портфоліо
Ці інженерні рішення не є абстрактною теорією - вони повністю реалізовані та перевірені у наступних робочих продуктах:
Плануєте міграцію стеку або розробку продукту?
Обговоріть архітектурні вимоги вашого проєкту з інтерактивним RAG AI-асистентом або зв’яжіться напряму для інженерної оцінки.
Інші інженерні статті
Next.js 16 проти Headless WordPress та Custom PHP: об’єктивний аналіз TCO, продуктивності та SEO (2026)
Інженерний аналіз архітектури, витрат на підтримку (TCO) та показників Google Core Web Vitals для Next.js 16, Headless WordPress та кастомного PHP.
Повний розбір архітектури Fullstack AI Lab: компіляція 1 135+ MDX-уроків за 90 секунд на Next.js 16 та Rust MDX-RS
Повний технічний та архітектурний розбір інтерактивної освітньої платформи Fullstack AI Lab: як ми прискорили статичну збірку у 14 разів (із 21.6 хв до 1.5 хв), створили браузерну WebAssembly-пісочницю WordPress, симулятор AI-співбесід, інтерактивні симулятори рантайму та аудіогенератор для NotebookLM.