Referência para Manutenção em OpenAI (Storage)

Esta seção detalha a estratégia de gestão de dados para manter a eficiência técnica e a saúde financeira da sua infraestrutura de RAG (Retrieval-Augmented Generation).

Estratégia de Monitoramento e Auditoria

Antes de realizar qualquer intervenção, é fundamental mapear o estado atual do armazenamento para evitar deleções acidentais ou redundâncias.

Monitoramento Macro (Visão da Conta)

Endpoint: GET /storage/vector_stores/all

• Quando usar: No início de cada ciclo de auditoria ou para validar o sucesso de novos deploys de conteúdo.

• Por que usar: Como a tarifação da OpenAI é diária, este endpoint permite identificar rapidamente Vector Stores (VS) que não deveriam estar ativas ou que estão acumulando volume de dados acima do previsto.

• Fluxo Operacional: Utilize o campo size_readable para identificar quais Stores são responsáveis pelo maior consumo da sua cota.

Diagnóstico de Saúde (Arquivos por Store)

Endpoint: GET /storage/vector_stores/{vs_id}/all

• Quando usar: Quando notar uma queda na qualidade das respostas da IA ou um aumento inesperado no tamanho de uma Store específica.

• Por que usar: Permite visualizar o status individual de cada arquivo indexado. Arquivos com status failed ocupam espaço, mas não contribuem para a busca semântica, devendo ser removidos e reenviados.

Ciclo de Vida e Limpeza Automatizada

A exclusão simples de uma Vector Store no painel da OpenAI costuma deixar resíduos. O sistema Menthor implementa uma lógica de proteção de custos.

Deleção em Cascata (O «Cleanup Total»)

Endpoint: DELETE /storage/vector_stores/{vs_id}/delete

• Quando usar: Sempre que um cliente for desativado, um projeto encerrado ou um id_context removido.

• Por que usar: Na infraestrutura padrão da OpenAI, deletar a Store não deleta os arquivos do storage global. Este endpoint garante que:

  1. A Store seja removida.

  2. Os arquivos vinculados sejam identificados.

  3. Cada arquivo físico (user_data) seja permanentemente excluído para cessar a cobrança.

Otimização e Higienização de Storage

Processos de upload interrompidos ou deleções manuais incompletas geram «arquivos orfãos» (arquivos que custam dinheiro, mas não estão em nenhuma Store).

Detecção de Arquivos Órfãos

Endpoint: GET /storage/files_unassociated

• Quando usar: Recomendado como uma rotina semanal de manutenção.

• Por que usar: Este é o seu «scanner de desperdício». Ele cruza todos os arquivos da conta contra todas as Stores ativas e isola apenas o que está flutuando sem utilidade.

Exclusão em Lote (Bulk Purge)

Endpoint: POST /storage/bulk_delete_files

• Quando usar: Logo após a identificação de órfãos ou para limpar backups de arquivos antigos de uma só vez.

• Fluxo de Uso Recomendado:

  1. Identifique os órfãos via /storage/files_unassociated.

  2. Revise a lista para garantir que nenhum arquivo é de uso compartilhado.

  3. Envie a lista de IDs para este endpoint para realizar o purge massivo e imediato.

Aviso

A operação de Bulk Purge é irreversível. Certifique-se de que os arquivos realmente não possuem utilidade em outros projetos vinculados à mesma API Key.

Guia de Decisão Rápida

Qual ferramenta usar?

Objetivo	Fluxo Sugerido
Reduzir a conta da OpenAI	Detectar Órfãos -> Bulk Purge.
Encerrar um Contexto	Deleção em Cascata (Cascading Delete).
Investigar erro de busca	Listar Arquivos por Store -> Verificar status individual.
Inventário Mensal	Listagem Global de Vector Stores.