Relatório de Tabelas Vetoriais - ArboreoLab

Data: 08 de Janeiro de 2026
MariaDB: 11.8.5
Modelo de Embedding: paraphrase-multilingual-mpnet-base-v2 (768 dimensões)

📊 Resumo Executivo

Métrica	Valor
Databases com vetores	2 (ClioVector, GeopoliticasVector)
Tabelas com colunas VECTOR	10
Índices vetoriais ativos	10
Total de registros vetorizados	~374.000
Tamanho total em disco	~1.06 GB
Tipo de distância	COSINE (todos os índices)

🗄️ Inventário de Tabelas Vetoriais

ClioVector

Tabela	Coluna	Tipo	Registros	Com Vetor	Tamanho
`clio_ocr`	`ocr_vector`	VECTOR(768)	16.117	16.117 (100%)	0.13 MB
`clio_ocr_segments`	`segment_vector`	VECTOR(768)	0	0	0.03 MB
`clio_entidades`	`semantic_vector`	VECTOR(768)	145.478	145.478 (100%)	0.11 MB
`clio_entidades_vector`	`entity_vector`	VECTOR(768)	20.359	20.359 (100%)	79.59 MB
`clio_ocr_vector`	`ocr_vector` + `ocr_vector1,2,3`	VECTOR(768)	16.024	16.024 (100%)	604.63 MB

GeopoliticasVector

Tabela	Coluna	Tipo	Registros	Com Vetor	Tamanho
`clio_ocr`	`ocr_vector`	VECTOR(768)	16.431	16.431 (100%)	251.98 MB
`clio_ocr_segments`	`segment_vector`	VECTOR(768)	13.969	13.969 (100%)	121.19 MB
`clio_entidades`	`semantic_vector`	VECTOR(768)	145.478	145.478 (100%)	0.13 MB
`clio_entidades_vector`	`entity_vector`	VECTOR(768)	0	0	0.02 MB
`clio_ocr_vector`	`ocr_vector`	VECTOR(768)	0	0	0.02 MB

🔍 Índices Vetoriais Existentes

Status: ✅ TODOS OS ÍNDICES JÁ EXISTEM

Database	Tabela	Índice	Tipo	Distância
ClioVector	`clio_ocr`	`idx_ocr_vec`	VECTOR	COSINE
ClioVector	`clio_ocr_segments`	`idx_segment_vec`	VECTOR	COSINE
ClioVector	`clio_entidades`	`idx_semantic_vector`	VECTOR	COSINE
ClioVector	`clio_entidades_vector`	`idx_entity_vec`	VECTOR	COSINE
ClioVector	`clio_ocr_vector`	`idx_ocr_vec`	VECTOR	COSINE
GeopoliticasVector	`clio_ocr`	`idx_ocr_vec`	VECTOR	COSINE
GeopoliticasVector	`clio_ocr_segments`	`idx_segment_vec`	VECTOR	COSINE
GeopoliticasVector	`clio_entidades`	`idx_semantic_vector`	VECTOR	COSINE
GeopoliticasVector	`clio_entidades_vector`	`idx_entity_vec`	VECTOR	COSINE
GeopoliticasVector	`clio_ocr_vector`	`idx_ocr_vec`	VECTOR	COSINE

⚙️ Configuração MHNSW (MariaDB Vector)

Variável	Valor Atual	Recomendação
`mhnsw_default_distance`	`euclidean`	OK (índices usam COSINE explícito)
`mhnsw_default_m`	`6`	Considerar aumentar para `12` em produção
`mhnsw_ef_search`	`20`	Considerar aumentar para `50` para melhor recall
`mhnsw_max_cache_size`	`16 MB`	🔴 AUMENTAR para 256-512 MB

Recomendação de Tuning

-- Aumentar cache do índice vetorial (16 MB → 256 MB)
SET GLOBAL mhnsw_max_cache_size = 268435456;

-- Aumentar precisão de busca (20 → 50)
SET GLOBAL mhnsw_ef_search = 50;

Nota: Adicionar ao /etc/mysql/mariadb.conf.d/50-server.cnf para persistir:
mhnsw_max_cache_size = 268435456
mhnsw_ef_search = 50

📐 Estrutura das Tabelas Principais

clio_ocr (OCR de Páginas)

CREATE TABLE clio_ocr (
  id BIGINT UNSIGNED AUTO_INCREMENT,
  workflow_id INT UNSIGNED NOT NULL,
  content LONGTEXT,                    -- Conteúdo JSON do OCR
  content_markdown LONGTEXT,           -- Markdown do texto
  ocr_vector VECTOR(768) NOT NULL,     -- Embedding da página
  engine_version VARCHAR(50),          -- Motor: legacy, gemini-2.0, vision-macos-v1
  file_hash_sha256 CHAR(64),           -- Hash para deduplicação
  ...
  VECTOR KEY idx_ocr_vec (ocr_vector) DISTANCE=COSINE
);

clio_ocr_segments (Segmentos Layout-Aware)

CREATE TABLE clio_ocr_segments (
  id BIGINT UNSIGNED AUTO_INCREMENT,
  ocr_id BIGINT UNSIGNED NOT NULL,     -- FK para clio_ocr.id
  text_content TEXT NOT NULL,          -- Texto do segmento
  segment_vector VECTOR(768) NOT NULL, -- Embedding do segmento
  bbox_x, bbox_y, bbox_w, bbox_h FLOAT,-- Coordenadas normalizadas (0-1)
  confidence FLOAT,                    -- Confiança do OCR (0-1)
  reading_order INT,                   -- Ordem de leitura
  ...
  VECTOR KEY idx_segment_vec (segment_vector) DISTANCE=COSINE,
  CONSTRAINT fk_segment_ocr FOREIGN KEY (ocr_id) REFERENCES clio_ocr(id) ON DELETE CASCADE
);

clio_entidades (Entidades Extraídas)

CREATE TABLE clio_entidades (
  id INT AUTO_INCREMENT,
  entity_name LONGTEXT,                -- Nome da entidade (JSON)
  isA LONGTEXT,                        -- Tipo: Pessoa, Organização, Local...
  semantic_vector VECTOR(768) NOT NULL,-- Embedding da entidade
  cluster_id INT,                      -- Agrupamento de entidades similares
  is_principal TINYINT,                -- Entidade principal do cluster
  entity_name_text VARCHAR(500) STORED,-- Texto extraído do JSON
  ...
  VECTOR KEY idx_semantic_vector (semantic_vector) DISTANCE=COSINE,
  FULLTEXT KEY idx_fulltext_entity_name (entity_name_text)
);

� Manutenção de Entidades DESCRICAO

Implementação (08/01/2026)

Foi implementado um mecanismo de consolidação automática para entidades com relationshipType="DESCRICAO":

Componente	Descrição
UNIQUE KEY	`idx_unique_descricao` em `clio_entidades` (MariaDB)
Coluna Gerada	`unique_key_descricao = CONCAT(entity_name, '
UPSERT	`INSERT ... ON DUPLICATE KEY UPDATE` agrega inFileIDs automaticamente
Migração SQL	`migracoesdedb/002_upsert_descricao.sql`

Arquivos Modificados

enviar_db/entidadesV2.py - UPSERT para DESCRICAO, INSERT para relacionamentos
gerar_entidades/gerarEntespagina.py - Usa entidadesV2.py (sem mudanças diretas)
migracoesdedb/002_upsert_descricao.sql - Schema com UNIQUE KEY

⚠️ Manutenção Periódica Recomendada

O UPSERT usa CONCAT_WS para agregar inFileIDs. Reprocessamentos do mesmo documento podem gerar IDs duplicados dentro do campo CSV.

Script de Limpeza:

cd /home/arboreolab/estudos/1_funcionais/fregeRAG_v1/enviar_db/

# Simular consolidação
python consolidar_entidades_descricao.py --dry-run

# Executar consolidação
python consolidar_entidades_descricao.py

Frequência Recomendada: Mensalmente ou após reprocessamentos em massa.

Resultados da Consolidação Inicial

Métrica	Antes	Depois	Redução
Rows DESCRICAO	113.829	65.686	-42,3%
Rows/Entidade	Múltiplas	1:1	Normalizado

�🚨 Observações Importantes

1. Tabelas Legadas (candidatas a remoção)

Tabela	Observação
`clio_ocr_vector`	Contém 4 colunas de vetor (redundante) — 604 MB em ClioVector
`clio_entidades_vector`	Parece duplicar `clio_entidades`

Recomendação: Avaliar migração para tabelas principais e arquivamento.

2. Segmentos Não Populados (ClioVector)

A tabela ClioVector.clio_ocr_segments está vazia (0 registros), enquanto GeopoliticasVector.clio_ocr_segments tem 13.969 registros.

Ação: Executar backfill de segmentos para ClioVector se necessário.

3. Cache de Índice Vetorial Pequeno

O mhnsw_max_cache_size está em 16 MB (default), muito pequeno para ~374k vetores de 768 dimensões.

Cálculo:

1 vetor = 768 × 4 bytes (float32) = 3.072 bytes
374.000 vetores × 3.072 bytes = ~1.15 GB de dados vetoriais

Cache de 16 MB = apenas 0.014% dos vetores em cache
Cache de 256 MB = ~2.2% dos vetores em cache

✅ Status Atual

Item	Status
Índices vetoriais criados	✅ Completo
Distância COSINE configurada	✅ Completo
Buffer pool (18 GB)	✅ Completo
Cache MHNSW otimizado	⚠️ Pendente (16 MB → 256 MB)
Tabelas legadas arquivadas	⚠️ Pendente
Backfill de segmentos (ClioVector)	⚠️ Pendente
Embeddings Worker (Mac)	✅ Operacional (teste 08/01/2026)

🆕 Embeddings Worker (08/01/2026)

Novo Worker para Geração de Embeddings

Foi criado e testado com sucesso o ArboreoLab Embeddings Worker, executando em MacBook Air M2 com aceleração MPS (Metal Performance Shaders).

Componente	Valor
Localização Servidor	`/home/arboreolab/Clio/embeddings-worker-interface`
Localização Mac	`/Users/douglasromao/ArboreoLab/embeddings-worker`
Modelo	`paraphrase-multilingual-mpnet-base-v2` (768 dim)
Aceleração	MPS (Apple Silicon)
API Port (Mac)	9999
API Port (Servidor via túnel)	9002

Novas Colunas em `clio_entidades_vector`

Coluna	Tipo	Descrição
`entity_vector`	VECTOR(768)	Embedding do nome da entidade
`relatedto_entity_name_vector`	VECTOR(768)	NOVA - Embedding da entidade relacionada
`triple_vector`	VECTOR(768)	NOVA - Embedding da tripla completa

Status de Processamento

Database	Total	Processados	Pendentes	Status
GeopoliticasVector	10.024	32	9.992	⏳ Teste OK
ClioVector	20.359	0	20.359	⏳ Pendente

Índices Vetoriais Pendentes

Após população completa, criar índices:

-- GeopoliticasVector
ALTER TABLE GeopoliticasVector.clio_entidades_vector 
  ADD VECTOR INDEX idx_relatedto_vec (relatedto_entity_name_vector);
ALTER TABLE GeopoliticasVector.clio_entidades_vector 
  ADD VECTOR INDEX idx_triple_vec (triple_vector);

-- ClioVector
ALTER TABLE ClioVector.clio_entidades_vector 
  ADD VECTOR INDEX idx_relatedto_vec (relatedto_entity_name_vector);
ALTER TABLE ClioVector.clio_entidades_vector 
  ADD VECTOR INDEX idx_triple_vec (triple_vector);

Documentação completa: RELATORIO_EMBEDDINGS_WORKER_2026-01-08.md

🔮 Próximos Passos

Prioridade	Ação	Impacto Esperado
🔴 Alta	Processar embeddings GeopoliticasVector (~52 min)	Busca semântica de entidades
🔴 Alta	Aumentar `mhnsw_max_cache_size` para 256 MB	Reduzir I/O de disco
🔴 Alta	Aumentar `mhnsw_ef_search` para 50	Melhor recall/precisão
🟡 Média	Criar índices para novas colunas vetoriais	Busca por triplas
🟡 Média	Avaliar remoção de tabelas `*_vector` legadas	Economia de 684 MB
🟡 Média	Backfill segmentos para ClioVector	Busca granular funcional
🟢 Baixa	Documentar procedimento de manutenção de índices	Operações futuras

Gerado por: Engenheiro Sênior ArboreoLab
Última atualização: 08/01/2026 14:50 UTC

📊 Resumo Executivo​

🗄️ Inventário de Tabelas Vetoriais​

ClioVector​

GeopoliticasVector​

🔍 Índices Vetoriais Existentes​

Status: ✅ TODOS OS ÍNDICES JÁ EXISTEM​

⚙️ Configuração MHNSW (MariaDB Vector)​

Recomendação de Tuning​

📐 Estrutura das Tabelas Principais​

clio_ocr (OCR de Páginas)​

clio_ocr_segments (Segmentos Layout-Aware)​

clio_entidades (Entidades Extraídas)​

� Manutenção de Entidades DESCRICAO​

Implementação (08/01/2026)​

Arquivos Modificados​

⚠️ Manutenção Periódica Recomendada​

Resultados da Consolidação Inicial​

�🚨 Observações Importantes​

1. Tabelas Legadas (candidatas a remoção)​

2. Segmentos Não Populados (ClioVector)​

3. Cache de Índice Vetorial Pequeno​

✅ Status Atual​

🆕 Embeddings Worker (08/01/2026)​

Novo Worker para Geração de Embeddings​

Novas Colunas em clio_entidades_vector​

Status de Processamento​

Índices Vetoriais Pendentes​

🔮 Próximos Passos​