From 1c607f3f728a283a9d5a7ccbcba2d5b339b77256 Mon Sep 17 00:00:00 2001 From: Antonio Sergio Rodrigues Figueiredo Date: Fri, 24 Jul 2026 17:39:39 -0300 Subject: [PATCH] Adiciona criterios de validacao apos cada etapa critica Depois de uma sessao de troubleshooting real (schema errado, tipo de OCID errado, credencial com valor velho, Application Settings do APEX desincronizadas da tabela de config), formaliza cada um desses pontos como uma checagem que roda imediatamente apos a etapa correspondente, em vez de so aparecer como sintoma bem mais tarde: - Entre Secao 1 e 2: confirma que a sessao trocou para AMPMINSIGHTS (SELECT USER FROM DUAL) antes de continuar. - Fim da Secao 2: confere que EMBEDDING_COMPARTMENT/OCI_TENANCY_OCID/ OCI_USER_OCID tem o PREFIXO de OCID certo (nao so que foram preenchidos) - pega o caso real de hoje onde o OCID do Autonomous Database foi colado no lugar do compartimento. - Fim da Secao 3: lembrete de que a credencial precisa ser recriada se EMBEDDING_COMPARTMENT mudar depois dela ja existir. - Fim da Secao 7: confere STATUS = VALID dos 6 objetos novos antes de seguir pra instalacao do APEX. - docs/09: nova secao explicando que a lupa "AI Insight" le credencial/ compartimento/regiao das Application Settings do APEX (Shared Components), nao da TB_26AI_TECH_PARAMS - as duas fontes precisam ser mantidas em sincronia manualmente. Duas linhas novas no checklist de erros comuns. Co-Authored-By: Claude Sonnet 5 --- docs/04-passo-a-passo-banco.html | 60 +++++++++++++++++++++++++-- docs/09-operacao-observabilidade.html | 23 ++++++++++ sql/01_ampminsights_db_setup.sql | 52 +++++++++++++++++++++++ 3 files changed, 131 insertions(+), 4 deletions(-) diff --git a/docs/04-passo-a-passo-banco.html b/docs/04-passo-a-passo-banco.html index ec83104..7600204 100644 --- a/docs/04-passo-a-passo-banco.html +++ b/docs/04-passo-a-passo-banco.html @@ -153,7 +153,16 @@ WHERE principal = 'AMPMINSIGHTS'; -------------------------------------------------------------------------------- -- A partir daqui, conecte-se como o usuario AMPMINSIGHTS (nao mais como ADMIN) --------------------------------------------------------------------------------- +-------------------------------------------------------------------------------- +-- +-- VALIDACAO (rode antes de continuar - erro mais comum deste script): +SELECT USER FROM DUAL; +-- Tem que retornar AMPMINSIGHTS. Se retornar ADMIN, voce ainda nao trocou de +-- usuario/sessao - troque agora, senao a SECAO 2 (e tudo depois) vai falhar +-- com ORA-00942 (table or view "ADMIN"."TB_26AI_TECH_PARAMS" does not exist). +-- No Database Actions/SQL Developer Web, trocar o "schema" num seletor do +-- Worksheet NAO basta - precisa fazer login de novo com o usuario/senha do +-- AMPMINSIGHTS.

Seção 2 · Tabela de configuracao (preencha os valores UMA UNICA VEZ aqui)

Agora conecte como o usuário AMPMINSIGHTS que você acabou de criar (não mais @@ -235,7 +244,26 @@ COMMIT; -- Confira: nenhuma linha abaixo deve ainda mostrar um valor "<SUBSTITUA...>" -- antes de voce seguir para a SECAO 3. -SELECT param_name, param_value, description FROM TB_26AI_TECH_PARAMS ORDER BY param_name; +SELECT param_name, param_value, description FROM TB_26AI_TECH_PARAMS ORDER BY param_name; + +-- VALIDACAO EXTRA: confere que cada OCID e do TIPO certo, nao so que foi +-- preenchido. Ja aconteceu de EMBEDDING_COMPARTMENT ser preenchido com o +-- OCID do proprio Autonomous Database (ocid1.autonomousdatabase...) em vez +-- do compartimento (ocid1.compartment...) - o valor "parece" um OCID valido +-- e passa despercebido, mas quebra silenciosamente mais tarde (Generative AI +-- retorna ORA-20404 "Object not found", dificil de associar a este campo). +SELECT param_name, param_value, + CASE + WHEN param_name = 'EMBEDDING_COMPARTMENT' AND param_value NOT LIKE 'ocid1.compartment.%' + THEN 'ERRO: deveria comecar com ocid1.compartment. - confira se nao colou o OCID do banco/Autonomous Database por engano' + WHEN param_name = 'OCI_TENANCY_OCID' AND param_value NOT LIKE 'ocid1.tenancy.%' + THEN 'ERRO: deveria comecar com ocid1.tenancy.' + WHEN param_name = 'OCI_USER_OCID' AND param_value NOT LIKE 'ocid1.user.%' + THEN 'ERRO: deveria comecar com ocid1.user.' + ELSE 'OK' + END AS validacao +FROM TB_26AI_TECH_PARAMS +WHERE param_name IN ('EMBEDDING_COMPARTMENT', 'OCI_TENANCY_OCID', 'OCI_USER_OCID');

Seção 3 · Credencial de acesso a OCI (Generative AI + Object Storage)

Cria a credencial OCI_CRED, usada pelo banco para chamar o OCI Generative AI e o @@ -311,7 +339,16 @@ END; -- Conferir que a credencial foi criada (nao mostra a chave privada) SELECT credential_name, username, comments FROM user_credentials -WHERE credential_name = 'OCI_CRED'; +WHERE credential_name = 'OCI_CRED'; + +-- VALIDACAO/LEMBRETE: esta credencial grava tenancy/user/compartment por +-- dentro, NO MOMENTO em que e criada. Se voce corrigir qualquer valor da +-- SECAO 2 (principalmente EMBEDDING_COMPARTMENT) DEPOIS de ja ter rodado +-- este bloco, a credencial antiga continua com o valor velho - corrigir a +-- tabela sozinho NAO conserta. Nesse caso, rode: +-- BEGIN DBMS_VECTOR_CHAIN.DROP_CREDENTIAL(credential_name => 'OCI_CRED'); END; +-- / +-- e este bloco de novo, nesta ordem.

Seção 4 · Modelo de embeddings ONNX

Opcional — só necessária se você for usar embeddings de imagem/texto combinados (CLIP). O @@ -1789,7 +1826,22 @@ EXCEPTION END IF; COMMIT; END; -/ +/ + +-- VALIDACAO: confere que todos os objetos desta secao compilaram sem erro +-- antes de seguir para a instalacao do APEX. Nao vale so olhar se o CREATE +-- "rodou sem erro na tela" - PL/SQL pode compilar um objeto que chama outro +-- ainda inexistente sem acusar erro na hora (resolucao adiada de nomes); o +-- STATUS aqui e a fonte de verdade. +SELECT object_name, object_type, status +FROM user_objects +WHERE object_name IN ('TB_26AI_TECH_LOG','PRC_26AI_TECH_LOG','FNC_26AI_EMBED', + 'FNC_26AI_TECH_RAG','FNC_26AI_RAG','PRC_26AI_TECH') +ORDER BY object_name; +-- As 6 linhas tem que aparecer com STATUS = VALID. Se alguma faltar, o +-- CREATE dela nao rodou (role a secao de novo); se aparecer INVALID, rode +-- para descobrir o motivo: +-- SELECT line, position, text FROM user_errors WHERE name = '<NOME_DO_OBJETO>' ORDER BY sequence;

Seção 8 · Instalar a aplicacao APEX (ampmInsights)

Últimos passos, agora fora do SQL Worksheet: instalar a aplicação APEX. Detalhado em diff --git a/docs/09-operacao-observabilidade.html b/docs/09-operacao-observabilidade.html index 285f708..2a2a363 100644 --- a/docs/09-operacao-observabilidade.html +++ b/docs/09-operacao-observabilidade.html @@ -52,6 +52,8 @@ rapidamente qualquer problema, e o checklist abaixo para os casos mais comuns.Erro de rede/timeout ao chamar o Generative AIACL de rede (Seção 1.6) não cobre o host correto.SELECT host, privilege FROM dba_host_aces WHERE principal = 'AMPMINSIGHTS'; — deve listar inference.generativeai.us-chicago-1.oci.oraclecloud.com com RESOLVE e CONNECT. ORA-20404 ("Object not found", domínio oci.my$cloud_domain)Perfil de SELECT AI usando a região "de casa" do tenancy (OCI_REGION) em vez da região do Generative AI.Use o valor de GENAI_REGION (Seção 2), não OCI_REGION — ver Seção 5.3 do Passo a passo: banco de dados. ORA-20404 com URL bem formada (região correta no domínio)A tenancy não alcança a região configurada em GENAI_REGION, ou o modelo não está mais disponível para uso on-demand nessa região (a disponibilidade de modelos varia por região e muda com o tempo).Rode oci generative-ai model-collection list-models --compartment-id <seu-compartimento> --region <regiao-candidata> --capability CHAT --all (ou o Console OCI) e confirme que o modelo usado está ACTIVE e sem time-on-demand-retired preenchido nessa região; ajuste GENAI_REGION (e a ACL da Seção 1.6 para o novo host) para uma região que sua tenancy alcance e que ainda sirva o modelo on-demand. +ORA-20404 mesmo com credencial/ACL/região corretosEMBEDDING_COMPARTMENT preenchido com o OCID errado (ex.: do Autonomous Database em vez do compartimento — os dois "parecem" um OCID válido).Confira o prefixo: tem que ser ocid1.compartment...., nunca ocid1.autonomousdatabase..... Se corrigir, recrie a credencial (OCI_CRED) — ela grava o compartimento internamente na criação. +Lupa do "AI Insight" falha mesmo com tudo certo em TB_26AI_TECH_PARAMSCOMPARTMENT_ID/OCI_CREDENTIAL/REGION nas Application Settings do APEX (config separada, ver seção abaixo) desatualizados em relação à tabela.App Builder → Shared Components → Application Settings — compare com TB_26AI_TECH_PARAMS. @@ -127,6 +129,27 @@ END; / +

Application Settings do APEX — uma segunda fonte de configuração

+

A funcionalidade "AI Insight" (lupa na lista de vulnerabilidades) não lê +EMBEDDING_COMPARTMENT direto de TB_26AI_TECH_PARAMS — o processo da página +usa apex_app_setting.get_value('OCI_CREDENTIAL') e +apex_app_setting.get_value('COMPARTMENT_ID'), valores configurados dentro do próprio +APEX (App Builder → Shared Components → Application Settings), separados da tabela de configuração +do banco.

+
+ + + + + +
Application Setting (APEX)Deve bater com
OCI_CREDENTIALOCI_CRED (nome da credencial da Seção 3)
COMPARTMENT_IDo mesmo valor de EMBEDDING_COMPARTMENT em TB_26AI_TECH_PARAMS
REGIONo mesmo valor de GENAI_REGION em TB_26AI_TECH_PARAMS
+
+

Confira direto no App Builder: abra a aplicação → Shared Components → +Application Settings, e compare os três valores acima com a +TB_26AI_TECH_PARAMS atual. Sempre que corrigir EMBEDDING_COMPARTMENT ou +GENAI_REGION no banco, atualize também aqui — são dois lugares de armazenamento +independentes, corrigir um não corrige o outro.

+

Ferramentas nativas — sem código novo

ADB Performance Hub

Saúde do banco (CPU, I/O, sessões, SQL Monitor) direto no Console OCI, sem instrumentação extra.

diff --git a/sql/01_ampminsights_db_setup.sql b/sql/01_ampminsights_db_setup.sql index 311f0dc..e1a58ee 100644 --- a/sql/01_ampminsights_db_setup.sql +++ b/sql/01_ampminsights_db_setup.sql @@ -145,6 +145,15 @@ WHERE principal = 'AMPMINSIGHTS'; -------------------------------------------------------------------------------- -- A partir daqui, conecte-se como o usuario AMPMINSIGHTS (nao mais como ADMIN) -------------------------------------------------------------------------------- +-- +-- VALIDACAO (rode antes de continuar - erro mais comum deste script): +SELECT USER FROM DUAL; +-- Tem que retornar AMPMINSIGHTS. Se retornar ADMIN, voce ainda nao trocou de +-- usuario/sessao - troque agora, senao a SECAO 2 (e tudo depois) vai falhar +-- com ORA-00942 (table or view "ADMIN"."TB_26AI_TECH_PARAMS" does not exist). +-- No Database Actions/SQL Developer Web, trocar o "schema" num seletor do +-- Worksheet NAO basta - precisa fazer login de novo com o usuario/senha do +-- AMPMINSIGHTS. @@ -217,6 +226,25 @@ COMMIT; -- antes de voce seguir para a SECAO 3. SELECT param_name, param_value, description FROM TB_26AI_TECH_PARAMS ORDER BY param_name; +-- VALIDACAO EXTRA: confere que cada OCID e do TIPO certo, nao so que foi +-- preenchido. Ja aconteceu de EMBEDDING_COMPARTMENT ser preenchido com o +-- OCID do proprio Autonomous Database (ocid1.autonomousdatabase...) em vez +-- do compartimento (ocid1.compartment...) - o valor "parece" um OCID valido +-- e passa despercebido, mas quebra silenciosamente mais tarde (Generative AI +-- retorna ORA-20404 "Object not found", dificil de associar a este campo). +SELECT param_name, param_value, + CASE + WHEN param_name = 'EMBEDDING_COMPARTMENT' AND param_value NOT LIKE 'ocid1.compartment.%' + THEN 'ERRO: deveria comecar com ocid1.compartment. - confira se nao colou o OCID do banco/Autonomous Database por engano' + WHEN param_name = 'OCI_TENANCY_OCID' AND param_value NOT LIKE 'ocid1.tenancy.%' + THEN 'ERRO: deveria comecar com ocid1.tenancy.' + WHEN param_name = 'OCI_USER_OCID' AND param_value NOT LIKE 'ocid1.user.%' + THEN 'ERRO: deveria comecar com ocid1.user.' + ELSE 'OK' + END AS validacao +FROM TB_26AI_TECH_PARAMS +WHERE param_name IN ('EMBEDDING_COMPARTMENT', 'OCI_TENANCY_OCID', 'OCI_USER_OCID'); + -------------------------------------------------------------------------------- @@ -281,6 +309,15 @@ SELECT credential_name, username, comments FROM user_credentials WHERE credential_name = 'OCI_CRED'; +-- VALIDACAO/LEMBRETE: esta credencial grava tenancy/user/compartment por +-- dentro, NO MOMENTO em que e criada. Se voce corrigir qualquer valor da +-- SECAO 2 (principalmente EMBEDDING_COMPARTMENT) DEPOIS de ja ter rodado +-- este bloco, a credencial antiga continua com o valor velho - corrigir a +-- tabela sozinho NAO conserta. Nesse caso, rode: +-- BEGIN DBMS_VECTOR_CHAIN.DROP_CREDENTIAL(credential_name => 'OCI_CRED'); END; +-- / +-- e este bloco de novo, nesta ordem. + -------------------------------------------------------------------------------- @@ -1578,6 +1615,21 @@ EXCEPTION END; / +-- VALIDACAO: confere que todos os objetos desta secao compilaram sem erro +-- antes de seguir para a instalacao do APEX. Nao vale so olhar se o CREATE +-- "rodou sem erro na tela" - PL/SQL pode compilar um objeto que chama outro +-- ainda inexistente sem acusar erro na hora (resolucao adiada de nomes); o +-- STATUS aqui e a fonte de verdade. +SELECT object_name, object_type, status +FROM user_objects +WHERE object_name IN ('TB_26AI_TECH_LOG','PRC_26AI_TECH_LOG','FNC_26AI_EMBED', + 'FNC_26AI_TECH_RAG','FNC_26AI_RAG','PRC_26AI_TECH') +ORDER BY object_name; +-- As 6 linhas tem que aparecer com STATUS = VALID. Se alguma faltar, o +-- CREATE dela nao rodou (role a secao de novo); se aparecer INVALID, rode +-- para descobrir o motivo: +-- SELECT line, position, text FROM user_errors WHERE name = '' ORDER BY sequence; + --------------------------------------------------------------------------------