Antes de começar

Pré-requisitos e criação de credenciais

Nenhuma habilidade prévia é assumida: este é o roteiro completo para gerar, do zero, tudo que os scripts pedem como .

Checklist de pré-requisitos

Autonomous Database 26ai

Provisionado (ATP/ADW), com acesso ADMIN e AI Vector Search disponível.

Acesso ao Console OCI

Usuário com permissão para criar API Signing Key no compartimento correto.

Política IAM

Uso do Generative AI e leitura de objetos no bucket do modelo ONNX (se for usar).

Região com Generative AI

Confirme que a região do seu tenancy oferece o OCI Generative AI (ex.: us-chicago-1 ou sa-saopaulo-1, conforme disponibilidade).

Cliente SQL

Database Actions (SQL Worksheet), SQL Developer ou SQLcl para rodar os scripts.

Workspace APEX

Um workspace disponível (ou permissão para criar um) para instalar a aplicação.

Você preenche cada valor uma única vez

Todo OCID/região/bucket coletado nesta página é digitado uma única vez, na tabela de configuração criada na Seção 2 do 01_ampminsights_db_setup.sql. Os blocos seguintes do script (credencial, modelo ONNX, SELECT AI) leem esses valores automaticamente — você não precisa repetir nenhum OCID em vários lugares do arquivo.

Passo a passo: criar a chave de API da OCI

Esta chave autentica o banco de dados para chamar o OCI Generative AI (e, opcionalmente, o Object Storage). É o único pré-requisito "manual" fora do banco de dados.

  1. Abrir "User settings"

    No Console OCI, clique no seu avatar/usuário (canto superior direito) e selecione "User settings" — ou peça a um administrador OCI para gerar a chave para o usuário/service account que a aplicação vai usar.

  2. Adicionar API key

    No menu lateral, clique em "API keys" e depois em "Add API key".

  3. Gerar o par de chaves

    Selecione "Generate API key pair", clique em "Download private key" (baixa um arquivo .pem) e depois em "Add".

  4. Guardar os 4 valores

    A tela final mostra um "Configuration file preview" com user, fingerprint, tenancy e region. Guarde esses 4 valores — eles vão para a tabela de configuração (Seção 2 do script 1).

  5. Obter o OCID do compartimento

    Identity & Security → Compartments → abra o compartimento do banco → copie o OCID no topo da página.

  6. Obter o namespace do Object Storage

    Console OCI → Storage → Buckets → o "Namespace" aparece no topo da página, independente de qual bucket você abrir. Só necessário se for usar o modelo ONNX (Seção 4 do script 1).

  7. Copiar o conteúdo da chave privada

    Abra o arquivo .pem em um editor de texto simples e copie todo o conteúdo, incluindo as linhas BEGIN/END PRIVATE KEY e as quebras de linha originais. Este é o único valor que não vai para a tabela de configuração — ele é colado direto no bloco da Seção 3, na hora de criar a credencial.

Trate a chave privada como uma senha

Não envie o arquivo .pem por e-mail ou chat, não o suba para repositórios de código e restrinja a política IAM do usuário ao mínimo necessário. Depois de criar a credencial no banco (script 1, Seção 3), o arquivo local pode ser apagado com segurança — o Autonomous Database guarda a chave de forma criptografada e ela não aparece em nenhuma consulta.

Exemplo de política IAM mínima

Política IAM 
Allow group ampminsights-app to use generative-ai-family in compartment <nome-do-compartimento>
Allow group ampminsights-app to read objects in compartment <nome-do-compartimento> where target.bucket.name='<seu-bucket-onnx>'

Onde cada valor da tabela de configuração é preenchido

Campo (PARAM_NAME)Onde obter
EMBEDDING_COMPARTMENTPasso 5 acima (OCID do compartimento do banco).
OCI_TENANCY_OCIDPasso 4 acima (campo tenancy).
OCI_USER_OCIDPasso 4 acima (campo user).
OCI_FINGERPRINTPasso 4 acima (campo fingerprint).
OCI_REGIONPasso 4 acima (campo region), ex.: sa-saopaulo-1.
OS_NAMESPACEPasso 6 acima. Só necessário se for usar o modelo ONNX (Seção 4 do script 1).
OS_BUCKETNome que você escolher para o bucket que vai criar na Seção 4 do script 1.
GENAI_REGIONRegião do OCI Generative AI (Seção 5+) — pode ser diferente de OCI_REGION. Padrão us-chicago-1; troque se sua tenancy não alcançar essa região (ver Operação & observabilidade).
AI_LOG_RETENTION_DAYSPreenchido automaticamente (90 dias) — dias de retenção do log de chamadas de IA/embeddings.
Chave privada (.pem)Passo 7 acima — colada direto na Seção 3 do script 1, nunca na tabela de configuração.
Credenciais do export APEX (apex_cred, RAG_CRED, compartimento no remote server apex_genai)Mesmos valores de tenancy/compartimento acima — preenchidos na importação do app (ver Passo a passo: aplicação APEX).