DBMS_CLOUD_AI - Pacote

O pacote DBMS_CLOUD_AI, com Select AI, facilita e configura a tradução de prompts de linguagem natural para gerar, executar e explicar instruções SQL. Além disso, permite geração aumentada de recuperação e interações baseadas em linguagem natural, incluindo bate-papo com LLMs.

Pré-requisitos

Uma conectividade de saída deve ter sido configurada usando um gateway NAT pelo administrador da frota, conforme descrito abaixo:
  • Crie um gateway NAT na Rede Virtual na Nuvem (VCN) em que seus recursos do Autonomous Database residem seguindo as instruções em Criar um Gateway NAT na Documentação do Oracle Cloud Infrastructure.
  • Após criar o gateway NAT, adicione uma regra de roteamento e uma regra de segurança de saída a cada sub-rede (na VCN) na qual os recursos do Autonomous Database residem para que esses recursos possam usar o gateway para obter uma chave pública da sua instância do Azure AD:
    1. Vá para a página Detalhes da Sub-rede da sub-rede.
    2. Na guia Informações da Sub-rede, clique no nome da Tabela de Rota da sub-rede para exibir sua respectiva página Detalhes da Tabela de Rota.
    3. Na tabela de Regras de Roteamento existentes, verifique se já existe uma regra com as seguintes características:
      • Destino: 0.0.0.0/0
      • Tipo de Destino: Gateway NAT
      • Alvo: O nome do gateway NAT recém-criado na VCN

      Se essa regra não existir, clique em Adicionar Regras de Rota e adicione uma regra de roteamento com essas características.

    4. Retorne à página Detalhes da Sub-rede da sub-rede.
    5. Na tabela Listas de Segurança da sub-rede, clique no nome da lista de segurança da sub-rede para exibir a página Detalhes da Lista de Segurança.
    6. No menu lateral, em Recursos, clique em Regras de Saída.
    7. Na tabela de Regras de Saída existentes, verifique se já existe uma regra com as seguintes características:
      • Tipo de Destino: CIDR
      • Destino: 0.0.0.0/0
      • Protocolo IP: TCP
      • Faixa de Portas de Origem: 443
      • Faixa de Portas de Destino: Todas

      Se essa regra não existir, clique em Adicionar Regras de Saída e adicione uma regra de saída com essas características.

As definições de Proxy HTTP em seu ambiente devem permitir que o banco de dados acesse o provedor de serviços em nuvem.

Essas definições são definidas pelo administrador da frota ao criar a infraestrutura do Exadata Cloud@Customer, conforme descrito em Usando a Console para Provisionar o Exadata Database Service on Cloud@Customer.

Observação:

A configuração de rede, incluindo o Proxy HTTP, só poderá ser editada até que o Exadata Infrastructure esteja no estado Exige Ativação. Depois de ativado, você não poderá editar essas configurações.

A configuração de um Proxy HTTP para uma Infraestrutura do Exadata já provisionada precisa de uma Solicitação de Serviço (SR) no My Oracle Support. Consulte Criar uma Solicitação de Serviço no My Oracle Support para obter detalhes.

Resumo de Subprogramas DBMS_CLOUD_AI

Esta seção abrange os subprogramas DBMS_CLOUD_AI fornecidos com o Autonomous Database.

Subprograma Descrição

Procedimento CREATE_PROFILE

Esse procedimento cria um novo perfil AI para traduzir prompts de linguagem natural para instruções SQL.

Procedimento DISABLE_PROFILE

Este procedimento desativa um perfil do AI no banco de dados atual.

Procedimento DROP_PROFILE

Este procedimento elimina um perfil do AI existente.

Procedimento ENABLE_PROFILE

Esse procedimento permite que um perfil do AI seja usado no banco de dados atual.

Função GENERATE

Esta função gera uma instrução SQL usando AI para traduzir.

Procedimento SET_ATTRIBUTE

Este procedimento define atributos de perfil do AI.

Procedimento SET_PROFILE

Este procedimento define o perfil do AI para o banco de dados atual.

Procedimento CREATE_PROFILE

O procedimento cria um novo perfil AI para traduzir prompts de linguagem natural para instrução SQL.

Sintaxe

DBMS_CLOUD_AI.CREATE_PROFILE
   profile_name        IN  VARCHAR2,
   attributes          IN  CLOB      DEFAULT NULL,
   status              IN  VARCHAR2  DEFAULT NULL,
   description         IN  CLOB      DEFAULT NULL
);

Parâmetros

Parâmetro Descrição

profile_name

Um nome para o perfil AI. O nome do perfil deve seguir as regras de nomenclatura do identificador Oracle SQL. O tamanho máximo do nome do perfil é de 125 caracteres.

Este é um parâmetro obrigatório.

attributes

Atributos de perfil no formato JSON. Consulte Atributos de Perfil do AI para obter mais detalhes.

O valor default é NULL.

status

Status do perfil.

O valor default é ativar.

description

Descrição do perfil AI.

O valor default é NULL.

Exemplo

BEGIN
     DBMS_CLOUD_AI.CREATE_PROFILE(
          profile_name    => 'OpenAI,
          attributes      => JSON_OBJECT('provider' value 'openai',
                                         'credential_name' value 'openai_cred'),
          description     => 'AI profile to use OpenAI for SQL translation'
     );
END;
/

Procedimento DROP_PROFILE

O procedimento elimina um perfil do AI existente. Se o perfil não existir, o procedimento gerará um erro.

Sintaxe

DBMS_CLOUD_AI.DROP_PROFILE(
       profile_name        IN   VARCHAR2,
       force               IN   BOOLEAN DEFAULT FALSE
 );

Parâmetros

Parâmetro Descrição

profile_name

O nome do perfil AI

force

Se TRUE, o procedimento ignorará erros se o perfil do AI não existir.

O valor padrão desse parâmetro é FALSE.

Exemplo

BEGIN
     DBMS_CLOUD_AI.DROP_PROFILE(profile_name => 'OPENAI');
END;
/

Observações sobre Uso

Use force para eliminar um perfil e ignorar erros se o perfil do AI não existir.

Procedimento ENABLE_PROFILE

Esse procedimento ativa o perfil do AI que o usuário especifica. O procedimento altera o status do perfil do AI para ENABLED.

Sintaxe

DBMS_CLOUD_AI.ENABLE_PROFILE(
     profile_name         IN   VARCHAR2
 );

Parâmetros

Parâmetro Descrição

profile_name

Nome do perfil AI a ser ativado

Esse parâmetro é obrigatório.

Exemplo para Ativar o Perfil do AI

BEGIN
     DBMS_CLOUD_AI.ENABLE_PROFILE(
         profile_name    => 'OPENAI'
     );
END;
/

Procedimento DISABLE_PROFILE

Este procedimento desativa o perfil AI no banco de dados atual. O status do perfil do AI é alterado para DISABLED por este procedimento.

Sintaxe

DBMS_CLOUD_AI.DISABLE_PROFILE(
      profile_name  IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição

profile_name

Nome do perfil AI.

Esse parâmetro é obrigatório.

Exemplo

BEGIN
     DBMS_CLOUD_AI.DISABLE_PROFILE(
         profile_name    => 'OPENAI'
     );
END;
/

Procedimento SET_ATTRIBUTE

Esse procedimento permite definir atributos de perfil do AI.

Sintaxe

DBMS_CLOUD_AI.SET_ATTRIBUTE(
      profile_name         IN   VARCHAR2,
      attribute_name       IN   VARCHAR2,
      attribute_value      IN   CLOB
);

Parâmetros

Somente o proprietário pode definir ou modificar os atributos do perfil AI. Para obter uma lista de atributos suportados, consulte Atributos de Perfil.

Parâmetro Descrição

profile_name

Nome do perfil AI para o qual você deseja definir os atributos.

Esse parâmetro é obrigatório.

attribute_name

Nome do atributo de perfil AI

Esse parâmetro é obrigatório.

attribute_value

Valor do atributo de perfil.

O valor default é NULL.

Exemplo

BEGIN
 DBMS_CLOUD_AI.SET_ATTRIBUTE(
   profile_name    => 'OPENAI',
   attribute_name  => 'credential_name',
   attribute_value => 'OPENAI_CRED_NEW'
 );
END;
/

Procedimento SET_PROFILE

Este procedimento define o perfil AI para a sessão atual.

Depois de definir um perfil AI para a sessão do banco de dados, qualquer instrução SQL com o prefixo SELECT AI será considerada um prompt de linguagem natural. Dependendo da ação especificada com o prefixo AI, uma resposta é gerada usando o AI. Para usar o prefixo AI, consulte Usar Palavra-chave AI para Informar Prompts. Opcionalmente, é possível substituir os atributos de perfil ou modificar atributos especificando-os no formato JSON. Consulte Procedimento SET_ATTRIBUTE para definir os atributos.

O perfil AI só poderá ser definido para a sessão atual se o proprietário do perfil AI for o usuário da sessão.

Para definir um perfil de AI para todas as sessões de um usuário de banco de dados específico ou todas as sessões de usuário no banco de dados, considere o uso de um trigger de evento de banco de dados para o evento AFTER LOGON no usuário específico ou no banco de dados inteiro. Consulte Instrução CREATE TRIGGER em Referência de Linguagem PL/SQL do Banco de Dados Oracle Database 19c ou Referência de Linguagem PL/SQL do Banco de Dados Oracle Database 23ai para obter mais detalhes.

Sintaxe

DBMS_CLOUD_AI.SET_PROFILE(
    profile_name      IN  VARCHAR2,
);

Parâmetros

Parâmetro Descrição

profile_name

Um nome para o perfil AI na sessão atual.

Esse parâmetro é obrigatório.

Exemplo


   BEGIN
        DBMS_CLOUD_AI.SET_PROFILE(
          profile_name    => 'OPENAI'
        );
   END;
   /

Função GENERATE

Esta função fornece tradução de IA de maneira sem monitoramento de estado. Com seu perfil do AI existente, você pode usar essa função para executar as ações suportadas, como showsql, narrate ou chat. A ação default é showsql.

A substituição de alguns ou todos os atributos de perfil também é possível usando essa função.

Sintaxe

DBMS_CLOUD_AI.GENERATE(
    prompt          IN  CLOB,
    profile_name    IN  VARCHAR2 DEFAULT NULL,
    action          IN  VARCHAR2 DEFAULT NULL,
    attributes      IN  CLOB     DEFAULT NULL
) RETURN CLOB;

Parâmetros

Parâmetro Descrição

prompt

Prompt de linguagem natural para traduzir usando IA.

O prompt pode incluir SELECT AI <action> como prefixo. A ação também pode ser fornecida separadamente como um parâmetro de "ação". O action fornecido no prompt substitui o parâmetro "action". A ação padrão é showsql.

Esse parâmetro é obrigatório.

profile_name

O nome do perfil AI. Esse parâmetro será opcional se um perfil do AI já estiver definido na sessão usando DBMS_CLOUD_AI.SET_PROFILE.

O valor default é NULL.

As seguintes condições se aplicam:
  • Se um perfil for definido na sessão atual, o usuário poderá omitir o argumento profile_name na função DBMS_CLOUD_AI.GENERATE.
  • Se o argumento profile_name for fornecido na função DBMS_CLOUD_AI.GENERATE, ele substituirá qualquer valor definido na sessão usando o procedimento DBMS_CLOUD_AI.SET_PROFILE.
  • Se não houver um perfil definido na sessão usando o procedimento DBMS_CLOUD_AI.SET_PROFILE, o argumento profile_name deverá ser fornecido na função DBMS_CLOUD_AI.GENERATE.

Observação:

Para o Database Actions, você pode especificar o argumento profile_name em DBMS_CLOUD_AI.GENERATE ou pode executar duas etapas como um script PL/SQL: DBMS_CLOUD_AI.SET_PROFILE e DBMS_CLOUD_AI.GENERATE.
EXEC DBMS_CLOUD_AI.set_profile('OPENAI');

-----------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'showsql')
FROM dual;

------------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'narrate')
FROM dual;
-------------------------------------------
SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'what is oracle autonomous database',
                              profile_name => 'OPENAI',
                              action       => 'chat')
FROM dual;
Consulte Executando Instruções SQL no Editor de Código para obter mais informações.
action

Ação para traduzir prompt natural usando IA. As ações suportadas incluem showsql (padrão), narrate e chat. As descrições das ações são incluídas em Usar Palavras-chave do AI para Informar Prompts.

Observação:

Esta função não suporta a ação runsql. Se você fornecer a ação runsql, ela retornará o seguinte erro:
ORA-20000: runsql action is not supported by generate function ORA-06512: at "C##CLOUD$SERVICE.DBMS_CLOUD", line xxxx 
ORA-06512: at "C##CLOUD$SERVICE.DBMS_CLOUD_AI", line 2696 ORA-06512: at line x
attributes Substitua atributos de perfil de IA específicos fornecendo atributos no formato JSON. Consulte Atributos de Perfil para obter mais detalhes.

Exemplos

Os exemplos a seguir ilustram as ações showsql, narrate e chat que podem ser usadas com a função DBMS_CLOUD_AI.GENERATE.

Veja a seguir um exemplo com a ação showsql:

SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'showsql')
FROM dual;

Veja a seguir um exemplo com a ação narrate:

SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'how many customers',
                              profile_name => 'OPENAI',
                              action       => 'narrate')
FROM dual;

Veja a seguir um exemplo com a ação chat:

SELECT DBMS_CLOUD_AI.GENERATE(prompt       => 'what is oracle autonomous database',
                              profile_name => 'OPENAI',
                              action       => 'chat')
FROM dual;

Atributos de Perfil

Os atributos de um perfil do AI ajudam a gerenciar e configurar o comportamento do perfil do AI. Alguns atributos são opcionais e têm um valor padrão.

Atributos

Nome do Atributo Descrição

azure_deployment_name

Nome do modelo implantado do Azure OpenAI Service. O nome só pode incluir caracteres alfanuméricos, sublinhado (_) e hífen (-). O nome não pode terminar com um sublinhado (_) ou um hífen (-). Para saber como obter o azure_deployment_name, consulte Criar e implantar um recurso do Serviço OpenAI do Azure.

azure_resource_name

Nome do recurso do Serviço OpenAI do Azure. O nome do recurso só pode incluir caracteres alfanuméricos e hifens e não pode começar ou terminar com um hífen. Para saber como obter o azure_resource_name, consulte Criar e implantar um recurso do Serviço OpenAI do Azure.

comments

Inclua comentários de coluna nos metadados usados para traduzir prompts de linguagem natural usando o AI. O tipo de dados BOOLEAN é suportado. Os valores válidos são TRUE ou FALSE para uma string com o tipo de dados VARCHAR2.

Observação:

Os valores boolianos não são aplicáveis no procedimento DBMS_CLOUD_AI.SET_ATTRIBUTE ao definir um único atributo porque o parâmetro attribute_value é do tipo de dados CLOB.

conversation

Um atributo VARCHAR2 que indica se o histórico de conversas está ativado para um perfil. Somente o OpenAI e o Azure OpenAI Service suportam o histórico de conversas. Os valores válidos são true ou false. O valor default é false. Os valores não diferenciam maiúsculas de minúsculas.

credential_name

O nome da credencial para acessar as APIs do provedor de IA.

A credencial usando tokens de portador pode ser criada usando o nome do provedor como o nome do usuário e o token de portador como a senha.

É um atributo obrigatório. Consulte CREATE_CREDENTIAL Procedure.

max_tokens

Denota o número de tokens a serem previstos por geração. O padrão é 1024. Consulte Tokens e Tokenizers para obter mais detalhes.

model

O nome do modelo de IA que está sendo usado para gerar respostas.

Modelos suportados para:

  • OpenAI: gpt-4, gpt-4-0613, gpt-4-32k, gpt-4-32k-0613, gpt-3.5-turbo (padrão), gpt-3.5-turbo-0613, gpt-3.5-turbo-16k, gpt-3.5-turbo-16k-0613
  • Cohere: comando (padrão), command-nightly (experimental), command-light e command-light-nightly (experimental). Modelos menores e "leves" são mais rápidos, enquanto modelos maiores têm melhor desempenho. Modelos personalizados também podem ser fornecidos com seu ID completo.
  • OCI Generative AI: Para OCI Generative AI: cohere.command (padrão). Os modelos pré-treinados para a OCI Generative AI são todos suportados pela Select AI. Modelos personalizados também podem ser fornecidos com seus OCIDs completos.

    Para saber mais sobre os modelos suportados no OCI Generative AI, consulte Modelos Básicos Pré-treinados no Generative AI.

Observação:

Esse parâmetro não é usado para o Azure, pois o modelo é determinado quando você cria sua implantação no portal do Azure OpenAI Service.

object_list

Array de objetos JSON especificando o proprietário e os nomes de objetos elegíveis para tradução de linguagem natural para SQL. Para incluir todos os objetos de um determinado usuário, omita o "nome" e especifique apenas a chave "proprietário" no objeto JSON.

Para traduzir linguagem natural para SQL, o nome do objeto, o proprietário do objeto, as colunas do objeto e os comentários são enviados ao provedor de IA usando solicitações HTTPS. Evite especificar objetos com nome de objeto confidencial, nomes de coluna ou comentários na lista de objetos.

Os provedores de IA podem ter limite no tamanho dos metadados permitidos nas solicitações de tradução. Considere limitar a lista de objetos adequados aos prompts de linguagem natural pelos usuários do aplicativo.

Formato:
[
  {"owner": "SH", "name": "SALES",
  {"owner": "TEST_USER"}
]

oci_compartment_id

Especifica o OCID do compartimento que você tem permissão para acessar ao chamar o serviço OCI Generative AI. O ID do compartimento pode conter caracteres alfanuméricos, hifens e pontos.

O padrão é o ID do compartimento do Autonomous Database.

oci_endpoint_id

Esses atributos indicam o OCID do ponto final do cluster de hospedagem de IA dedicado da Oracle. O ID do ponto final pode conter caracteres alfanuméricos, hifens e pontos. Para localizar o OCID do ponto final, consulte Obtendo Detalhes de um Ponto Final no Serviço Generative AI.

Quando quiser usar o cluster de IA dedicado da Oracle, forneça o OCID do ponto final do cluster de hospedagem.

Por padrão, o ID do ponto final está vazio e o modelo está sob demanda em uma infraestrutura compartilhada.

oci_runtimetype

Este atributo indica o tipo de runtime do modelo fornecido. Esse atributo é obrigatório quando o atributo model é especificado e é aplicável aos Modelos de Geração do OCI.

Todos os valores permitidos podem ser encontrados no OCI Generative AI runtimeType. Consulte LlmInferenceRequest Referência.

Os valores suportados são:
  • COHERE
  • LLAMA

provider

Provedor de IA para o perfil de IA.

Provedores suportados:

  • openai
  • cohere
  • azul-celeste
  • oci
  • google
  • antrópico
  • rosto abraçando

É um atributo obrigatório.

region

Este atributo indica o local do cluster do Generative AI que você deseja usar. A região pode conter caracteres alfanuméricos e hífen.

Observação:

O cluster do Oracle Generative AI está disponível nas regiões de Chicago, Frankfurt e Londres. Consulte Modelos Fundamentais Pré-treinados no Serviço Generative AI.
A região padrão é us-chicago-1.

stop_tokens

O texto gerado será encerrado no início da sequência de parada mais antiga. A sequência será incorporada ao texto. O valor do atributo deve ser um array válido de valores de string no formato JSON. stop_tokens usa um array JSON como entrada. Para saber mais sobre tokens de parada ou sequências de parada, consulte a documentação OpenAI ou Cohere.

temperature

A amostragem dos modelos Gerar Texto incorpora aleatoriedade, de modo que o mesmo prompt pode gerar saídas diferentes toda vez que você clicar em "gerar". A temperatura é um número flutuante não negativo usado para ajustar o grau de aleatoriedade. Temperaturas mais baixas significam gerações menos aleatórias. Consulte Temperatura para obter mais detalhes. Esse parâmetro é aplicável a todos os provedores de serviços suportados.

O exemplo a seguir é usar Cohere como o provedor e exibe atributos de perfil personalizados:
BEGIN
  DBMS_CLOUD_AI.CREATE_PROFILE(
     profile_name => 'COHERE',
     attributes =>
      '{"provider": "cohere",
        "credential_name": "COHERE_CRED",
        "object_list": [{"owner": "ADB_USER"}],
        "max_tokens":512,
        "stop_tokens": [";"],
        "model": "command-nightly",
        "temperature": 0.5,
        "comments": true
       }');
END;
/

O exemplo a seguir mostra atributos de perfil personalizados usando o OCI Generative AI:

BEGIN                                                                        
  DBMS_CLOUD_AI.CREATE_PROFILE(                                              
      profile_name => 'GENAI',                                                             
      attributes => '{"provider": "oci",                                                                   
        "credential_name": "GENAI_CRED",                                     
        "object_list": [{"owner": "SH", "name": "customers"},                
                        {"owner": "SH", "name": "countries"},                
                        {"owner": "SH", "name": "supplementary_demographics"},
                        {"owner": "SH", "name": "profits"},                  
                        {"owner": "SH", "name": "promotions"},               
                        {"owner": "SH", "name": "products"}],
        "oci_compartment_id": "ocid1.compartment.oc1...",
	"oci_endpoint_id": "ocid1.generativeaiendpoint.oc1.us-chicago-1....",
	"region": "us-chicago-1",
	"model": "cohere.command-light",
	"oci_runtimetype": "COHERE"            
       }');                                                                  
END;                                                                         
/