/projekte/detect-api/Open Source/Live/04/2026 → laufend/Alleinentwickler

detect_api

Selbst betriebene Plattform zur Bild- und Videoklassifikation für mehrere Mandanten.

Läuft im Eigenbetrieb auf eigener GPU-Hardware. Der Code ist öffentlich, der Betrieb nicht.

Keine öffentliche Demo — der Dienst läuft auf eigener GPU-Hardware hinter API-Keys. Zugang auf Anfrage.

PythonFastAPISQLAlchemyAlembicPostgreSQLRedisNext.jsTypeScriptMantineDockerYOLONudeNetCLIPffmpegJWT
project dossier

Snapshot

detect-api

Alleinentwickler

category

Open Source

status

LIVE

stack

15 tech

code

22.862 Zeilen
PythonFastAPISQLAlchemyAlembicPostgreSQLRedisNext.js
Source öffnen
01

Story

Problem

Bild- und Videoinhalte mehrerer Mandanten mussten automatisch klassifiziert werden, ohne die Daten an einen externen Dienst zu geben.

Lösung

Eigene Plattform mit YOLO-basierter Erkennung, Warteschlangen-Verarbeitung, API-Key-Verwaltung je Mandant und Admin-Dashboard; GPU-Anbindung auf eigener Hardware.

Learnings

Die Modell-Inferenz war der kleinere Teil. Ob der Dienst unter Last brauchbar bleibt, entscheiden Queueing, Timeouts und Wiederholungen.

02

Key Features

features.md
  • →Mandantentrennung über eigene API-Keys und Kontingente
  • →Bild- und Videoanalyse mit YOLO auf eigener GPU
  • →Warteschlangen-Verarbeitung mit Wiederholung nach Fehlern
  • →Admin-Dashboard für Mandanten und Auswertung
03

Über das Projekt

README.md

Plattform zur automatischen Klassifikation von Bild- und Videoinhalten für mehrere Mandanten. Erkennung auf YOLO-Basis läuft auf eigener GPU-Hardware, die Verarbeitung über Warteschlangen. Jeder Mandant hat eigene API-Keys und Kontingente, die Auswertung läuft über ein Admin-Dashboard.

04

Meine Rolle

rolle
rolle:Alleinentwickler
  • Aufteilung in vier Dienste, gemeinsames Datenmodell und Alembic-Migrationen
  • Modellanbindung: NudeNet, EraX-YOLO11m und CLIP, inklusive Ensemble-Zusammenführung
  • Mandantentrennung: API-Keys gehasht, Pläne, Kontingente, Nutzungsprotokoll
  • Asynchrone Jobs mit signierten Webhooks und Wiederholung nach Fehlern
  • Admin-Dashboard in Next.js, zweisprachig
  • Betrieb: Docker-Compose-Varianten für GPU, Redis und Traefik
05

Architektur

architecture.md

Vier Dienste in einem Compose-Stack, jeder mit einer klaren Aufgabe:

  • api (FastAPI, Port 8000) — die Erkennung selbst: Bild- und Videoklassifikation, Zensieren, Batch, CLIP-Embeddings, Moderation, Pose, Szenenschnitt.
  • auth (FastAPI, Port 8001) — alles rund um Mandanten: JWT-Login, API-Keys (Master und persönlich, nur gehasht gespeichert), Pläne, Nutzungsprotokoll, Webhooks.
  • studio (Next.js 16 + Mantine 9, Port 3000) — Admin-Dashboard mit Upload-Oberfläche, Demo-Seite und zweisprachiger Oberfläche.
  • db — PostgreSQL im Docker-Betrieb, SQLite lokal. Beide hinter derselben SQLAlchemy-Schicht, Schemaänderungen über Alembic.

Redis ist optional zuschaltbar und übernimmt dann dreistufiges Rate-Limiting und einen Ergebnis-Cache über den SHA-256 des Bildes.

Die Modelle sind austauschbar: NudeNet (640m) und EraX-YOLO11m laufen einzeln oder als Ensemble auf demselben Input. Überlappende Treffer werden über ein gemeinsames concept zusammengeführt; das Feld sources zeigt, welches Modell den Treffer stützt. Für kleinere Maschinen lässt sich die EraX-Modellgröße per Environment auf s oder n drehen, ohne am Code zu drehen.

Erkennung (api)

Bild- und Videoklassifikation, Zensieren mit H.264-Ausgabe über ffmpeg, Batch-Verarbeitung, Szenen-Extraktion aus Videos.

FastAPIYOLONudeNetffmpeg

CLIP-Endpunkte

768-dimensionale Embeddings, Cosine-Vergleich zweier Bilder, freies Tagging und Altersschätzung.

CLIPPython

Mandanten und Schlüssel (auth)

JWT-Login, Master- und persönliche API-Keys (gehasht), Pläne mit Kontingenten, Nutzungsprotokoll je Schlüssel.

FastAPIJWTSQLAlchemy

Asynchrone Jobs

Batch und Video laufen auf Wunsch asynchron: sofort eine job_id, Ergebnis per Webhook, Status über /jobs/{id}. Webhooks sind HMAC-signiert und werden mit Backoff wiederholt.

FastAPIWebhooksHMAC

Studio

Admin-Dashboard: Mandanten, Schlüssel, Auswertung, Upload-Oberfläche und Demo. Zweisprachig, mit Fehlergrenzen und Toasts.

Next.jsMantineTypeScript

Datenschicht

Eine SQLAlchemy-Schicht für PostgreSQL (Docker) und SQLite (lokal), Migrationen über Alembic. Dadurch braucht die lokale Entwicklung keinen Datenbank-Container.

SQLAlchemyAlembicPostgreSQL
06

Herausforderungen

Zwei Modelle, ein Ergebnis
Problem

NudeNet und EraX-YOLO11m erkennen unterschiedlich gut und liefern unterschiedliche Labels. Beide laufen zu lassen brachte zwei Trefferlisten, die sich überlappten — der Aufrufer hätte sie selbst zusammenführen müssen.

Lösung

Ein gemeinsames `concept` je Treffer, über das überlappende Funde zusammengelegt werden. Das Feld `sources` sagt, welches Modell den Treffer stützt. Für den Aufrufer ist der Ensemble-Lauf ein einzelner Request mit einer Ergebnisliste.

Lange Videos blockierten die Verbindung
Problem

Batch und Videoanalyse liefen synchron. Bei großen Archiven und langen Videos hing der Client an einer offenen HTTP-Verbindung, bis alles durch war — mit allen Timeout-Problemen, die daran hängen.

Lösung

`?async=true` für /batch und die Video-Endpunkte: sofort eine job_id, Ergebnis über den bestehenden Webhook-Dispatcher mit HMAC und Backoff, dazu mandantengetrennte /jobs/{id}-Endpunkte. Die Ereignisse heißen job.completed und job.failed.

Lokale Entwicklung ohne Docker
Problem

Der Produktivbetrieb braucht PostgreSQL, GPU und ffmpeg. Wer nur einen Endpunkt ändern wollte, musste den kompletten Stack hochziehen.

Lösung

Eine gemeinsame SQLAlchemy-Schicht für SQLite (lokal) und PostgreSQL (Docker), plus ein Makefile mit `make dev-local` und Einzelzielen je Dienst. Modelle werden bei Bedarf automatisch nachgeladen.

07

Technologie-Entscheidungen

Python

Projektabhängigkeit

FastAPI

Projektabhängigkeit

SQLAlchemy

Projektabhängigkeit

Alembic

Projektabhängigkeit

PostgreSQL

Objekt-relationale Open-Source-Datenbank mit JSONB, FTS und reicher Erweiterbarkeit.

database
Redis

Projektabhängigkeit

Next.js

React-Framework mit App Router, RSC und Hybrid-Rendering.

framework
TypeScript

Typsicheres Superset von JavaScript.

language
Mantine

Projektabhängigkeit

Docker

Container-Plattform für reproduzierbare Build-/Deploy-Pipelines.

infrastructure
YOLO

Projektabhängigkeit

NudeNet

Projektabhängigkeit

CLIP

Projektabhängigkeit

ffmpeg

Projektabhängigkeit

JWT

Projektabhängigkeit

08

Codebasis

codebase
Codezeilen22.862
Dateien122
Sprachen
  • TypeScript/TSX54%
  • Python44%
  • Shell2%
09

Repository

11

Verwandte Projekte