Creación de un gráfico de conocimientos con Oracle Autonomous Database y Property Graph Query Language

Introducción

En este tutorial se exploran los conceptos de teoría de grafos, gráficos de conocimientos y cómo se implantan mediante Oracle Autonomous Database con Property Graph Query Language (PGQL). También explica la implantación de Python que se utiliza para extraer relaciones de documentos mediante LLM y almacenarlas como estructuras de gráficos en Oracle.

¿Qué es el gráfico?

Graph es un campo de las matemáticas y la informática centrado en el modelado de relaciones entre objetos. Un gráfico consta de:

Vertices (nodos): representan entidades.
Edificios (enlaces): representan relaciones entre entidades.

Los gráficos se utilizan ampliamente para representar estructuras de datos en redes sociales, redes semánticas, gráficos de conocimiento y más.

¿Qué es un Gráfico de Conocimiento?

Un gráfico de conocimientos es una representación basada en gráficos del conocimiento del mundo real donde:

Los nodos representan entidades como personas, lugares, productos, etc.
Los bordes representan relaciones semánticas. Por ejemplo, trabaja en, parte de, y más.

Los gráficos de conocimiento mejoran la búsqueda semántica, los sistemas de recomendación y las aplicaciones de respuesta a preguntas.

¿Por qué utilizar Oracle Autonomous Database con PGQL?

Oracle proporciona un entorno totalmente gestionado para almacenar y consultar gráficos de propiedades:

PGQL es similar a SQL y está diseñado para consultar patrones de gráficos complejos.
Oracle Autonomous Database permite ejecutar consultas de grafos de forma nativa con funciones de grafos de propiedades, como la creación, las consultas y la visualización.
La integración con LLM permite la extracción automática de estructuras de gráficos a partir de datos no estructurados (como los PDF).

Comparación con otros idiomas de consulta de gráficos

Ventajas de Oracle Autonomous Database con PGQL frente a bases de datos de gráficos tradicionales

Objetivos

Cree un gráfico de conocimientos con Oracle Autonomous Database y PGQL.

Requisitos

Instale Python version 3.10 o superior y la interfaz de línea de comandos de Oracle Cloud Infrastructure (CLI de OCI).

Tarea 1: Instalación de paquetes de Python

El código Python requiere determinadas bibliotecas para utilizar Oracle Cloud Infrastructure (OCI) Generative AI. Ejecute el siguiente comando para instalar los paquetes de Python necesarios. Puede descargar el archivo desde aquí: requirements.txt.

pip install -r requirements.txt

Tarea 2: Creación de una instancia de Oracle Database 23ai (siempre gratis)

En esta tarea, aprenderemos a aprovisionar Oracle Database 23ai en modo Siempre gratis. Esta versión ofrece un entorno totalmente gestionado, ideal para el desarrollo, las pruebas y el aprendizaje, sin costo adicional.

Conéctese a la consola de OCI, vaya a Oracle Database, Autonomous Database y haga clic en Crear instancia de Autonomous Database.
Introduzca la siguiente información.
- Nombre de la base de datos: introduzca un nombre de identificación para la instancia.
- Tipo de carga de trabajo: seleccione Almacén de datos o Procesamiento de transacciones, según sus necesidades.
- Compartimento: seleccione un compartimento adecuado para organizar los recursos.
Seleccione Siempre gratis para asegurarse de que la instancia se aprovisiona de forma gratuita.
Cree una contraseña segura para el usuario ADMIN, que se utilizará para acceder a la base de datos.
Revise la configuración y haga clic en Create Autonomous Database. Espere unos minutos a que la instancia se aprovisione y esté disponible para su uso.

Si no está familiarizado con el proceso de conexión a Oracle Autonomous Database, siga estos enlaces para comprender y configurar correctamente el código.

Nota: Tendrá que conectarse a la base de datos dentro del código Python con el método Wallet.

Tarea 3: Descarga y comprensión del código

Un caso de uso muy común para Graph es utilizarlo como uno de los componentes que trabajan junto con LLM y una base de conocimientos, como archivos PDF.

Vamos a utilizar este tutorial: Análisis de documentos PDF en lenguaje natural con OCI Generative AI como base, que utiliza todos los componentes mencionados. Sin embargo, a los efectos de este documento, nos centraremos en utilizar Oracle Database 23ai junto con Graph. Básicamente, el código Python (main.py) del material base solo se modificará en las partes que utilicen Oracle Database 23ai.

Estos son los procesos ejecutados en este servicio:

Cree el esquema de gráfico.
Extraer entidades y relaciones mediante LLM.
Insertar datos en Oracle.
Cree el gráfico de propiedades.

Descargue el código de gráfico de Python actualizado compatible con Oracle Database 23ai desde aquí: 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.")

El esquema de gráfico se crea con CREATE PROPERTY GRAPH, enlazando ENTITIES (vértices) y RELATIONS (bordes).
Utiliza MERGE INTO para insertar nuevas entidades solo si no existen (lo que garantiza la unicidad).
El LLM (Oracle Generative AI) se utiliza para extraer triples del formulario Entity1 -[RELATION]-> Entity2.
Todas las interacciones con Oracle se realizan a través de bloques anónimos oracledb y PL/SQL.

Ahora puede hacer lo siguiente:

Utilice PGQL para explorar y consultar relaciones de gráficos.
Conéctese a Graph Studio para obtener visualizaciones.
Muestre el gráfico a través de un agente REST o LangChain de API.

Funciones de soporte de consulta de grafos

Hay dos funciones esenciales que permiten la búsqueda semántica y el razonamiento en el gráfico de conocimientos: extract_graph_keywords y query_knowledge_graph. Estos componentes permiten interpretar las preguntas en consultas de gráficos significativas mediante PGQL en 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 ""

Función:

Utiliza un LLM (llm_for_rag) para transformar las preguntas en lenguaje natural en una lista de palabras clave fáciles de usar para gráficos.
La petición de datos está diseñada para extraer de forma limpia entidades y términos que son relevantes para buscar en el gráfico.

Por qué es importante:

Salva la brecha entre preguntas no estructuradas y consultas estructuradas.
Garantiza que solo se utilicen términos específicos relevantes para el dominio para la coincidencia en la consulta PGQL.

Comportamiento mejorado del LLM:

Rompe términos técnicos compuestos.
Elimina palabras irrelevantes (como qué, cómo, etc.).
Normaliza el texto reduciendo y desduplicando los términos.

Ejemplo:

Entrada:

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

Palabras clave de salida:
```
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()

Función:

Acepta una cadena basada en palabras clave (a menudo producida por extract_graph_keywords) y crea una consulta PGQL para recuperar relaciones del gráfico de conocimientos.

Mecánica clave:

La cláusula GRAPH_TABLE utiliza MATCH para recorrer el gráfico del nodo de origen al de destino.
Utiliza CONTAINS() para permitir la búsqueda parcial y parcial en atributos de nodo/perímetro (e1.name, e2.name, r.RELATION_TYPE).
Limita los resultados a 20 para evitar inundar la salida.

Por qué utilizar PGQL:

PGQL es similar a SQL, pero está diseñado para el recorrido de gráficos.
Oracle Autonomous Database soporta gráficos de propiedades, lo que permite una integración perfecta entre los mundos relacional y gráfico.
Ofrece capacidades nativas de búsqueda de gráficos, optimización e indexación listas para la empresa.

Notas específicas de Oracle:

GRAPH_TABLE() es único para Oracle PGQL y permite consultas sobre vistas lógicas de gráficos definidos a través de tablas relacionales.
A diferencia de Cypher (Neo4j), PGQL se ejecuta sobre datos estructurados mediante extensiones SQL, lo que lo hace más amigable en entornos con mucha RDBMS.

Tarea 4: Ejecución del bot conversacional

Ejecute el siguiente comando para ejecutar el bot conversacional.

python main.py

Acuses de recibo

Autor: Cristiano Hoshikawa (Oracle LAD A, ingeniero de soluciones de equipo)

Más recursos de aprendizaje

Explore otros laboratorios en docs.oracle.com/learn o acceda a más contenido de aprendizaje gratuito en el canal YouTube de Oracle Learning. Además, visite education.oracle.com/learning-explorer para convertirse en un explorador de Oracle Learning.

Para obtener documentación sobre el producto, visite Oracle Help Center.

Título e Información de Copyright

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

G38832-02