Створення помічника з документацією на основі RAG (розбиття на фрагменти, ембеддинги та пошук)

Що ви отримаєте

Я створив помічника з документацією на основі RAG і упакував його у boilerplate, який ви можете використати одразу.

• Містить готовий до використання додаток (Next.js + OpenAI API)
• Включає робочий RAG-пайплайн (розбиття на фрагменти, ембеддинги, косинусна схожість)
• Надає повний інтерфейс чат-бота, побудований на React
• Усі UI-компоненти повністю редагуються за допомогою Tailwind CSS
• Реєструє кожний запит користувача, щоб допомогти виявити відсутню документацію, болі користувачів та продуктові можливості

👉 Жива демонстрація 👉 Шаблон коду

Вступ

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

Ось тут і з’являється RAG (Retrieval-Augmented Generation). Замість того, щоб змушувати користувачів ритися в тексті, ми можемо поєднати retrieval (пошук потрібних частин документації) з generation (коли LLM природно пояснює їх).

У цій статті я покажу, як я створив чатбот для документації на базі RAG і як він не лише допомагає користувачам швидше знаходити відповіді, а й дає продуктовим командам новий спосіб розуміти болючі точки користувачів.

Чому варто використовувати RAG для документації?

RAG став популярним не випадково: це один із найпрактичніших способів зробити великі мовні моделі дійсно корисними.

Для документації переваги очевидні:

• Миттєві відповіді: користувачі запитують природною мовою і отримують релевантні відповіді.
• Кращий контекст: модель бачить лише найбільш релевантні розділи документації, що зменшує галюцинації.
• Пошук, який відчувається природно: поєднання Algolia + FAQ + чатбот в одному.
• Зворотний зв'язок: зберігаючи запити, ви виявляєте, з чим насправді мають труднощі користувачі.

Той останній пункт є вирішальним. Система RAG не лише відповідає на запитання, вона показує, що саме запитують користувачі. Це означає:

• Ви виявляєте відсутню інформацію в документації.
• Ви бачите появу запитів на нові фічі.
• Ви помічаєте патерни, які можуть навіть спрямовувати продуктову стратегію.

Отже, RAG, це не лише інструмент підтримки. Це також двигун product discovery.

Як працює RAG-пайплайн

У загальних рисах, ось рецепт, який я використав:

1. Розбиття документації на чанки Великі Markdown-файли розбиваються на чанки. Розбиття дозволяє передавати у контекст лише релевантні частини документації.
2. Генерація embeddings Кожен шматок перетворюється на вектор за допомогою embedding API від OpenAI (text-embedding-3-large) або через векторну базу даних (Chroma, Qdrant, Pinecone).
3. Індексація & зберігання Embeddings зберігаються у простому JSON-файлі (для мого демо), але в продакшні ви, ймовірно, використовуватимете векторну БД.
4. Пошук (R у RAG) Запит користувача перетворюється на embedding, обчислюється косинусна схожість, і витягуються топ-найбільш підхожі шматки.
5. Augmentation + Generation (AG у RAG) Ці шматки вставляються в prompt для ChatGPT, тож модель відповідає з урахуванням реального контексту документації.
6. Логування запитів для зворотного зв'язку Кожен запит користувача зберігається. Це золото для розуміння больових точок, відсутньої документації або нових можливостей.

Крок 1: Читання документації

Перший крок був простим: мені потрібно було просканувати папку docs/ на предмет усіх .md файлів. Використовуючи Node.js та glob, я завантажив вміст кожного Markdown-файлу в пам'ять.

Це робить конвеєр гнучким: замість Markdown ви можете отримувати документацію з бази даних, CMS або навіть через API.

Крок 2: Розбиття документації на чанки

Навіщо розбивати? Тому що мовні моделі мають обмеження контексту. Підживлення їх цілою книгою документації не спрацює.

Отже, ідея полягає в тому, щоб розбити текст на керовані частини (наприклад 500 токенів кожна) з перекриттям (наприклад 100 токенів). Перекриття забезпечує безперервність, щоб ви не втрачали сенс на межах частин.

Приклад:

• Chunk 1 → “…стару бібліотеку, яку багато хто забув. Її велетенські полиці були заповнені книгами…”
• Chunk 2 → “…полиці були заповнені книгами з усіх уявних жанрів, кожна шепотіла свої історії…”

Перекриття гарантує, що обидва чанки містять спільний контекст, тож retrieval залишається послідовним.

Цей компроміс (розмір чанка проти перекриття) є ключовим для ефективності RAG:

• Занадто маленький → отримаєте шум.
• Занадто великий → ви перевантажите розмір контексту.

Крок 3: Генерація embeddings

Як тільки документи розбиті на чанки, ми генеруємо embeddings, високорозмірні вектори, що представляють кожний чанк.

Я використовував модель OpenAI’s text-embedding-3-large, але ви можете використати будь-яку сучасну модель embeddings.

Приклад embedding:

[
  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,
  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,
  //...+1533 елементів
];

Кожний вектор, це математичний відбиток тексту, що дозволяє виконувати пошук за схожістю.

Крок 4: Індексування та збереження embeddings

Щоб уникнути багаторазової регенерації embeddings, я зберіг їх у embeddings.json.

У продакшні ви, ймовірно, захочете використовувати векторну базу даних, наприклад:

• Chroma
• Qdrant
• Pinecone
• FAISS, Weaviate, Milvus тощо

Векторні БД обробляють індексування, масштабованість і швидкий пошук. Але для мого прототипу локальний JSON працював добре.

Крок 5: Отримання за допомогою косинусної схожості

Коли користувач ставить запитання:

1. Згенерувати embedding для запиту.
2. Порівняти його з усіма embeddings документа за допомогою косинусної схожості.
3. Залишити лише топ N найбільш схожих chunks.

Косинусна схожість вимірює кут між двома векторами. Ідеальне співпадіння має оцінку 1.0.

Таким чином система знаходить найближчі фрагменти документації до запиту.

Крок 6: Розширення (Augmentation) + Генерація

Тепер починається магія. Ми беремо топові сегменти та вставляємо їх у system prompt для ChatGPT.

Це означає, що модель відповідає так, ніби ці сегменти були частиною розмови.

Результат: точні, відповіді, засновані на документації.

Крок 7: Логування запитів користувачів

Це прихована суперсила.

Кожне поставлене питання зберігається. З часом ви формуєте набір даних із:

• Найчастіших питань (чудово підходить для FAQ)
• Питань без відповіді (документація відсутня або нечітка)
• Запитів на функціональність, замаскованих під питання (“Чи інтегрується це з X?”)
• Нових сценаріїв використання, на які ви не розраховували

This turns your RAG assistant into a continuous user research tool.

Скільки це коштує?

Одне з поширених зауважень щодо RAG, це вартість. Насправді це дивно дешево:

• Генерація embeddings для ~200 документів займає близько 5 хвилин і коштує 1–2 євро.
• Пошук по документації повністю безкоштовний.
• Для запитів ми використовуємо gpt-4o-latest без режиму «thinking». На Intlayer у нас близько 300 запитів у чаті на місяць, і рахунок за OpenAI API рідко перевищує $10.

Крім того, можна додати вартість хостингу.

Деталі реалізації

Стек:

• Монорепозиторій: pnpm workspace
• Пакет документації: Node.js / TypeScript / OpenAI API
• Фронтенд: Next.js / React / Tailwind CSS
• Бекенд: Node.js API route / OpenAI API

Пакет @smart-doc/docs, це пакет на TypeScript, який відповідає за обробку документації. Коли файл Markdown додається або змінюється, пакет містить скрипт build, який перебудовує список документації для кожної мови, генерує embeddings і зберігає їх у файлі embeddings.json.

Для фронтенду ми використовуємо застосунок Next.js, який надає:

• Рендеринг Markdown у HTML
• Рядок пошуку для знаходження релевантної документації
• Інтерфейс чат-бота для запитань щодо документації

Щоб виконати пошук по документації, Next.js-застосунок містить API-рут, який викликає функцію з пакета @smart-doc/docs для отримання фрагментів документації, що відповідають запиту. Використовуючи ці фрагменти, ми можемо повернути список сторінок документації, релевантних до пошуку користувача.

Для функціоналу чатбота ми дотримуємося того ж процесу пошуку, але додатково вставляємо отримані фрагменти документації у промпт, який відправляється до ChatGPT.

Ось приклад промпту, який надсилається в ChatGPT:

System prompt :

You are a helpful assistant that can answer questions about the Intlayer documentation.

Related chunks :

-----
docName: "getting-started"
docChunk: "1/3"
docUrl: "https://example.com/docs/uk/getting-started"
---

# Як почати

...

-----
docName: "another-doc"
docChunk: "1/5"
docUrl: "https://example.com/docs/uk/another-doc"
---

# Ще один документ

...

User query :

Як почати?

Ми використовуємо SSE для потокової передачі відповіді з API-роуту.

Як уже згадувалося, ми використовуємо gpt-4-turbo без "thinking" режиму. Відповіді релевантні, а затримки низькі. Ми експериментували з gpt-5, але затримка була занадто великою (іноді до 15 секунд на відповідь). Проте ми повернемося до цього в майбутньому.

👉 Спробувати демо тут 👉 Переглянути шаблон коду на GitHub

Подальші кроки

Цей проєкт, мінімальна реалізація. Але ви можете розширити його багатьма способами:

• MCP server → перемістити функцію пошуку по документації на MCP-сервер, щоб підключати документацію до будь-якого AI-помічника

• Vector DBs → масштабувати до мільйонів фрагментів документації
• LangChain / LlamaIndex → готові фреймворки для RAG-пайплайнів
• Analytics dashboards → візуалізувати запити користувачів та проблемні місця
• Multi-source retrieval → витягувати не лише документацію, а й записи з баз даних, пости в блогах, тікети тощо.
• Покращені підказки → reranking, filtering та гібридний пошук (ключові слова + семантичний)

Обмеження, з якими ми зіткнулися

• Розбивка на фрагменти (chunking) та перекриття мають емпіричний характер. Пошук правильного балансу (розмір фрагмента, відсоток перекриття, кількість витягнутих фрагментів) вимагає ітерацій та тестування.
• Векторні представлення (embeddings) не оновлюються автоматично при зміні документів. Наша система скидає embeddings для файлу лише якщо кількість фрагментів відрізняється від збереженої.
• У цьому прототипі embeddings зберігаються в JSON. Це підходить для демо, але засмічує репозиторій Git. В продакшні краще використовувати базу даних або спеціалізоване сховище векторів (vector store).

Чому це важливо поза межами документації

Цікаво не лише в чат-боті. Це, механізм зворотного зв'язку (feedback loop).

З RAG ви не просто відповідаєте на запити:

• Ви дізнаєтеся, що плутає користувачів.
• Ви виявляєте, які функції вони очікують.
• Ви адаптуєте свою продуктову стратегію на основі реальних запитів.

Приклад:

Уявіть запуск нової фічі й миттєве бачення:

• 50% запитань стосуються одного й того ж незрозумілого кроку налаштування
• Користувачі неодноразово просять інтеграцію, яку ви ще не підтримуєте
• Люди шукають терміни, що виявляють новий сценарій використання

Це, product intelligence прямо від ваших користувачів.

Висновок

RAG, це один із найпростіших і найпотужніших способів зробити LLMs практичними. Поєднавши retrieval + generation, ви можете перетворити статичну документацію на smart assistant і, одночасно, отримувати безперервний потік insights про продукт.

Для мене цей проєкт показав, що RAG, це не просто технічний трюк. Це спосіб трансформувати документацію у:

• інтерактивну систему підтримки
• канал зворотного зв'язку
• інструмент для продуктової стратегії

👉 Спробуйте демо тут 👉 Перегляньте шаблон коду на GitHub

І якщо ви теж експериментуєте з RAG, мені було б цікаво дізнатися, як ви його використовуєте.