ZVV-MCP mit SpiceAI

Dieses Projekt demonstriert die Integration von SpiceAI in eine Next.js-Anwendung.

Lokale Entwicklung

1. Installiere die Abhängigkeiten:

npm install

2. Installiere die SpiceAI-Runtime:

curl https://install.spiceai.org | /bin/bash

3. Starte die SpiceAI-Runtime:

spice run

4. Starte den Entwicklungsserver:

npm run dev

5. Öffne http://localhost:3000 im Browser

Vercel-Deployment

Für das Deployment auf Vercel benötigst du einen Spice.ai-API-Key:

1. Erstelle einen Account auf spice.ai
2. Erstelle eine App und generiere einen API-Key
3. Verknüpfe dein GitHub-Repository mit Vercel
4. Füge den API-Key als Umgebungsvariable SPICE_API_KEY in deinen Vercel-Projekteinstellungen hinzu
5. Deploye dein Projekt

Funktionen

• SQL-Abfragen an SpiceAI senden
• Ergebnisse in einer Tabelle anzeigen
• Fehlerbehandlung für fehlgeschlagene Abfragen

Technologien

• Next.js 14
• TypeScript
• SpiceAI Client
• Vercel Deployment

Übersicht

ZVV-MCP ist eine Anwendung, die Spice.ai mit Daten von opendata.swiss kombiniert, um öffentliche Verkehrsdaten des Zürcher Verkehrsverbunds (ZVV) mittels LLM abfragbar zu machen.

Features

• Spice.ai Integration: Beschleunigte Datenabfragen für effiziente Verarbeitung großer Verkehrsdatensätze
• opendata.swiss Anbindung: Zugriff auf offizielle ZVV-Daten
• LLM-Abfragen: Natürlichsprachliche Abfrage von Verkehrsinformationen
• Responsive Design: Optimale Nutzung auf allen Geräten

Projektstruktur

• src/: Quellcode der Anwendung
  • components/: Wiederverwendbare UI-Komponenten
  • pages/: Next.js-Seiten und API-Routes
  • styles/: Globale CSS-Stile
• public/: Statische Dateien
• docs/: Dokumentation
• zvv-data/: Spice.ai Konfiguration und Daten

Technische Architektur

Systemkomponenten

Die Anwendung besteht aus drei Hauptkomponenten:

1. Next.js Frontend: React-basierte Benutzeroberfläche
2. Spice.ai Engine: Verarbeitet und analysiert Verkehrsdaten
3. OpenAI Service: Stellt LLM-Funktionalitäten für natürlichsprachliche Abfragen bereit

Datenfluss

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌──────────────┐
│ GTFS-Daten  │───>│ Spice.ai    │<───│ Next.js     │<───│ Benutzer-    │
│ (opendata)  │    │ Engine      │    │ Frontend    │    │ anfrage      │
└─────────────┘    └──────┬──────┘    └──────┬──────┘    └──────────────┘
                          │                   │
                          │                   │
                          │                   ▼
                          │           ┌─────────────┐
                          └──────────>│ OpenAI LLM  │
                                      │ (GPT-4o)    │
                                      └─────────────┘

Sequenzdiagramm für eine Benutzeranfrage

┌─────────┐          ┌─────────┐          ┌──────────┐          ┌────────┐
│ Benutzer│          │ Frontend│          │ OpenAI   │          │Spice.ai│
└────┬────┘          └────┬────┘          └─────┬────┘          └────┬───┘
     │                     │                     │                    │
     │ Stellt Frage        │                     │                    │
     │ zu ZVV-Linien       │                     │                    │
     │────────────────────>│                     │                    │
     │                     │                     │                    │
     │                     │ Verbindungsstatus   │                    │
     │                     │ abfragen            │                    │
     │                     │───────────────────────────────────────────>
     │                     │                     │                    │
     │                     │ Daten-Metadaten     │                    │
     │                     │<───────────────────────────────────────────
     │                     │                     │                    │
     │                     │ LLM-Anfrage mit     │                    │
     │                     │ Kontext & Frage     │                    │
     │                     │────────────────────>│                    │
     │                     │                     │                    │
     │                     │ LLM-Antwort         │                    │
     │                     │<────────────────────│                    │
     │                     │                     │                    │
     │ Antwort anzeigen    │                     │                    │
     │<────────────────────│                     │                    │
     │                     │                     │                    │
┌────┴────┐          ┌────┴────┐          ┌─────┴────┐          ┌────┴───┐
│ Benutzer│          │ Frontend│          │ OpenAI   │          │Spice.ai│
└─────────┘          └─────────┘          └──────────┘          └────────┘

Installation

Voraussetzungen

• Node.js (>= 14.x)
• npm oder yarn
• Spice.ai CLI (siehe docs/installation.md)
• Docker (optional, für Containerisierung)

Setup

# Projektabhängigkeiten installieren
npm install

# Spice.ai installieren (siehe docs/installation.md für Details)
curl -fsSL https://raw.githubusercontent.com/spiceai/spiceai/trunk/install/install.sh | bash

# Spice.ai Projekt initialisieren
spice init zvv-data

Entwicklung

# Next.js Entwicklungsserver starten
npm run dev

# In einem separaten Terminal: Spice.ai Runtime starten
cd zvv-data
spice run

Daten

ZVV GTFS-Daten

Das Projekt verwendet GTFS-Daten (General Transit Feed Specification) vom Zürcher Verkehrsverbund. Die Daten werden im data/-Verzeichnis erwartet und sind in der spicepod.yaml konfiguriert.

Hinweis: Die CSV-Datendateien sind sehr groß und werden nicht im Git-Repository gespeichert. Sie müssen separat heruntergeladen und im data/-Verzeichnis platziert werden.

Folgende Dateien werden benötigt:

• stops.csv - Haltestellen (~5.791 Einträge)
• routes.csv - Linien (~383 Einträge)
• trips.csv - Fahrten (~205.526 Einträge)
• stop_times.csv - Fahrplanzeiten (~3.456.460 Einträge)
• calendar.csv - Betriebstage (~1.695 Einträge)
• transfers.csv - Umsteigeverbindungen (~10.342 Einträge)
• agency.csv - Verkehrsunternehmen
• shapes.csv - Streckenverläufe
• calendar_dates.csv - Zusätzliche Betriebstage/Ausnahmen

Die Daten können von opendata.swiss heruntergeladen werden.

Best Practices

Entwicklung

• Komponenten-Design: Funktionale React-Komponenten mit Hooks verwenden
• Typisierung: TypeScript für statische Typprüfung und bessere IDE-Unterstützung
• State Management: React Context für geteilten Zustand zwischen Komponenten
• CSS-Organisation: Tailwind-Klassen für konsistentes Design

Datenverarbeitung

• Daten-Caching: Spice.ai Beschleunigung für schnelle Abfragen großer Datensätze
• Inkrementelles Laden: Nur benötigte Daten laden, um Leistung zu optimieren
• Error Handling: Robuste Fehlerbehandlung für API-Aufrufe und Datenverarbeitung

LLM-Integration

• Prompt Engineering: Präzise System-Prompts für genaue Antworten
• Kontext-Management: Relevante Daten ins LLM-Prompt aufnehmen
• Antwort-Parsing: Strukturierte Verarbeitung der LLM-Antworten

Produktion

npm run build
npm start

Dokumentation

• Installation von Spice.ai
• Datenmodell
• Projektplan
• LLM-Integration
• API-Dokumentation - OpenAPI/Swagger Spezifikation

Technologie-Stack

• Frontend: Next.js, React, TypeScript, Tailwind CSS
• Datenverarbeitung: Spice.ai
• Datenquellen: opendata.swiss (GTFS-Daten)
• KI-Modelle: OpenAI GPT-4o für natürlichsprachliche Abfragen