Crea un Knowledge Graph con Oracle Autonomous Database e Property Graph Query Language

Introduzione

Questa esercitazione esplora i concetti di teoria dei grafici, knowledge graph e come vengono implementati utilizzando Oracle Autonomous Database con Property Graph Query Language (PGQL). Inoltre, spiega l'implementazione di Python utilizzata per estrarre le relazioni dai documenti utilizzando LLM e memorizzarle come strutture grafiche in Oracle.

Che cos'è Graph?

Graph è un campo di matematica e informatica focalizzato sulla modellazione di relazioni tra oggetti. Un grafico è costituito da:

Vertici (nodi): rappresentano le entità.
Edge (collegamenti): rappresentano le relazioni tra entità.

I grafici sono ampiamente utilizzati per rappresentare le strutture di dati nei social network, nelle reti semantiche, nei grafici della conoscenza e altro ancora.

Che cos'è un Knowledge Graph?

Un knowledge graph è una rappresentazione basata su grafici della conoscenza del mondo reale in cui:

I nodi rappresentano entità quali persone, luoghi, prodotti e così via.
I bordi rappresentano relazioni semantiche. Ad esempio, funziona in, parte di e altro ancora.

I grafici delle conoscenze migliorano la ricerca semantica, i sistemi di raccomandazione e le applicazioni di risposta alle domande.

Perché utilizzare Oracle Autonomous Database con PGQL?

Oracle offre un ambiente completamente gestito per memorizzare ed eseguire query sui grafici delle proprietà:

PGQL è simile a SQL e progettato per eseguire query su pattern grafici complessi.
Oracle Autonomous Database consente di eseguire query su grafici in maniera nativa con funzioni di grafico delle proprietà, tra cui creazione, esecuzione di query e visualizzazione.
L'integrazione con LLM consente l'estrazione automatica di strutture grafiche da dati non strutturati (come i PDF).

Confronto con altre lingue query grafico

Vantaggi di Oracle Autonomous Database con PGQL e database grafici tradizionali

Obiettivi

Crea un knowledge graph con Oracle Autonomous Database e PGQL.

Prerequisiti

Installare Python version 3.10 o versione successiva e l'interfaccia della riga di comando di Oracle Cloud Infrastructure (OCI CLI).

Task 1: Installa pacchetti Python

Il codice Python richiede determinate librerie per utilizzare l'intelligenza artificiale generativa di Oracle Cloud Infrastructure (OCI). Eseguire il comando seguente per installare i pacchetti Python necessari. È possibile scaricare il file da qui: requirements.txt.

pip install -r requirements.txt

Task 2: Creare un Oracle Database 23ai (sempre gratuito)

In questo task verrà descritto come eseguire il provisioning di un Oracle Database 23ai in modalità Sempre gratuita. Questa versione offre un ambiente completamente gestito, ideale per lo sviluppo, il test e l'apprendimento, senza costi aggiuntivi.

Eseguire il login a OCI Console, andare a Oracle Database, Autonomous Database e fare clic su Crea istanza di Autonomous Database.
Immettere le informazioni riportate di seguito.
- Nome database: immettere un nome identificativo per l'istanza.
- Tipo di carico di lavoro: selezionare Data Warehouse o Elaborazione transazioni in base alle proprie esigenze.
- Compartimento: selezionare un compartimento appropriato per organizzare le risorse.
Selezionare Sempre gratis per assicurarsi che il provisioning dell'istanza venga eseguito gratuitamente.
Creare una password sicura per l'utente ADMIN, che verrà utilizzata per accedere al database.
Rivedere le impostazioni e fare clic su Crea Autonomous Database. Attendere alcuni minuti prima che il provisioning dell'istanza venga eseguito e sia disponibile per l'uso.

Se non hai familiarità con il processo di connessione a Oracle Autonomous Database, segui questi collegamenti per comprendere e configurare correttamente il tuo codice.

Nota: sarà necessario connettersi al database all'interno del codice Python con il metodo Wallet.

Task 3: Scaricare e Comprendere il Codice

Un caso d'uso molto comune per Graph è quello di usarlo come uno dei componenti che lavorano insieme a LLM e una knowledge base, come i file PDF.

Useremo questa esercitazione: Analizza i documenti PDF in linguaggio naturale con l'AI generativa OCI come base, che utilizza tutti i componenti menzionati. Tuttavia, ai fini di questo documento, ci concentreremo sull'uso di Oracle Database 23ai insieme a Graph. In pratica, il codice Python (main.py) del materiale di base verrà modificato solo nelle parti che utilizzano Oracle Database 23ai.

Di seguito sono riportati i processi eseguiti su questo servizio.

Creare lo schema del grafico.
Estrai entità e relazioni utilizzando LLM.
Inserire i dati in Oracle.
Creare il grafico delle proprietà.

Scarica il codice grafico Python aggiornato compatibile con Oracle Database 23ai da qui: 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.")

Lo schema grafico viene creato con CREATE PROPERTY GRAPH, collegando ENTITIES (vertici) e RELATIONS (edge).
Utilizza MERGE INTO per inserire nuove entità solo se non esistono (assicurandone l'univocità).
LLM (Oracle Generative AI) viene utilizzato per estrarre tripli del modulo Entity1 -[RELATION]-> Entity2.
Tutte le interazioni con Oracle vengono eseguite tramite blocchi anonimi oracledb e PL/SQL.

Ora è possibile:

Utilizzare PGQL per esplorare ed eseguire query sulle relazioni dei grafici.
Connettersi a Graph Studio per le visualizzazioni.
Esporre il grafico tramite un agente REST o LangChain API.

Funzioni di supporto query grafico

Ci sono due funzioni essenziali che consentono la ricerca semantica e il ragionamento sul grafico knowledge: extract_graph_keywords e query_knowledge_graph. Questi componenti consentono di interpretare le domande in query grafiche significative utilizzando PGQL su 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 ""

Descrizione:

Utilizza un LLM (llm_for_rag) per trasformare le domande in linguaggio naturale in un elenco di parole chiave grafiche.
Il prompt è progettato per estrarre in modo pulito le entità e i termini rilevanti per la ricerca nel grafico.

Perché è importante:

Colma il divario tra domande non strutturate e query strutturate.
Garantisce che vengano utilizzati solo termini specifici relativi al dominio per la corrispondenza nella query PGQL.

Comportamento potenziato dai LLM:

Interrompe i termini tecnici composti.
Rimuove le stopword (come cosa, come e così via).
Normalizza il testo mediante termini minuscoli e di deduplicazione.

Esempio:

Input:

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

Parole chiave di output:
```
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()

Descrizione:

Accetta una stringa basata su parole chiave (spesso prodotta da extract_graph_keywords) e crea una query PGQL per recuperare le relazioni dal grafico knowledge.

Meccanica chiave:

La clausola GRAPH_TABLE utilizza MATCH per attraversare il grafico dal nodo di origine a quello di destinazione.
Utilizza CONTAINS() per consentire la ricerca parziale e non esatta negli attributi nodo/edge (e1.name, e2.name, r.RELATION_TYPE).
Limita i risultati a 20 per evitare di inondare l'output.

Perché utilizzare PGQL:

PGQL è simile a SQL ma progettato per la traversata del grafico.
Oracle Autonomous Database supporta i grafici delle proprietà, che consentono una perfetta integrazione tra mondi relazionali e grafici.
Offre funzionalità di indicizzazione, ottimizzazione e ricerca grafica nativa pronte per l'azienda.

Note specifiche di Oracle:

GRAPH_TABLE() è univoco per Oracle PGQL e consente query su viste logiche dei grafici definiti tramite tabelle relazionali.
A differenza di Cypher (Neo4j), PGQL esegue i dati strutturati utilizzando le estensioni SQL, rendendolo più amichevole negli ambienti RDBMS-pesanti.

Task 4: Eseguire il chatbot

Eseguire il comando riportato di seguito per eseguire il chatbot.

python main.py

Conferme

Autore - Cristiano Hoshikawa (Oracle LAD A, Solution Engineer del team)

Altre risorse di apprendimento

Esplora altri laboratori su docs.oracle.com/learn o accedi a più contenuti di formazione gratuiti sul canale YouTube di Oracle Learning. Inoltre, visitare education.oracle.com/learning-explorer per diventare Oracle Learning Explorer.

Per la documentazione del prodotto, visitare Oracle Help Center.

Titolo e informazioni sul copyright

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

G38835-02