Crie um Knowledge Graph com o Oracle Autonomous Database e a Property Graph Query Language

Introdução

Este tutorial explora os conceitos de teoria de grafos, grafos de conhecimento e como eles são implementados usando o Oracle Autonomous Database com Property Graph Query Language (PGQL). Ela também explica a implementação do Python usada para extrair relacionamentos de documentos usando LLMs e armazená-los como estruturas de gráfico na Oracle.

O que é Gráfico?

Graph é um campo da matemática e da ciência da computação focado em modelar relações entre objetos. Um gráfico consiste em:

Vértices (Nós): Representa entidades.
Bordas (Links): Representa relacionamentos entre entidades.

Os gráficos são amplamente utilizados para representar estruturas de dados em redes sociais, redes semânticas, gráficos de conhecimento e muito mais.

O que é um Knowledge Graph?

Um gráfico de conhecimento é uma representação baseada em gráfico do conhecimento do mundo real em que:

Os nós representam entidades como pessoas, locais, produtos, etc.
As bordas representam relacionamentos semânticos. Por exemplo, trabalha em, parte e muito mais.

Os gráficos de conhecimento aprimoram a pesquisa semântica, os sistemas de recomendação e os aplicativos de resposta a perguntas.

Por que Usar o Oracle Autonomous Database com PGQL?

A Oracle fornece um ambiente totalmente gerenciado para armazenar e consultar gráficos de propriedades:

O PGQL é semelhante a SQL e projetado para consultar padrões gráficos complexos.
O Oracle Autonomous Database permite executar consultas de gráfico nativamente com recursos de gráfico de propriedades, incluindo criação, consulta e visualização.
A integração com os LLMs permite a extração automática de estruturas de gráficos de dados não estruturados (como PDFs).

Comparação com Outros Idiomas de Consulta de Gráfico

Vantagens do Oracle Autonomous Database com PGQL versus Bancos de Dados de Gráficos Tradicionais

Objetivos

Crie um gráfico de conhecimento com o Oracle Autonomous Database e o PGQL.

Pré-requisitos

Instale o Python version 3.10 ou superior e a CLI do OCI (Oracle Cloud Infrastructure Command Line Interface).

Tarefa 1: Instalar Pacotes Python

O código Python requer certas bibliotecas para usar a IA Generativa da Oracle Cloud Infrastructure (OCI). Execute o seguinte comando para instalar os pacotes Python necessários. É possível fazer download do arquivo aqui: requirements.txt.

pip install -r requirements.txt

Tarefa 2: Criar um Oracle Database 23ai (Sempre Gratuito)

Nesta tarefa, aprenderemos a provisionar um Oracle Database 23ai no modo Always Free. Esta versão oferece um ambiente totalmente gerenciado, ideal para desenvolvimento, teste e aprendizado, sem custo adicional.

Faça log-in na Console do OCI, navegue até Oracle Database, Autonomous Database e clique em Criar Instância do Autonomous Database.
Digite as seguintes informações.
- Nome do Banco de Dados: Informe um nome de identificação para sua instância.
- Tipo de Carga de Trabalho: Selecione Data Warehouse ou Processamento de Transações, de acordo com suas necessidades.
- Compartimento: Selecione um compartimento apropriado para organizar seus recursos.
Selecione Always Free para garantir que a instância seja provisionada gratuitamente.
Crie uma senha segura para o usuário ADMIN, que será usada para acessar o banco de dados.
Verifique as definições e clique em Criar Autonomous Database. Aguarde alguns minutos para que a instância seja provisionada e esteja disponível para uso.

Se você não estiver familiarizado com o processo de conexão com o Oracle Autonomous Database, siga esses links para entender e configurar seu código corretamente.

Observação: Você precisará estabelecer conexão com o banco de dados dentro do seu código Python com o método Wallet.

Tarefa 3: Fazer Download e Compreender o Código

Um caso de uso muito comum para o Graph é usá-lo como um dos componentes que trabalham em conjunto com LLMs e uma base de conhecimento, como arquivos PDF.

Usaremos este tutorial: Analise Documentos PDF em Linguagem Natural com a OCI Generative AI como nossa base, que usa todos os componentes mencionados. No entanto, para o propósito deste documento, nos concentraremos no uso do Oracle Database 23ai juntamente com o Graph. Basicamente, o código Python (main.py) do material base será modificado somente nas partes que usam o Oracle Database 23ai.

Estes são os processos executados neste serviço:

Crie o esquema de gráfico.
Extrair entidades e relacionamentos usando LLM.
Inserir dados na Oracle.
Crie o gráfico de propriedades.

Faça download do código de gráfico Python atualizado compatível com o Oracle Database 23ai aqui: 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.")

O esquema de gráfico é criado com CREATE PROPERTY GRAPH, vinculando ENTITIES (vértices) e RELATIONS (bordas).
Usa MERGE INTO para inserir novas entidades somente se elas não existirem (garantindo a exclusividade).
O LLM (Oracle Generative AI) é usado para extrair triplos do formulário Entity1 -[RELATION]-> Entity2.
Todas as interações com a Oracle são feitas por meio de blocos anônimos do oracledb e do código PL/SQL.

Agora, você pode:

Use PGQL para explorar e consultar relacionamentos gráficos.
Estabeleça conexão com o Graph Studio para visualizações.
Exponha o gráfico por meio de um agente REST ou LangChain da API.

Funções de Suporte da Consulta de Gráfico

Há duas funções essenciais que permitem pesquisa semântica e raciocínio no gráfico de conhecimento: extract_graph_keywords e query_knowledge_graph. Esses componentes permitem que as perguntas sejam interpretadas em consultas gráficas significativas usando PGQL no 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 ""

O que essa opção faz:

Usa um LLM (llm_for_rag) para transformar perguntas em linguagem natural em uma lista de palavras-chave simples para gráficos.
O prompt foi projetado para extrair entidades e termos que sejam relevantes para pesquisar o gráfico.

Por que isso é importante:

Ele preenche a lacuna entre perguntas não estruturadas e consultas estruturadas.
Garante que somente termos específicos relevantes ao domínio sejam usados para correspondência na consulta PGQL.

Comportamento aprimorado por LLM:

Quebra termos técnicos compostos.
Remove palavras de parada (como o que, como e assim por diante).
Normaliza o texto por termos minúsculos e deduplicativos.

Exemplo:

Entrada:

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

Palavras-chave de saída:
```
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()

O que essa opção faz:

Aceita uma string baseada em palavra-chave (geralmente produzida por extract_graph_keywords) e constrói uma consulta PGQL para recuperar relacionamentos do gráfico de conhecimento.

Mecânica chave:

A cláusula GRAPH_TABLE usa MATCH para percorrer o gráfico do nó de origem para o de destino.
Ele usa CONTAINS() para permitir pesquisa parcial e difusa em atributos de nó/borda (e1.name, e2.name, r.RELATION_TYPE).
Limita os resultados a 20 para evitar inundar a saída.

Por que usar PGQL:

O PGQL é semelhante a SQL, mas projetado para travessia de gráfico.
O Oracle Autonomous Database oferece suporte a gráficos de propriedades, o que permite uma integração perfeita entre os mundos relacional e gráfico.
Oferece recursos de indexação, otimização e pesquisa de gráficos nativos prontos para a empresa.

Observações Específicas da Oracle:

O GRAPH_TABLE() é exclusivo do Oracle PGQL e permite consultas sobre views lógicas de gráficos definidos por meio de tabelas relacionais.
Ao contrário do Cypher (Neo4j), o PGQL executa dados estruturados usando extensões SQL, tornando-o mais amigável em ambientes pesados de RDBMS.

Tarefa 4: Executar o Chatbot

Execute o comando a seguir para executar o chatbot.

python main.py

Confirmações

Autor - Cristiano Hoshikawa (Oracle LAD A, Engenheiro de Soluções de Equipe)

Mais Recursos de Aprendizado

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal do Oracle Learning YouTube. Além disso, acesse education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.

Título e Informações de Copyright

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

G38838-02