Modular RAG MCP Server

Плагибаемый, наблюдаемый модульный сервисный фреймворк RAG (генерация с дополнением поисковыми данными, Retrieval-Augmented Generation), который через протокол MCP (Model Context Protocol) предоставляет интерфейсы инструментов и поддерживает их прямой вызов AI‑ассистентами, такими как Copilot / Claude Automation. Это также практический проект и сопутствующий учебный материал, созданные специально для изучения тематики больших моделей и подготовки к собеседованиям по соответствующим вакансиям.

📖 Содержание

• Обзор проекта

• Описание веток

• Быстрый старт

• Кому подходит этот проект & как его использовать

• Примеры для резюме

• Частые вопросы

• Дальнейшие планы

Related MCP server: mcp-rag-agent

🏗️ Обзор проекта

Что это за проект

Этот проект объединяет самые частые ключевые звенья интервью по RAG — поиск (Hybrid Search + Rerank), мультимодальное зрение (Image Captioning), оценку RAG (Ragas + Custom) и генерацию (LLM Response) — вместе с актуальным прикладным протоколом MCP (Model Context Protocol) в единый законченный, работающий инженерный проект.

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

Это не просто проект, а целая методология

Ещё ценнее, чем сам проект, — весь набор инженерных подходов, который в нём лежит:

• Как писать DEV_SPEC (документ спецификации разработки) как драйвер разработки

• Как с помощью Skill на основе Spec автоматически писать код

• Как с помощью Skill автоматизировать тестирование, упаковку, конфигурацию окружения

• Как расширять код, опираясь на плагинную (модульную) архитектуру (например, в сторону Agent)

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

Обзор ключевых возможностей

Технические особенности

🔌 Вся цепочка — плагинизируемая архитектура: для каждого ключевого звена — LLM / Embedding / Reranker / Splitter / VectorStore / Evaluator — заданы абстрактные интерфейсы, поддерживается замена по принципу «Lego». Бэкенд переключается одним изменением файла конфигурации, без правки кода.

🔍 Гибридный поиск + переранжирование: BM25-спарс-поиск отвечает за точное совпадение по терминам, Dense Embedding — за семантические эквиваленты (сходство по смыслу). После слияния по RRF можно включить Cross-Encoder / LLM Rerank для финального ранжирования. Так балансируются полнота и точность (recall и precision).

🖼️ Мультимодальная обработка изображений: по стратегии Image-to-Text vision-LLM автоматически генерирует описание картинки и «взливку» его в chunk. За счёт этого можно переиспользовать чисто текстовый RAG-контур и реализовать поиск «текст идёт → картинка находится».

🎡 Интеграция с экосистемой MCP: соответствие стандарту Model Context Protocol, это можно прямо подключать к MCP-клиентам (GitHub Copilot, Claude Desktop и другим). Ноль фронт-енд разработки — написали в одном месте, работает везде.

📊 Визуальное управление + автоматическая оценка: панель Streamlit Dashboard с полным управлением данными и трассировкой цепочек, интеграция с фреймворками оценки (Ragas и другие) — замкнутый цикл улучшений, опирающийся на данные.

🧪 Трёхуровневая система тестов: Unit / Integration / E2E — покрывают логику отдельно каждого модуля, взаимодействие между модулями и полный контур (MCP Client / Dashboard).

🤖 Skill-driven полный процесс: встроенные Agent-навыки — auto-coder (автонаписание кода), qa-tester (автотесты), package (чистка и упаковка), setup (конфигурация в один клик) — обеспечения полного жизненного цикла от написания кода до тестирования, упаковки и развёртывания. Использование каждого Skill и дизайн-идеи разбираются в видео в разделе про проект в конспектах — можно смотреть для изучения.

📖 Подробнее об архитектуре, модулях и планировании задач — в DEV_SPEC.md

📂 Описание веток

В проекте три ветки — под разные сценарии сценария. Выберите по своим задачам:

main — самый чистый полный код

• Репозиторий всегда содержит только 1 commit с актуальным полным кодом

• Кому подходит:

  • тем, кто хочет быспросить проект и быстро оценить полный функционал;

  • тем, у кого совсем мало времени и нужно скорее получить проект в резюме, пропустив промежуточные этапы разработки;

  • тем, кто планирует сразу делать доработки на базе этого проекта;

• Как использовать: клонировать и запустить сразу через Setup Skill.

dev — с полной историей разработки

• Код полностью совпадает с main, но сохранена вся история commit.

• Зафиксировано, как проект шаг за шагом строился с нуля; там большое число промежуточных узлов.

• Кому подходит: тем, кому интересно понять, как проект создавался с нуля по шагам. По commit-истории можно проследить логику разработки.

clean-start — чистое начало, старт с нуля

• Включает только инженерный скелет (Agent Skills + DEV_SPEC), весь прогресс по задачам обнулён.

• Сохранены все настройки Skill-ов; можно разрабатывать при помощи Agent.

• Кому подходит:

  • тем, у кого достаточно времени и кто хочет начать всё с нуля (настоятельно рекомендуется);

  • тем, кто хочет пройти весь рабочий процесс целиком: написать Spec → разбить на задачи → написать "код" → написать "тесты" → итерации улучшения;

  • тем, кто может перепроектировать архитектуру по собственному пониманию и реализовать всё по-своему — так глубже вникаешь в каждый модуль;

  • вы можете применить все методы, о которых мы рассказываем (разработка от Spec, test-first, модульная архитектура и т.д.), и собрать так весь проект.

• Основная идея: весь код проекта — это AI автоматически пишет его на основе DEV_SPEC, самому писать код руками не требуется. AI через Skill считывает определения задач, архитектуру и интерфейсы со спецификации и генерирует по соответствующий код. Почему это работает — смотри в соответствующем видео в конспектах: 5.1 Использование назначений Skills в проекте: как заставить AI использовать Skill и следовать DEV_SPEC при написании кода.

🚀 Быстрый старт

1. Клонирование проекта

git clone <repo-url>
cd Modular-RAG-MCP-Server

2. Настройка в один клик (Setup Skill)

В проекте есть Setup Skill — он в один клик выполняет всю конфигурацию: выбор Provider → задание API Key → установка зависимостей → генерация файлов конфигурации → запуск Dashboard.

Откройте проект в VS Code и в диалоге Copilot / Claude отправьте:

setup

Агент сам проведёт вас через весь процесс настройки.

💡 Если вы не умеете пользоваться Skill — посмотрите видео «Разбор Setup Skill: использование» в сопутствующих конспектах.

🎯 Кому подходит этот проект и как его использовать

У всех разный фон — кто-то пришёл по кампусу, кто-то обладатель опыт; разный стартовый уровень — у одних уже есть AI-проект, другие переходят в это направление. Поэтому и стратегия использования этого проекта должна быть разной — пользовальностью не шаблонно, а гонко адаптируя под себя.

Едина у всех одна точка: тот набор инженерных идей, который стоит за проектом — как написать Spec и быстро поднять проект, как через Skill вести каузальное кодирование и тестирование — эти подходы подходят к люб всем проектам и Ми ДGI valuable для всех.

Дальше я детально обрисую типичные сценарии и на личном опыте — как бы им я поступил в разных ситуациях — как ориентиры.

1. Просто изучание RAG — применяйте проект как учебный материал по всему пайплайну RAG

Этот проект — самостоятельная RAG-система, и его можно использовать как в сопутствующий практический материал при изучении RAG.

Когда я начинал изучать RAG, я читал книгу: «Практика RAG на больших моделях: принципы RAG, приложения и построение систем» (авторы: Ван Пэн, Гу Циншуй, Бянь Лунпэн и др., эксперты в области искусственного интеллекта). С этой книгой RAG удобно с ним связаны по понятиям: какие в типовые звенья — поиск, генерация, векторная база данных, стратегия разделения на чанки, переупорядочивание — по сути, любой книгwe по RAG эти ядра там будут.

Этот проект их всех связывает в один поток — это может быть универсальное изучение всего процесса RAG. Можете комбинировать с этой книгой; уверен, подойдете и с другими книгами по RAG, потому что общий процесс одинаков. На интервью по RAG спрашивают в основном те же комбинации этих этапов, их принципы, трудности и оптимизация на практике.

2. Мало времени — срочно нужен проект для собеседования

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

1. Используйте этот проект напрямую — клонируйте ветвь main, запустите его через Setup Skill.

2. В связке с Resume Writer Skill — сгенерируйте собственное резюме (Skill подгонит описание проекта под особенность вашего бэкграунда).

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

4. С каждым интервью углубление и расширение проекта — само собеседование уже является дополнительным драйвером обучения.

Например, сейчас март, и придётся студентам, ищут летнюю стажировку. Времени мало — сначала добавьте проект в резюме, учитесь во время собеседований, и если найдете время — расширяйте. Это решает острую проблему "нет проекта под интервью". И в схеме: сначала добавить в резюме → пойти на интервью → улучшить проект по обратной связи с интервью.

Обычно на летние стажировки есть шансы с марта по июль. Как получите стажировку и опыт работы над LLM-проектом — используйте это как трамплин для дальнейшего накопления: осенью 7–10месяцев идёт кампус-набор, даже весеннего ключа весной следующего года — у вас полно времени. Кажется, начать сейчас уже поздновато, но на деле нет. Если сохранить темп, с егодня до весны следующего года — ровно год учёбы, and университетская стратегия построения в сторону больших моделей не проблема. Ключ — сможете ли вы держать такой длинный спринтовый темп.

3. Времени относительно достаточно — начать с этого проекта и расширять

Проект можно брать отправной точкой и расширения точечно по вашему направлению развития. В DEV_SPEC уже указаны направления расширения. Вот распределение типичные:

• Хочу получить знания об Agent: сами реализуйте Agent-часть — обработка контекста, Tool Calling, логика ReAct. Подключать этот проект как один из модулей и источник способностей, превратите в визит Agent + RAG.

• Хочу показать бэкенд-навыки: добавьте бэкенд-деплой — напишите Dockerfile, настройте CI/CD пайплайн, добавьте мониторинг и сбор логов.

• Хочу глубже сделать RAG: расширение к продвинутым формам Agentic RAG, Graph RAG и т.п., или больше экспериментов по оптимизации стратегий поиска.

По-у каждом направление развития разное. Пусть пример — встроенный Resume Writer Skill: при резюме он задаёт первые вопросы о background. Ориентирование на должность инженера по приложениям LLM, RAG-инженера, фулстекка — набор требований для кампуса и для найма, разные функции (подробно о различных ролях больших моделей и технике набора см. в разделе "Описание должностей больших моделей" в конспектах). Поэтому надо расширять точечно под себя.

Настоятельно рекомендую: какой фон не был вне зависимости — резюме относитесь к построению вашей работе. Поэтому попробуйте хотя бы раз: бросьте в проект документы из вашей предметной области (банки, юр., медицинские, или же бизнес-документы) и посмотрите на качество поиска. Если качество неудовлетворительно — и настраивает улучшаете. Сам процесс уже — лучший опыт, and 샘플 на интервью это живые практика, которую трудно оспорить.

4. Всё достаточно — с нуля пройти полный рабочий процесс

Если время есть с головой, рекомендую стартовать с ветки clean-start, или даже удалить DEV_SPEC из clean-start и начинать с проектирования документации:

Проектирование документа → AI пишет код → итерации → тесты → деплой.

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

Так вы получаете полный набор методов разработки проекта. The biggest advantage — входной порог очень низкий — практически normal you can build and complete whole project. Так вы учите и саму методологию, сам процесс, а результат проекта получается глубоко каглум. Many friends in the group have already done this.

5. Интеграция в существующий проект — встройте RAG-потенциал этого проекта к вам

Впрочем, это очень parsable strategy — возможно, я сам поступил бы так.

Личвый пример: когда я много искал работу, у меня уже было два Agent-проекта, но часть RAG была просрачена грубо. В резюме было примерно так "в проектс Agent сделал то и это, потупил RAG". На интервью меня всегда отпрашивают по RAG, и я что-то рассказывал, но старая RAG была мелкой — просто base embed + vectors, без кандидатского retrieval, без re-rank и т.д. Поэтому собеседник быстро упокупался по глубине.

После этого проекта есть вариант влить RAG-ал этого проекта в тот прежний Agent-проект и в резюме даже не отдельным пунктом, а частью Agent-проекта в целом. Например:

*… — в проекте для поисковых знаний использовалась собственная модульная RAG-система: гибридный отбор BM25 + Dense Embedding с фьюженом-ранжированием RRF, дополнительно Cross-Encoder переранжирование для повышения качества Top-K; поддерживалась работа с мультимодальными документами (парсинг PDF + Image Captioning); через протокол MCP выставлялась единая инструментально-ориентированная интерфейс для вызова агентом. Встроена платформа оценки Ragas, создан регресс-tests mechanism Golden Test Set — качество поиска непрерывно улучшается…"

Так у вашего прежнего Agent-проекта появляется глубина RAG — когда собеседующий пытается копнуть, вам уже есть что напомнить.

6. Продакт-Mенеджер — да, вы не ослышались: PM тоже может использовать этот проект

На собеседованиях на большие LLM Product-карты всё чаще справливают основные по RAG, some companies даже требуют, чтобы PM сам написал POC (proof-key) and only then gave it to developers for implementation. Этот проект и стоящая за ним методология справятся с этим.

Почему PM может использовать этот проект:

1. требования на собесах: круг РDM — на ролях big models могут спросить блаceae basic, принципы и весь процесс RAG. Этот проект даст вам визуально весь pipeline — загрузка документа, чанки, векораизация, поиск, переупорядочивание, финальная генерация — и таким образом сформируется product-level прочтение.

2. возможность POC: у вас это можно полностью собрать этот проект этим методом — Совсем документ (DEV_SPEC), или взять существующий документ, и использовать Skill для что AI сгенерировал each code. On resume you are talking about sum and product интерес к продукта, код — написаный AI, это современная легализованная практика.

3. Не нужно вникать в детали: produce Нет вникать in every line of code. Проходя процесс, можно думать про продукты уровни, например — точечные metrics определения "неправильно ищется", как спроектировать механизм обратной связи на пользовател, как качество исходных данных влияет на результат RAG и т.п.

Конкретные шаги вためにне: PM:

• Загрузите ветку main, поднимите Setup-навыком и пройдите весь процесс.

• Вкинув свои бизнес-руки, посмотрите результат retrieval, подумайте, что улучшать на продуктовом уровне.

• На собесе поговорите и ваших продуктовых решениях и о вашем дизайне, а техническую часть обоснованност можно описывать так, что реализация есть через AI-assisted.

💡 В конспектах также есть материалы про Vibe Coding (например, объяснения Танию Хуан), они отлично подходят для людей, без аппаратного фона — быстрые прототипы на подходе.

О "плоском" проекте

И последнее отдельно скажу (это относится ко всем вариантом выше):

Глубина всех проектов продходит не разово.

Если вы переходили в ИИ and все проекты делали сами, то пусть few интервьюер заметит, что проект из коробки. I’ve already said this once, but do not be afraid.

1. Глубина проекта не обязательное минимум для входа в сферу. В прошлом году I got 6 offers, including one from a large corporation. Anyway, у некоторых было то, что как про проекты у меня мелкие. Собеседование, глядящее на другое: теоретическая база, алгоритмика, совпадение бекграунда, кругозор. Не укажите себя из-за "проект мелковат" — будто их не войти.

2. Проект — это постоянная полировка и углубление. Когда интервьюер вы даёт "пло" и вы с intrusion strict note, вы — и вы See, why not say: data system не кар compl' — сделаете вклад complex данные; images handled too simply — развития multimodal strategy and так далее. I сам при изучении т gradually add to the agent project: depoymentій, обучение, отражения, evaluation — эта parallel сleted, когда собе были.

Выделите себе больше времени на собеседование — идёте на собесе, параллельно улучшая и углубляя проект. The "可见" треть за спиной проекта именно для этого: методология позволит постоянно расширять и стоимость каждого расширения очень мала — просто сформулировал задач и позвольте AI писать. Бояться нечего.

The reliable писать: проект был разработан за ~2 месяца в вечернее время после работы, paralleльно : рабо был, занимались self-media, само-медиа الأخرى материалы и не$ busy. Поэтому не стоит construir на этот проект как на что-то ультраглубокого сам по себе без доп расшiro: theme most typical for those apply with experience. But давай по—преж is เหลือ обрати внимание: за two months of sume evenings have gotten so much; if you have mastered method, what speed can your own extensions reach?! Everything is обоснован:

Все methods — это исходный код, процесс, записи — сохранены и есть видео-разъяснения. В итоге стратеги важно самому расширять, итератировать, and сделать ту deepest, под собственный свою конкретную задачу.

📝 Примеры для резюме

⚠️ Настоятельная рекомендация: для раздела "опыт/проекты" в резюme используйте встроенный в проекте Resume Writer Skill — не копируйте примеры ниже.

Резюме в резюме всегда персонализируется — Сложив наименование должен быть под конкретию, ваша отрасль, вашу целевую должность и нужные вам акценты. Примеры ниже показа попней: только проходит как демонстрация выходного квалитета Skill и как иллюстрация референса на разные сценарии. Дословный копипаст смысла не имеет.

Как works with Resume Writer Skill: в проекте в VS Code откройте диалог Copilot / Claude проject и enter "写简历" or resume. Skill проведет вас по сбору профиля and automatic generate a блок из четырех разделов in резюме. Подробнее о том, как им пользоваться и какаято логика — see vidéo в section Project of the конспекты.

Как работает Resume Writer Skill

In Skill используется модель «принципы письма + ключевые возможности проекта + профиль соискателя = кастомизированное резюме». Порядок:

1. Снимок образа: Skill спросит целевая позицию (RAG Engineer / Backend / Agent и т.п.), ваше бизнес-бэкграунд, техническую акценту, специальные требования.

2. Сопоставление бонусов: опираясь на вашу роль, из 10 технических особенностей проекта для себя, three подходящих и включены в bullet-пункты.

3. Генерация четырёх разделов: строго структура фон → цель → процесс → результат, каждый bullet построен правилом "глагол + технические деталей + измеримый результат".

4. Предсказание добивающих вопросов интервью: автоматически генерирует 3–5 вероятных follow-up вопросы интервью — можно защититься.

Пример 1. Выпускник · направление RAG Engineer

Ниже — пример выхода, сгенерированный Skill на основе "выпуск онап, направление RAG, универсальный сценарий":

Умная система поиска и вопросов-ответов по знаниям | 09.2024 — 02.2025 | Индивидуальное проектирование и разработка

Контекст: под корпоративные knowledge-base сценарии, где документы разсипанные, поиск nedотеченный, AI-триложения трудно связываться экспертные знания, спроектирован и реализован модульную RAG-систему.

Цель: построить рекомендационно-ответную систему на базе гибридного поиска + MCP протокол — добиться точного семантического retrieval и возможности AI Agents напрямую выбирают из private "knowledge hub" —добиться точности ответа по документом 90%+.

Работы:

• Спроектирована гибридная архитектура отбора: BM25 + Dense Embedding, объемирангирование RRF чтобы баланс полноты retrieval. Совместно с Cross-Encoder пер-ранжирование подняло процент попадания Top-10 Will на ≈25%.

• Реализован сквозный последний Ingestion: PDF-парсинг → Markdown → семантическая чанкизация → обогащение метадандами → Embedding → Upsert. Интегрирован Vision LLM, который автоматически описывает изображения and прививает их в чанки, hence через что чисто-текстовой pipeline позволяет "находит картинку по текстовомуой".

• Реализована плагинная архитектура всей цепочки: LLM / Embedding / Reranker / VectorStore получили единые абстрактные интерфейсы; через конфигурационный файл можно сменить backend одним кликом. Поддержка 4+ LLM-провайдеров, правок кода не требуется.

• Встроена двойной оценка Ragas + Custom: создан механизм регрессионных тестов на golden test set по метрикам Faithfulness / Relevancy / Recall. Onстройка по "ощущениям". — отказ от неопр.

• Разработка по управлению Agile/Skill: через 5 основных Agent Skills — auto-coder / qa-tester / setup / package — закрыт весь цикл coding, теста, конфигурации, packing; 2 свободных месяца довели 68 многих минизадач до сдачи.

Результат: система обслуживает в реальном времени semantic search по 5000+ documents, точность поиска (Hit Rate@10) = 92%, end-to-end latency под 800 мс, трёхуровневые тесты (Unit / Integration / E2E) покрыли 1200+ кейсов.

Технологии: Python / LangChain / ChromaDBБM25 / Cross-Encoder / MCP Protocol / Streamlit / Ragas / Azure OpenAI

Пример 2. Специалист с опытом · есть Agent-проект — глубоко RAG

Ниже — пример выхода, сгенерированный Skill на основе "с опытом, Agent-направление, бэкграунд разработка под Windows" (RAG-возможности добавляются в уже имевшийся Agent-проект):

Умный помощник по знаниям для Windows | 06.2024 — 02.2025 | Core Development

Фон: в командах, развивающих платформу Windows, сведения о релиз (Release Notes, changelog, патчи, описания compatibility) разбросаны по многих Wiki, репозиториях и внутренних системах. Инженеру при разборе несоответствия версий или ответе клиента нужно переключаться между системами; по стрельбе keywords до сих пор не понимает смысл — выдержи низкая скорость похода, частные недостачи информации.

Цель: выстроить внутри команды умный помощник по знаниям на базе Agent + RAG, выполнить смысловой retrieval по документам in cross-map через все систем and automatic Q&A, интегрировать его по протоколу MCP в естественный инструмента лентой инженеров (VS Code / Chat / Desktop) — и добиться сокращенические рост времени поиска документа им на более 60%.

Работы:

• Спроектирована многослойная архитектура Agent + RAG: на стороне Agent — распознавание намерения и Tool Calling; со стороны RAG — двумя фазами retrieves: смешанный отбор BM25 + Dense Embedding и точное пер-ранжирование Cross-Embedding. Стандартн интерфейсы по MCP вынесены для вызова агентной.

• presumably полносен Iterator: значения PDF → Markdown → chunk → embedding → upsert. Данные Optional.

• INT a Vision LLM to generate image caption for короткие изображения (schemas, scripts), закрывая запрос "no text — no image".

• Курсы to plug-in Architecture: LLM / Embedding / Reranker / VectorStore interfaces universal, Azure OpenAI ↔ DeepSeek ↔ Ollama switchable one-click — под разные. network-положения.

• Встроен Streamlit Dashboard — 6 страниц: обзор, обзор data, управление Ingestion, троса приёма, трассировка запросов, except через панель оценки — каждая звено видна прозрачно.

• Регистрация оценки Ragas + Golden Test Set: в В releases not систем quality continuously monitors (без соучастimize), показательность Faithfulness стабильно держатся не ниже 0.85.

• Agile-доставка (Skill-driven): пишем DEV_SPEC — это читает автоматом кодер auto-coder, тест и исправление qa-tester, одну настройкой setup. The five Agent Skills закрыют непрерывный lifecycle разработания. В неисп работу исполнено 68 подзадачь during off-hours.

Результат: си ultraviolet covers 8000+ тех.dokumentov; ежедневно длина time похodы plant in Engineer's докум from 15 минут к 3 минутам; retrieval accuracy (Hit Rate@10) = 90%; через MCP протокол подключен к 3 внутренним AI-instrumentam; суммарно обработано 20k+ обращений.

Технологический стек: Python / Agent / Tool Calling / RAG / BM25 / Attention Retrieval / Cross-Encoder / MCP Protocol / ChromaDB / Streamlit / Ragas / Skill-Driven Development / Azure OpenAI

Пример 3. Специалист с опытом · переход с backend в AI

Ниже — пример выхода, сгенерированный Skill на основе "из начинающего в ИИ, направление backend / разработка архитектура, банковская комплаенс-специфика":

Wait, need preserve the text exactly. It should be "输出" and continue "的示例输出：" with blockquote text only. Fine.

Now let me check: The original at the end stops after that line (no resume body). So we end there.

In my final translation I have heading and blockquote. Good.

Now, let's review any typos and errors.

Wrong: In my translation I wrote "Модуль "r" etc. Let's make sure we keep the "##" etc.

Also, I need to double-check "Обзор проекта —" direct link in Table of Contents.

Look TOC: first item is 项目概述 → now "Обзор проекта" and anchor #-项目概述 unchanged. In Russian "Обзор" may be russian. Fine.

The original section "📂 分支说明" appears after horizontal rules. We have "## 📂 Описание веток".

" *main — 最干净的完整代码" runs in doc.

Now let's spot translation in the TOC and later heading: LT.

The intro block quote: I wrote "инвер. Check: "ДА" In the final text I may have "Подключаемый, модульный..." need.

Let's now check original first-line emphasis—should preserve > quote.

I need to ensure no missing elements:

• Title (# heading)

• blockquote

• "📖目录" heading

• TOC list

• "***"

• "🏗️ project summary" heading

• "The project is..." heading

• paragraph

• bold paragraph

• list (4 bullets)

• "核心能力一览" heading

• table with 3 rows (7 data rows) and relevant separators

• "技术亮点" heading

• 7 bullets

• quote

• "***"

• "📂 分支说明" heading

• paragraph

• 3 subsections with bullets

• "***"

• "🚀 快速开始" heading

• two subsections with placeholders

• quote

• "***"

• "🎯 谁..." heading

• paragraph with text

• paragraphs

• 6 subheadings with content, some with bullets/quotes.

• "***"

• "📝 简历参考" heading

• quote block

• two subsection headings

• three example subsections

• etc.

All present.

Need to keep "RE" quotes and the exact placeholders GXTI and GXIP2 as lines. In final we have them as typed.

Make sure not to inadvertently drop "owner/my-mcp-server" because the instruction requires keeping repository names — but the original text did not include the repo URL. The GXP1 probably hides it. We must preserve the placeholder not expand it.

Система интеллектуального поиска по нормативным документам | 10.2024 — 02.2025 | Проектирование и ведущая разработка

Контекст: В отделе комплаенс одной финансовой организации объём нормативных документов и внутренних политик непрерывно рос и достиг десятков тысяч единиц. Команде комплаенса при проведении проверок и консультаций требовалось быстро находить конкретные положения, однако существующая система полнотекстового поиска могла выполнять только точное сопоставление по ключевым словам и не понимала семантически близкие выражения, такие как «противодействие отмыванию денег» и «AML», из-за чего эффективность поиска положений была низкой.

Цель: Спроектировать и реализовать модульную RAG-систему поиска, внедрить возможности семантического поиска в процесс управления нормативными документами, обеспечить сопоставление положений по синонимам и на разных языках, поднять точность поиска положений до 90% и выше.

Процесс:

• Руководил проектированием архитектуры системы: применена полностью подключаемая сквозная архитектура, для LLM / Embedding / Reranker / Splitter / VectorStore определены абстрактные интерфейсы и фабричный паттерн, переключение бэкендов выполняется одной командой через YAML-конфигурацию, адаптация к различным средам развёртывания без изменения кода

• Реализована гибридная стратегия поиска: разреженный поиск BM25 + семантический поиск Dense Embedding, с объединением результатов через RRF для одновременного учёта точного сопоставления собственных имён и семантически близких выражений; точность поиска повышена на 22% по сравнению с чисто векторным подходом

• Построен полный конвейер приёма данных: парсинг PDF → семантическое разбиение на чанки → Chunk Refinement → Metadata Enrichment → векторизованное хранение; реализовано идемпотентное управление через DocumentManager для обеспечения согласованности данных при обновлении документов

• Создана трёхуровневая система тестирования (Unit / Integration / E2E), покрывающая более 1200 тестовых сценариев; интегрирован фреймворк оценки Ragas для автоматической регрессии, гарантирующий отсутствие деградации качества поиска в процессе итераций

• На основе протокола MCP предоставлены стандартизированные интерфейсы инструментов, поддерживающие прямой вызов из AI-ассистентов GitHub Copilot / Claude Desktop, реализована сервисная модель «разработка один раз — вызов с разных платформ»

• Применён метод полной инженерии процесса на основе Skill: спецификация DEV_SPEC управляет AI-агентом для автоматического выполнения кодирования (auto-coder), тестирования (qa-tester), настройки окружения (setup), очистки и упаковки (package); все 68 подзадач выполнены агентом, цикл разработки сжат до 2 месяцев в свободное время

Результат: После запуска система обеспечивает семантический поиск в реальном времени по более чем 12 000 нормативных документов; точность поиска положений выросла с 68% до 91%, задержка одного запроса — в пределах 700 мс, эффективность проверки документов командой комплаенса повысилась примерно на 50%.

Технологический стек: Python / подключаемая архитектура / фабричный паттерн / BM25 / Dense Retrieval / RRF / Cross-Encoder / ChromaDB / MCP Protocol / Streamlit / Ragas / Skill-Driven Development / Azure OpenAI

💡 Напоминания об использовании и важные пояснения:

1. О стратегии усиления: В Resume Writer Skill встроена разработанная мной стратегия усиления — AI в разумных пределах «приукрашивает» и усиливает описание вашего проектного опыта (например, количественные показатели, масштабы бизнеса). Это мной допускается и является нормальной практикой при написании резюме. Но это означает: после генерации резюме вы обязаны продумать, о чём именно интервьюер может спросить по каждому пункту и как вы будете отвечать. Skill при генерации резюме автоматически выдаёт 3–5 прогнозируемых вопросов интервьюера — пожалуйста, серьёзно подготовьтесь к ним.

2. Относитесь к резюме как к списку практики: Каждый технический пункт, указанный в резюме, вы должны реально попробовать. Например, если в резюме написано «точность поиска повышена на XX%» — значит, вы должны прогнать это на своих данных и посмотреть, каков реальный эффект, с какими проблемами столкнулись и как вы их решали. Именно этот практический опыт является по-настоящему убедительным на собеседовании и тем, чему вы действительно научились. Части, не упомянутые в резюме (например, если вы не пробовали мультимодальность или не запускали оценку), также можно использовать как повод для проведения экспериментов с кодом.

3. Сгенерированное — это черновик, обязательно доработайте под себя: Резюме, сгенерированное Skill, — это черновик, а не финальная версия. Вам нужно скорректировать его под свою реальную ситуацию — какие технологии вы действительно глубоко использовали, какие только знаете поверхностно, какие данные нужно заменить на свои. В написании резюме есть железное правило: всё, что написано в резюме, вы должны уметь объяснить. Даже если какой-то пункт преувеличен, вы должны продумать, как интервьюер спросит и как вы будете выкручиваться. То, что не можете объяснить, лучше вообще не писать; если написали — должны выдержать расспросы.

4. Метод важнее шаблона: Вся методология написания резюме — моя: включая стратегию усиления, четырёхчастную структуру (контекст → цель → процесс → результат → технологический стек), логику сопоставления ключевых моментов и т.д. Всё это заложено в Resume Writer Skill. Если у вас есть более надёжный шаблон резюме или вы расширили/изменили проект — вы можете изменить сам Skill для адаптации. Усвоить эту логику «закреплять методологию в Skill, а AI выполняет по правилам» — ценнее самого резюме — этот подход можно применять при написании резюме для любых ваших будущих проектов.

5. Настоятельно рекомендую указать Skill-управляемый полный процесс: Моё личное мнение — замкнутый цикл Skill-управляемой разработки подходит для резюме любого человека. Skill — очень актуальное направление, уже обязательная тема на собеседованиях, многие компании внутренне исследуют, как с помощью Skill ускорить построение проектов. Умение рассказать, как вы использовали Skill для полного цикла проекта от кодирования → тестирования → исправления → конфигурации → упаковки, само по себе является инновационным и передовым преимуществом, которое произведёт впечатление на интервьюера. О том, как рассказывать про Skill на собеседовании и как отвечать на уточняющие вопросы, я позже приведу несколько примеров.

❓ Часто задаваемые вопросы

1. Как переключить Provider (например, на Qwen / DeepSeek / Ollama)?

Очень просто — просто попросите AI помочь вам.

С точки зрения архитектуры в проекте используется фабричный паттерн (Factory Pattern), поэтому расширение и переключение Provider выполняется очень удобно. Вам достаточно понять внутренний принцип: разные API по сути представляют собой аналогичные HTTP-запросы, и большинство даже следуют формату запросов OpenAI, так что переключение особенно простое.

Есть два способа:

1. Использовать Setup Skill (рекомендуется): Запустите однокнопочный Setup Skill — AI сам спросит, какой Provider вы хотите использовать, проведёт вас по заполнению API Key и автоматически выполнит адаптацию кода и генерацию конфигурации.

2. Просто попросить AI изменить: Сообщите AI, на какой Provider хотите переключиться (например, «помоги переключиться на Qwen» или «настрой DeepSeek»), и AI на основе фабричной архитектуры автоматически напишет код.

Пояснение принципа: Модули LLM, Embedding, Reranker и др. в src/libs/ проекта используют фабричный паттерн. Для добавления нового Provider нужно: ① добавить класс Provider; ② зарегистрировать его в фабрике; ③ обновить конфигурацию settings.yaml. AI полностью может выполнить эти шаги автоматически.

2. Модули оценки проекта (Custom Evaluator) и Cross-Encoder Reranker

Каркас кода этих двух модулей уже готов, но полного тестирования не проходил — желающие могут доработать самостоятельно:

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

3. Что делать при ошибках / багах в проекте?

Это не производственный проект, прошедший широкое тестирование, а практический проект, ориентированный на собеседование. Ошибки — это нормально.

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

• Как исправить: Самый простой способ — сбросить сообщение об ошибке прямо в AI, большинство проблем AI сможет исправить.

• Справочные ресурсы: В видео Tina Huang, рекомендованном в заметках, также описан этот метод быстрого исправления ошибок с помощью AI.

4. Что делать, если нужно загружать документы не в формате PDF (Word / Markdown / HTML и т.д.)?

Просто попросите AI расширить.

Слой Loader в проекте использует подключаемую абстрактную конструкцию (BaseLoader), по умолчанию реализован PDF Loader. Если вам нужна поддержка Word, Markdown, HTML и других форматов — точки расширения уже заложены в архитектуре, попросите AI добавить соответствующую реализацию Loader.

Например, скажите AI: «Добавь Loader для Word-документов, по образцу существующего PDF Loader» — AI полностью справится.

5. Как интегрировать в AI-инструменты (Copilot / Cursor / Claude Code и др.)?

Этот проект — MCP Server, который можно интегрировать в любой AI-инструмент и агент, поддерживающий протокол MCP. В моей демонстрации он уже интегрирован в GitHub Copilot и Cursor, вы также можете интегрировать его в Claude Code или другие инструменты с поддержкой MCP.

Как интегрировать? Очень просто — спросите AI.

По сути, для разных инструментов нужно написать конфигурационный файл MCP:

• Copilot (VS Code): Попросите AI сгенерировать конфигурационный файл MCP

• Cursor: Просто импортируйте проект — Cursor распознает его автоматически

• Claude Code / другие фреймворки: Спросите AI, как настроить — способ настройки у каждого инструмента немного отличается, но принцип один

Конечно, рекомендую также разобраться в принципах протокола MCP — понять, как Server и Client общаются, как регистрируются и вызываются Tool. Это тоже плюс на собеседовании.

6. Общая рекомендация: активно используйте AI

Большинство перечисленных выше проблем (переключение Provider, расширение модулей, исправление багов, понимание архитектуры) AI может решить:

• 🔧 Уровень кода: Попросите AI переключить Provider, реализовать методы оценки, исправить баги

• 📖 Уровень знаний: Вопросы по архитектуре проекта, паттернам проектирования — всё можно спросить у AI

• 🚀 Уровень расширения: Хотите добавить новые функции или адаптировать под новые сценарии — опишите требования, и AI реализует

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

📌 Дальнейшие планы

✅ Что будет сделано

• Сводка вопросов по проекту и составление FAQ

• Сборник часто задаваемых вопросов на собеседованиях с эталонными ответами

• Разбор ключевых технических моментов (базовые знания RAG, проектирование архитектуры и т.д.)

• Рекомендации и примеры по «упаковке» резюме

• Личная практика собеседований: Я пойду на собеседования с этим проектом, а все возникшие вопросы и мои ответы обобщу в документации

• Приветствуются материалы от сообщества: Если вы ходили на собеседование с этим проектом, можете прислать мне запись собеседования — я проанализирую вопросы, связанные с проектом, и внесу их в документацию, а также послушаю, какие есть общие рекомендации по улучшению. Так мы сможем совместно развиваться и вместе обобщать и совершенствовать вопросы и ответы по этому проекту

❌ Что не будет делаться

• Не будет дальнейшего расширения функциональности

• Не будет исправления багов, оптимизации дизайна и т.п.

  • При обнаружении багов и точек улучшения — исправляйте и оптимизируйте в своём проекте

  • Дальнейшие расширения и исправления обязательно должны делаться самостоятельно, и с AI это очень легко

  • Это само по себе отличная возможность для обучения и плюс на собеседовании

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

📝 Пояснение личных планов

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

• Обобщать вопросы, возникавшие по этому проекту на собеседованиях

• Систематизировать подходы к ответам и идеи по итеративной оптимизации

• Фиксировать вопросы и ответы с собеседований в документации для общего пользования

📚 Сопутствующие ресурсы

К проекту прилагается полный комплект учебных материалов, включая:

• 🎬 Видеообъяснения: проектирование архитектуры, использование Skill, написание DEV_SPEC, демонстрация полного процесса разработки

• 📝 Заметки для собеседований: подготовка по направлению больших моделей, систематизация ключевых знаний RAG

• ❓ Справочник вопросов для собеседований: реальные вопросы по этому проекту с эталонными ответами

• 📖 Систематизация «восьмигранника»: частые вопросы на собеседованиях по большим моделям / RAG / NLP

👉 Подписывайтесь на Xiaohongshu: 不转到大模型不改名, чтобы получить все указанные ресурсы.