Création d'un Knowledge Graph avec Oracle Autonomous Database et Property Graph Query Language

Introduction

Ce tutoriel explore les concepts de la théorie des graphes, des graphiques de connaissances et leur implémentation à l'aide d'Oracle Autonomous Database avec le langage GQL (Property Graph Query Language). Il explique également l'implémentation Python utilisée pour extraire des relations de documents à l'aide de LLM et les stocker en tant que structures de graphique dans Oracle.

Qu'est-ce que Graph ?

Graph est un domaine de mathématiques et d'informatique axé sur la modélisation des relations entre les objets. Un graphique se compose des éléments suivants :

Exercices (noeuds) : représentent les entités.
Arêtes (liens) : représentent les relations entre les entités.

Les graphiques sont largement utilisés pour représenter les structures de données dans les réseaux sociaux, les réseaux sémantiques, les graphiques de connaissances, etc.

Qu'est-ce qu'un Knowledge Graph ?

Un graphique de connaissances est une représentation graphique des connaissances du monde réel où :

Les noeuds représentent des entités telles que des personnes, des lieux, des produits, etc.
Les arêtes représentent des relations sémantiques. Par exemple, travaille sur, en partie, et plus encore.

Les graphiques de connaissances améliorent la recherche sémantique, les systèmes de recommandation et les applications d'analyse des questions.

Pourquoi utiliser Oracle Autonomous Database avec PGQL ?

Oracle fournit un environnement entièrement géré pour stocker et interroger les graphiques de propriétés :

PGQL est de type SQL et conçu pour interroger des modèles de graphes complexes.
Oracle Autonomous Database permet d'exécuter des requêtes de graphe de manière native avec des fonctionnalités de graphe de propriétés, notamment la création, l'interrogation et la visualisation.
L'intégration aux LLM permet l'extraction automatique des structures de graphe à partir de données non structurées (comme les PDF).

Comparaison avec d'autres langages de requête de graphique

Avantages d'Oracle Autonomous Database avec PGQL et des bases de données orientées graphe traditionnelles

Objectifs

Créez un graphique de connaissances avec Oracle Autonomous Database et PGQL.

Prérequis

Installez Python version 3.10 ou une version ultérieure et l'interface de ligne de commande Oracle Cloud Infrastructure (interface de ligne de commande OCI).

Tâche 1 : installer des packages Python

Le code Python nécessite certaines bibliothèques pour l'utilisation d'Oracle Cloud Infrastructure (OCI) Generative AI. Exécutez la commande suivante pour installer les packages Python requis. Vous pouvez télécharger le fichier à partir d'ici : requirements.txt.

pip install -r requirements.txt

Tâche 2 : créer une base de données Oracle Database 23ai (toujours gratuit)

Dans cette tâche, nous allons apprendre à provisionner une instance Oracle Database 23ai en mode Toujours gratuit. Cette version offre un environnement entièrement géré, idéal pour le développement, les tests et l'apprentissage, sans frais supplémentaires.

Connectez-vous à la console OCI, accédez à Oracle Database, à Autonomous Database et cliquez sur Créer une instance Autonomous Database.
Saisissez les informations suivantes .
- Nom de base de données : entrez un nom d'identification pour l'instance.
- Type de charge globale : sélectionnez Data Warehouse ou Transaction Processing en fonction de vos besoins.
- Compartiment : sélectionnez un compartiment approprié pour organiser vos ressources.
Sélectionnez Toujours gratuit pour vous assurer que l'instance est provisionnée gratuitement.
Créez un mot de passe sécurisé pour l'utilisateur ADMIN, qui sera utilisé pour accéder à la base de données.
Vérifiez les paramètres et cliquez sur Create Autonomous Database (Créer une base de données autonome). Attendez quelques minutes que l'instance soit provisionnée et disponible pour utilisation.

Si vous n'êtes pas familiarisé avec le processus de connexion à Oracle Autonomous Database, suivez ces liens pour comprendre et configurer correctement votre code.

Remarque : vous devrez vous connecter à la base de données dans votre code Python avec la méthode Wallet.

Tâche 3 : télécharger et comprendre le code

Un cas d'utilisation très courant pour Graph est de l'utiliser comme l'un des composants travaillant avec les LLM et une base de connaissances, comme les fichiers PDF.

Nous utiliserons ce tutoriel : Analyser des documents PDF en langage naturel avec OCI Generative AI comme base, qui utilise tous les composants mentionnés. Toutefois, dans le cadre de ce document, nous allons nous concentrer sur l'utilisation d'Oracle Database 23ai avec Graph. Fondamentalement, le code Python (main.py) du matériau de base sera modifié uniquement dans les parties qui utilisent Oracle Database 23ai.

Les processus exécutés sur ce service sont les suivants :

Créez le schéma de graphique.
Extraire des entités et des relations à l'aide du LLM.
Insérer des données dans Oracle.
Créez le graphe de propriétés.

Téléchargez le code graphique Python mis à jour compatible avec Oracle Database 23ai à partir d'ici : main.py.

create_knowledge_graph:

def create_knowledge_graph(chunks):
    cursor = oracle_conn.cursor()

    # Creates graph if it does not exist
    try:
        cursor.execute(f"""
        BEGIN
            EXECUTE IMMEDIATE '
                CREATE PROPERTY GRAPH {GRAPH_NAME}
                VERTEX TABLES (ENTITIES
                    KEY (ID)
                    LABEL ENTITIES
                    PROPERTIES (NAME))
                EDGE TABLES (RELATIONS
                    KEY (ID)
                    SOURCE KEY (SOURCE_ID) REFERENCES ENTITIES(ID)
                    DESTINATION KEY (TARGET_ID) REFERENCES ENTITIES(ID)
                    LABEL RELATIONS
                    PROPERTIES (RELATION_TYPE, SOURCE_TEXT))
            ';
        EXCEPTION
            WHEN OTHERS THEN
                IF SQLCODE != -55358 THEN -- ORA-55358: Graph already exists
                    RAISE;
                END IF;
        END;
        """)
        print(f"🧠 Graph '{GRAPH_NAME}' created or already exists.")
    except Exception as e:
        print(f"[GRAPH ERROR] Failed to create graph: {e}")

    # Inserting vertices and edges into the tables
    for doc in chunks:
        text = doc.page_content
        source = doc.metadata.get("source", "unknown")

        if not text.strip():
            continue

        prompt = f"""
        You are an expert in knowledge extraction.

        Given the following technical text:

        {text}

        Extract key entities and relationships in the format:
        - Entity1 -[RELATION]-> Entity2

        Use UPPERCASE for RELATION types.
        Return 'NONE' if nothing found.
        """
        try:
            response = llm_for_rag.invoke(prompt)
            result = response.content.strip()
        except Exception as e:
            print(f"[ERROR] Gen AI call error: {e}")
            continue

        if result.upper() == "NONE":
            continue

        triples = result.splitlines()
        for triple in triples:
            parts = triple.split("-[")
            if len(parts) != 2:
                continue

            right_part = parts[1].split("]->")
            if len(right_part) != 2:
                continue

            raw_relation, entity2 = right_part
            relation = re.sub(r'\W+', '_', raw_relation.strip().upper())
            entity1 = parts[0].strip()
            entity2 = entity2.strip()

            try:
                # Insertion of entities (with existence check)
                cursor.execute("MERGE INTO ENTITIES e USING (SELECT :name AS NAME FROM dual) src ON (e.name = src.name) WHEN NOT MATCHED THEN INSERT (NAME) VALUES (:name)", [entity1, entity1])
                cursor.execute("MERGE INTO ENTITIES e USING (SELECT :name AS NAME FROM dual) src ON (e.name = src.name) WHEN NOT MATCHED THEN INSERT (NAME) VALUES (:name)", [entity2, entity2])
                # Retrieve the IDs
                cursor.execute("SELECT ID FROM ENTITIES WHERE NAME = :name", [entity1])
                source_id = cursor.fetchone()[0]
                cursor.execute("SELECT ID FROM ENTITIES WHERE NAME = :name", [entity2])
                target_id = cursor.fetchone()[0]
                # Create relations
                cursor.execute("""
                    INSERT INTO RELATIONS (SOURCE_ID, TARGET_ID, RELATION_TYPE, SOURCE_TEXT)
                    VALUES (:src, :tgt, :rel, :txt)
                """, [source_id, target_id, relation, source])
                print(f"✅ {entity1} -[{relation}]-> {entity2}")
            except Exception as e:
                print(f"[INSERT ERROR] {e}")

    oracle_conn.commit()
    cursor.close()
    print("💾 Knowledge graph updated.")

Le schéma de graphique est créé avec CREATE PROPERTY GRAPH, liant ENTITIES (vertices) et RELATIONS (edges).
Utilise MERGE INTO pour insérer de nouvelles entités uniquement si elles n'existent pas (garantir l'unicité).
Le LLM (Oracle Generative AI) est utilisé pour extraire des triples du formulaire Entity1 -[RELATION]-> Entity2.
Toutes les interactions avec Oracle sont effectuées via des blocs anonymes oracledb et PL/SQL.

A présent, vous pouvez :

Utilisez PGQL pour explorer et interroger les relations de graphique.
Connectez-vous à Graph Studio pour les visualisations.
Affichez le graphique via un agent REST d'API ou LangChain.

Fonctions de prise en charge des requêtes de graphique

Deux fonctions essentielles permettent la recherche sémantique et le raisonnement sur le graphique de connaissances : extract_graph_keywords et query_knowledge_graph. Ces composants permettent d'interpréter les questions en requêtes graphiques significatives à l'aide de PGQL sur Oracle Autonomous Database.

extract_graph_keywords:

def extract_graph_keywords(question: str) -> str:
    prompt = f"""
    Based on the question below, extract relevant keywords (1 to 2 words per term) that can be used to search for entities and relationships in a technical knowledge graph.

    Question: "{question}"

    Rules:
    - Split compound terms (e.g., "API Gateway" → "API", "Gateway")
    - Remove duplicates
    - Do not include generic words such as: "what", "how", "the", "of", "in the document", etc.
    - Return only the keywords, separated by commas. No explanations.

    Result:
    """
    try:
        resp = llm_for_rag.invoke(prompt)
        keywords_raw = resp.content.strip()

        # Additional post-processing: remove duplicates, normalize
        keywords = {kw.strip().lower() for kw in re.split(r'[,\n]+', keywords_raw)}
        keywords = [kw for kw in keywords if kw]  # remove empty strings
        return ", ".join(sorted(keywords))
    except Exception as e:
        print(f"[KEYWORD EXTRACTION ERROR] {e}")
        return ""

Résultat:

Utilise un LLM (llm_for_rag) pour transformer des questions en langage naturel en une liste de mots-clés conviviaux pour les graphiques.
L'invite est conçue pour extraire correctement les entités et les termes pertinents pour la recherche dans le graphique.

Pourquoi est-ce important :

Il comble l'écart entre les questions non structurées et les requêtes structurées.
Garantit que seuls des termes spécifiques et pertinents pour le domaine sont utilisés pour la mise en correspondance dans la requête PGQL.

Comportement optimisé pour le LLM :

Brise les termes techniques composés.
Supprime les mots d'arrêt (comme quoi, comment, etc.).
Normalise le texte en minuscules et en dédupliquant les termes.

Exemple :

Entrée :

"What are the main components of an API Gateway architecture?"

Mots-clés de sortie :
```
api, gateway, architecture, components
```

query_knowledge_graph:

def query_knowledge_graph(query_text):
    cursor = oracle_conn.cursor()

    sanitized_text = query_text.lower()

    pgql = f"""
        SELECT from_entity,
            relation_type,
            to_entity
        FROM GRAPH_TABLE(
            {GRAPH_NAME}
            MATCH (e1 is ENTITIES)-[r is RELATIONS]->(e2 is ENTITIES)
            WHERE CONTAINS(e1.name, '{sanitized_text}') > 0
            OR CONTAINS(e2.name, '{sanitized_text}') > 0
            OR CONTAINS(r.RELATION_TYPE, '{sanitized_text}') > 0
            COLUMNS (
                e1.name AS from_entity,
                r.RELATION_TYPE AS relation_type,
                e2.name AS to_entity
            )
        )
        FETCH FIRST 20 ROWS ONLY
    """

    print(pgql)

    try:
        cursor.execute(pgql)
        rows = cursor.fetchall()
        if not rows:
            return "⚠️ No relationships found in the graph."

        return "\n".join(f"{r[0]} -[{r[1]}]-> {r[2]}" for r in rows)

    except Exception as e:
        return f"[PGQL ERROR] {e}"

    finally:
        cursor.close()

Résultat:

Accepte une chaîne basée sur un mot-clé (souvent produite par extract_graph_keywords) et construit une requête PGQL pour extraire les relations du graphique de connaissances.

Mécanique clé :

La clause GRAPH_TABLE utilise MATCH pour parcourir le graphique d'un noeud source à un noeud cible.
Il utilise CONTAINS() pour autoriser la recherche partielle et partielle dans les attributs de noeud/d'extrémité (e1.name, e2.name, r.RELATION_TYPE).
Limite les résultats à 20 pour éviter d'inonder la sortie.

Pourquoi utiliser PGQL :

PGQL est de type SQL mais conçu pour la traversée de graphes.
Oracle Autonomous Database prend en charge les graphes de propriétés, ce qui permet une intégration transparente entre les mondes relationnel et graphique.
Offre des fonctionnalités d'indexation, d'optimisation et de recherche de graphes natifs adaptées à l'entreprise.

Notes propres à Oracle :

GRAPH_TABLE() est unique à Oracle PGQL et permet d'interroger les vues logiques des graphiques définis via des tables relationnelles.
Contrairement à Cypher (Neo4j), PGQL s'exécute sur des données structurées à l'aide d'extensions SQL, ce qui le rend plus convivial dans les environnements SGBDR lourds.

Tâche 4 : exécuter le chatbot

Exécutez la commande suivante pour exécuter le chatbot.

python main.py

Accusés de réception

Auteur - Cristiano Hoshikawa (ingénieur solutions d'équipe Oracle LAD A)

Ressources de formation supplémentaires

Explorez d'autres ateliers sur le site docs.oracle.com/learn ou accédez à d'autres contenus d'apprentissage gratuits sur le canal Oracle Learning YouTube. En outre, visitez le site education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

Pour obtenir de la documentation sur le produit, consultez Oracle Help Center.

Informations relatives au titre et au copyright

Create a Knowledge Graph with Oracle Autonomous Database and Property Graph Query Language

G38834-02