Встроенный поиск по документации в KodaCode. Сравниваем с Context7

Если вы используете AI-ассистента для написания кода, довольно часто выясняется, что модель уверенно говорит неправду. Она выдумывает методы, которых нет в библиотеке, или описывает API, удалённый два релиза назад. Формально это называют галлюцинациями и knowledge cutoff, но для пользователя разницы нет. Ассистент ошибается именно там, где от него ждут точности.

Проблема усугубляется тем, что ошибки ^[1] выглядят правдоподобно. Код компилируется, сигнатуры выглядят знакомо, комментарии звучат убедительно. В результате разработчик тратит время не на работу, а на перепроверку. В этот момент инструмент перестаёт экономить время и начинает его забирать.

Решение: RAG на документацию

Индустрия давно пришла к выводу, что без доступа к актуальной документации эта проблема не решается. Retrieval-Augmented Generation ^[2] стал стандартным ответом: модель перестаёт «вспоминать», а начинает искать. Нужно просто находить релевантные документы и тем самым обогащать знания модели при выдаче ответа.

Context7 ^[3] — наиболее популярный mcp-сервер, который предоставляет функциональность поиска по большой базе актуальной документации. Вставляете как mcp в вашего агента, и всякий раз, когда нужно пойти поискать актуальную информацию в документации библиотек, агент сам это делает. Правда, часто агенту нужно явно писать “посмотри в Context7” или что-то такое, хотя некоторые модели уже хорошо знают про этот mcp. В целом, это проблема всех MCP, не только Context7.

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

Context7 докидывает актуальности, но вот насколько он это делает хорошо?

Второй вопрос: а что, если агент не имеет прямого доступа в интернет? И как тогда быть? Например, это особенно актуально для компаний с закрытым контуром разработки и с усиленными требованиями по безопасности. В общем, мы в KodaCode ^[4] решили изучить эту проблему и предложить своё решение с поиском по актуальной базе документации.

Retrieval как инженерная дисциплина

Мы собрали список документации к большинству популярных библиотек и фреймворков и подняли retrieval-пайплайн, наилучшим образом настроенный на поиск по документации.

В нашем случае стек для решения описанной выше проблемы выглядит следующим образом: Elasticsearch 8 как хранилище и поисковый слой, vLLM для инференса нашей модели эмбеддера и реранкера.

• Первая точка, где обычно теряется качество, — нарезка документации. Мы используем structure-aware chunking на основе Markdown-иерархии. Документы режутся строго по заголовкам, а слишком крупные секции дробятся с наследованием контекста. Это позволяет сохранить смысл страницы и не превращать её в набор несвязанных абзацев.

  Отдельная проблема — код. В нём часто нет слов, по которым пользователь формулирует запрос. Класс модели может не содержать ни названия фреймворка, ни описания задачи. Поэтому перед векторизацией мы принудительно добавляем в текст чанка метаданные: язык, библиотеку, тему, путь в документации. Это увеличивает recall без изменения самих исходников.

  

  Из примера выше, даже если юзер спросит “как создать модель в фастапи”, мы найдём этот кусок, хотя слова “FastAPI” в коде класса нет.

  На этапе поиска мы используем гибридный подход. Dense-retrieval на эмбеддингах хорошо работает с семантикой и кодом, но плохо справляется с точными именами классов и методов. BM25, наоборот, цепляется за токены. Проблема объединения их оценок решается через Reciprocal Rank Fusion: мы смотрим не на абсолютные скоры, а на позиции документов в выдаче. Это снимает необходимость ручной калибровки коэффициентов.

  

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

• Чтобы избежать «рваного контекста», мы используем dynamic window retrieval ^[5]. Для каждого релевантного чанка подтягиваются соседи по документу, после чего текст склеивается и уже в таком виде передаётся модели.

  

• Финальный шаг — reranking. После гибридного поиска и RRF у нас остаётся порядка 50 кандидатов. Отдавать их все в LLM дорого и неэффективно. Мы используем нашу модель реранкера (дообученная версия Qwen3-reranker 0.6B), которая оценивает пары «вопрос–документ» и отбирает наиболее релевантные. Это увеличивает задержку, но заметно поднимает precision на верхних позициях.

Как мы сравнивали себя с Context7

Как вы поняли, мы реализовали свой вариант встроенного инструмента поиска по документации в KodaCode под названием docs_search, который, как и Context7, обогащает актуальной документацией через RAG. Теперь к метрикам и замерам.

Чтобы сравнение не сводилось к ощущениям, мы собрали собственный бенчмарк. В него вошли 250 пар «вопрос–эталонный ответ» по документации популярных фреймворков для Python, Java и JavaScript.

Эталонные ответы заранее атомизируются в набор фактов: имя функции, аргументы, типы, значения по умолчанию, возвращаемые объекты. Оценка строится как NLI-задача: модель-судья проверяет наличие каждого факта в ответе и отвечает «да» или «нет».

Основная метрика — mean recall, доля найденных фактов. Мы считаем, что такая метрика хорошо подходит для оценки RAG-системы, так как штрафует, если в ответе отсутствуют нужные факты. Это более устойчивая метрика сравнительно с долей условно “идеальных” ответов (где присутствуют все факты из эталона), так как ошибка в одном факте приводит к существенным “скачкам” значений метрики. Чувствительность метрики составляет около 0.33%, что позволяет фиксировать небольшие изменения в retrieval-части пайплайна.

На этом бенчмарке мы сравнили модель без RAG, модель с Context7 и модель с Koda docs_search. В среднем Context7 даёт заметный прирост по сравнению с голой моделью, но наш пайплайн показывает более высокий recall — около 60% против 40–50%. Для ориентира мы также прогнали модель с прямым доступом к эталонному документу, что даёт порядка 85% и показывает верхнюю границу качества.

Заключение

Koda docs_search запустили недавно, и сейчас он работает над более чем 260 популярными библиотеками и фреймворками. В Context7 документации значительно больше, но и мы список активно пополняем и с периодичностью раз в месяц обновляем актуальные страницы документации, которые изменились.

Кроме того, вы можете сами добавлять нужную вам документацию через меню @, выбрав “Документация” -> “Добавить документацию”. Но имейте в виду, что проиндексированная таким образом документация будет храниться локально. Включайте docs_search в списке доступных инструментов. (docs_search пока не доступен в Koda CLI.) Запрос к модели можно явно писать: “поищи в документации…” или что-то такое, если модель в процессе решения сама не пошла в него.

Скачивайте и пользуйтесь KodaCode уже сейчас: https://download.kodacode.ru ^[6]

И подписывайтесь на наш ТГК ^[7], чтобы не пропустить новую информацию про Koda, AI и всё, что с ними связано!