RAG · Experten-Chatbot für NTC CDMX (2004 / 2017 / 2023)

Retrieval-Augmented-Generation-System über die Normas Técnicas Complementarias del Reglamento de Construcciones de la Ciudad de México, mit hybrider Suche (BM25 + multilinguale Embeddings + RRF) und Zitaten nach Ausgabe und Abschnittsnummer.

Struktur

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-Server (für opencode, codex, Claude Desktop, etc.)

Das Projekt wird als MCP-Server mit drei Tools bereitgestellt:

Automatische Installation (registriert den Server in opencode und/oder 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

Starten Sie opencode/codex neu, und der RAG steht als Tools (answer_ntc, usw.) zur Verfügung. Der Server liest den API-Schlüssel des Anbieters aus RAG/.env, der entsprechenden Umgebungsvariable oder ~/.config/ntc-cdmx/.env.

Installation mit einem einzigen Befehl (GitHub + uv)

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

Dieser Befehl installiert und registriert das MCP in opencode, Codex, Command Code und Kilo Code. Starten Sie die Clients neu, und answer_ntc, search_ntc und get_section sind verfügbar. Der Index (BM25 + Embeddings) wird im Paket mitgeliefert; der API-Schlüssel des Anbieters wird in ~/.config/ntc-cdmx/.env konfiguriert.

Um nur die ausführbare Datei zu installieren:

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

Den Server manuell testen:

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

Pipeline

# 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 konfigurieren

Die Antworten verwenden DeepSeek V4 Flash. Konfigurieren Sie den Anbieter/API-Schlüssel in src/answer.py (LLM_MODEL, LLM_BASE_URL). Ohne Schlüssel antwortet der Chatbot mit den abgerufenen Abschnitten (ohne LLM), was zum Debuggen nützlich ist.

Validierte Berechnungen (src/calc.py)

Wenn die Frage eine Berechnung verlangt (z. B. „Berechne den Winddruck für Vz=35 m/s“), erkennt die Engine dies und verwendet eine gegen den Normentext verifizierte Formel, ohne den LLM einzusetzen. Enthaltene Rechner:

Fehlen Daten, fragt der Chatbot explizit danach.

Fine-Tuning des Generators (src/finetune_gen.py)

Erzeugt einen Datensatz im Chat-Format, bei dem jedes Beispiel den abgerufenen Kontext enthält (damit der Generator lernt, aus dem Kontext zu antworten, anstatt die Normen auswendig zu lernen):

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

Filtert automatisch die Beispiele heraus, deren „Gold“-Antwort NICHT durch den abgerufenen Kontext gestützt wird (fehlende zitierte Abschnittsnummern → werden verworfen).

Evaluierung

Das Modul evaluate.py verwendet Ihren Datensatz aus Documents\Fine_Tuning\NTC_CDMX\dataset.jsonl: Für jede Frage mit zitierten Abschnittsnummern in der „Gold“-Antwort wird geprüft, ob die Abschnittsnummer unter den abgerufenen Abschnitten vorkommt.

Referenzergebnis (Stichprobe 164 Fragen mit Zitat, Top-6): recall@q ≈ 0.58. Etwa 18 % der vom Datensatz zitierten Abschnittsnummern existieren nicht im Korpus ihrer Ausgabe (möglicherweise falsche Zitate im Datensatz oder Extraktionslücken).

Technische Hinweise

• Die Ausgaben 2004 und 2017 stammen aus Amtsblättern (mehrere Dokumente pro PDF); die Grenzen jeder Norm sind in src/config.py hinterlegt.

• Die Aufteilung erfolgt nach nummerierten Abschnitten (niemals nach Absätzen), wobei Formeln/Tabellen erhalten bleiben.

• Jeder Abschnitt trägt Metadaten {edición, norma, numeral, página}, um präzise zu zitieren.

• Die PDFs von 2023 haben auf der Festplatte Dateinamen mit beschädigten Zeichen; der Extraktor löst diese über ein numerisches Präfix auf.