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

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

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

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

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

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

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

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

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

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

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

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

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

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

  

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

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

  

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

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

  

• Финальный шаг — 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

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