Antonio Sergio Rodrigues Figueiredo
56c11d0715
Estado na virada para versionamento: Secoes 1-5 do setup de banco validadas ponta a ponta (ONNX CLIP corrigido - ORA-54426; regiao do Generative AI corrigida na Secao 5.3 - ORA-20404), observabilidade de IA adicionada (TB_26AI_TECH_LOG + PRC_26AI_TECH_LOG instrumentando FNC_26ai_rag/fnc_26ai_tech_rag/fnc_26ai_embed/PRC_26AI_TECH), bug de vazamento de sqlerrm em insight_report corrigido, job de geracao em lote agora se autoencerra, e nova doc 09-operacao-observabilidade.html com checklist de erros comuns e consultas de troubleshooting. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
109 lines
7.3 KiB
HTML
109 lines
7.3 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="pt-BR">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>ampmInsights · Arquitetura</title>
|
|
<meta name="description" content="Componentes, objetos de banco e PL/SQL do ambiente ampmInsights sobre Oracle AI Database 26ai.">
|
|
<link rel="stylesheet" href="assets/main.css">
|
|
</head>
|
|
<body>
|
|
<div class="layout">
|
|
<aside class="sidebar">
|
|
<div class="brand">
|
|
<span class="oracle">ORACLE</span>
|
|
<span class="name">ampmInsights</span>
|
|
</div>
|
|
<button class="menu-toggle" type="button">Menu ☰</button>
|
|
<div class="kicker">Documentação V1 · AM/PM</div>
|
|
<ul class="nav-list">
|
|
<li><a class="" href="index.html"><span class="step-no">1</span>Visão geral</a></li>
|
|
<li><a class="active" href="02-arquitetura.html"><span class="step-no">2</span>Arquitetura</a></li>
|
|
<li><a class="" href="03-pre-requisitos-credenciais.html"><span class="step-no">3</span>Pré-requisitos & credenciais</a></li>
|
|
<li><a class="" href="04-passo-a-passo-banco.html"><span class="step-no">4</span>Passo a passo: banco de dados</a></li>
|
|
<li><a class="" href="05-passo-a-passo-apex.html"><span class="step-no">5</span>Passo a passo: aplicação APEX</a></li>
|
|
<li><a class="" href="06-validacao-testes.html"><span class="step-no">6</span>Validação & testes</a></li>
|
|
<li><a class="" href="07-seguranca-boas-praticas.html"><span class="step-no">7</span>Segurança & boas práticas</a></li>
|
|
<li><a class="" href="08-glossario-roadmap.html"><span class="step-no">8</span>Glossário & roadmap</a></li>
|
|
<li><a class="" href="09-operacao-observabilidade.html"><span class="step-no">9</span>Operação & observabilidade</a></li>
|
|
</ul>
|
|
<div class="sidebar-footer">
|
|
Vulnerability & Audit AI Insights<br>
|
|
Oracle AI Database 26ai · AI Vector Search<br>
|
|
Versão V1 · ambiente reprodutível do cliente
|
|
</div>
|
|
</aside>
|
|
<main class="content">
|
|
<p class="page-kicker">Arquitetura</p>
|
|
<h1>Como as peças se conectam</h1>
|
|
<p class="lede">Do dado bruto ao insight de IA vetorizado e pesquisável — os componentes técnicos do ambiente e o papel de cada objeto de banco.</p>
|
|
|
|
<div class="diagram">
|
|
<div class="node"><strong>CMDB</strong>Ativos/servidores</div>
|
|
<div class="node"><strong>Vulnerabilidades</strong>Export Tenable</div>
|
|
<div class="node"><strong>Syslog</strong>(opcional)</div>
|
|
</div>
|
|
<p>As três fontes acima chegam por <em>Data Load</em> da própria aplicação APEX (upload de planilha/CSV)
|
|
e alimentam as tabelas técnicas do schema <code>AMPMINSIGHTS</code>.</p>
|
|
|
|
<h2>Componentes principais</h2>
|
|
<div class="table-wrap">
|
|
<table>
|
|
<tr><th>Componente</th><th>Papel no fluxo</th></tr>
|
|
<tr><td>Autonomous Database 26ai</td><td>Hospeda o schema <code>AMPMINSIGHTS</code>: tabelas, view, PL/SQL, credencial OCI e o job de geração de insights.</td></tr>
|
|
<tr><td>AI Vector Search (<code>DBMS_VECTOR</code> / <code>DBMS_VECTOR_CHAIN</code>)</td><td>Gera embeddings (Cohere embed-v4, ou ONNX local opcional) e realiza a busca por similaridade usada no RAG.</td></tr>
|
|
<tr><td>OCI Generative AI</td><td>Modelo <code>meta.llama-4-maverick-17b-128e-instruct-fp8</code> para geração de texto/insight e <code>cohere.embed-v4.0</code> para embeddings.</td></tr>
|
|
<tr><td><code>DBMS_CLOUD_AI</code> (SELECT AI)</td><td>Permite perguntas em linguagem natural diretamente sobre <code>V_26AI_TECH</code> e <code>TB_26AI_TECH_CMDB</code>.</td></tr>
|
|
<tr><td>APEX — ampmInsights (app 100)</td><td>Interface web: cadastro/carga de dados, tabela de achados, chat RAG, disparo do job de geração de insights em lote.</td></tr>
|
|
<tr><td><code>DBMS_SCHEDULER</code></td><td>Job criado dinamicamente pela própria aplicação (botão "Gerar Insights em Lote") para processar os registros pendentes.</td></tr>
|
|
</table>
|
|
</div>
|
|
|
|
<h2>Objetos de banco (nomes preservados)</h2>
|
|
<p>Os nomes abaixo são referenciados diretamente, em dezenas de pontos, pelo export da aplicação
|
|
APEX (<code>02_ampminsights_apex_app.sql</code>). Por isso eles <strong>não foram renomeados</strong>
|
|
nesta versão V1 — apenas o schema/usuário que os contém mudou de nome.</p>
|
|
<div class="table-wrap">
|
|
<table>
|
|
<tr><th>Objeto</th><th>Tipo</th><th>Uso</th></tr>
|
|
<tr><td><code>TB_26AI_TECH_PARAMS</code></td><td>Tabela</td><td>Parâmetros (nome da credencial e OCID do compartimento) lidos por todo o PL/SQL e pelo job em lote.</td></tr>
|
|
<tr><td><code>TB_26AI_TECH_CMDB</code></td><td>Tabela</td><td>Ativos/servidores (CMDB).</td></tr>
|
|
<tr><td><code>TB_26AI_TECH_V2</code></td><td>Tabela</td><td>Achados de vulnerabilidade (fonte principal) + insight gerado.</td></tr>
|
|
<tr><td><code>TB_26AI_TECH</code></td><td>Tabela</td><td>Tabela legada, ainda usada por uma carga/página mais antiga da aplicação.</td></tr>
|
|
<tr><td><code>TB_26AI_TECH_SYS</code></td><td>Tabela</td><td>Eventos de syslog (opcional) + insight gerado.</td></tr>
|
|
<tr><td><code>TB_26AI_TECH_CHAT</code></td><td>Tabela</td><td>Histórico de interações do chat "fale com os dados".</td></tr>
|
|
<tr><td><code>TB_26AI_TECH_VECTOR</code></td><td>Tabela</td><td>Vetores/chunks usados na busca semântica (RAG).</td></tr>
|
|
<tr><td><code>V_26AI_TECH</code></td><td>View</td><td>Junta vulnerabilidades + CMDB; usada pela aplicação e pelo profile de SELECT AI.</td></tr>
|
|
<tr><td><code>SEQ_26AI_TECH</code> / <code>BIU_TB_26AI_TECH_V2</code></td><td>Sequence / Trigger</td><td>Gera o identificador sequencial de insight (<code>ID_INSIGHT</code>).</td></tr>
|
|
</table>
|
|
</div>
|
|
|
|
<h2>PL/SQL de geração de insights e RAG</h2>
|
|
<div class="table-wrap">
|
|
<table>
|
|
<tr><th>Rotina</th><th>Função</th></tr>
|
|
<tr><td><code>fnc_26ai_embed</code></td><td>Gera o embedding de um texto (COHERE via OCI Generative AI, ONNX local, ou vLLM self-hosted opcional).</td></tr>
|
|
<tr><td><code>fnc_26ai_tech_rag</code></td><td>Busca os trechos mais similares em <code>TB_26AI_TECH_VECTOR</code> e monta a resposta aumentada (RAG) via Llama 4.</td></tr>
|
|
<tr><td><code>FNC_26AI_TECH_MCP_V1</code></td><td>Wrapper de <code>fnc_26ai_tech_rag</code> pensado para exposição como ferramenta MCP a um agente externo.</td></tr>
|
|
<tr><td><code>FNC_26ai_rag</code></td><td>Chamada genérica ao OCI Generative AI (chat) usada tanto pelo RAG quanto pela geração de insight.</td></tr>
|
|
<tr><td><code>prc_26ai_tech</code></td><td>Gera o insight (análise/diagnóstico/recomendações/plano de ação) para um registro e cria o vetor correspondente.</td></tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="callout info">
|
|
<div class="callout-title">Sobre o "job de banco"</div>
|
|
<p>Não existe um <code>DBMS_SCHEDULER.CREATE_JOB</code> estático no script de setup: o job
|
|
(<code>JOB_26AI_TECH_VULNERABILIDADE</code> / equivalente para syslog) é criado <strong>em tempo de
|
|
execução</strong> pela própria aplicação APEX, quando o usuário aciona o botão de processamento em
|
|
lote. O job lê o nome da credencial e o OCID do compartimento diretamente de
|
|
<code>TB_26AI_TECH_PARAMS</code> — por isso preencher essa tabela corretamente (SEÇÃO 2 do script 1,
|
|
a tabela de configuração) é o passo mais crítico de toda a configuração.</p>
|
|
</div>
|
|
|
|
<div class="pillnav"><a class="prev" href="index.html">← Visão geral</a><a class="next" href="03-pre-requisitos-credenciais.html">Pré-requisitos & credenciais →</a></div>
|
|
</main>
|
|
</div>
|
|
<script src="assets/main.js"></script>
|
|
</body>
|
|
</html>
|