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; + --------------------------------------------------------------------------------