---
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-пайплайн

![RAG-пайплайн](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)

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

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, мені було б цікаво дізнатися, як ви його використовуєте.
