Créer un graphique de connaissances avec Oracle Autonomous Database et le langage d'interrogation Property Graph

Présentation

Ce tutoriel explore les concepts de théorie des graphiques, de graphiques de connaissances et de leur mise en oeuvre à l'aide d'Oracle Autonomous Database avec Property Graph Query Language (PGQL). Elle explique également la mise en oeuvre Python utilisée pour extraire les relations des documents à l'aide de LLM et les stocker sous forme de structures graphiques dans Oracle.

Qu'est-ce que Graph?

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

Vertices (Noeuds) : Représentent des entités.
Arêtes (liens) : Représente 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 à, en partie, et plus encore.

Les graphiques de connaissances améliorent la recherche sémantique, les systèmes de recommandation et les applications de réponse aux questions.

Pourquoi utiliser Oracle Autonomous Database avec PGQL?

Oracle fournit un environnement entièrement géré permettant de stocker et d'interroger des graphiques de propriétés :

PGQL est de type SQL et conçu pour l'interrogation de modèles de graphique complexes.
Oracle Autonomous Database permet l'exécution native des interrogations de graphique avec des fonctions de graphique de propriété, notamment la création, l'interrogation et la visualisation.
L'intégration avec les LLM permet l'extraction automatique de structures graphiques à partir de données non structurées (telles que des PDF).

Comparaison avec d'autres langages d'interrogation de graphique

Avantages d'Oracle Autonomous Database avec PGQL et les bases de données graphiques traditionnelles

Objectifs

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

Conditions requises

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

Tâche 1 : Installer les ensembles Python

Le code Python nécessite certaines bibliothèques pour utiliser l'IA générative d'Oracle Cloud Infrastructure (OCI). Exécutez la commande suivante pour installer les ensembles 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 gratuite)

Dans cette tâche, nous allons apprendre à provisionner une base de données 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, naviguez jusqu'à Oracle Database, Autonomous Database et cliquez sur Créer une instance Autonomous Database.
Entrez les informations suivantes .
- Nom de la base de données : Entrez un nom d'identification pour votre instance.
- Type de charge de travail : Sélectionnez Entrepôt de données ou Traitement des transactions, selon 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 Créer une base de données Autonomous Database. Attendez quelques minutes que l'instance soit provisionnée et disponible pour utilisation.

Si vous ne connaissez pas le processus de connexion à Oracle Autonomous Database, suivez ces liens pour comprendre et configurer correctement votre code.

Note : Vous devrez vous connecter à la base de données dans votre code Python à l'aide de la méthode de portefeuille.

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 des LLM et une base de connaissances, tels que des fichiers PDF.

Nous utiliserons ce tutoriel : Analyser des documents PDF en langage naturel avec l'intelligence artificielle générative pour OCI en tant que base, qui utilise tous les composants mentionnés. Toutefois, aux fins du présent document, nous allons nous concentrer sur l'utilisation d'Oracle Database 23ai avec Graph. Fondamentalement, le code Python (main.py) à partir du matériel de base sera modifié uniquement dans les pièces qui utilisent Oracle Database 23ai.

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

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

Téléchargez le code de 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 (ajustements).
Utilise MERGE INTO pour insérer de nouvelles entités uniquement si elles n'existent pas (garantir l'unicité).
Le GML (Oracle Generative AI) est utilisé pour extraire les triples du formulaire Entity1 -[RELATION]-> Entity2.
Toutes les interactions avec Oracle sont effectuées au moyen de blocs anonymes oracledb et PL/SQL.

Maintenant, vous pouvez :

Utilisez PGQL pour explorer et interroger les relations de graphique.
Connectez-vous à Graph Studio pour les visualisations.
Présentez le graphique au moyen d'un agent REST ou LangChain d'API.

Fonctions de prise en charge des interrogations 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 interrogations 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 ""

Fonction :

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

Pourquoi c'est important :

Il comble le fossé 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 l'interrogation PGQL.

Comportement amélioré par LLM :

Rupture les termes techniques composés.
Supprime les mots vides (par exemple, quoi, comment, etc.).
Normalise le texte en minuscules et en déduplicant 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()
```
Fonction :
- Accepte une chaîne basée sur des mots clés (souvent produite par extract_graph_keywords) et construit une interrogation PGQL pour extraire les relations à partir du graphique de connaissances.
Mécanique clé :
- La clause GRAPH_TABLE utilise MATCH pour parcourir le graphique de la source au noeud cible.
- Il utilise CONTAINS() pour autoriser la recherche partielle et floue dans les attributs de noeud/bordure (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 graphe.
- Oracle Autonomous Database prend en charge les graphiques de propriétés, ce qui permet une intégration transparente entre les mondes relationnel et graphique.
- Offre des fonctions d'indexation, d'optimisation et de recherche de graphiques natifs prêtes pour l'entreprise.
Notes propres à Oracle :
- GRAPH_TABLE() est unique à Oracle PGQL et permet les interrogations sur des vues logiques de graphiques définis au moyen de 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 riches en SGBDR.

Tâche 4 : Exécuter l'agent conversationnel

Exécutez la commande suivante pour exécuter l'agent conversationnel.

python main.py

Remerciements

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

Ressources d'apprentissage supplémentaires

Explorez d'autres laboratoires sur le site docs.oracle.com/learn ou accédez à plus de contenu d'apprentissage gratuit sur le canal Oracle Learning YouTube. De plus, visitez education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

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

Informations sur le titre et les droits d'auteur

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

G38833-02