HW RAG + MCP Knowledge Base

Проект строит базу знаний, индексирует ее в Chroma и открывает поиск по базе через MCP-инструмент search_docs.

1. Установка зависимостей

cd hw_rag_mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

2. Переменные окружения

Создайте .env из примера:

cp .env.example .env

Заполните .env:

GIGACHAT_CREDENTIALS=...
GIGACHAT_SCOPE=GIGACHAT_API_PERS
GIGACHAT_MODEL=GigaChat-2-Max
GIGACHAT_EMBEDDINGS=EmbeddingsGigaR
SOURCE_FETCH_TIMEOUT=30

3. Подготовка корпуса

Корпус скачивается автоматически в src/ingest.py из открытых источников:

1. PDF Банка России: кодекс этики ИИ на финансовом рынке.
2. Web-страница Банка России: искусственный интеллект на финансовом рынке.
3. Wikipedia: статья "Искусственный интеллект".
4. Wikipedia: статья "Искусственный интеллект в проектах Викимедиа".

Дополнительно скачивать файлы вручную не нужно.

4. Разбиение и индексация

Запустите ingestion:

python src/ingest.py

Скрипт:

1. скачивает корпус;
2. очищает текст;
3. разбивает документы на фрагменты;
4. добавляет метаданные document_id, chunk_id, source;
5. считает embeddings через EmbeddingsGigaR;
6. сохраняет индекс в Chroma collection course_rag.

После успешного запуска появится папка:

data/chroma_db/

5. Запуск MCP-сервера

MCP-сервер находится в src/mcp_server.py.

python src/mcp_server.py

Сервер использует stdio transport. В обычном сценарии его запускает MCP-клиент, например src/agent_demo.py.

Пример MCP-конфигурации:

{
  "knowledge_base": {
    "transport": "stdio",
    "command": "python3",
    "args": ["src/mcp_server.py"]
  }
}

Публикуемые возможности:

• resource kb://corpus/stats;
• tool search_docs(query, k);
• tool search_by_source(source_id, query, k).

6. Демонстрационный запрос

Проверка поиска напрямую через Chroma:

python src/search_demo.py --k 3

Проверка поиска через агента и MCP:

python src/agent_demo.py

В выводе agent_demo.py должно быть видно:

1. MCP tools загружены;
2. агент вызвал search_docs;
3. результат содержит top-k фрагменты с document_id, chunk_id, source и score.

7. Проверка на 15 запросах

Список запросов:

eval/eval_queries.csv

Запуск проверки:

python src/eval_search.py

Скрипт создает:

eval/eval_results.jsonl
eval/eval_report.md

eval_report.md содержит top-k результаты, ожидаемый источник, признак попадания в top-3 и краткую ручную оценку.