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). .. contents:: Tabela de Conteúdos :local: :depth: 2 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. .. warning:: 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 ---------------------- .. list-table:: Qual ferramenta usar? :widths: 30 70 :header-rows: 1 * - 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.