Picalike Dokuwiki Archive

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== LillyDB - Die Flauschi-DB ======



==== Übersicht ====

Die DB bietet ein einfaches HTTP-Interface, um ähnliche Produkte für einen Kunden abzufragen. Angebunden wird es über AF-Unix-Sockets in PHP.


==== Dienst ====

Der Dienst kann über ''%%$LILLY_ROOT/bin/lillydb.sh –start%%'' gestartet und mit ''%%–stop%%'' beendet werden. Der Schalter ''%%–status%%'' dient dazu, anzuzeigen ob die Lilly läuft und unter welcher PID.


==== Anforderungen ====

Die benötigte Größe der Festplatte hängt von der Größe der Kunden ab. Generell wird eine ausreichende Menge (50GB+) für Metadaten und Features benötigt. Je mehr RAM-Speicher spendiert wird, desto besser. Minimum sind 16 GB RAM, die Tendenz geht klar zu 32 GB. Da Python echtes Multi-Threading nur über parallele Prozesse abbilden kann, sollte die Maschine über mindestens 4 Kerne verfügen, besser 8.


==== Momentanes Format für die Anfrage ====


  * http://frontend-prelive.picalike.corpex-kunden.de:8080/index.html?uid=182

mit folgenden Parametern:


  * limit: Anzahl der TOP-K Ergebnisse
  * uid: Collection UID
  * id: Image ID
  * elm, ce: Gewichte für Features [0,1]
  * debug: falls gesetzt, wird die Rückgabe als //einfache// HTML-Seite zurückgeliefert.


===== Verzeichnisstruktur =====

Die Lilly residiert im Ordner “lillydb”. Dort liegen die PY-Dateien. Folgende Ordner werden verwendet und müssen existieren:


  * ROOT_DIR/var/run: Lock-Dateien für alle Prozesse
  * ROOT_DIR/var/lilly-data: Hauptverzeichnis für Kundendaten

Im Ordner mit den Kundendaten sieht es wie folgt aus:

<code>
/kunde[921]
 /meta
 /data
</code>
Jeder Kunde hat ein separates Verzeichnis und darunter liegen getrennt Metadaten und Featuredaten.


===== Export aus der Lilly =====

Es ist möglich, Features für eine Liste von Produkten direkt aus der Lilly als JSON zu exportieren. Dafür verwendet man als Anfrage 'export.html?uid=189&id_list=id1,id2, …', um für Kunden 189 die Produkte mit der ID id1, id2 zu exportierten.

Weiterhin besteht die Möglichkeit, ganze Kategorien für einen Kunden zu exportieren: export_category.html?uid=189&id_list=Dingenshalter'. Dabei ist zu beachten, dass die Operation rechnungsintensiv sein kann und damit etwas mehr Zeit benötigt.


===== Mobile =====

Obacht: das Interface ist noch //NICHT// finalisiert und der Code ist veraltet.

Mit curl is es möglich, ein POST mit JSON-Daten zu similieren:

''%% curl -H "Content-Type: application/json" -d "`cat /tmp/out/enrichment.json`" http://localhost:8080/%%''

Die Lilly-DB erwartet dabei als Format genau das, dass auch von pvt-dev erzeugt wird. Beispiel-Anfragen befinden sich im git im 'sample_requests'-Ordner. Bitte darauf achten, dass es jetzt 'ColorDescriptor' heißt, nicht mehr 'ColorExport'.


=== Rückgabe ===

Ein serialisiertes JSON-Objekt:

{ "category": [...], "num_products": 970, [optional] "meta": {"gender": "Damen", "price": "22.99", "brand": "Lascana"}, "topk": [[0.0, "6277733"], [0.0, "6982364"], [1.553, "6638555"], [1.89, "6129509"], [2.06, "4605797"],[2.12, "6868285"], [2.135, "6781222"], [2.22, "6993055"], [2.23, "6191728"], [2.251, "6457596"]], "time": 0.01618}

Details: Dictionary mit folgenden Paaren.


  * category: Kategorie
  * num_products: Menge der Produkte, die untersucht wurden
  * meta: die Metadaten des Produkts
  * topk: Beste Treffer. Liste mit Paaren (DISTANCE, IMAGEID)
  * time: Laufzeit der Anfrage

In den meisten Fällen wird ein 'error' mitgeliefert. Die Wert wird von der API nicht ausgewertet.

Das Interface im Fehlerfall sieht so aus, dass 'topk' **nur einen Eintrag** enthält und zwar das angefragte Bild selbst: {'topk': [{'id': 0xdeadbeef, 'w'}]}. Die API liefert dann nur einen Wert zurück, als Hinweis, dass keine weiteren Treffer gefunden wurden.


===== Export in die Lilly =====

Zwei Arten von Daten werden in der Lilly verwaltet. Die Verwaltung geschieht pro Kunde. Egal welche Art, die Daten sind stets nach Kategorie organisiert. Die Lilly bemerkt automatisch, dass Daten geändert wurden und lädt diese neu.

<HTML><ol></HTML>
  * Metadaten: Also die Beschreibung von Produkten durch Größe, Farbe, Preis, Geschlecht. Diese Daten werden in dem Ordner ''%%meta%%'' direkt unter dem Kundenverzeichnis vorgehalten. Sie sind unabhängig von den Feature-Daten und können somit einzeln aktualisiert werden
  * Featuredaten: Sämtliche Werte zur Beschreibung der Bilder. Momentan 'ExactLegendreMoments' und 'ColorDescriptor'. Die Speicherung geschieht als Matrix im Ordner ''%%data%%'' und es gibt jeweils eine Datei pro Feature. Als zusätzliche Infos werden die Produkt-IDs pro Kategorie gespeichert, sowie das Mapping Produkt-ID nach Position in Matrix.<HTML></ol></HTML>

Ein **manueller Export** kann durch folgende Kommandos angestoßen werden. Alle Kommandos sieht direkt in dem Verzeichnis wo der Quellcode der Lilly residiert auszuführen. Es sollte ein ROOT_DIR gesetzt sein (''%%export ROOT_DIR=/home/picalike/pvt-dev/%%'')


  * Metadaten: ''%%python ./export.py –meta 189%%''. Die Ausgabe sollte mit 189: “total runtime A.B” quittiert werden. Ab diesem Zeitpunkt beantwortet die Lilly mit den neuen Daten.
  * Featuredaten: Falls Daten eines Kunden unbrauchbar geworden sind, könnten diese im Worst-Case-Szenario aus der Mongo-Datenbank exportiert werden. Dies geschieht mit folgendem Befehl: ''%%python ./export –features 189%%''. Hierbei ist zu beachten, dass ggf. sehr viel RAM-Speicher verwendet wird, da die Gruppierung nach Kategorie im Speicher durchgeführt wird. Bei größeren Kunden bedeutetet dies mehrere GB an Daten.

Hinweis: Die Dateien werden erst nach der vollständigen Erzeugung ersetzt, so dass nur in dem Moment des “rename” ein File-Not-Found möglich ist.

Im Normalfall werden die Daten automatisch in die Lilly exportiert und kein manuelles Eingreifen ist notwendig.


===== Daten löschen =====

Falls die Lilly vollständig zurückgesetzt werden soll, erst einmal die cronjobs anhalten(!). Danach muss das root-Verzeichnis komplett gelöscht und wieder neu angelegt werden.

''%%$ cd /mnt/storage/var%%''

''%%$ mv root root-$DATUM%%'' (optional)

''%%$ mkdir root%%''


===== Kunde neu/löschen =====

Falls im FTP-Ordner ein Kunde auftaucht, der noch keinen Ordner in der Lilly hat, wird dieser automatisch erzeugt; manuelle Schritte sind nicht notwendig.

Soll ein Kunde gelöscht werden, reicht das verschieben des Kunden-Ordners aus ''%%var/root%%'' an eine andere Stelle, bzw. der Ordner kann gelöscht werden. Hierbei ist zu beachten, dass zu dem Zeitpunkt keine Anfragen für den Kunden mehr aktiv sind.

In beiden Fällen erkennt die Lilly, dass ein neuer Kunde angelegt, bzw. ein vorhandener Kunde gelöscht wurde und aktualisiert die internen Strukturen. Dies lässt sich einfach in den Logdateien nachvollziehen


===== Übersicht Export-Prozess =====

Sobald ein Kunde zur Berechnung neu angestossen wird, laufen in dem FTP-Ordner auf der Lilly-Maschine Daten ein. Verschiedene Kategorien sind möglich:


  * catInfo: Übersicht welche Kategorien und wie viele Produkte beim Export zu erwarten sind
  * remove: Liste von Produkten, die nicht mehr vom Kunden angeboten werden
  * result: Die eigentlichen Features verknüpft mit Produkt-ID und Kategorie

Als erstes wird der Typ-catInfo erzeugt. Dieser führt dazu, dass die Metadaten des Kunden aktualisiert werden (“.update”-Datei im Kunden-Ordner). Die remove-Datei ist optional und führt zur Löschung der Produkten aus den jeweiligen Matrizen. Es folgen mehrere result-Dateien. Eine Kategorie wird abgeschlossen und aktualisiert, falls der Zähle der Kategorie aus catInfo Null erreicht hat.

Wenn alle Zähler auf Null stehen, ist der Export eines Kunden abgeschlossen. Alle JSON-Dateien werden nach Abarbeitung in den Ordner 'done' im picalike_ftp-Ordner verschoben.

Durchgeführt wird der Export durch folgende cronjobs:


  * new_export.py: Überwacht FTP-Ordner, “locked” jeweils einen Kunden und führt am Ende den Export durch.
  * export.py: Prüft, ob Metadaten aktualisiert werden müssen.


===== Fehlerfälle =====

Aus Erfahrung sind folgende Situation möglich, ggf. mit Lösung


  * Eine result-Datei auf einem Indexer geht kaputt, woraus folgt, dass eine Kategorie in der Lilly nicht abgeschlossen werden kann.
  * Der Export in die Lilly schlug fehl, ggf. da kein Speicherplatz auf Platte. Einfache Lösung, Featuredaten löschen 'data' und alle JSON-Dateien des Kunden aus 'done' wieder in den FTP-Ordner legen. Obacht: funktioniert nur, falls die gesamten Daten im Ordner liegen. Sonst Export aus DB.
  * Es ist kein Problem, falls mehrmals die gleiche Datei aus 'done' verarbeitet wird. Bei jedem Durchgang wird geprüft, ob das Produkt in den Features bereits enthalten ist.