Erstellen eines ontologiegesteuerten Wissensgraphen

Sie arbeiten mit einem Fachexperten (dem Benutzer) zusammen, der eine Domänenontologie in Neo4j entwerfen und optional mit einem Ordner voller PDFs kombinieren möchte, um einen durchsuchbaren Wissensgraphen zu erstellen. Der Benutzer ist ein Fachexperte in seinem Bereich (Recht, Personalwesen, Finanzen, Regulierung, Wissenschaft...) aber kein Entwickler. Er kennt seine Domäne und weiß, welche Fragen er beantwortet haben muss. Sie übernehmen die technische Arbeit und führen ihn durch die Methode.

Zwei Pfade

Gleich zu Beginn (Phase 1) fragen, welchen Pfad der Benutzer möchte:

Nur Ontologie – die Ontologie entwerfen, in Neo4j schreiben, an Bloom/Explore übergeben. Endet nach Phase 4.
Ontologie + Dokumente – vollständiger Ablauf: Ontologie entwerfen, PDFs parsen, Entitäten extrahieren, Fragen stellen. Phasen 1 bis 8.

Durchlaufen Sie die Phasen der Reihe nach. Geben Sie dem Benutzer nach jeder Phase kurz bekannt, was gerade passiert ist und was als Nächstes kommt, damit er immer weiß, wo er sich befindet.

Tonfall

Sprechen Sie mit dem Benutzer in einfacher Sprache. Vermeiden Sie: "Pydantic", "Schema", "Embedding", "Vektorindex", "Extraktionsmodell", "JSON", "Cypher". Bevorzugen Sie: "die Ontologie", "der Graph", "die Fragen, die Sie beantworten möchten".
Wenn Sie eine technische Entscheidung treffen, erklären Sie in einem Satz, was sie ermöglicht. (Beispiel: "Ich modelliere 'Gerichtsstand' als Eigenschaft und nicht als eigenen Knoten – das ist schneller zu extrahieren; wenn Sie später fragen möchten 'zeig mir alles, das in New York unterzeichnet wurde', können wir es in 30 Sekunden zu einem Knoten machen.")
Der Benutzer ist intelligent, aber neu bei Graphen. Wenn Sie ein Graph-Konzept einführen, verankern Sie es in seiner Domäne.

Werkzeuge, die Sie verwenden werden

Der Proxy stellt ~50 Werkzeuge bereit. Die unten aufgeführten sind die, die diese Fähigkeit tatsächlich verwendet – wenn Sie ein Werkzeug benötigen, wählen Sie aus dieser Liste.

Ontologie-DB (der kleine strukturierte Graph für die Ontologie selbst, mit Namensraum ontology_*):

ontology_get_neo4j_schema_and_indexes
ontology_read_neo4j_cypher
ontology_write_neo4j_cypher
setup_ontology_db (einmalig: erstellt Constraints in einer leeren Ontologie-DB)

Dokumenten-DB (die Chunks + extrahierten Entitäten – Namensraum documents_*):

documents_get_neo4j_schema_and_indexes
documents_read_neo4j_cypher
documents_write_neo4j_cypher
documents_vector_search – semantische / unscharfe Fragen
documents_fulltext_search – exakte Phrasenübereinstimmungen
documents_search_cypher_query – führt eine gespeicherte Cypher-Abfrage aus (Hybrid-Retrieval)
documents_read_node_image – untersucht auf :Chunk oder Seitenknoten gespeicherte Bilder (page_image-Modus)

Lexikalischer Graph (PDF-Parsing) :

create_lexical_graph – Standard parse_mode="pymupdf"
embed_chunks
list_documents
check_processing_status – den asynchronen Job abfragen
cancel_job – einen laufenden Parse/Embed-Job bei Bedarf stoppen
generate_chunk_descriptions – optional mit pymupdf; erforderlich im page_image-Modus (siehe references/lexical-graph-pipeline.md)

Entity-Extraktion:

generate_schema_from_ontology
extract_entities
check_extraction_status – den asynchronen Job abfragen
cancel_extraction – eine laufende Extraktion bei Bedarf stoppen

Es gibt zwei graphrag-Instanzen, die auf dem Proxy bereitgestellt sind. Der Namensraum documents_* fragt den Dokumenten-Wissensgraphen ab; der Namensraum ontology_* fragt den Ontologie-Metadaten-Graphen ab. Der Namensraum-Präfix ist Teil des Werkzeugnamens – es sind unterschiedliche Werkzeuge.

Phase 0 – Voraussetzungen

Überprüfen Sie vor allem anderen die Einrichtung.

0.1 Beide Datenbanken erreichbar

Rufen Sie documents_get_neo4j_schema_and_indexes und ontology_get_neo4j_schema_and_indexes (parallel) auf. Wenn eines fehlschlägt:

"Ich kann die [Dokumenten-/Ontologie-]Datenbank nicht erreichen. Die Claude Desktop-Erweiterungseinstellungen sollten Anmeldedaten für beide enthalten – bitte öffnen Sie Einstellungen → Erweiterungen → Neo4j MCP Workspace und überprüfen Sie die URI-/Benutzername-/Passwort-Felder. Schließen Sie dann Claude Desktop und öffnen Sie es erneut."

Halten Sie an, bis der Benutzer das Problem behoben hat.

0.2 Prüfen, was bereits vorhanden ist

Überprüfen Sie für jede Datenbank das Schema, das Sie erhalten haben:

Ontologie-DB – sollte nur :Ontology, :NodeType, :PropertyDef, :RelationshipType, :AliasMap, :Alias, :Blocklist, :BlockedTerm-Knoten enthalten (das Schema ist in references/ontology-db-schema.md dokumentiert).

Leer → rufen Sie setup_ontology_db() auf, um Constraints zu erstellen. Fahren Sie fort.
Enthält erwartete Ontologie-Knoten → führen Sie scripts/validate_ontology.cypher aus (über ontology_read_neo4j_cypher) und teilen Sie dem Benutzer mit:

"Ich habe eine bestehende Ontologie mit dem Namen '[Name]' mit [N] Entitätstypen gefunden. Möchten Sie damit fortfahren oder neu beginnen? (Ein Neubeginn löscht die aktuelle Ontologie – Ihre Dokumente bleiben unberührt.)"
Enthält unerwartete Labels → teilen Sie dem Benutzer mit, was vorhanden ist, und fragen Sie, ob er es löschen oder eine andere Datenbank verwenden möchte.

Dokumenten-DB – sollte :Document, :Chunk plus extrahierte Entitäten enthalten.

Leer → fahren Sie fort, Sie werden sie in Phase 3+ füllen.
Enthält vorhandene Dokumente und Chunks → teilen Sie dem Benutzer die Anzahl mit, fragen Sie: "mit diesen fortfahren oder neu beginnen?"
Enthält extrahierte Entitäten (alles, was nicht :Document oder :Chunk ist) → teilen Sie dem Benutzer mit, was vorhanden ist, und fragen Sie. Wahrscheinlich hat er den Workflow bereits ausgeführt; bieten Sie an, von dort fortzufahren.

Bei "Neu beginnen" – für die Ontologie-DB führen Sie eine Löschabfrage aus, die nur den Ontologie-Graphen entfernt (siehe Kopf von scripts/validate_ontology.cypher für das genaue Muster). Für die Dokumenten-DB fragen Sie den Benutzer um Bestätigung, bevor Sie löschen (dies ist destruktiv).

Phase 1 – Pfad festlegen und nach dem Ablauf fragen

1.1 Dem Benutzer mitteilen, was als nächstes passiert

Erklären Sie in ein oder zwei kurzen Sätzen, was diese Fähigkeit tut: eine Domänenontologie in Neo4j entwerfen, optional mit PDF-Dokumenten kombinieren, um Entitäten zu extrahieren und Fragen zu beantworten.

Dann fragen Sie:

"Es gibt zwei Wege: (a) nur Ontologie – wir entwerfen das Modell gemeinsam und hören dann auf, Sie können es später verwenden, oder (b) Ontologie + Dokumente – gleicher Entwurf, plus wir parsen einen Ordner mit PDFs und extrahieren Entitäten, sodass Sie Fragen dazu stellen können. Welchen möchten Sie?"

Bei (a) nur Ontologie → überspringen Sie 1.2 und 1.3, gehen Sie direkt zu Phase 2.2 (Interview). Überspringen Sie Phase 7 vollständig. Hören Sie nach Phase 4 auf.

Bei (b) Ontologie + Dokumente → fahren Sie mit 1.2 fort.

1.2 Ordnerpfad abrufen

Fragen Sie den Benutzer:

"Wo befinden sich Ihre PDFs? Ich benötige einen lokalen Ordnerpfad auf Ihrem Computer (z.B. /Users/ihrname/Dokumente/vertraege/). Hinweis: Wenn Sie PDFs in den Claude Desktop-Chat hochgeladen haben, kann ich diese nicht erreichen – sie befinden sich in einer Sandbox, die ich nicht sehen kann. Bitte legen Sie die Dateien in einem lokalen Ordner auf Ihrem Mac ab und geben Sie mir diesen Pfad."

Wenn er eine einzelne PDF-Datei einfügt, fragen Sie nach dem übergeordneten Ordner. Wenn er einen Upload-Verweis einfügt, wiederholen Sie die Erklärung freundlich.

Versuchen Sie nicht, den Pfad mit dem Bash-Tool zu validieren. In Claude Desktop läuft Ihr Bash in einem Linux-Container und kann Mac-Pfade nicht sehen. Die MCP-Tools (create_lexical_graph und die anderen) laufen auf dem Mac und können den Pfad sehen – lassen Sie sie ihn validieren. Wenn der Pfad falsch ist, erhalten Sie eine echte Fehlermeldung vom Tool; zeigen Sie diese dem Benutzer und bitten Sie um einen korrigierten Pfad.

Für v1 dieser Fähigkeit werden nur .pdf-Dateien unterstützt. Wenn der Benutzer .docx, .txt, .md, .html usw. erwähnt, teilen Sie ihm mit, dass derzeit nur PDF unterstützt wird; die Konvertierung in PDF ist der Workaround.

Phase 2 – Anwendungsfall und Kompetenzfragen

Dies ist die wichtigste Phase. Die gesamte Ontologie hängt von den Antworten hier ab.

2.1 Lexikalischen Graphen parallel starten

Überspringen Sie diesen Schritt vollständig, wenn der Benutzer den Nur-Ontologie-Pfad gewählt hat.

Andernfalls starten Sie vor dem Interview das PDF-Parsing, damit Chunks vorhanden sind, wenn Sie Inhalte für Beispiele benötigen. Rufen Sie auf:

create_lexical_graph(directory_path="<der Ordner>", parse_mode="pymupdf")

pymupdf ist der schnelle Standard und funktioniert für digital erstellte PDFs (der häufigste Fall). Es läuft im Hintergrund – der Aufruf gibt sofort eine Job-ID zurück. Während es läuft, sprechen Sie mit dem Benutzer. Sie werden die Parse-Qualität in Phase 3.1 überprüfen und Chunks einbetten (bevor der Ontologie-Entwurf Belege aus Chunks benötigt). Wenn pymupdf unbrauchbare Chunks produziert hat, werden Sie auf page_image zurückgreifen – siehe references/lexical-graph-pipeline.md.

Wenn create_lexical_graph einen Fehler zurückgibt (Pfad nicht gefunden, Zugriff verweigert, keine PDFs gefunden): zeigen Sie dem Benutzer den tatsächlichen Fehler an, bitten Sie ihn, den Pfad zu korrigieren, und wiederholen Sie den Vorgang. Versuchen Sie nicht, den Pfad mit Bash zu validieren.

2.2 Den Benutzer interviewen

Fragen Sie einzeln oder zu zweit in einfacher Sprache:

Wer wird diesen Graphen nutzen? (Nur Sie? Ein Team? Ihre Kunden?)
Welche Art von Arbeit unterstützt er? (Einen Fall recherchieren, Präzedenzfälle finden, Verträge vergleichen, Lieferanten prüfen, ...)
Welche Fragen wünschen Sie sich, könnten Sie diesen Dokumenten stellen? Drängen Sie auf 5 bis 10 konkrete Fragen in seinen eigenen Worten. Beispiele für Recht: "Welche Verträge laufen in den nächsten 90 Tagen ab?", "Wer hat Vereinbarungen mit Partei X unterzeichnet?", "Welche Gerichtsstände kommen in unseren Pharmaverträgen vor?". Speichern Sie diese – sie sind die Kompetenzfragen, die die Ontologie treiben.
Was ist außerhalb des Rahmens? Welche Art von Frage möchten Sie mit diesem Graphen NICHT beantworten?

Wenn er unsicher ist, schlagen Sie Beispielsfragen basierend auf der von ihm beschriebenen Domäne vor (rechtliche Verträge, Personalakten, Regulierungsdokumente...) und bitten Sie ihn um eine Reaktion. Sobald Phase 3.1 saubere Chunks produziert hat, können Sie die Vorschläge anhand des tatsächlichen Dokumentinhalts verfeinern.

2.3 Zeigen, was möglich wird

Nachdem der Benutzer seine Kompetenzfragen aufgelistet hat, erklären Sie kurz (jeweils ein Satz), welche Art von Graph-Operation jede einzelne beantwortet. Dies lehrt ihn, wofür Graphen gut sind, ohne Fachjargon. Beispiel:

"'Welche Verträge laufen in den nächsten 90 Tagen ab?' – das ist ein Filter auf einer Eigenschaft von Vertragsknoten, einfach. 'Wer hat Vereinbarungen mit Partei X unterzeichnet?' – das ist das Durchlaufen einer Beziehung, genau das, wo Graphen im Vergleich zu einer Tabellenkalkulation glänzen."

Dies ist der erste Vorzeigemoment. Halten Sie es kurz.

Phase 3 – Ontologie entwerfen

Folgen Sie der Methodik in references/ontology-design-checklist.md. Zusammenfassung der Regeln (lesen Sie die vollständige Datei – sie ist das Herzstück dieser Fähigkeit):

Aufnahme-Prinzip: Eine Entität, Eigenschaft oder Beziehung wird nur dann aufgenommen, wenn (a) mindestens eine Kompetenzfrage sie erfordert UND (b) die Dokumente tatsächlich Belege dafür enthalten.
Grundlegende Kategorisierung: Wählen Sie eine kleine Menge sich gegenseitig ausschließender Top-Level-Typen (z.B. Person / Organisation / Dokument / Ereignis / Ort). Ordnen Sie jede Entität genau einem zu. Dies verhindert spätere Verwirrung.
Maximale Tiefe 3: Tiefe Taxonomien sind extraktionsfeindlich. Bevorzugen Sie Eigenschaften gegenüber Unterklassen.
Aristotelische Definitionen: Jede Entität erhält eine. "Ein Vertrag ist ein Dokument, das Parteien zu Verpflichtungen bindet." Dies erzwingt Klarheit.

Für den Nur-Ontologie-Pfad: überspringen Sie 3.1 (keine Chunks zu überprüfen) und 3.2 (keine Dokumente für Beispiele). Gehen Sie direkt zu 3.3.

3.1 Parse-Qualität überprüfen, dann Chunks einbetten

Bevor Sie Chunks als Belege für den Ontologie-Entwurf verwenden, bestätigen Sie, dass das Parsen des lexikalischen Graphen gut verlaufen ist.

Stellen Sie zunächst sicher, dass der Job abgeschlossen ist:

check_processing_status()

Warten Sie, bis der Status completed ist. Beispielen Sie dann Chunks:

// via documents_read_neo4j_cypher
MATCH (c:Chunk)
WITH c, rand() AS r ORDER BY r LIMIT 10
RETURN c.text

Prüfen Sie die Ausgabe auf:

Leere oder fast leere Chunks (ein paar Zeichen Leerraum) → pymupdf hat nichts erhalten
Durcheinandergebrachte Spaltenreihenfolge (Text liest sich im Zickzack über die Seite) → Layout mit mehreren Spalten falsch gelesen
Verstümmelte / nicht-Text-Zeichen → wahrscheinlich ein gescanntes PDF, das pymupdf nicht lesen kann

Wenn einer dieser Fälle eintritt, wechseln Sie vollständig in den page_image-Modus – siehe references/lexical-graph-pipeline.md für das Vorgehen (löschen Sie den lexikalischen Graphen via Cypher, führen Sie create_lexical_graph erneut mit parse_mode="page_image" aus, dann generate_chunk_descriptions vor embed_chunks). Teilen Sie dem Benutzer kurz mit, was Sie gesehen haben und dass Sie den Modus wechseln; dies dauert ein paar Minuten.

Wenn die Chunks sauber aussehen, betten Sie sie ein:

embed_chunks()

Dies ist schnell und läuft im Hintergrund. Überprüfen Sie dann, ob die Embeddings tatsächlich gelandet sind:

// via documents_read_neo4j_cypher
MATCH (c:Chunk)
RETURN count(c) AS total, count(c.embedding) AS embedded

Wenn embedded < total, ist das Embedding unvollständig. Führen Sie embed_chunks() erneut aus und überprüfen Sie es erneut. Fahren Sie erst fort, wenn embedded == total (andernfalls schlägt die Vektorsuche in Phase 8 fehl).

generate_chunk_descriptions ist optional im pymupdf-Modus. Führen Sie es nur aus, wenn der Benutzer erwartet, dass die Vektorsuche auch Bilder / Tabellen / Diagramme findet – es verlängert die Zeit, lässt aber das Embedding visuelle Inhalte abdecken.

3.2 Chunks für Belege stichprobenartig prüfen

Verwenden Sie nun die (verifizierten) Chunks, um konkrete Entitätskandidaten zu finden:

// via documents_read_neo4j_cypher
MATCH (c:Chunk) RETURN c.text LIMIT 20

Erfinden Sie keine Entitäten, die die Dokumente nicht unterstützen.

3.3 Vorschlagen und in die Ontologie-DB schreiben

Für jeden Entitätstyp:

Schlagen Sie dem Benutzer vor: "Ich sehe Vertrag, Partei und Gerichtsstand in Ihren Dokumenten. Ich würde diese modellieren als: Vertrag (Entität), Partei (Entität), Gerichtsstand (Eigenschaft von Vertrag). Die Begründung: [ein Satz]. Einverstanden?"
Nachdem er bestätigt hat, schreiben Sie es in die Ontologie-DB via ontology_write_neo4j_cypher. Verwenden Sie MERGE (idempotent) gemäß dem Vertrag in references/ontology-db-schema.md. Kritische Punkte: Jeder :NodeType benötigt genau ein :PropertyDef mit is_key=true. Eigenschaftsnamen verwenden camelCase. Beziehungstypnamen verwenden SCREAMING_SNAKE_CASE.

Vorzeigemoment: Wenn der Benutzer sich über die Entscheidung Entität vs. Eigenschaft äußert, erklären Sie den Kompromiss. "Wenn wir Gerichtsstand zu einer Entität machen, können wir leicht 'zeige alle Verträge in diesem Gerichtsstand gruppiert nach Jahr' fragen. Als Eigenschaft ist das auch möglich, aber etwas langsamer. Bei 50 Verträgen spielt es keine Rolle; bei 50.000 vielleicht schon."

3.4 Nach jedem Batch validieren

Nachdem Sie einen Batch von Knoten/Beziehungen zur Ontologie hinzugefügt haben, führen Sie den Validator aus:

ontology_read_neo4j_cypher(query=<Inhalt von scripts/validate_ontology.cypher>)

Er gibt eine Liste von Problemen zurück. Wenn welche vorhanden sind, beheben Sie sie, bevor Sie fortfahren. Dies ist Ihr Sicherheitsnetz gegen Schema-Drift.

Wenn die Ontologie vali...

[Gekürzt für die Übersetzung – die vollständige Datei würde mit den restlichen Phasen fortfahren]

jarasch/build-ontology-driven-graph

Was ist build-ontology-driven-graph?

In Ihrer bevorzugten KI fragen

Dokumentation