RAG · Экспертный чат-бот по NTC CDMX (2004 / 2017 / 2023)

Система Retrieval-Augmented Generation на основе Normas Técnicas Complementarias del Reglamento de Construcciones de la Ciudad de México, с гибридным поиском (BM25 + мультиязычные эмбеддинги + RRF) и цитированием по редакции и пункту.

Структура

RAG/
├── src/
│   ├── config.py        # rutas y mapeo PDF → (edición, norma)
│   ├── extract.py       # PDF → páginas de texto por norma (temp/extracted_text/)
│   ├── structure.py     # páginas → secciones X.Y.Z (data/corpus/*.json)
│   ├── index_build.py   # secciones → catálogo + BM25 + embeddings (data/index/)
│   ├── retrieve.py      # retriever híbrido (BM25 + embeddings + RRF + numeral)
│   ├── answer.py        # generador de respuestas con LLM (DeepSeek V4 Flash)
│   ├── calc.py          # cálculos validados (viento, sismo, combinaciones)
│   ├── evaluate.py      # evaluación recall@k con el dataset de 21k Q&A
│   └── finetune_gen.py  # genera dataset RAG-formateado para fine-tune del generador
├── app/app.py           # interfaz web (Streamlit)
└── scripts/run_all.py   # orquesta el pipeline completo

MCP-сервер (для opencode, codex, Claude Desktop и т. д.)

Автоматическая установка (регистрирует сервер в opencode и/или codex):

.venv\Scripts\python.exe scripts\install_mcp.py            # opencode + codex
.venv\Scripts\python.exe scripts\install_mcp.py --opencode # solo opencode
.venv\Scripts\python.exe scripts\install_mcp.py --codex    # solo codex

Перезапустите opencode/codex, и RAG будет доступен в виде tools (answer_ntc и т. д.). Сервер читает API-ключ провайдера из RAG/.env, соответствующей переменной окружения или ~/.config/ntc-cdmx/.env.

Установка одной командой (GitHub + uv)

uvx --from git+https://github.com/Sobrio25/ntc-cdmx-mcp ntc-cdmx-install

Эта команда устанавливает и регистрирует MCP в opencode, Codex, Command Code и Kilo Code. Перезапустите клиенты, и answer_ntc, search_ntc и get_section будут доступны. Индекс (BM25 + эмбеддинги) поставляется внутри пакета; API-ключ провайдера настраивается в ~/.config/ntc-cdmx/.env.

Чтобы установить только исполняемый файл:

uv tool install git+https://github.com/Sobrio25/ntc-cdmx-mcp

Проверить сервер вручную:

ntc-cdmx                                     # stdio (modo instalado)
.venv\Scripts\python.exe src\mcp_server.py   # stdio (modo desarrollo)

Пайплайн

# 1) Extraer y estructurar e indexar
.venv/Scripts/python.exe scripts/run_all.py --steps extract structure index

# 2) Evaluar recall del retriever (muestra 400 preguntas del dataset de 21k)
.venv/Scripts/python.exe scripts/run_all.py --steps eval

# 3) Interfaz web
.venv/Scripts/python.exe -m streamlit run app/app.py

Настройка LLM

Ответы используют DeepSeek V4 Flash. Настройте провайдера/API-ключ в src/answer.py (LLM_MODEL, LLM_BASE_URL). Без ключа чат-бот отвечает извлечёнными разделами (без LLM), что полезно для отладки.

Проверенные вычисления (src/calc.py)

Если вопрос требует расчёта (например, «рассчитай давление ветра для Vz=35 м/с»), движок это определяет и использует формулу проверенную по тексту нормы, не обращаясь к LLM. Включены калькуляторы:

Если данных не хватает, чат-бот явно запрашивает их.

Тонкая настройка генератора (src/finetune_gen.py)

Создаёт набор данных в формате chat, где каждый пример включает извлечённый контекст (чтобы генератор учился отвечать из контекста, а не запоминать нормы):

.venv/Scripts/python.exe src/finetune_gen.py --max 2000 --top_k 8 --require_all

Автоматически отфильтровывает примеры, чей «золотой» ответ НЕ подтверждается извлечённым контекстом (отсутствующие цитируемые пункты → отбрасываются).

Оценка

Модуль evaluate.py использует ваш набор данных из Documents\Fine_Tunning\NTC_CDMX\dataset.jsonl: для каждого вопроса с цитируемыми пунктами в «золотом» ответе проверяется, появляется ли этот пункт среди извлечённых разделов.

Базовый результат (выборка 164 вопросов с цитатами, top-6): recall@q ≈ 0.58. Около 18 % пунктов, цитируемых датасетом, не существуют в корпусе своей редакции (возможные ошибочные цитаты в датасете или пробелы извлечения).

Технические примечания

• Редакции 2004 и 2017 выходят в официальных вестниках (по несколько документов на PDF); границы каждой нормы определены в src/config.py.

• Разбиение выполняется по нумерованным разделам (никогда по абзацам), с сохранением формул/таблиц.

• Каждый раздел содержит метаданные {edición, norma, numeral, página} для точного цитирования.

• У PDF-файлов 2023 года имена с повреждёнными символами на диске; экстрактор определяет их по числовому префиксу.