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 <noreply@anthropic.com>
This commit is contained in:
2026-07-24 17:39:39 -03:00
parent 1e9af90582
commit 1c607f3f72
3 changed files with 131 additions and 4 deletions

View File

@@ -52,6 +52,8 @@ rapidamente qualquer problema, e o checklist abaixo para os casos mais comuns.</
<tr><td>Erro de rede/timeout ao chamar o Generative AI</td><td>ACL de rede (Seção 1.6) não cobre o host correto.</td><td><code>SELECT host, privilege FROM dba_host_aces WHERE principal = 'AMPMINSIGHTS';</code> — deve listar <code>inference.generativeai.us-chicago-1.oci.oraclecloud.com</code> com <code>RESOLVE</code> e <code>CONNECT</code>.</td></tr>
<tr><td><code>ORA-20404</code> ("Object not found", domínio <code>oci.my$cloud_domain</code>)</td><td>Perfil de SELECT AI usando a região "de casa" do tenancy (<code>OCI_REGION</code>) em vez da região do Generative AI.</td><td>Use o valor de <code>GENAI_REGION</code> (Seção 2), não <code>OCI_REGION</code> — ver Seção 5.3 do <a href="04-passo-a-passo-banco.html">Passo a passo: banco de dados</a>.</td></tr>
<tr><td><code>ORA-20404</code> com URL bem formada (região correta no domínio)</td><td>A tenancy não alcança a região configurada em <code>GENAI_REGION</code>, 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).</td><td>Rode <code>oci generative-ai model-collection list-models --compartment-id &lt;seu-compartimento&gt; --region &lt;regiao-candidata&gt; --capability CHAT --all</code> (ou o Console OCI) e confirme que o modelo usado está <code>ACTIVE</code> e sem <code>time-on-demand-retired</code> preenchido nessa região; ajuste <code>GENAI_REGION</code> (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.</td></tr>
<tr><td><code>ORA-20404</code> mesmo com credencial/ACL/região corretos</td><td><code>EMBEDDING_COMPARTMENT</code> preenchido com o OCID errado (ex.: do Autonomous Database em vez do compartimento — os dois "parecem" um OCID válido).</td><td>Confira o prefixo: tem que ser <code>ocid1.compartment....</code>, nunca <code>ocid1.autonomousdatabase....</code>. Se corrigir, recrie a credencial (<code>OCI_CRED</code>) — ela grava o compartimento internamente na criação.</td></tr>
<tr><td>Lupa do "AI Insight" falha mesmo com tudo certo em <code>TB_26AI_TECH_PARAMS</code></td><td><code>COMPARTMENT_ID</code>/<code>OCI_CREDENTIAL</code>/<code>REGION</code> nas Application Settings do APEX (config separada, ver seção abaixo) desatualizados em relação à tabela.</td><td>App Builder → Shared Components → Application Settings — compare com <code>TB_26AI_TECH_PARAMS</code>.</td></tr>
</table>
</div>
@@ -127,6 +129,27 @@ END;
/</code></pre>
</div>
<h2>Application Settings do APEX — uma segunda fonte de configuração</h2>
<p>A funcionalidade "AI Insight" (lupa na lista de vulnerabilidades) não lê
<code>EMBEDDING_COMPARTMENT</code> direto de <code>TB_26AI_TECH_PARAMS</code> — o processo da página
usa <code>apex_app_setting.get_value('OCI_CREDENTIAL')</code> e
<code>apex_app_setting.get_value('COMPARTMENT_ID')</code>, valores configurados dentro do próprio
APEX (App Builder → Shared Components → Application Settings), separados da tabela de configuração
do banco.</p>
<div class="table-wrap">
<table>
<tr><th>Application Setting (APEX)</th><th>Deve bater com</th></tr>
<tr><td><code>OCI_CREDENTIAL</code></td><td><code>OCI_CRED</code> (nome da credencial da Seção 3)</td></tr>
<tr><td><code>COMPARTMENT_ID</code></td><td>o mesmo valor de <code>EMBEDDING_COMPARTMENT</code> em <code>TB_26AI_TECH_PARAMS</code></td></tr>
<tr><td><code>REGION</code></td><td>o mesmo valor de <code>GENAI_REGION</code> em <code>TB_26AI_TECH_PARAMS</code></td></tr>
</table>
</div>
<p>Confira direto no App Builder: abra a aplicação → <strong>Shared Components</strong> →
<strong>Application Settings</strong>, e compare os três valores acima com a
<code>TB_26AI_TECH_PARAMS</code> atual. Sempre que corrigir <code>EMBEDDING_COMPARTMENT</code> ou
<code>GENAI_REGION</code> no banco, atualize também aqui — são dois lugares de armazenamento
independentes, corrigir um não corrige o outro.</p>
<h2>Ferramentas nativas — sem código novo</h2>
<div class="grid">
<div class="card"><h4>ADB Performance Hub</h4><p>Saúde do banco (CPU, I/O, sessões, SQL Monitor) direto no Console OCI, sem instrumentação extra.</p></div>