---
createdAt: 2025-09-10
updatedAt: 2025-09-10
title: "Створення помічника з документацією на основі RAG (розбиття на фрагменти, ембеддинги та пошук)"
description: "Створення помічника з документацією на основі RAG (розбиття на фрагменти, ембеддинги та пошук)"
keywords:
- RAG
- Документація
- Помічник
- Розбиття на фрагменти
- Ембеддинги
- Пошук
slugs:
- blog
- rag-powered-documentation-assistant
---
# Створення помічника з документацією на основі RAG (розбиття на фрагменти, ембеддинги та пошук)
## Що ви отримаєте
Я створив помічника з документацією на основі RAG і упакував його у boilerplate, який ви можете використати одразу.
- Містить готовий до використання додаток (Next.js + OpenAI API)
- Включає робочий RAG-пайплайн (розбиття на фрагменти, ембеддинги, косинусна схожість)
- Надає повний інтерфейс чат-бота, побудований на React
- Усі UI-компоненти повністю редагуються за допомогою Tailwind CSS
- Реєструє кожний запит користувача, щоб допомогти виявити відсутню документацію, болі користувачів та продуктові можливості
👉 [Жива демонстрація](https://intlayer.org/doc/why) 👉 [Шаблон коду](https://github.com/aymericzip/smart_doc_RAG)
## Вступ
Якщо ви колись губилися у документації, нескінченно гортали в пошуках однієї відповіді, ви знаєте, наскільки це болісно. Документація корисна, але вона статична, і пошук у ній часто здається незручним.
Ось тут і з’являється **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 токенів). Перекриття забезпечує безперервність, щоб ви не втрачали сенс на межах частин.
<p align="center">
<img width="480" alt="Надійне джерело даних" src="https://github.com/user-attachments/assets/ee548851-7206-4cc6-821e-de8a4366c6a3" />
</p>
**Приклад:**
- Chunk 1 → “…стару бібліотеку, яку багато хто забув. Її велетенські полиці були заповнені книгами…”
- Chunk 2 → “…полиці були заповнені книгами з усіх уявних жанрів, кожна шепотіла свої історії…”
Перекриття гарантує, що обидва чанки містять спільний контекст, тож retrieval залишається послідовним.
Цей компроміс (розмір чанка проти перекриття) є ключовим для ефективності RAG:
- Занадто маленький → отримаєте шум.
- Занадто великий → ви перевантажите розмір контексту.
## Крок 3: Генерація embeddings
Як тільки документи розбиті на чанки, ми генеруємо **embeddings** — високорозмірні вектори, що представляють кожний чанк.
Я використовував модель OpenAI’s text-embedding-3-large, але ви можете використати будь-яку сучасну модель embeddings.
**Приклад embedding:**
```js
[
-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 :
```txt
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 :
```txt
Як почати?
```
Ми використовуємо SSE для потокової передачі відповіді з API-роуту.
Як уже згадувалося, ми використовуємо gpt-4-turbo без "thinking" режиму. Відповіді релевантні, а затримки низькі.
Ми експериментували з gpt-5, але затримка була занадто великою (іноді до 15 секунд на відповідь). Проте ми повернемося до цього в майбутньому.
👉 [Спробувати демо тут](https://intlayer.org/doc/why) 👉 [Переглянути шаблон коду на GitHub](https://github.com/aymericzip/smart_doc_RAG)
## Подальші кроки
Цей проєкт — мінімальна реалізація. Але ви можете розширити його багатьма способами:
- 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 — це не просто технічний трюк. Це спосіб трансформувати документацію у:
- інтерактивну систему підтримки
- канал зворотного зв'язку
- інструмент для продуктової стратегії
👉 [Спробуйте демо тут](https://intlayer.org/doc/why) 👉 [Перегляньте шаблон коду на GitHub](https://github.com/aymericzip/smart_doc_RAG)
І якщо ви теж експериментуєте з RAG, мені було б цікаво дізнатися, як ви його використовуєте.
