Создание помощника по документации на базе RAG (разбиение на части, эмбеддинги и поиск)

Что вы получите

Я создал помощника по документации на базе RAG и упаковал его в шаблон, который вы можете использовать сразу.

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

👉 Демо в реальном времени 👉 Шаблон кода

Введение

Если вы когда-либо терялись в документации, бесконечно прокручивая в поисках одного ответа, вы знаете, как это может быть мучительно. Документация полезна, но она статична, и поиск по ней часто кажется неудобным.

Вот тут и приходит на помощь RAG (Retrieval-Augmented Generation). Вместо того чтобы заставлять пользователей рыться в тексте, мы можем объединить извлечение (нахождение нужных частей документа) с генерацией (позволяя большой языковой модели объяснять это естественным языком).

В этом посте я расскажу, как я создал чатбот для документации на базе RAG и как он не только помогает пользователям быстрее находить ответы, но и предоставляет командам продукта новый способ понимания болевых точек пользователей.

Почему стоит использовать RAG для документации?

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

Для документации преимущества очевидны:

• Мгновенные ответы: пользователи задают вопросы на естественном языке и получают релевантные ответы.
• Лучший контекст: модель видит только самые релевантные разделы документации, что снижает количество ошибок (галлюцинаций).
• Поиск, который ощущается как человеческий: что-то вроде сочетания Algolia + FAQ + чатбота в одном.
• Обратная связь: сохраняя запросы, вы выявляете, с чем пользователи действительно испытывают трудности.

Этот последний пункт очень важен. Система RAG не просто отвечает на вопросы, она показывает, что именно спрашивают люди. Это значит:

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

Таким образом, RAG — это не просто инструмент поддержки. Это также движок для обнаружения продукта.

Как работает конвейер RAG

В общих чертах, вот рецепт, который я использовал:

1. Разбиение документации на части Большие Markdown-файлы разбиваются на части. Разбиение позволяет предоставлять в качестве контекста только релевантные части документации.
2. Генерация эмбеддингов Каждая часть преобразуется в вектор с помощью API эмбеддингов OpenAI (text-embedding-3-large) или векторной базы данных (Chroma, Qdrant, Pinecone).
3. Индексация и хранение Встраивания сохраняются в простом JSON-файле (для моего демо), но в продакшене вы, скорее всего, будете использовать векторную базу данных.
4. Извлечение (R в RAG) Запрос пользователя преобразуется в вектор, вычисляется косинусное сходство, и извлекаются наиболее подходящие фрагменты.
5. Дополнение и генерация (AG в RAG) Эти фрагменты вставляются в подсказку для ChatGPT, чтобы модель отвечала с учетом реального контекста документации.
6. Логирование запросов для обратной связи Каждый пользовательский запрос сохраняется. Это бесценно для понимания болевых точек, отсутствующей документации или новых возможностей.

Шаг 1: Чтение документации

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

Это сохраняет гибкость конвейера: вместо Markdown вы можете получать документы из базы данных, CMS или даже API.

Шаг 2: Разбиение документации на части

Зачем разбивать? Потому что у языковых моделей есть ограничения по контексту. Передавать им целую книгу документации не получится.

Идея в том, чтобы разбить текст на управляемые части (например, по 500 токенов каждая) с перекрытием (например, 100 токенов). Перекрытие обеспечивает непрерывность, чтобы вы не теряли смысл на границах частей.

Пример:

• Часть 1 → «…старая библиотека, которую многие забыли. Ее высокие полки были заполнены книгами…»
• Часть 2 → «…полки были заполнены книгами из всех мыслимых жанров, каждая шептала свои истории…»

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

Этот компромисс (размер чанка против перекрытия) является ключевым для эффективности RAG:

• Слишком маленький → появляется шум.
• Слишком большой → увеличивается размер контекста.

Шаг 3: Генерация эмбеддингов

После разбиения документов на чанки мы генерируем эмбеддинги — векторы высокой размерности, представляющие каждый чанк.

Я использовал модель OpenAI text-embedding-3-large, но вы можете использовать любую современную модель эмбеддингов.

Пример эмбеддинга:

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

Каждый вектор — это математический отпечаток текста, позволяющий выполнять поиск по сходству.

Шаг 4: Индексация и хранение эмбеддингов

Чтобы избежать многократной генерации эмбеддингов, я сохранил их в файле embeddings.json.

В продакшене вам, скорее всего, понадобится векторная база данных, такая как:

• Chroma
• Qdrant
• Pinecone
• FAISS, Weaviate, Milvus и др.

Векторные базы данных обеспечивают индексацию, масштабируемость и быстрый поиск. Но для моего прототипа локальный JSON отлично подошёл.

Шаг 5: Поиск с помощью косинусного сходства

Когда пользователь задаёт вопрос:

1. Генерируется эмбеддинг для запроса.
2. Сравнивается с эмбеддингами всех документов с использованием косинусного сходства.
3. Оставляются только топ N наиболее похожих чанков.

Косинусное сходство измеряет угол между двумя векторами. Идеальное совпадение оценивается в 1.0.

Таким образом система находит наиболее близкие к запросу фрагменты документа.

Шаг 6: Расширение + Генерация

Теперь начинается магия. Мы берём топ чанков и вставляем их в системный промпт для ChatGPT.

Это означает, что модель отвечает так, как будто эти фрагменты были частью разговора.

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

Шаг 7: Логирование запросов пользователей

Это скрытая суперсила.

Каждый заданный вопрос сохраняется. Со временем вы создаёте набор данных из:

• Наиболее частых вопросов (отлично подходит для FAQ)
• Невыясненных вопросов (документация отсутствует или неясна)
• Запросов на функции, замаскированных под вопросы («Интегрируется ли с X?»)
• Новых сценариев использования, которые вы не планировали

Это превращает вашего RAG-ассистента в инструмент непрерывного исследования пользователей.

Сколько это стоит?

Одно из распространённых возражений против RAG — стоимость. На практике это удивительно дешево:

• Генерация эмбеддингов для ~200 документов занимает около 5 минут и стоит 1–2 евро.
• Функция поиска по документации абсолютно бесплатна.
• Для запросов мы используем gpt-4o-latest без режима «размышления». В 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:

Системная подсказка:

Вы — полезный помощник, который может отвечать на вопросы по документации Intlayer.Связанные фрагменты:-----docName: "getting-started"docChunk: "1/3"docUrl: "https://example.com/docs/ru/getting-started"---# Как начать...-----docName: "another-doc"docChunk: "1/5"docUrl: "https://example.com/docs/ru/another-doc"---# Другой документ...

Запрос пользователя :

Как начать?

Мы используем SSE для потоковой передачи ответа с API маршрута.

Как упоминалось, мы используем gpt-4-turbo без режима "размышления". Ответы релевантны, а задержка низкая. Мы экспериментировали с gpt-5, но задержка была слишком высокой (иногда до 15 секунд на ответ). Однако мы вернемся к этому в будущем.

👉 Попробуйте демо здесь 👉 Посмотрите шаблон кода на GitHub

Дальнейшие шаги

Этот проект является минимальной реализацией. Но вы можете расширить его во многих направлениях:

• MCP сервер → функция поиска по документации на MCP сервер для подключения документации к любому AI-ассистенту

• Векторные базы данных → масштабирование до миллионов фрагментов документации
• LangChain / LlamaIndex → готовые фреймворки для RAG-пайплайнов
• Аналитические панели → визуализация запросов пользователей и проблемных точек
• Многоисточниковый поиск → извлечение не только документов, но и записей из баз данных, блогов, тикетов и т.д.
• Улучшенный prompting → повторная ранжировка, фильтрация и гибридный поиск (ключевые слова + семантика)

Ограничения, с которыми мы столкнулись

• Разбиение на фрагменты и перекрытие эмпиричны. Правильный баланс (размер фрагмента, процент перекрытия, количество извлекаемых фрагментов) требует итераций и тестирования.
• Встраивания (embeddings) не регенерируются автоматически при изменении документации. Наша система сбрасывает встраивания для файла только если количество фрагментов отличается от сохранённого.
• В этом прототипе эмбеддинги хранятся в формате JSON. Это подходит для демонстраций, но засоряет Git. В продакшене лучше использовать базу данных или специализированное хранилище векторов.

Почему это важно не только для документации

Интересная часть — это не просто чат-бот. Это обратная связь.

С RAG вы не просто отвечаете:

• Вы узнаёте, что сбивает пользователей с толку.
• Вы обнаруживаете, какие функции они ожидают.
• Вы адаптируете стратегию продукта на основе реальных запросов.

Пример:

Представьте, что вы запускаете новую функцию и сразу видите:

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

Это продуктовая аналитика прямо от ваших пользователей.

Заключение

RAG — один из самых простых и мощных способов сделать LLM практичными. Объединив извлечение + генерацию, вы можете превратить статичную документацию в умного помощника и одновременно получить непрерывный поток инсайтов о продукте.

Для меня этот проект показал, что RAG — это не просто технический трюк. Это способ преобразовать документацию в:

• интерактивную систему поддержки
• канал обратной связи
• инструмент для продуктовой стратегии

👉 Попробуйте демо здесь 👉 Посмотрите шаблон кода на GitHub

Если вы тоже экспериментируете с RAG, мне было бы интересно узнать, как вы его используете.