Как сделать AI-ассистента по своей документации: что работает, что нет

Представьте: у вашей компании есть документация. Инструкции, регламенты, база знаний поддержки, техпаспорта продукта. Сотни страниц. И есть люди — клиенты, сотрудники, партнёры, — которые должны всё это читать, но не читают. Кто-то пишет в поддержку и ждёт ответ. Кто-то звонит вашему менеджеру. Кто-то просто решает, что вашим продуктом пользоваться сложно, и уходит к конкуренту.

Знакомо? Мы видим это у клиентов постоянно — особенно там, где продукт сложный: медицинское оборудование, промышленные станки, enterprise-софт. Поэтому мы собрали AI-ассистента для пользователей УЗ-сканеров Samsung: живая документация на 1 000+ страниц, которая теперь отвечает на вопросы как человек. Как устроен этот проект — отдельный разбор. А тут я объясню на пальцах, как это вообще работает и стоит ли делать вам.

Зачем вообще AI-ассистент, если есть поиск

Начну с неудобного вопроса. У вас наверняка уже есть поиск по документации — на сайте, в Confluence, в PDF. Зачем тогда AI?

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

Второе. Обычный поиск возвращает ссылки — «вот вам 40 документов, читайте». Человек приходил с вопросом, а получил домашку. AI даёт готовый ответ в двух предложениях, да ещё и со ссылкой на источник, если надо проверить.

Третье. AI отвечает в мессенджере, в чате на сайте, в голосе — везде, где удобно клиенту. Поиск живёт только там, где вы его поставили.

Короткий ответ на вопрос «зачем»: если к вам с одним и тем же вопросом обращаются больше десяти человек в неделю, и ответ есть в документах, — AI-ассистент окупится. Быстро.

Что такое RAG — на одном примере

Эту штуку называют по-английски RAG. Расшифровка — Retrieval-Augmented Generation, «генерация с подгрузкой контекста». Но смысл проще: AI сначала находит нужный кусок в вашей документации, потом на его основе пишет ответ. Не выдумывает.

Сравните с обычным ChatGPT. Его спросили: «У меня на УЗИ-сканере Samsung HS60 не запускается эластография, что делать?» ChatGPT что-то напишет — возможно, правдоподобное, возможно, вообще мимо. Он не знает вашу инструкцию. Он отвечает «в среднем по интернету».

Теперь тот же вопрос в RAG-ассистенте:

1. Система берёт вопрос.
2. Находит в вашей инструкции кусок про эластографию на HS60.
3. Передаёт этот кусок в AI вместе с вопросом: «вот документация, вот вопрос, ответь строго по ней».
4. AI формулирует ответ: «На HS60 эластография запускается клавишей X. Если не загорается — проверьте пункт Y в разделе Z инструкции».

Всё. Никаких «а может быть такое, что…». Только то, что есть в вашей документации. Это принципиально — именно поэтому RAG безопасно ставить в медицинский или юридический контекст, где цена выдуманного ответа очень высокая.

Когда RAG нужен, а когда это лишнее

Ключевой вопрос перед стартом — а надо ли оно вообще. Разобью на три случая.

Случай 1 — RAG точно окупится. Большая база (сотни страниц и больше). Регулярные вопросы одних и тех же типов. Есть люди, которым дорого отвечать (поддержка, менеджеры) или у которых это отвлекает от основной работы (инженеры, методисты). Документация часто обновляется — версии продукта, новые модели, регламенты.

Случай 2 — сначала подумайте, потом делайте. Документация влезает в одну книжку (меньше 200 страниц). Вопросов немного, и они нетиповые. В таком объёме современные AI вроде Claude Sonnet умеют держать всё в «памяти» и отвечать без всякого поиска — дешевле и проще. Это, кстати, официальная рекомендация Anthropic [1]: для маленьких баз есть более лёгкие способы, чем RAG.

Случай 3 — RAG не поможет. Если у вас вопросы не про факты, а про решения («что мне выбрать», «какая стратегия»), — RAG не про это. Он достаёт из документов то, что там написано. Рассуждать за клиента он не должен и не умеет безопасно.

Тут часто путают RAG с «обучением AI под свою компанию» (это называется fine-tuning). Разница большая. Fine-tuning меняет манеру AI — стиль речи, формат ответов, tone of voice. RAG даёт AI факты. Если вы хотите, чтобы ассистент отвечал цитатами из вашей инструкции, fine-tuning не поможет: он научит модель «говорить как ваша инструкция», но выдумывать содержание. Это классическая ошибка, на которой сгорают бюджеты.

Из чего собирается такая система

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

Шаг 1. Загрузка документов. Берём ваши PDF, Word, Confluence, Notion — и переводим в обычный текст. Звучит скучно, но 30% проблем в проектах начинаются тут: в PDF таблицы превращаются в кашу, картинки теряются, сноски перемешиваются. Поэтому на этом шаге нужны руки, а не готовая кнопка.

Шаг 2. Нарезка на кусочки. AI не может переварить инструкцию целиком — слишком длинная. Поэтому её режут на куски примерно по страничке-полстраничке. Называется это «чанкинг». Важно резать по смыслу: чтобы описание процедуры не разорвало на пункте 3 из 7, и чтобы заголовок «Эластография» не оторвался от содержания. Pinecone (это один из известных вендоров vector search) подробно разбирает рабочие стратегии нарезки [2] — мы используем их как отправную точку.

Шаг 3. Превращение в числа. Каждый кусочек документации переводится в длинный список чисел — это называется «эмбеддинг». Звучит абстрактно, но суть понятная: компьютер умеет быстро сравнивать числа, а не буквы. Два кусочка текста «про одно и то же» получают похожие числа. Когда приходит вопрос — его тоже переводят в числа и ищут кусочки с похожими.

Шаг 4. Поиск. Система берёт вопрос, переводит в числа, находит 10–20 самых близких кусочков в вашей документации. Это секунды.

Шаг 5. Ответ. Эти кусочки вместе с вопросом уходят в AI (в нашем случае — Claude), и тот формулирует читаемый ответ. С установкой «не придумывай, отвечай только по документам».

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

Где ошибаются 9 из 10 команд

Здесь интересное. По нашему опыту (и по публикациям сильных инженерных команд), типовые ошибки — одни и те же.

Ошибка 1. Нарезка «как получится»

Команда берёт готовый инструмент, выставляет «куски по 500 символов», и всё. Для новостной ленты это нормально. Для инструкции — катастрофа. Параметр «частота 3,5 МГц» попадает в один кусок, «для абдоминального сканирования» — в следующий. Вопрос «какая частота для живота» не находит ни одного.

Как делаем мы: режем по структуре документа — разделы, подразделы, шаги процедур. Заголовок всегда остаётся со своим содержанием. Перекрытие между соседними кусками 15–20% — чтобы ничего не терялось на границах. Для сложных документов пробуем «умную нарезку» по смыслу предложений — это повышает точность ещё на 5–10%.

Ошибка 2. Одна система поиска вместо двух

Самая частая. Есть два способа искать в тексте. Один — по смыслу (те самые эмбеддинги, «числа»). Второй — по точным словам (старый добрый поиск по вхождению). Оба нужны. Поиск по смыслу не находит артикулы вроде «SN-12345» или коды ошибок. Поиск по словам не понимает синонимов.

Индустрия называет это «гибридный поиск», и ещё в 2020-м Pinecone показали [5], что два алгоритма вместе дают на 10–20% лучше результата, чем любой из них по отдельности. Мы всегда ставим оба параллельно и объединяем результаты. Это одно из самых дешёвых улучшений, которое почему-то многие пропускают.

Ошибка 3. Нет «второго фильтра»

После поиска система возвращает, скажем, 20 самых близких кусочков. Но близких — не значит подходящих. Свежий приём: поверх результатов поиска поставить реранкер — отдельную модель, которая читает пару «вопрос ↔ кусочек текста» целиком и говорит, насколько они реально связаны. Плюс ещё 15–30% к точности [6]. Наш выбор обычно — Cohere Rerank, ставится одной кнопкой, стоит копейки.

Ошибка 4. AI галлюцинирует, несмотря на документы

Это особенно больно в медтехе и юриспруденции. Модели обучены быть полезными — они всегда что-то отвечают. Даже если в документах ответа нет. Решается это жёстким системным промптом — инструкцией, которую AI получает в самом начале:

Отвечай только на основании предоставленных документов.
Если ответа в них нет — ответь дословно:
«В предоставленной документации нет ответа на этот вопрос».
Перед ответом приведи цитату из документа, на которой строится ответ.

Выглядит примитивно. Работает хорошо. У Anthropic есть отдельная страница документации [7] про то, как снижать галлюцинации — все их рекомендации мы используем. У OpenAI похожий гайд [8] — паттерны одни и те же.

Ошибка 5. Индекс построен один раз и забыт

Система запустилась, показала отличные ответы в первую неделю, потом качество тихо поехало. Причина — документация меняется, а индекс не обновляется. Или у AI поменялась версия, и она перестала хорошо работать со старыми настройками. Это нормальный проектный риск, но его надо предусмотреть на старте: мониторинг качества ответов, обновление индекса по расписанию, обратная связь от пользователей («ответ помог / нет»).

Ошибка 6. Никто не знает, хорошо ли оно работает

Самая скрытая ошибка. Ассистент отвечает, пользователи вроде пишут — а метрики качества никто не смотрит. Есть открытый стандарт проверки таких систем — RAGAS [9]. Четыре основных метрики: насколько ответ опирается на документы, насколько он отвечает на вопрос, насколько точно найдены нужные куски, насколько полно. Минимум — взять 50–100 реальных вопросов и прогнать систему через них раз в неделю. Без этого вы летите вслепую.

Один приём, который удивительно дёшев и сильно помогает

Про него стоит рассказать отдельно. В сентябре 2024-го инженеры Anthropic опубликовали [1] простую идею с громкими цифрами. Перед тем как класть каждый кусок документации в индекс, они просят AI написать короткое описание: «вот этот кусок — про такой-то аспект такого-то документа». Это описание пришивается к куску и кладётся в индекс вместе с ним.

Эффект: поиск перестаёт промахиваться на 35% чаще (тест Anthropic). Если этот трюк совместить со всеми предыдущими (гибридный поиск, реранкер), промахи сокращаются в 3,5 раза. Стоит эта контекстуализация — около доллара на каждый миллион токенов документа при использовании экономичной модели Claude Haiku. Это единовременная трата при индексации. На базу на 1 000 страниц вы потратите один-два доллара. Сотые доли процента от бюджета проекта.

Почему это так хорошо работает? Потому что обычный кусок документации, вырванный из контекста, часто непонятен даже человеку («…нажмите кнопку X…» — на каком экране? в каком режиме?). AI, который «видит» кусок с поясняющим контекстом, находит его в ответ на запрос гораздо точнее.

Это хороший пример того, как нужно следить за англоязычными первоисточниками. Русские статьи про AI часто отстают на полгода-год. Мы читаем Anthropic, OpenAI, Cohere, Pinecone напрямую — поэтому можем такие приёмы внедрять сразу, а не через полтора года.

Что можно сделать самому, а где нужен инженер

Честный разбор. Самому можно: собрать прототип на n8n или LangChain за пару выходных, подключить OpenAI и векторную базу, прогнать на своей документации, посмотреть «работает / не работает». Это хорошая проверка гипотезы — стоит ли вкладываться дальше. Если у вас есть технически подкованный сотрудник и не-очень-ответственный домен — может и прототипа хватит.

Инженер нужен, когда система уходит в продакшн. Почему:

• Документы меняются — надо автоматически обновлять индекс, без простоя.
• Запросов становится больше — надо следить за стабильностью, откликами, расходом на AI.
• Появляются сложные случаи — диаграммы, таблицы, сноски, мультиязычность. Прототип тут рассыпается.
• В медицине/финансах/юриспруденции нужна проверка качества, логи, аудит ответов.
• Нужно интегрировать с вашим сайтом, CRM, Telegram, дилерским порталом. У нас в кейсе с Samsung один и тот же ассистент живёт в Telegram и готов к встраиванию в сайт — это архитектура, а не разовая настройка.

Коротко: прототип — легко, продакшн — инженерная работа. И продакшн — это там, где начинается экономика проекта. Плохо сделанный RAG-ассистент стоит вам доверия клиентов каждый день. Хорошо сделанный — экономит сотни часов в месяц на поддержке.

Отдельная история — российский контекст

Три вещи, про которые обычно вспоминают последними, а надо — первыми.

VPN не вариант. Большинство сильных AI-моделей (OpenAI, Anthropic, Cohere, Voyage) заблокированы по IP из России. Ставить клиентов перед необходимостью включать VPN — значит хоронить проект. Решение — поставить сервер-посредник за границей, через который ходят запросы. Пользователь об этом ничего не знает, VPN ему не нужен. Это архитектура, которую мы закладываем с нулевого дня; в кейсе с Samsung именно так и сделано.

Русский язык в «числовом представлении». Не все модели эмбеддингов одинаково хорошо работают с русским. Большинство тренировались преимущественно на английском. Мы выбираем те, что специально хорошо понимают русский — Cohere или open-source модель от Microsoft. Разница в качестве существенная, особенно на медицинской и технической лексике.

Термины и аббревиатуры. «УЗД», «ЛПО», «BI-RADS», «допплер» — если система этого не понимает, ассистент становится бесполезным. Решается на этапе настройки: словарь синонимов, подсказки для AI, иногда — лёгкий fine-tuning. Это не магия, но про это нужно думать, а не надеяться, что «AI сам разберётся».

С чего начать, если решили делать

Простой план на первые 2–3 недели:

1. Соберите 50 настоящих вопросов. Возьмите тикеты поддержки за месяц. Это ваш эталон — на чём система будет проверяться.
2. Подготовьте документы. PDF → чистый текст. Таблицы — в структурированный формат. Один день, один человек.
3. Соберите прототип. Любой базовый пайплайн из шести кубиков: ingest → chunking → embedding → search → LLM. Даже на n8n + Supabase (как у нас) — запускается за неделю.
4. Прогоните на 50 вопросах. Посчитайте, на скольких ответ верный, на скольких «в нужную сторону», на скольких — провал.
5. Если на этапе 4 получилось больше 60% нормальных ответов — проект живой, имеет смысл вкладываться дальше в продакшн, гибридный поиск, реранкер, мониторинг. Меньше 40% — что-то не так с документами или с задачей, надо разбираться.

Главное не начинайте с «давайте сразу красиво, с ColPali и семантическим чанкингом». Начинайте с простого, измеряйте, улучшайте по результатам. Это главное правило: сначала базовая версия на реальных данных, потом оптимизация. Большинство проектов, которые сгорели, шли ровно наоборот.

Что в итоге

AI-ассистент по документации в 2026-м — это уже не эксперимент. Это рабочий инструмент, который окупает себя за 3–6 месяцев в B2B с длинным жизненным циклом продукта. Мы это видим на своих проектах — Samsung Medison взяли первую такую систему в эксплуатацию, и она сразу сняла заметную часть повторяющихся обращений с поддержки.

Главное — делать с пониманием, что внутри. Если подрядчик обещает «сделаем за три дня на ChatGPT», — это звоночек. Если обещает «AI сам разберётся в документах» — это второй звоночек. Хорошая система собирается неделями, а не часами, и тестируется на ваших реальных вопросах, а не на презентации.

Если у вас есть документация, которой никто не пользуется, и хочется разобраться, что с ней делать, — напишите мне в Telegram. Посмотрим ваш случай, скажем честно: окупится или пока рано. Первый разговор — бесплатно, без «коммерческих предложений на всякий случай».