Перейти до основного вмісту
AI-інженерія
12 хв читання

Автономна архітектура Hybrid RAG: браузерний векторний пошук, Generative UI та Next.js 16 SSG

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

AY
Artur Yusupov
Fullstack веб-інженер та AI-розробник
Впроваджено в проєктах:Next.js 16 & Hybrid RAG Portfolio Platform
Автономна архітектура Hybrid RAG: браузерний векторний пошук, Generative UI та Next.js 16 SSG

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.

3. Ключові механізми: як платформа працює під капотом

Механізм 1: Триетапний гібридний пайплайн ранжування (Okapi BM25 + Дамерау-Левенштейн + Косинусна подібність)

Чистий векторний пошук часто помиляється на точних назвах версій (Next.js 16 проти Next.js 14) або власних назвах продуктів (IT-Magic, Unitrition, Fullstack AI Lab). І навпаки, звичайний пошук за підрядком не розуміє концептуальних питань на кшталт *«Як ви оптимізуєте швидкість завантаження на мобільних?»*.

Наш ретривер у src/lib/ai/rag.ts поєднує три математичні сигнали для кожного документа d та запиту Q:

TS
FinalScore(d, Q) = (w_bm25 * BM25(d, Q)) + (w_sem * CosineSimilarity(q, d)) + FieldBoost(d, Q) + ContextBoost(d)
1
Етап 1 - Тримовна токенізація, словник синонімів та виправлення одруківок:

Запит нормалізується через foldForSearch(), очищується від стоп-слів англійської, української та іспанської мов і розширюється через граф доменних синонімів (expandTokens()). Якщо токен не знайдено напряму, алгоритм відстані Дамерау-Левенштейна (distance <= 1 для коротких слів, <= 2 для довших термінів) виправляє друкарські помилки на льоту (наприклад, зіставляє wpskilz із wpskills).

2
Етап 2 - Лексичне ранжування Okapi BM25 (`k1 = 1.5, b = 0.75`):

Кожен фрагмент оцінюється за зворотною частотою документа (IDF) із нормалізацією довжини тексту відносно середньої довжини по базі (avgDocLength):

TS
   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
3
Етап 3 - Косинусна подібність векторів та контекстний бустинг:

Багатовимірні вектори порівнюються через нормалізований скалярний добуток (calculateCosineSimilarity). Якщо відвідувач відкрив чат зі сторінки конкретного проєкту (Active Case Study: IT-Magic), чанки з currentProjectSlug отримують детермінований бонус +18.0 для прицільної точності відповіді.


Механізм 2: Багатоходова пам'ять діалогу та захист від повторів (Conversational State Machine)

Типова проблема простих RAG-ботів - втрата контексту на уточнюючих питаннях (*«А який там був стек?»*, *«Які виклики вирішили?»*) або повторення одного й того самого оглядового абзацу.

У src/lib/ai/rag.ts реалізовано детермінований кінцевий автомат діалогу:

1
Відновлення сутності з історії діалогу (`resolveTargetProject` та `resolveBlogFromQueryOrContext`):

Якщо поточна репліка не містить назви проєкту, рушій сканує options.history у зворотному хронологічному порядку, знаходить активний проєкт або статтю блогу з попередніх повідомлень і автоматично закріплює їх у верхній плашці контексту.

2
Аспектна декомпозиція кейсу (`detectProjectAspects`):

Синтезатор визначає, який саме зріз проєкту цікавить користувача: Стек (technologies), Архітектура (architecture.rows), Виклики та рішення (challenges / solutions), Метрики (detailMetrics) чи Посилання (liveUrl / githubUrl), і видає саме потрібну інженерну секцію.

3
Захист від повторів (`answeredQuestions`):

Усі поставлені питання фіксуються в 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-асистент працюють від єдиного джерела даних:

1
Статична генерація трьома мовами (`app/[locale]/projects/[slug]/page.tsx`):

Під час збірки generateStaticParams() обходить усі 71 проєкт та 9 статей блогу для локалей ['en', 'ua', 'es'], попередньо генеруючи понад 240 статичних HTML-сторінок на Vercel Edge Network.

2
Програмне SEO та динамічна розмітка Schema.org JSON-LD:

Кожен маршрут автоматично формує локалізовані мета-теги, канонічні hreflang-посилання та граф JSON-LD (Person, CreativeWork, TechArticle, BreadcrumbList).

3
Generative Engine Optimization (GEO - `/llms.txt` та `/llms-full.txt`):

Для того щоб зовнішні нейропошуковики (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 є абсолютно безпечною, оскільки захист базується на суворих серверних і клієнтських бар'єрах, а не на приховуванні назв технологій:

1
IP Rate Limiter із обмеженим LRU-кешем пам'яті (`src/lib/ratelimit.ts`):

Ендпоінт POST /api/chat обмежує частоту запитів (15 запитів на годину з одного IP) через Upstash Redis у продакшені та in-memory LRU-сховище з жорстким лімітом у 5 000 записів, що унеможливлює переповнення оперативної пам'яті під час бот-атак.

2
Екран санітизації Prompt Injection (`sanitizeUserPrompt`):

Усі вхідні повідомлення обмежуються за довжиною (до 600 символів) та очищуються від інструкцій перезапису системного промпту (ignore previous instructions, system:, <|im_start|>).

3
Відсутність секретів у клієнтському бандлі та автономний фолбек:

Ключі API (OPENAI_API_KEY) зберігаються виключно в зашифрованих серверних змінних оточення Vercel. Браузер отримує лише публічні кейси портфоліо та математичні функції ранжування.

4
Zero-Trust обфускація контактів у Base64 (`src/utils/contacts.ts`):

Особистий email, телефон, WhatsApp та Telegram ніколи не рендеряться у відкритому HTML або SSR-відповіді - вони декодуються з Base64 виключно під час явної дії користувача в браузері.

Практичне впровадження в коді

Де ця архітектура працює у моєму портфоліо

Ці інженерні рішення не є абстрактною теорією - вони повністю реалізовані та перевірені у наступних робочих продуктах:

Архітектурний аудит

Плануєте міграцію стеку або розробку продукту?

Обговоріть архітектурні вимоги вашого проєкту з інтерактивним RAG AI-асистентом або зв’яжіться напряму для інженерної оцінки.

Написати напряму