Gemischte Signale: Verwendung der Signals API von Lucidworks Fusion

Ein weiterer fantastischer Gastbeitrag von Sean Mare von Knowledgent. Aufgrund der vielen Codeschnipsel finden Sie hier eine herunterladbare Version des…

Ein weiterer fantastischer Gastbeitrag von Sean Mare von Knowledgent. Aufgrund der vielen Codeschnipsel finden Sie hier eine herunterladbare Version des Beitrags zum leichteren Ausschneiden und Einfügen.

Eine meiner Lieblingsfunktionen in Lucidworks Fusion ist die Signals API – ein RESTful, flexibler, einfach zu implementierender Mechanismus zur Erfassung interessanter Benutzerereignisse, wie(aber nicht nur) Abfragen und Ergebnisklicks, und der damit verbundenen Metadaten. Wenn Signale für eine Sammlung aktiviert sind (das ist die Standardeinstellung – es sei denn, die Sammlung wurde mit der REST-API erstellt), erstellt Fusion automatisch eine entsprechende „Signals“-Sammlung, in der die an die Signals-API übermittelten Signal-Rohdaten indiziert werden. Wenn Sie mit Fusion arbeiten, haben Sie vielleicht schon bemerkt, dass mehrere Sammlungen angezeigt werden, wenn eine neue Sammlung erstellt wird. Diese Signals-Sammlung wird nach der ursprünglichen Sammlung mit dem Suffix „_signals“ benannt. Wenn Sie zum Beispiel eine Signals-Sammlung mit dem Namen „periodicals“ haben, erstellt Fusion automatisch eine Sammlung mit dem Namen „periodicals_signals“. Alle Signals-API-Aufrufe beziehen sich auf die ursprüngliche Sammlung, da die API die Signals-Sammlung verwaltet. Daher sollten alle Signale-API-Aufrufe an die Sammlung „periodicals“ gerichtet werden, und sie werden automatisch in „periodicals_signals“ indiziert.

Eine weitere Sammlung, die Ihnen vielleicht aufgefallen ist, ist die Sammlung der aggregierten Signale, die nach der Signalsammlung mit dem Suffix „_aggr“ benannt ist; für das vorherige Beispiel würde die Aggregations-Sammlung „periodicals_signals_aggr“ heißen. Die Aggregation ist die automatisierte Methode, mit der Fusion die rohen Signaldaten aufnimmt und sie zu Zusammenfassungen, Metriken und anderen wichtigen Leistungsindikatoren verarbeitet, die indiziert und in der oben erwähnten Sammlung gespeichert werden. Diese Sammlung kann dann über das Fusion Dashboard visualisiert oder für Empfehlungen abgefragt werden.

Diejenigen unter Ihnen, die mit Lucidworks Search, der Vorgängerplattform, gearbeitet haben, erinnern sich vielleicht noch an das „Click Scoring Relevance Framework„, das in der Regel nur als „Click Scoring“ bezeichnet wird – eine unkomplizierte API, die eine begrenzte Anzahl von Daten in einer Protokolldatei erfasst, die LWS dann nach einem bestimmten Zeitplan analysieren kann. Die Signale von Fusion sind in vielerlei Hinsicht ein großer Schritt nach vorn:

• Wie bereits erwähnt, werden rohe und aggregierte Signale in Sammlungen erfasst, mit all den Vorteilen, die das bietet
• Zusätzlich zu einigen vordefinierten Parametern (wie Ereignistyp und Zeitstempel) kann die API eine beliebige Anzahl von benutzerdefinierten Parametern akzeptieren
• Rohsignaldaten können nahezu in Echtzeit in einer Vielzahl von Formaten visualisiert werden

Die neueste Version bietet noch weitere Vorteile, die sich jedoch direkt auf den ersten Schritt der Analyse, Visualisierung und Empfehlungen beziehen: die Erfassung von Ereignissen mithilfe der Signals API.

Senden von Signalen

Wie bereits erwähnt, ist die Signals API eine RESTful-Schnittstelle. Sie akzeptiert POSTs, bei denen der Anfragekörper aus JSON besteht, das einige vordefinierte Parameter und eine beliebige Anzahl von benutzerdefinierten Parametern enthält, die dazu dienen, interessante Ereignisse zu erfassen, die bei der Interaktion eines Benutzers mit der Suche auftreten. Der erste Schritt bei der Erstellung der Anfrage besteht darin, zu bestimmen, welche der vollständigen Liste von Eingabeparametern explizit zugewiesen werden sollen und welche, wenn überhaupt, benutzerdefinierten Parameter erfasst werden sollen. Von den vordefinierten Parametern gibt es nur einen obligatorischen Parameter, „type“ (andere wichtige Parameter wie „id“ und „timestamp“ sind optional; wenn sie nicht vorhanden sind, erstellt die API Standardwerte und weist sie zu); „type“ kann eine beliebige benutzerdefinierte Zeichenkette sein , sollte aber konsequent angewendet werden, um eine genaue Aggregation zu gewährleisten. Zwei der interessanteren Interaktionen, die ein Benutzer mit der Suche hat, sind die Abfragen, die er stellt (type=“query“) und die Ergebnisse, die er auswählt (type=“click“), daher sehen wir uns Beispiele für API-Anfragen für beide an. In allen Beispielen gibt die API den Zeitstempel und die ID vor, und es sind einige benutzerdefinierte Parameter definiert (je nach Ereignistyp). Die Signals-API akzeptiert Anfrageparameter im JSON-Format, daher werden wir zunächst die Struktur und den Inhalt unserer JSON-Ereignisse definieren und dann zeigen, wie sie an die REST-API gesendet werden.

Ereignisse abfragen

Dies ist ein Ereignis des Typs „Abfrage“, das den Abfrage-String eines Benutzers erfasst, damit wir verstehen, wie die Benutzer suchen. Es erfasst auch die Anmelde-ID des Benutzers und die Gesamtergebnisse für die Abfrage.

Hier ist ein Beispiel für einen JSON-String, der ein Abfrageereignis darstellt und diese Felder erfasst:

Diese Zeichenkette kann über jeden Ihnen zur Verfügung stehenden Mechanismus erstellt werden – hier ein Beispiel für die Erstellung dieses Ereignisses in Ruby (aus der Komponente catalog_controller einer Blacklight-fähigen Ruby on Rails-Anwendung ):

Beachten Sie die Verwendung der Eigenschaft „params“ zur Definition von benutzerdefinierten Feldern (user, numresults). Hier können beliebig viele zusätzliche Felder hinzugefügt werden, um nützliche Informationen für eine spätere Analyse zu erfassen.

Ereignisse anklicken

Hier definieren wir ein Ereignis vom Typ „Klick“, das immer dann ausgelöst wird, wenn ein Benutzer auf ein Suchergebnis klickt. Wir wollen feststellen, welche Ergebnisse von den Nutzern für eine bestimmte Anfrage tatsächlich untersucht werden. Daher erfassen wir nicht nur den Nutzer und seine Anfrage, sondern auch die ID des Ergebnisdokuments, auf das der Nutzer geklickt hat, und die Bewertung dieses Dokuments. Hier ist ein Beispiel für einen JSON-String, der diese Informationen erfasst:

Hier ist ein Beispiel für die Erstellung dieses JSON in Ruby on Rails:

POSTing der Anfrage

Nun, da die Ereignisdaten erfasst und als JSON formatiert sind, können sie an die Signals REST API gesendet werden. Der Pfad für die Anfrage lautet <serverName>:8764/api/apollo/signale/<collectionName>, wobei <serverName> ist die IP-Adresse oder der Rechnername des Fusion-API-Servers, und <collectionName> ist der Name der Sammlung, für die Sie Signale erfassen möchten. Bei der Sammlung „Zeitschriften“ würde die URL http://fusionserver.local:8764/api/apollo/signals/periodicals lauten.

Die Signals API akzeptiert einige Anfrageparameter:

• commit, ein Flag, das, wenn es auf true gesetzt ist, Fusion anweist, am Ende der Indizierung einen Commit durchzuführen
• async, ein Flag, das, wenn es auf true gesetzt ist, Fusion anweist, Signale asynchron zu indizieren (und autoCommit auszulösen und Fehlerberichte zu unterdrücken.) Wenn es (wie in diesem Beispiel) weggelassen wird, ist dieses Flag standardmäßig false.
• Pipeline, mit der Sie eine bestimmte Index-Pipeline für die Indizierung der Signale definieren können. Wenn sie nicht angegeben wird (wie in diesem Fall, da wir keine erweiterten Anforderungen für die Aufnahme von Signalen haben), verwendet Fusion standardmäßig die vorkonfigurierte Pipeline „signals_ingest“.

Neben den Anfrageparametern sollte der Anfrage-Header „Content-Type“ auf „application/json“ gesetzt werden, da JSON das Format des Anfragekörpers ist. Außerdem verlangt Fusion von API-Clients eine Authentifizierung – der Anfrage-Header muss für eine einfache Authentifizierung mit einem gültigen Benutzernamen und Passwort konfiguriert werden.

Um die Anfrage mit den entsprechenden Kopfzeilen, Parametern und Textkörpern an die Beispielsammlung „Periodika“ zu senden, könnten wir also den folgenden curl-Befehl ausführen:

Dies ist zwar nützlich, um alle Anforderungen an eine gut formatierte API-Anfrage zu veranschaulichen, aber die Wahrscheinlichkeit, dass Signale mit curl in einem realen Szenario erfasst werden, ist geringer als mit anderen Mechanismen. Höchstwahrscheinlich werden die Ereignisse in Echtzeit und nicht durch einen Batch-Prozess indiziert, was je nach Art des erfassten Ereignisses und der Art, wie das Ereignis an die Signals-API übermittelt wird, einige Komplexitäten mit sich bringt. Die bisherigen Beispiele veranschaulichen die Erfassung von Signaldaten aus einer Live-Anwendung, die in Ruby on Rails implementiert ist und das Blacklight-Gem für die Solr-Integration verwendet. Wir werden die Signals in diesem Kontext weiter erforschen – aber diese Beispiele könnten leicht auf ein anderes Implementierungs-Framework portiert werden.

Das Signal „Abfrage“ wird von einer serverseitigen Komponente gesendet, die von Blacklight erweitert wurde und als Schnittstelle zu Solr fungiert. Die Signals API-Anfrage erfolgt nach dem Empfang der Ergebnisliste von Solr (aber vor dem Rendern der Ergebnisse). Diese Komponente ist eine Ruby-Klasse, so dass einfacher Ruby-Code zum Erstellen und Ausführen der Anfrage verwendet wird.

Das „Klick“-Signal wird anders erfasst. Da das Klick-Signal als das Ereignis definiert ist, das eintritt, wenn ein Benutzer ein Dokument aus einer Liste von Suchergebnissen auswählt, wäre es sinnvoll, diese API-Anfrage in die Benutzeroberfläche einzubetten und nicht auf dem Server. Der naheliegendste Ansatz ist der Aufruf einer JavaScript-Methode für das Ergebnis (vielleicht implementiert als onclick()-Methode eines Dokumenttitels in der Ergebnisliste), die die Signals-API-Anfrage stellt. AngularJS ist ein beliebtes Webanwendungs-Framework, das umfangreiche clientseitige Funktionen bietet, die sich gut für diese Art der Implementierung eignen.

Ein Link zu dieser Methode kann dann in jedes Ergebnis eingebettet werden.

Dieser Ansatz funktioniert, solange sich der Client auf demselben Rechner befindet wie die Fusion-API (d.h. im obigen Beispiel ist die Anwendung, die die Signalanfragen übermittelt, auf demselben Rechner wie Fusion installiert). In einer typischen Produktions- (und Test- und höchstwahrscheinlich auch Entwicklungs-) Umgebung würden diese Anwendungen jedoch auf verschiedenen Rechnern eingesetzt. Wenn Sie in einer solchen Umgebung auf ein Suchergebnis klicken, um sendClickSignal auszulösen , tritt ein Fehler auf:

Für die Unwissenden: Diese Meldung beschreibt einen CORS-Fehler. Zum Schutz vor der Ausführung von bösartigem Code schränkt die Signals API HTTP-Anfragen von einer anderen Domäne außerhalb der Domäne ein, aus der die Ressource stammt (daher der Erfolg des serverseitigen Beispiels). Es gibt eine Reihe von Möglichkeiten, damit umzugehen, und fast alle implementieren letztendlich eine Art Proxy, der sich in derselben Ursprungsdomäne befindet, Anfragen von Clients annimmt und sie an den Server weiterleitet (eine Alternative, die kein Proxy ist, wäre JSONP, die leider unterstützt keine Basisauthentifizierung.) Für viele Unternehmensanwendungen ist ein dedizierter, laufender CORS-Proxy-Dienst keine praktikable Lösung, aber eine einfache serverseitige Komponente in Ihrer Anwendung kann mit minimalem Aufwand wie ein Proxy fungieren. Senden Sie eine JavaScript-Funktion, die alle erforderlichen Felder übergibt, an die Komponente. Von dort aus erstellt und sendet die Komponente die Signals-API-Anfrage.

Die folgende JavaScript-Funktion verwendet die jQuery.ajax()-API, um asynchron an einen Ruby on Rails-Controller zu posten (Sie könnten jedoch problemlos an jede beliebige serverseitige Komponente posten, die auf Anfragen wartet).

Der Controller verwendet dann den gleichen Mechanismus wie die Signalanforderung „query“, um an die Signals API zu senden.

Da der Abfrageparameter „commit“ in den Signals-API-Anfragen explizit auf „true“ gesetzt ist, stehen die Rohereignisse und ihre Daten sofort zur Ansicht zur Verfügung.

Signale visualisieren

Da nun einige Signale indiziert sind, ist es an der Zeit, sich mit den Dashboards und der Visualisierung der Daten vertraut zu machen. Die Fusion Dashboards finden Sie unter http://<fusion_home>:8764/banana/index.html#/dashboard. Das Standard-Dashboard ist „Fusion Logs“. Navigieren Sie also zum Dashboard „Signale“, indem Sie auf „Lucidworks Fusion Signals“ im Bereich „Explore Dashboards“ klicken:

Im Dashboard von Fusion Signals müssen wir auf unsere Signalsammlung verweisen. Zuvor müssen wir jedoch das vom Dashboard verwendete Standardzeitfeld ändern. Klicken Sie im Panel „Zeitspanne festlegen“ auf das Zahnradsymbol in der oberen rechten Ecke, um das Fenster „Timepicker-Einstellungen“ zu öffnen und wählen Sie die Registerkarte „Panel“:

Ändern Sie den „Standardmodus“ in „relativ“, „Standardzeitspanne“ in „30d“ und vor allem das „Zeitfeld“ in „timestamp_tdt“:

Jetzt können wir unsere Signalsammlung auswählen. Klicken Sie dazu auf das Zahnradsymbol in der oberen rechten Ecke des Dashboards (beachten Sie das Panel „Erste Schritte“, das diese Anweisungen enthält):

Das Fenster „Dashboard-Einstellungen“ wird geöffnet. Klicken Sie auf die Registerkarte „Solr“ und ändern Sie „Sammlung“ in den Namen Ihrer Signalsammlung:

Das Dashboard wird automatisch aktualisiert und die Standardpanels zeigen Metriken für die in der Sammlung indizierten Signale an:

Nächste – Signal-Aggregation

Die Rohsignale zeigen zwar einige interessante Informationen, aber damit die Daten wirklich nützlich sind, müssen Sie sie aggregieren – die Rohsignale einlesen und interessante Zusammenfassungen zurückgeben, die von einfachen Summen bis hin zu ausgefeilten statistischen Funktionen reichen. Wir werden die Aggregation von Signalen in einem zukünftigen Blogbeitrag anhand der Signale, die wir jetzt mit der Signals API erfassen, untersuchen.

Über den Autor

Sean Mare ist ein Technologe mit fast 20 Jahren Erfahrung in der Konzeption und Entwicklung von Unternehmensanwendungen. Als Solution Architect bei Knowledgent, einem führenden Beratungsunternehmen für Big Data und Analytik und Partner von Lucidworks, nutzt er die Möglichkeiten der Unternehmenssuche, um Menschen und Unternehmen die Möglichkeit zu geben, ihre Daten auf spannende und interessante Weise zu erkunden. Er wohnt im Großraum New York City.