Документация умерла, да здравствует ассистент
Сколько раз вы открывали README и понимали, что оно писано год назад под дедлайн? Или пытались разобраться в чужом микросервисе, а там только комментарии в духе // TODO: fix this? У нас в Звуке это было нормой. Команда выросла до 200+ разработчиков, кодовая база — монолит, раздербаненный на 150 микросервисов, документация — разрозненные документы в Confluence, половина из которых устарела месяц назад.
Онбординг нового разработчика превращался в квест: две недели с ментором, бесконечные вопросы в Slack, а потом — «забей, я тебе скину ссылку». Мы решили, что хватит. Давайте сделаем ИИ-ассистента, который знает весь наш код и документацию. Не очередной чат-бот, а напарника, который ответит на любой вопрос по архитектуре, API, бизнес-логике — и сделает это быстрее, чем коллега.
Ниже — наш путь от хаоса к ассистенту. Никакой теоретической воды, только грабли, которые мы собрали, и решения, которые сработали. Спойлер: онбординг теперь занимает три дня, но пришлось пережить несколько ночных деплоев.
Сначала разберитесь, что у вас есть (спойлер: бардак)
Мы начали с инвентаризации. Собрали все репозитории, вики-страницы, ADR (Architecture Decision Records), README, даже TODO-файлы. И поняли, что 30% кода не имеет документации, а 20% документации ссылается на несуществующие модули.
Первая ошибка — попытаться запихнуть в ассистента всё сразу. Наш прототип на GPT-4o с контекстным окном в 128K токенов просто «забывал» середину. Модель начинала галлюцинировать, придумывая несуществующие эндпоинты. Как выяснилось, качество ответа падает, если контекст перегружен шумом — нерелевантными файлами, старыми версиями, бинарниками.
Не делайте так: скормить модели все гигабайты репозитория. Это не только дорого, но и вредно — модель теряет фокус. Лучше сначала отфильтровать актуальные источники и разбить их на осмысленные фрагменты.
Мы выбрали RAG (Retrieval-Augmented Generation) вместо fine-tuning. Почему? Файнтюнинг дороже, требует GPU-кластера, и его нужно переобучать при каждом изменении кода. RAG — гибче: обновил документацию и индексы — ассистент уже знает новое. К тому же, мы не хотели терять общие знания модели о программировании (паттерны, best practices), которые есть в GPT-4o. Файнтюнинг мог бы «забыть» часть этих знаний — классический catastrophic forgetting.
Инструментарий: что внутри ассистента
Сейчас, в середине 2026 года, выбор LLM и векторных БД огромен. Мы остановились на стеке:
- LLM: GPT-4o (последняя версия, июнь 2026). Отличное понимание кода, знает все популярные языки, поддерживает инструменты (function calling). Важно: мы используем её только для генерации ответа, ретривер у нас отдельный.
- Embeddings: text-embedding-3-large от OpenAI — даёт векторы размерностью 3072, что повышает точность поиска по сравнению со старыми ada-002.
- Векторная база: Qdrant (self-hosted в Kubernetes). Сравнивали с Chroma (не хватает производительности на больших объемах) и Pinecone (дорого для нашего масштаба ~5 млн чанков). Qdrant — opensource, быстрый, поддерживает фильтрацию по метаданным (например, только Python-файлы).
- RAG-фреймворк: LangChain версии 0.8 (2026). Да, он всё ещё жив, хотя появились альтернативы типа LlamaIndex. Но LangChain даёт гибкость в пайплайнах и интеграцию со Slack.
Шаг 1: Парсинг и чанкинг — режьте аккуратно
Самый трудоёмкий этап — превратить код и документацию в кусочки, которые можно индексировать. Мы использовали tree-sitter для синтаксического разбора — это даёт возможность резать код по границам функций и классов, а не тупо по количеству символов.
Пример: У нас есть Go-файл с одной большой функцией. Если резать по 1000 токенов, то модель получит половину функции — контекст потеряется. Tree-sitter позволяет выделить всю функцию как один чанк, даже если она занимает 2000 токенов. Для документации (Markdown, Confluence export) мы используем семантический сплиттер из LangChain — он делит по заголовкам, параграфам, спискам.
from langchain_text_splitters import Language
# Настройка splitter для Python кода
splitter = RecursiveCharacterTextSplitter.from_language(
language=Language.PYTHON,
chunk_size=1500,
chunk_overlap=200
)Критично: overlap в 10-15% от размера чанка. Без него ретривер может пропустить границу между двумя чанками, и ответ будет неполным. Ещё один нюанс — удаляем из индекса сгенерированные файлы (protobuf, openapi-спеки) и зависимости (vendor, node_modules). Иначе они засоряют векторное пространство.
Шаг 2: Индексация и поиск — магия метаданных
Каждый чанк мы снабжаем метаданными: путь к файлу, язык программирования, последний коммит, автор. Это позволяет ретриверу фильтровать по релевантности. Например, если разработчик спрашивает про API авторизации, ассистент должен искать в первую очередь в сервисе auth, а не в соседнем payments.
Мы используем гибридный поиск: dense embeddings + sparse (BM25). Qdrant поддерживает это из коробки. BM25 хорошо ловит точные совпадения (названия функций, переменных), а dense — семантику. Веса выставили 70/30 в пользу dense, но это настраивается.
from qdrant_client import models
# Создаем коллекцию с поддержкой sparse vectors
client.create_collection(
collection_name="codebase",
vectors_config=models.VectorParams(size=3072, distance=models.Distance.COSINE),
sparse_vectors_config={
"text": models.SparseVectorParams()
}
)Шаг 3: RAG-пайплайн — собираем всё вместе
Когда ретривер нашёл топ-5 чанков, мы формируем промпт для GPT-4o. Важно: не просто склеивать чанки, а добавить контекст и инструкцию. Наш системный промпт звучит так:
Ты — ассистент разработчика в Звуке. Отвечай на вопросы, используя только предоставленные фрагменты кода и документации. Если информации недостаточно, скажи, что не знаешь, не придумывай. Всегда указывай источник (путь к файлу). Если вопрос касается бизнес-логики, давай краткое объяснение и ссылку на ADR.
Мы добавили механизм проверки релевантности: если confidence score ретривера низкий, ассистент возвращает «Я не уверен, посмотрите в этих файлах…» вместо генерации ответа. Это снизило количество галлюцинаций на 40%.
А ещё мы интегрировали ассистента с Slack и VS Code (через extension). Разработчики могут написать @assistant как запустить тесты для сервиса payments? — и получить ответ за 2 секунды. Психологически это проще, чем открывать отдельный веб-интерфейс. Подробнее про внедрение AI-инструментов в команду — в статье Психология сопротивления ИИ.
Деплой и эксплуатация — без коробочного решения
Мы развернули сервис в Kubernetes (AWS EKS). Qdrant крутится как StatefulSet с NVMe-дисками для низкой задержки. Сам API — FastAPI-приложение с эндпоинтом /ask. Для кеширования частых запросов используем Redis. Когда разработчик задаёт одинаковый вопрос второй раз, ответ возвращается без embarassment LLM.
Мониторинг: metrics (латентность ретривера, количество тюремных запросов, уровень галлюцинаций) собираем в Prometheus + Grafana. При превышении задержки больше 3 секунд — алерт в PagerDuty. И да, мы сделали A/B тест: разработчики, которые использовали ассистента, тратили на поиск информации в 4 раза меньше времени.
Критическая ошибка: не забудьте про безопасность. В коде могут лежать пароли, токены. Мы прогнали все чанки через детектор секретов (TruffleHog) и отфильтровали их. Иначе ассистент может по неосторожности выдать credentials.
Результаты и что пошло не так
Через месяц после запуска мы замерили: время онбординга нового разработчика сократилось с 14 дней до 3. Количество вопросов в #dev-help упало на 60%. Но не всё гладко. Проблема №1 — устаревший код в индексе. Если кто-то переименовал функцию, ассет меняется только после переиндексации. Мы сделали CI-триггер: при каждом мерже в master пересобирается векторная база для изменённых файлов. Это заняло время, но окупилось.
Проблема №2 — модель путает похожие названия. Например, UserService и UserServiceV2 в разных контекстах. Решили добавлением в метаданные тегов версий и уточняющих фильтров.
И последнее — кадры. Для поддержки ассистента нужен DevOps, который разбирается в MLops. Мы обучили пару инженеров основам RAG и промпт-инжиниринга. Если у вас в команде нет таких людей, возможно, стоит подумать о поиске продукт-менеджера с техническим бэкграундом — курс Product Manager + AI от Skillbox как раз учит управлять такими проектами. А если вы только начинаете автоматизировать HR-процессы в IT, курс по управлению персоналом с AI может быть полезен для планирования hejdpauнта.
Будущее: ассистент как часть платформы
Сейчас мы добавляем возможность для ассистента выполнять действия: создавать PR, запускать тесты, деплоить на staging. Это уже не просто Q&A, а AI-агент. Но тут важно не переборщить: риск автоматических ошибок высок. Мы движемся постепенно, начиная с read-only операций.
Судя по трендам, к концу 2026 года такие ассистенты станут стандартом для любой продуктовой команды. Если вы ещё не начали — самое время. Начните с малого: выберите один сервис, проиндексируйте его код, запустите в Slack. Результат вас удивит. И не бойтесь хейтеров, которые говорят, что «ИИ не понимает код». Понимает, если правильно приготовить. И помните: главное — качество данных, а не крутизна модели.
Хотите узнать, как мы решали проблему stability и как настраивали автоскейлинг для GPT-4o? Читайте продолжение в следующей статье (подписка на канал), а пока — дерзайте.
