FastAPI | FDMLab@LABW

Workshop - Python in OpenRefine

Wed, 14 May 2025 00:00:00 +0000

Wir verwenden Python zusammen mit OpenRefine.

Jython in der OpenRefine Dokumentation.
Einsteiger Workshop 19 Daten mit OpenRefine clustern.
Blogbeitrag Named Entity Recognition mit OpenRefine und spaCy.

Dieser Workshop wurde erstellt mit OpenRefine Version 3.5.0.
Dieser Workshop wurde zuletzt getestet mit OpenRefine Version 3.9.3.

Die in diesem Tutorial behandelten Funktionen sind teilweise erst verfügbar seit der Version OpenRefine 3.9.3.

Jython

Quasi überall, wo man in OpenRefine GREL-Expressions schreiben kann, kann man stattdessen auch auf Jython umstellen. Also beispielsweise für den Transformations-Dialog, Facets oder neu auch für eigene Clustering Methoden.

Bildschirmfoto des Transformations Dialogs mit Jython.

Praktisch wird das Jython-Snippet, welches man wie in Abbildung 1 gezeigt im Dialog eingibt, in eine Python-Funktion gepackt und dann von Jython ausgeführt. Daher benötigt man im Unterschied zu GREL ein return Statement, um anzugeben, welcher Wert zurückgegeben wird.

def some_fun_name(value, cell, cells, row, rowIndex, value1, value2):
 ...

Das eingegebene Snippet wird quasi anstelle von ... eingesetzt.

Zu den in GREL zur Verfügung stehenden Variablen haben wir schon einiges geschrieben. Diese stehen mit Ausnahmen in Jython unter OpenRefine ebenfalls zur Verfügung. Beispielsweise fehlt die Variable columnName mit dem aktuellen Spaltennamen.

Jython selbst ist eine Java Implementierung von Python. Das bedeutet, dass es innerhalb von Java interpretiert wird und man auch von Jython Code aus auf verfügbare Java Methoden zugreifen kann.

Leider hat das Projekt den Sprung auf Python 3 nicht geschafft und unterstützt daher nur die Funktionalität von Python 2.7. Das macht auch die Verwendung von externen Python Bibliotheken innerhalb von Jython deutlich komplexer.

Es gibt nur noch selten Python Bibliotheken, die Python 2.7 unterstützen. Und es können auch nur Python Bibliotheken verwendet werden, die komplett in Python geschrieben wurden. Einige gerade sehr beliebte Python Projekte verwenden aus Performance Gründen unter der Haube kompilierte Programmiersprachen wie C, Fortran oder Rust. Diese können unter Jython nicht direkt verwendet werden.

Praktisch ist die Ausführung von Jython Code in OpenRefine auch deutlich langsamer, als z.B. GREL oder Clojure Code. Das macht es eher schwierig komplexere Algorithmen z.B. für das Clustering direkt zu hinterlegen.

Alternativ kann von OpenRefine aus, via Jython auf externen Python Code zugegriffen werden, was im folgenden Teil vertieft wird.

Python

Standard Setup

Wir verfolgen die Idee von OpenRefine aus auf Python Code zuzugreifen, der nicht innerhalb von Jython ausgeführt wird. Dafür benötigen wir einen Blick in das Python Projekt Setup.

--- title: Python Setup config: look: handDrawn theme: neutral --- flowchart LR subgraph web[fas:fa-globe Web] subgraph python[fab:fa-python Python] python_3_12[fab:fa-python 3.12] python_3_13[fab:fa-python 3.13] end subgraph packages[fas:fa-folder-tree Packages] typer_0_15[Typer 0.15] fastapi_0_115[FastAPI 0.115] spacy_3_8[spaCy 3.8] my_project_0_1[My Project 0.1] end end subgraph laptop[fas:fa-laptop Laptop] subgraph local_python[fab:fa-python Python] local_python_3_12[fab:fa-python 3.12] local_python_3_13[fab:fa-python 3.13] end subgraph local_packages[fas:fa-folder-tree Packages] local_typer_0_15[Typer 0.15] local_fastapi_0_115[FastAPI 0.115] subgraph local_spacy_3_8[spaCy 3.8] c_code[fab:fa-c Code] compiled_c_code[fab:fa-c compiled] end end subgraph my_project[My Project] subgraph venv[fas:fa-folder-open venv] venv_python_3_12[fab:fa-python 3.12] venv_typer_0_15[Typer 0.15] venv_fastapi_0_115[FastAPI 0.115] venv_spacy_3_8[spaCy 3.8] end package_my_project[My Project] end end python --(1)--> local_python python_3_12 ~~~ local_python_3_12 python_3_13 ~~~ local_python_3_13 packages --(2)--> local_packages typer_0_15 ~~~ local_typer_0_15 fastapi_0_115 ~~~ local_fastapi_0_115 spacy_3_8 ~~~ local_spacy_3_8 c_code --(3)--> compiled_c_code local_python_3_12 --(4)--> venv_python_3_12 local_typer_0_15 --(4)--> venv_typer_0_15 local_fastapi_0_115 --(4)--> venv_fastapi_0_115 local_spacy_3_8 --(4)--> venv_spacy_3_8 my_project_0_1 ~~~ package_my_project package_my_project --(5)--> my_project_0_1

Für ein typisches Python Projekt benötigt man fünf Schritte, die durch verschiedene Tools in unterschiedlichem Ausmaß unterstützt werden.

Schritt 1: Python Interpreter

Zuerst benötigt man einen Python Interpreter, der es ermöglicht Python Code auf dem eigenen Rechner auszuführen. Zur Verwaltung verschiedener Python Versionen auf dem Rechner gibt es zum Beispiel das Projekt pyenv.

Schritt 2: Dependency Management

Üblicherweise werden verschiedene externe Bibliotheken benötigt. Diese stehen zum Beispiel im Python Package Index (PyPI) zur Verfügung und können mit pip verwaltet werden.

Alternativen zur Verwaltung der Abhängigkeiten sind Poetry, pip-tools und pipx.

Schritt 3: Compiler

Wie schon angesprochen beinhalten manche Python Projekte nicht nur Python Code, sondern auch Code in kompilierten Sprachen. Wenn für die von euch verwendete Kombination aus CPU und Betriebssystem (noch) kein kompiliertes Binärpaket für die Bibliothek zur Verfügung steht, dann muss das Paket ggf. auf eurem Rechner kompiliert werden. Dafür werden entsprechende Compiler und Entwicklungspakete auf dem Rechner benötigt.

Alternativ gibt es auf conda-forge eine Sammlung schon kompilierter Pakete.

Schritt 4: Virtuelle Umgebung

Erfahrungsgemäß bleibt es nicht bei einem Python Projekt auf dem eigenen Rechner. Um Konflikte zwischen den Python Versionen und/oder Abhängigkeiten zu vermeiden, ist es üblich für jedes Projekt eine eigene virtuelle Umgebung anzulegen.

Dafür gibt es das Werkzeug venv, welches früher ein separates Paket war, und seit Python 3.3 in den Standard übernommen wurde.

Schritt 5: Package und Release Management

Möchte man das Projekt anschließend für andere z.B. im Python Package Index zur Verfügung stellen, dann muss es davor noch in das passende Paketformat umgewandelt werden. Da das für die Benutzung mit OpenRefine nicht relevant ist, wird dieser Schritt hier nicht vertieft.

uv

Das oben beschriebene Setup klingt recht kompliziert und daher abschreckend gerade für kleinere Experimente. Spätestens seit 2025 setzt sich bei Python Entwicklern hier das Projekt uv durch, welches die Schritte 1, 2, 4 und 5 in einem Werkzeug vereint und das Python Setup dadurch deutlich vereinfacht.

Für die Installation von uv werden mehrere einfache und direkte Wege beschrieben.

Sollte man mit dem Windows-Subsystem for Linux (WSL) arbeiten, dann benötigt man die Installationsanleitung für Linux, auch wenn man Windows als Betriebssystem hat.

uv hat (quasi) drei für uns relevante Modi:

uvx zum Ausführen von Tools.
uv run zum Ausführen von Skripten.
uv zum Arbeiten mit Projekten
(mehrere abhängige Python Dateien, separates Dependency Management).

Wir konzentrieren uns in dieser Anleitung auf die ersten beiden.

Reconciliation Service

Um die Verwendung von uvx zum Ausführen von externen Python Werkzeugen zu demonstrieren, erstellen wir einen eigenen Reconciliation Service basierend auf einer CSV-Datei mit uvx und csv-reconcile. Zum Herunterladen der CSV-Datei von 12 Daten zwischen Projekten abgleichen verwenden wir uvx mit httpie.

In einem Terminal wie iTerm, xTerm, Bash oder Powershell führen wir den folgenden Befehl aus.

uvx --from httpie http --download GET https://fdmlab.landesarchiv-bw.de/data/openrefine-workshop/12_staedte-in-bw-geokoordinaten.csv

Dieses kompakte Snippet lädt die zu diesem Zeitpunkt standardmäßige Python Version und die aktuellste Version von httpie herunter, erstellt damit eine virtuelle Umgebung (venv) und führt darin den Befehl http --download GET ... aus.

Den Reconciliation Service basierend auf der im letzten Schritt heruntergeladenen Datei erstellen wir in zwei Schritten:

Datenbank für Reconcilation Service erstellen
Reconciliation Service starten

uvx csv-reconcile init 12_staedte-in-bw-geokoordinaten.csv "GND ID" "Name"

Mit diesem Snippet erstellen wir die Datenbank für den Reconciliation Service und legen die Spalte “GND ID” als ID-Spalte fest und die Spalte “Name” als Standardspalte für den Abgleich. Den Reconciliation Service selbst starten wir mit dem folgenden Befehl.

uvx csv-reconcile serve

In OpenRefine können wir den Reconciliation Service anschließend hinzufügen mit: http://127.0.0.1:5000/reconcile.

Datenbank mit eigener Konfiguration

Der oben erstelle Reconciliation Service ist recht generisch und es fehlt z.B. noch die Vorschaufunktion für die einzelnen Elemente. Um den Service nach unseren Anforderungen zu konfigurieren, erstellen wir eine Datei config.py mit dem folgenden Inhalt.

SERVER_NAME="localhost:5000"
CSVKWARGS={'delimiter': ',', 'quotechar': '"'}
CSVENCODING='UTF-8'
MANIFEST = {
 "name": "Städte in BW Reconciliation Service",
 "identifierSpace": "https://normdaten.landesarchiv-bw.de/ids",
 "schemaSpace": "https://normdaten.landesarchiv-bw.de/schema",
 "extend": {
 "propose_properties": {
 "service_url": "http://localhost:5000",
 "service_path": "/properties"
 }
 },
 "preview": {
 "url": "http://localhost:5000/preview/{{id}}",
 "width": 500,
 "height": 300
 }
}

Anschließend erstellen wir die Reconciliation Datenbank mit der neuen Konfiguration.

uvx csv-reconcile init --config config.py 12_staedte-in-bw-geokoordinaten.csv "GND ID" "Name"

Der neue Service ist nach dem Starten unter http://localhost:5000/reconcile erreichbar.

uvx csv-reconcile serve

In OpenRefine müssen wir den CSV Reconciliation Service aktuell bei jeder Änderung der Konfiguration neu hinzufügen.

Der Reconciliation Service kann jetzt wie in Abbildung 2 mit dem Beispiel aus 12 Daten zwischen Projekten abgleichen getestet werden.

Screencast zum Reconciling mit OpenRefine und CSV-Datei.

Eigene Skripte

Um Command Line Interfaces (CLIs) zu erstellen, gibt es in Python die Standardbibliothek argparse. Meistens möchte man aber “nur mal schnell” aus einer Python Funktion ein Werkzeug erstellen, welches von der Kommandozeile aufgerufen werden kann. Ein nützliches Python Projekt dafür ist typer.

Typer Hello World Beispiel

Ein einfaches “Hello World” Beispiel mit uv und Typer ist im folgenden Quellcode aus hello_world.py abgebildet.

# /// script
# requires-python = ">=3.12"
# dependencies = [
# "typer",
# ]
# ///
import typer

def hello_world():
 print("Hello World")

if __name__ == "__main__":
 typer.run(hello_world)

Zu Beginn wird über Inline Metadaten definiert, dass das Skript mit Python 3.12 oder neuer ausgeführt werden soll und das Skript zusätzlich die externe Abhängigkeit typer benötigt.

Das Werkzeug uv unterstützt diese inline Metadaten, so dass zum Ausführen dieses Skriptes in einem Terminal lediglich uv run hello_world.py ausgeführt werden muss.

Das Werkzeug Typer übersetzt den CLI-Aufruf für die Python Funktion, und validiert und konvertiert dabei die Eingabedaten.

Typer Beispiel mit Parametern

Wir beginnen mit einem einfachen Beispiel.

# /// script
# requires-python = ">=3.12"
# dependencies = [
# "typer",
# ]
# ///
import typer

def add(a, b):
 print(a + b)

if __name__ == "__main__":
 typer.run(add)

Die Funktion add soll zwei Parameter a und b miteinander addieren und dann ausgeben. Zum Ausgeben des Ergebnisses verwenden wir die Funktion print. Das Werkzeug typer erkennt automatisch die beiden Parameter a und b und meldet, wenn diese nicht gesetzt sind. Unter uv run add.py --help erhalten wir einen Informationstext zur Benutzung unseres CLI-Tools.

Standardmäßig werden die Parameter als Text interpretiert. Mit so genannten Type Hints können wir Typer mitteilen, dass wir hier Zahlen erwarten.

def add(a: int, b: int):
 print(a + b)

Es ist auch möglich, optionale Parameter wie c mit anzugeben.

def add(a: int, b: int, c: int = 0):
 print(a + b + c)

Individuelle Konfigurationen können mit Type Annotations hinterlegt werden.

def add(a, b, c: Annotated[int, typer.Argument()] = 0):
 print(a + b + c)

Mit den Annotationen lässt sich bei Bedarf der Text für die Hilfe weiter spezifizieren. Hier das fertige Skript mit ausführlicherem Hilfstext.

# /// script
# requires-python = ">=3.12"
# dependencies = [
# "typer",
# ]
# ///
import typer
from typing_extensions import Annotated

def add(
 a: Annotated[int, typer.Argument(help="The first number to add.")],
 b: Annotated[int, typer.Argument(help="The second number to add.")],
 c: Annotated[int, typer.Argument(help="The optionally third number to add.")] = 0,
):
 """
 Add the numbers in `a` and `b` and optionally `c` if `c` is provided.
 """
 print(a + b + c)

if __name__ == "__main__":
 typer.run(add)

Das Praktische an Typer ist, dass man “nur zum Ausprobieren” lediglich die type hints und den Aufruf von Typer im Skript ergänzen muss. Bei Bedarf können ausführlichere Hilfstexte oder Validierungen hinterlegt werden, deren Ergebnis in Abbildung 3 gezeigt ist.

Screenshot Terminal mit von Typer generierten Hilfstext.

Zugriff von OpenRefine auf Python Skript

Von OpenRefine heraus, lässt sich mit Jython recht unkompliziert auf das externe Python Skripte zugreifen. Es muss lediglich der Pfad des Skriptes in dem Jython Snippet unten angepasst werden. Ggf. müssen auch noch Parameter für das Skript ergänzt werden.

import subprocess
script = "C:\\...\\python_script.py"
res = subprocess.check_output(
 ["uv", "run", script, "\""+value+"\""],
 shell=True,
)
return res

Probleme beim Zugriff von OpenRefine auf Python Skripte

Der direkte Zugriff auf ein Skript ist erst einmal relativ performant, hat in der Praxis aber mehrere Probleme.

Die korrekte Übergabe von Daten an das Skript via Parametern ist nicht ganz so einfach. Besonders, wenn die Daten größer sind ggf. Sonderzeichen enthalten, …
Man ist selbst für die Fehlerbehandlung verantwortlich. Also dass die Skripte auch irgendwann beendet werden, bei zu langer Laufzeit abgebrochen werden, usw.
Es wird lediglich Text zurückgegeben. Die Interpretation in ein bestimmtes Format muss dann in Jython oder in einem Nachbearbeitungsschritt erfolgen.
Manche Skripte oder Tools müssen initial erst einmal Daten in den Arbeitsspeicher laden. Insbesondere bei Machine Learning Anwendungen kann das mehrere Sekunden dauern. Dies erfolgt bei jedem Skriptaufruf wieder erneut.

Daher ist es wesentlich stabiler stattdessen mit eigenen Web-APIs zu arbeiten.

Eigene Web-APIs mit FastAPI

--- title: Script vs Web-API config: look: handDrawn theme: neutral --- flowchart LR subgraph openrefine["OpenRefine"] subgraph jython["Jython"] jython_code["Jython Code"] end end subgraph venv script["fab:fa-python Skript"] end subgraph uvicorn["Uvicorn"] subgraph fastapi["FastAPI"] python_code["fab:fa-python Code"] end end jython_code -.-> script jython_code -.-> script jython_code -.-> script jython_code -.-> script jython_code -.-> script jython_code -.-> script jython_code -.-> script jython_code -.-> script jython_code -.-> script jython_code <--HTTP--> python_code

Für Web-APIs gibt es etablierte und stabile Protokolle zum Austausch von Daten. Ähnlich wie mit Typer können wir mit FastAPI unsere Python-Funktionen als Web-API zur Verfügung stellen. Mit einem Server wie uvicorn sorgen wir dabei für eine Stabilität der angestoßenen Prozesse für die Abfragen.

Beispielcode für spaCy

Das folgende Skript lädt ein deutschsprachiges Modell von spaCy und berechnet über Word Embeddings die Ähnlichkeit bzw. hier die Distanz der beiden übergebenen Texte.

# /// script
# requires-python = ">=3.12,<3.13"
# dependencies = [
# "spacy",
# "typer",
# "de_core_news_lg @ https://github.com/explosion/spacy-models/releases/download/de_core_news_lg-3.8.0/de_core_news_lg-3.8.0.tar.gz",
# ]
# ///

import typer
import de_core_news_lg as model


def spacy_distance(a: str, b: str):
 nlp = model.load()
 doc_a = nlp(a)
 doc_b = nlp(b)
 dist = 1 - doc_a.similarity(doc_b)
 print(dist)


if __name__ == "__main__":
 typer.run(spacy_distance)

Das Skript hat den eindeutigen Nachteil, dass es bei jedem Aufruf das “große” Sprachmodell laden muss, was mehrere Sekunden dauert. Hier im Vergleich das Skript spacy_distance_fastapi.py, welches die Funktionalität via FastAPI zur Verfügung stellt.

# /// script
# requires-python = ">=3.12,<3.13"
# dependencies = [
# "spacy",
# "fastapi",
# "uvicorn",
# "de_core_news_lg @ https://github.com/explosion/spacy-models/releases/download/de_core_news_lg-3.8.0/de_core_news_lg-3.8.0.tar.gz",
# ]
# ///

import de_core_news_lg as model
import uvicorn
from fastapi import FastAPI

app = FastAPI()
nlp = model.load()


@app.get("/distance")
def spacy_distance(a: str, b: str) -> float:
 doc_a = nlp(a)
 doc_b = nlp(b)
 dist = 1 - doc_a.similarity(doc_b)
 return dist


if __name__ == "__main__":
 uvicorn.run("spacy_distance_fastapi:app", host="127.0.0.1", port=5000)

Die Verarbeitungspipeline für die Texte mit dem “großen” Sprachmodell wird außerhalb der Python Methode definiert, weshalb das Modell pro Aufruf nur einmal aufgerufen werden muss. Im Vergleich zum direkten Skriptaufruf, ist der Zugriff auf unsere lokale Web-API zwar etwas langsamer. Wir profitieren aber von der Müglichkeit ladeintensive Prozesse nur einmal beim Starten auszuführen, sowie von dem zusätzlichen Protokoll im Bereich Fehlerbehandlung, Validierung von Eingaben und Antworten.

Ähnlich wie bei Typer übernimmt FastAPI hier das Mapping der Benutzeranfrage auf die entsprechende Python Funktion. Gleich wie bei Typer werden Type Hints für das Mapping, die Dokumentation und die Validierung verwendet. Auch bei FastAPI kann die Dokumentation mit weiteren Annotationen erweitert und personalisiert werden.

Somit lassen sich mit FastAPI eigene Web-APIs ähnlich leicht erstellen, wie einfache Python Skripte mit Typer. Ausführliche Beispiele stehen im Anhang bzw. als GitHub Gist unter spacy_fastapi.py und rapidfuzz_fastapi.py zur Verfügung.

Von OpenRefine heraus kann man via Jython auf die (lokalen) Web-APIs zugreifen.

Zugriff via GET

Web-APIs unterscheiden für den Abruf von Daten zwischen GET- und POST-Requests (Anfragen). Für GET-Requests gibt es in OpenRefine die Möglichkeit den Dialog Add column by fetching URLs zum Nachladen von Daten zu verwenden.

"http://localhost:5000/ner?text=" + escape(value, "url")

Hier kann man mit einfachem GREL die benötigte URL zusammen bauen. Man sollte jedoch daran denken, die Parameter mit escape für die URL kompatibel aufzubereiten.

In Abbildung 4 ist der Dialog aus 18 Nachladen von Geokoordinaten gezeigt.

Bildschirmfoto des Dialogs zum Nachladen von URLs für GeoNames.

Möchte man eine Web-API z.B. von einem Facet oder einem Clustering-Dialog heraus aufrufen, benötigt man dafür das folgende Jython-Snippet um einen validen GET-Request zu erstellen.

import json, urllib, urllib2
url = "http://localhost:5000/ner"
request_data = urllib.urlencode({
 "text": value.encode("utf-8"),
})
response = urllib2.urlopen(url + "?" + request_data)
return json.dumps(json.load(response), ensure_ascii=False)

Zur Erinnerung: Es gibt Python Bibliotheken wie requests, die das Erstellen und Verarbeiten von Web-Requests deutlich vereinfachen. Wir arbeiten in OpenRefine aber mit Jython und können daher nicht einfach auf externe Bibliotheken zugreifen.

Zugriff via GET und Form

Manche Web-APIs erwarten einen GET-Request mit zusätzlichem Nutzdaten z.B. aus einem Formular. Das lässt sich in Jython / Python 2.7 mit folgendem Snippet umsetzen.

import json, urllib, urllib2
url = "http://localhost:5000/ner"
request_data = urllib.urlencode({
 "text": value.encode("utf-8"),
})
response = urllib2.urlopen(url, request_data)
return json.dumps(json.load(response), ensure_ascii=False)

Der Unterschied zum letzten Beispiel ist, dass request_data als zusätzliche Nutzdaten mit einem Komma getrennt an urllib2 übergeben werden, anstatt sie mit an die URL zu kodieren.

Zugriff via POST

Der in den Beispielen im Anhang verwende Use-Case ist das Verwenden von POST-Requests. Hier werden die Nutzdaten als JSON kodiert an den Request angehängt. Das macht die Kodierung der Daten in der Anfrage komplexer, gleichzeitig aber die Übermittlung stabiler.

import json, urllib, urllib2
url = "http://localhost:5000/ner"
request_data = json.dumps({
 "text": value.encode("utf-8"),
})
request = urllib2.Request(
 url,
 request_data,
 {"Content-Type": "application/json"},
)
response = urllib2.urlopen(request)
return json.dumps(json.load(response), ensure_ascii=False)

Der komplette Workflow vom Starten des Web-Service, bis zur Verwendung von RapidFuzz als eigene Clustering Methode in OpenRefine ist in dem Screencast in Abbildung 5 gezeigt.

Screencast zur Verwendung von uv, FastAPI und RapidFuzz als eigene Clustering Methode bei OpenRefine.

Fazit

Kleinere Skripte mit Jython / Python 2.7 in OpenRefine sind möglich, jedoch gerade beim Clustering oder bei der Nachnutzung von externen Python Projekten problematisch.

Mit Typer und FastAPI lassen sich aus Python Funktionen heraus schnell CLI-Tools oder Web-APIs erstellen. Die beiden Werkzeuge ermöglichen es sowohl mit wenig Aufwand Prototypen zu erstellen, als auch diese zu dokumentierten praktischen Tools zu erweitern.

Mit uv sind die Hürden für das Erstellen von indivduellen Python Umgebungen für einzelne Skripte sehr stark gesenkt worden. Das reduziert nicht nur den Entwicklungsaufwand, sondern erleichtert auch die Nachnutzung von Skripten für Nutzerinnen und Nutzer.

Mit der Kombination aus Jython, uv und wahlweise Typer oder FastAPI lassen sich dadurch modernste Python Anwendungen direkt mit OpenRefine verbinden.

Anhang

FastAPI Wrapper für spaCy

FastAPI Wrapper für RapidFuzz

Named Entity Recognition mit OpenRefine und spaCy

Tue, 10 Aug 2021 00:00:00 +0000

In diesem Artikel beschreiben wir unsere Versuche mit OpenRefine ein “Named Entity Recognition” mit spaCy durchzuführen, um die Entities anschließend mit der Gemeinsamen Normdatei (GND) abzugleichen.

OpenRefine kann Python Code ausführen. Dann sollte es doch auch möglich sein, damit eine “Named Entity Recognition” mit dem auf Python basierten Framework spaCy durchzuführen. ⚠️ Leider hat es sich gezeigt, dass sich die Umsetzung technischer gestaltet als erwartet.

Da wir uns vornahmen auch negative Erfahrungen zu berichten gehen wir wie folgt vor:

Wir beschreiben, wie wir uns die Umsetzung vorgestellt hätten.
Wir erklären, weshalb das nicht funktioniert.
Wir zeigen eine flexible, dafür technisch aufwendigere Lösung.

Versuch: spaCy in OpenRefine ausführen

OpenRefine bringt mit Jython eine Java Implementierung für Python mit. Theoretisch ist es also möglich das Python Framework spaCy als Python Paket zu installieren und direkt in OpenRefine auszuführen.

Unser gedachtes Vorgehen: wir nehmen an, dass wir auf einem Windows System sind. Dort gehen wir mit dem Dateiexplorer in den OpenRefine Ordner mit integrierter Java Umgebung und öffnen dort eine PowerShell. Dann aktivieren wir mit Jython den Python Paketmanager pip (Zeile 1), installieren spaCy (Zeile 2) und laden ein deutsches Sprachmodell (Zeile 3).

1
2
3


.\server\target\jre\bin\java.exe -jar .\webapp\extensions\jython\module\MOD-INF\lib\jython-standalone-2.7.2.jar -m ensurepip
.\server\target\jre\bin\java.exe -jar .\webapp\extensions\jython\module\MOD-INF\lib\jython-standalone-2.7.2.jar -m pip install spacy
.\server\target\jre\bin\java.exe -jar .\webapp\extensions\jython\module\MOD-INF\lib\jython-standalone-2.7.2.jar -m spacy download de_core_news_sm

Hätte das funktioniert, könnten wir nun im “expression” Editor zum Beispiel beim Hinzufügen oder Transformieren von Spalten von GREL auf Jython umstellen und mit folgendem Code ein “Named Entity Recognition” mit spaCy auf den Inhalten durchführen.

import spacy
nlp = spacy.load("de_core_news_sm")
doc = nlp(value)
return "\n".join(ent.text + "||" + ent.label_ for ent in doc.ents)

🚫 Leider funktioniert die Installation von spaCy in Jython via pip nicht.

Technische Hintergründe

Jython implementiert aktuell Python in Version 2.7. Seit Januar 2020 wird Python in Version 2 jedoch nicht mehr weiterentwickelt und auch nicht mehr mit Bugfixes versorgt (Status end-of-life). Die aktuelle Version von Python ist Version 3.9.

Entsprechend sind Bibliotheken in aktueller Version häufig auch nur noch mit Unterstützung für Python 3 zu finden. Eine Neuentwicklung von Jython um Python in Version 3 zu unterstützen, oder basierend auf neuer Technologie wie GraalVM nutzbar zu machen, ist nach wie vor in Planung/Umsetzung (siehe Python 3 Roadmap).

Aber auch ältere Versionen von Bibliotheken mit Unterstützung für Python 2 sind nicht einfach via pip zu installieren. Das liegt daran, dass Jython auf Java basiert, viele Python Bibliotheken unter der Haube jedoch Abhängigkeiten zur Programmiersprache C haben.

Alternative: spaCy separat ausführen

Wenn wir spaCy nicht in OpenRefine zum Laufen bekommen, dann können wir es stattdessen separat als Webservice betreiben.

In “Fetching and Parsing Data from the Web with OpenRefine” wird gezeigt, wie mit OpenRefine das Text Processing API verwendet werden kann. Das Projekt unterstützt aktuell Englisch, Holländisch, Portugiesisch und Spanisch. Ähnliche Freemium Angebote gibt es auch mit deutschen Sprachmodellen.

Anstatt einen externen Dienst zu bemühen, wollen wir den Dienst lokal laufen lassen. Dafür packen wir spaCy mit FastAPI in ein API und verwenden Uvicorn als Server.

Python 3.9 installieren

Python 3.9 kann in Form einer ausführbaren Datei (.exe) von Python Downloads heruntergeladen und lokal installiert werden.

Virtuelle Umgebung aufsetzen

Wir erstellen einen Ordner ner-service. In dem Ordner starten wir eine PowerShell. Dann erstellen wir mit Python eine so genannte virtuelle Umgebung (Zeile 1). ¹ Die virtuelle Umgebung aktivieren wir anschließend (Zeile 2), installieren die benötigten Programme (Zeile 3) und laden das Sprachmodell mit spaCy herunter (Zeile 4).

1
2
3
4


python -m venv venv
.\venv\Scripts\activate
pip install fastapi python-multipart spacy uvicorn
python -m spacy download de_core_news_sm

NER Service erstellen

Den folgenden Python Code speichern wir in dem Ordner ner-service in der Datei simple-ner-service.py.

import spacy
import uvicorn
from fastapi import FastAPI, Form

app = FastAPI()
nlp = spacy.load("de_core_news_sm")


@app.post("/ner")
def ner(text: str = Form(...)):
 doc = nlp(text)
 return [{"text": ent.text, "label": ent.label_} for ent in doc.ents]


if __name__ == "__main__":
 uvicorn.run("simple-ner-service:app", host="127.0.0.1", port=5000)

Mit aktivierter virtueller Umgebung können wir den Server mit der PowerShell aus dem Ordner ner-service heraus starten:

1
2


.\venv\Scripts\activate
python .\simple-ner-service.py

NER Service in OpenRefine nutzen

In OpenRefine schicken wir im “expression” Editor den Inhalt einer Zelle (value) mit Jython an den ner-service unter http://localhost:5000/ner und geben das Ergebnis im JSON Format zurück. Dabei haben wir auf die Kodierung (“encoding”) zu achten, da Python 2 standardmäßig nicht mit UTF-8 arbeitet. Ein Problem, das in englischsprachigen Anleitungen häufig nicht relevant ist und daher ignoriert wird.

import json, urllib, urllib2
url = 'http://localhost:5000/ner'
request_data = urllib.urlencode({"text": value.encode('utf-8')})
response = urllib2.urlopen(url, request_data)
return json.dumps(json.load(response), ensure_ascii=False)

Die Vorschau des “expression” Editors in OpenRefine zeigt die ersten Ergebnisse.

OpenRefine ermöglicht es Spalten basierend auf URLs hinzuzufügen. Dabei werden so genannte GET-Requests ausgeführt, die von der Zeichenbeschränkung für URLs betroffen sind. Daher ist es empfehlenswert Texte via POST-Requests zu versenden, weshalb wir die Anfrage mit Python und urllib2 ausführen.

Zusammenfassung und Erweiterung

Mit etwa 15 Zeilen Python Code haben wir die Daten aus OpenRefine heraus mit einen (lokalen) Service verknüpft, der aufbauend auf der neuesten Technologie eine “Named Entity Recognition” durchführen kann.

Dabei ist der Ansatz so generisch, dass er auf ähnliche Anwendungen übertragen werden kann. Daher haben wir den minimalen Ansatz noch optimiert, dokumentiert und als GitHub Gist zur Verfügung gestellt.

NER mit OpenRefine und spaCy

--- title: Prozess config: look: handDrawn theme: neutral --- flowchart LR text[fas:fa-file-alt Text] spacy[fab:fa-python spaCy] data[fas:fa-list-alt Entities] gnd[fas:fa-database GND] semantic[fas:fa-project-diagram Graph] text --> data --> semantic spacy --> data gnd --> semantic

Mit dem funktionierenden NER Service können wir nun unserer ursprünglichen Idee nachgehen und ein “Named Entity Recognition” mit spaCy durchführen und die “Entities” anschließend mit der Gemeinsamen Normdatei (GND) abgleichen.

NER Service starten

Zuerst starten wir unseren NER Service. Dafür benötigen wir - wie im oberen Abschnitt beschrieben - Python 3 und eine virtuelle Umgebung mit spaCy, FastAPI und Uvicorn. Dort starten wir die Datei ner-service.py aus dem GitHub Gist.

Der NER Service ist nach dem Start unter http://localhost:5000 zu erreichen und kann wie in Abbildung 1 in einer interaktiven Dokumentation auch gleich getestet werden.

Bildschirmfoto der interaktiven API Dokumentation des NER Service.

OpenRefine Projekt erstellen

💾 Für OpenRefine haben wir einige Textschnippsel aus Wikipedia zusammengesucht (CC-BY-SA-3.0) und bieten diese mit Quellangabe unter gleichen Lizenzbedingungen in einer JSON Datei zum Download an (Rechtsklick und “Ziel speichern unter…”):

Wikipedia Textschnippsel als JSON .

Mit der JSON Datei erzeugen wir wie in Abbildung 2 ein neues Projekt in OpenRefine.

Bildschirmfoto zur Erstellung des Projektes mit einer JSON Datei in OpenRefine.

Anschließend benennen wir die Spalten zur Übersichtlichkeit in Quelle und Text um.

NER auf Text durchführen

Um eine “Named Entity Recognition” durchzuführen, erzeugen wir eine neue Spalte NER basierend auf der Spalte Text und verwenden wie in Abbildung 3 eine Jython Expression.

import json, urllib, urllib2
url = 'http://localhost:5000/ner'
request_data = json.dumps({'text': value.encode('utf-8')})
request = urllib2.Request(url, request_data, {'Content-Type': 'application/json'})
response = urllib2.urlopen(request)
return json.dumps(json.load(response), ensure_ascii=False)

Wir haben die “expression” im Vergleich zu unserem Test abgeändert, da wir bei der Überarbeitung des NER Service von form-urlencoded zu JSON wechselten.

Bildschirmfoto mit Dialog zur Durchführung von NER in OpenRefine.

Informationen aus JSON extrahieren

Um die Informationen aus dem JSON formatierten Text zu extrahieren, verwenden wir die Werkzeuge von GREL. Dafür erzeugen wir wie in Abbildung 4 eine neue Spalte Entity aus der Spalte NER mit einer"expression".

forEach(parseJson(value), v, v.text).join("||")

Bildschirmfoto mit Dialog zur Erzeugung einer neuen Spalte mit dem Entity Text in OpenRefine.

Für den Typ der Entities erzeugen wir wie in Abbildung 5 eine neue Spalte Label aus der Spalte NER mit einer “expression”.

forEach(parseJson(value), v, v.label).join("||")

Bildschirmfoto mit Dialog zur Erzeugung einer neuen Spalte mit dem Entity Label in OpenRefine.

Wir haben nun mehrere Werte in einer Zelle, weshalb wir diese wie in Abbildung 6 mit “Entity" "Edit Cells" "Split multi-valued cells…” und “Label" "Edit Cells" "Split multi-valued cells…” an der Trennsequenz || auftrennen.

Bildschirmfoto mit Dialog zur Aufteilung der Entities in mehrere Zeilen in OpenRefine.

Daten mit GND abgleichen

Nun haben wir die gefundenen Entities in einzelnen Zeilen und können sie nach Belieben bearbeiten, löschen oder mit externen Diensten abgleichen. Dafür verwenden wir den GND Reconciliation Service von lobid. Mit “Entity" "Reconcile" "Start reconciling” starten wir den Abgleichsvorgang. Siehe auch Findbuch Index mit OpenRefine aufbereiten für Details zum Datenabgleich von Daten in OpenRefine mit der Gemeinsamen Normdatei (GND). In Abbildung 7 haben wir einen Screenshot der Daten, nachdem die Entities mit der GND abgeglichen und mit der GND-ID angereichert wurden.

Bildschirmfoto der zugeordneten Entities in OpenRefine.

Fazit

In diesem Beitrag haben wir eine Möglichkeit gezeigt, wie generell mit OpenRefine Daten an einen lokalen Service übergeben und verarbeitet werden können. Das haben wir genutzt um ein “Named Entity Recognition” mit spaCy durchzuführen.

Wir hätten uns gewünscht, dass die Integration von Python Frameworks in OpenRefine direkter und weniger technisch zu bewerkstelligen wäre. Andererseits haben wir mit FastAPI eine Framework getestet, mit dem unkompliziert Dienste zur Verfügung gestellt werden können.

Eine virtuelle Umgebung ermöglicht es uns, die für dieses Projekt benötigten Abhängigkeiten direkt in den Ordner zu installieren, und bei Bedarf das komplette Projekt mit allen Abhängigkeiten wieder aufzuräumen. ↩︎