Zum Inhalt springen
← Alle Projekte

Songtexte-API mit Flet-Frontend

Ein Backend zur Verwaltung von Liedtexten, das zwei Suchwelten verbindet: exakte Stichwortsuche über eine relationale Datenbank und semantische Ähnlichkeit über Vektor-Embeddings – zusammengeführt zu einer Hybrid-Suche, die auch findet, was nicht wörtlich passt.

Status
Studienprojekt
Rolle
Konzeption & Umsetzung
Jahr
Aktualisiert
PythonFastAPISQLiteChromaDBSentence Transformers

Auf einen Blick

  • Hybrid-Suche: SQL-Stichwortsuche und ChromaDB-Vektorsuche werden zusammengeführt statt gegeneinander ausgespielt.
  • SQLite hält die Wahrheit, der Vektorindex wird jederzeit reproduzierbar daraus abgeleitet.
  • Spracherkennung vor der Suche, damit Anfrage und Treffer im selben Sprachraum liegen.
  • PowerPoint-Export mit QR-Code direkt aus der API.

Ausgangspunkt

Ein Bestand von Liedtexten lässt sich auf zwei Arten durchsuchen, und beide sind für sich unvollständig. Die Stichwortsuche findet nur, was wörtlich dasteht – wer sich an eine Zeile falsch erinnert oder ein Synonym eingibt, findet nichts. Die semantische Suche über Embeddings findet inhaltlich Verwandtes, verfehlt aber gelegentlich genau den Treffer, dessen Titel man exakt eingetippt hat. Die Frage dieses Projekts war deshalb nicht „Stichwort oder Vektor“, sondern: wie kombiniert man beides, ohne dass die eine Suche die Stärke der anderen verwässert?

Architektur

Architektur der Hybrid-SucheEine Suchanfrage wird sprachlich erkannt und parallel an zwei Suchen gegeben: eine Stichwortsuche über die relationale SQLite-Datenbank und eine semantische Vektorsuche über ChromaDB mit Sentence-Transformer- Embeddings. Beide Ergebnisse werden zu einem gewichteten Hybrid-Ergebnis zusammengeführt.SuchanfrageSprache erkannt · langdetectStichwortsucheSQL über SQLite · SQLAlchemySemantische SucheVektorsuche in ChromaDBSentence-Transformer-EmbeddingsZusammenführunggewichteter Hybrid-ScoreTreffer + ähnliche SongsWortlaut und Bedeutung kombiniert
Eine Anfrage läuft parallel in eine relationale Stichwortsuche und eine semantische Vektorsuche; die beiden Trefferlisten werden zu einem gewichteten Hybrid-Ergebnis zusammengeführt.

Das Backend ist eine FastAPI-Anwendung mit SQLAlchemy. Bedienen lässt es sich über die Swagger-UI unter /docs oder ein optionales Flet-Frontend, das nur über HTTP mit der API spricht. Interessant wird es bei der Suche.

Zwei Speicher, eine Quelle der Wahrheit

Die relationale SQLite-Datenbank ist die maßgebliche Ablage: Sie hält die Songs, ihre Metadaten und ist das, was bei Schreibvorgängen zählt. Die Embeddings in ChromaDB sind dagegen ein abgeleiteter Index – er wird über scripts/reindex.py aus dem relationalen Bestand aufgebaut und lässt sich jederzeit neu erzeugen. Diese Trennung ist bewusst: Der Vektorindex darf verloren gehen, ohne dass Daten verloren gehen. Sie ist zugleich die ehrlichste Einschränkung des Aufbaus, siehe unten.

Hybrid-Suche

Der Kern ist die Hybrid-Suche: Eine Anfrage geht gleichzeitig an die SQL-Stichwortsuche und an die semantische Ähnlichkeitssuche in ChromaDB, die die Anfrage in ein Sentence-Transformer-Embedding übersetzt und die nächstgelegenen Songs zurückgibt. Die beiden Trefferlisten werden anschließend zusammengeführt, statt sich gegenseitig auszuschließen. Ergänzend bietet die API die reinen Einzelmodi an – /songs/semantic für die pure Bedeutungssuche und /songs/{id}/similar, um zu einem Song die inhaltlich nächsten zu finden.

Mehrsprachigkeit als Vorstufe der Suche

Der Bestand ist mehrsprachig, also darf die Suche es nicht ignorieren. Über langdetect wird die Sprache der Anfrage erkannt, bevor gesucht wird – so landen Anfrage und Treffer im selben sprachlichen Raum, statt dass eine deutsche Anfrage an englischen Embeddings vorbeiläuft.

Mehr als Suche: Präsentationen auf Knopfdruck

Der praktische Anlass hinter dem Projekt war die Bühne, nicht die Datenbank. Über /songs/{id}/ppt erzeugt der Dienst mit python-pptx aus einem Liedtext eine fertige PowerPoint-Präsentation – inklusive eines QR-Codes, der von der Projektion oder dem Ausdruck direkt zum Song zurückführt. Dazu kommt ein versionierter JSON-Export des Bestands über /songs/export. Damit ist dieselbe Kernidee wie in einem früheren Projekt umgesetzt, hier aber sauber hinter einer API statt als loses Skript.

Grenzen

Das Projekt ist als Lern- und Demonstrationssystem gebaut, und die Grenzen gehören zur ehrlichen Beschreibung:

  • SQLite ist eine Ein-Datei-Datenbank – ideal für lokalen Betrieb und Demo, nicht für viele gleichzeitige Schreibzugriffe.
  • Der Vektorindex muss nach Änderungen am Bestand neu aufgebaut werden; eine automatische Synchronisation von SQLite nach ChromaDB bei jedem Schreibvorgang ist nicht Teil des Aufbaus.
  • Es gibt keine Authentifizierung und keine Rollen – die API geht von einer vertrauenswürdigen, lokalen Umgebung aus.
  • Die Trefferqualität der semantischen Suche hängt am gewählten Embedding-Modell und ist nicht auf den konkreten Liedtext-Bestand feinabgestimmt.