Documentos e Armazenamento

Guia

Importando Documentos

1. Selecionar a ferramenta de importação

   Na aba Armazenamento, clique em Importar. Um seletor exibe as ferramentas de importação disponíveis, organizadas por categoria (Arquivos, Triggers, API, Bancos de Dados).

2. Configurar os campos

   Preencha os campos específicos da ferramenta selecionada:

   • Nome e descrição do documento
   • Configurações adicionais (delimitador, formato, etc.)
   • Agendamento de importação (opcional)

3. Preencher os metadados (opcional)

   Abaixo dos campos principais, expanda o accordion Metadados para definir atributos de negócio que ficam vinculados ao documento e são herdados por cada chunk gerado:

   Campo	Descrição
   Origem (source)	Origem do conteúdo (ex.: manual, meeting, crm). Usado pelos filtros rápidos e pela detecção de duplicidade.
   Assunto (subject)	Assunto ou tópico do documento.
   Idioma (language)	Idioma do documento (ex.: pt-BR, en-US).
   Tags	Etiquetas livres separadas por vírgula.

   Todos os campos de metadados aceitam Magic Fill — clique no ícone de estrela para que a IA sugira um valor com base no arquivo (o conteúdo, no caso de PDFs; caso contrário, o nome) e nos campos já preenchidos.

4. Fazer upload do arquivo

   Arraste e solte o arquivo na área de upload ou clique para selecionar. O sistema valida o formato e o tamanho antes do envio.

5. Acompanhar o processamento

   Uma barra de progresso inicia em 1% assim que o upload começa e avança conforme o documento percorre o pipeline upload → storage → embedding. A barra substitui o antigo spinner, garantindo feedback concreto ao usuário durante todo o processamento.

Magic Fill

Ao fazer upload de um arquivo, o Magic Fill é acionado automaticamente para sugerir nome, descrição, campos de metadados (origem, assunto, idioma, tags) e facetas com auxílio de IA. O acionamento automático aguarda o carregamento completo do vocabulário de facetas antes de disparar, garantindo que as sugestões de facetas sempre venham do vocabulário controlado da organização. Caso nenhuma faceta seja sugerida no primeiro upload, verifique se sua organização tem facetas configuradas e acione o Magic Fill manualmente.

O Magic Fill funciona com qualquer tipo de arquivo — não apenas PDFs. Para arquivos PDF, ele também lê o conteúdo do documento; para qualquer outro formato (planilhas, CSV, Word, imagens, etc.), ele deriva as sugestões a partir do nome do arquivo e dos campos que você já preencheu. O upload em si nunca teve restrição de tipo — apenas as sugestões de IA, que agora rodam para todo arquivo.

---

Planilhas: respostas exatas a partir de dados tabulares

Planilhas enviadas à base de conhecimento (.xlsx, .xls, .csv, .tsv, .ods) recebem um tratamento dedicado: além de indexadas para busca, seus dados ficam consultáveis para perguntas analíticas.

Quando você pergunta algo como “qual o total de vendas por segmento?” ou “quantas unidades do produto X foram vendidas na Alemanha?”, o assistente executa uma consulta real sobre os dados da planilha — em vez de inferir a partir do texto — e retorna números exatos: totais, somas, médias, contagens, agrupamentos e filtros.

• Onde funciona: Playground, comunicadores (Slack/Teams), workflows (nós de RAG) e clientes MCP — a mesma competência em todas as superfícies.
• Cada aba vira uma unidade consultável: planilhas com várias abas são indexadas por aba, cada uma com seu próprio esquema (colunas e tipos).
• Várias planilhas: quando há mais de uma planilha relevante, o sistema escolhe a correta ou apresenta o resultado por planilha. Ele não soma dados de naturezas diferentes (moedas/definições distintas) — nesse caso, mostra o detalhamento por fonte em vez de um total sem sentido.
• Perguntas descritivas (“o que tem nessa planilha?”) recebem um resumo das colunas e uma amostra de linhas.

Nota

Para planilhas, o modal de detalhes exibe o esquema (abas, colunas e tipos) na aba Metadados e rotula a aba de chunks como Abas/Planilhas. A pontuação de Qualidade usa critérios próprios de dados tabulares.

Cuidado

Planilhas formatadas para leitura humana (células mescladas, cabeçalhos em vários níveis, colunas sem nome) podem ser indexadas em modo descritivo: continuam pesquisáveis por significado, mas não respondem a consultas exatas/agregações. A aba Qualidade do documento avisa quando isso acontece. Para habilitar respostas exatas, forneça os dados como uma tabela retangular limpa — uma linha de cabeçalho e um valor por célula.

---

Arquitetura Storage-First

Todo documento — independentemente de como entrou na base de conhecimento (upload manual, workflow, agente, API) — é primeiro persistido como entrada de Storage e só depois indexado como embeddings. Isso garante:

• Um único inventário de documentos visível na listagem, qualquer que seja a origem.
• Metadados de negócio pertencem à linha de storage e são replicados em cada chunk.
• Exclusão em cascata: remover uma entrada de Storage descarta automaticamente todos os embeddings vinculados.

---

Categorias de Importação

Categoria	Descrição
Arquivos	Upload direto de documentos (CSV, PDF, DOCX, MD, etc.)
Triggers	Importações baseadas em eventos
API	Dados obtidos de endpoints REST
Bancos de Dados	Conexões diretas com bancos de dados

---

Importação via API REST

Para fontes de dados externas via API, você pode configurar:

Campo	Descrição
URL base	Endereço do servidor
Endpoint	Caminho do recurso
Método HTTP	GET, POST, PUT, PATCH, DELETE
Autenticação	Nenhuma, Basic, Bearer, API Key
Parâmetros	Query parameters e headers
Formato de resposta	JSON, CSV, XML
Paginação	Configuração de paginação automática
Tentativas	Configuração de retentativas em caso de falha

---

Agendamento de Importação

Configure importações automáticas recorrentes:

Frequência	Opções
Por hora	A cada N horas
Diário	Horário específico
Semanal	Dias da semana + horário
Mensal	Dia do mês + horário

Nota

O agendamento permite manter a base de conhecimento atualizada automaticamente com dados de fontes externas. O sistema registra a data da última e próxima execução.

---

Gerenciando Documentos

A aba Armazenamento exibe todos os documentos importados em uma tabela, independentemente de terem sido enviados manualmente ou produzidos automaticamente por um agente ou workflow.

Colunas da Listagem

Coluna	Descrição
Nome	Nome do documento precedido pelo logo da ferramenta (o ícone identifica a origem da importação rapidamente).
Atualizado em	Data da última atualização.
Tamanho	Tamanho do arquivo original (formatado, ex.: 1,2 MB).
Status	Estado do processamento exibido como barra de progresso que avança durante a indexação.
Qualidade	Pontuação geral renderizada em escala de 5 estrelas (0 a 10 mapeado em meias-estrelas, cor âmbar).
Ações	Coluna fixa à direita (sticky) — permanece visível mesmo quando o usuário rola a tabela horizontalmente.

Nota

A largura das colunas pode ser redimensionada arrastando o cabo no canto direito de cada cabeçalho. A coluna Nome absorve o espaço horizontal restante, evitando vãos em branco na tabela.

Ordenação

A tabela vem ordenada por Atualizado em em ordem decrescente (mais recente primeiro) por padrão. Clique no cabeçalho de uma coluna para ordenar por ela; clique novamente para inverter a direção (crescente/decrescente). Uma seta no cabeçalho indica a coluna ativa e a direção.

Colunas ordenáveis: Nome, Atualizado em, Tamanho, Status e Qualidade. A ordenação é aplicada no servidor, então vale para todo o acervo — não apenas para a página atual — e ao alterá-la a listagem volta para a primeira página. O redimensionamento de coluna continua funcionando normalmente, sem disparar a ordenação.

Busca e Filtros Rápidos

A barra de busca compartilha a linha com o botão de filtro e um conjunto de cards de filtro rápido que atuam no lado do cliente:

Filtro rápido	Comportamento
Todos	Estado padrão — nenhum filtro client-side aplicado.
Tipo	Popover com os tipos de documento presentes na página atual (markdown, pdf, csv, etc.).
Facetas	Popover com as facetas de metadados indexadas nos documentos (origem, assunto, idioma, tags).

Os filtros rápidos são resetados automaticamente quando o usuário altera a busca por texto ou os filtros do servidor, mantendo a listagem coerente.

Recursos adicionais de busca:

• Busca por texto — nome, descrição e metadados.
• Busca por data — filtre por período de criação ou atualização.
• Filtro por status — filtre pelo estado de processamento.
• Filtros de qualidade e tamanho — disponíveis no botão principal de filtro (Category Filter).
• Visibilidade de colunas — mostre ou oculte colunas da tabela.

Status dos Documentos

Status	Descrição
Ativo	Documento disponível para consulta
Concluído	Processamento finalizado
Embedded	Embeddings gerados com sucesso
Processando	Geração de embeddings em andamento (barra de progresso avançando)
Pendente	Aguardando processamento
Armazenado	Arquivo salvo no sistema
Parcial	Parcialmente processado
Falha	Erro no processamento

Ações

O menu de ações da linha (lado direito) contém:

Ação	Ícone	Descrição
Info	i dentro de um círculo	Abre o modal Detalhes do Documento.
Baixar	Ícone de download	Disponível quando o documento possui arquivo no Storage.
Excluir	Ícone de lixeira	Remove o documento com diálogo de confirmação.

Nota

Excluir um documento também remove todos os embeddings vinculados ao seu storage_id da base vetorial. A ação é irreversível.

---

Modal de Detalhes do Documento

Selecionar Info abre um modal de altura fixa organizado em quatro abas:

Aba	Conteúdo
Detalhes	Nome do documento, descrição (texto completo), informações do arquivo (tamanho, tipo), origem e datas.
Metadados	Todas as chaves persistidas em storage.metadata, incluindo facetas e dados de processamento. Valores JSON (ex.: lista de participantes, objetos estruturados) são detectados automaticamente e renderizados como blocos formatados, não como string crua. Para planilhas, exibe também um bloco de Esquema legível (abas, colunas e tipos).
Qualidade	Pontuações de qualidade, completude e relevância; bloco de processamento com método de chunk, tipo de documento, modelo, provedor e timestamp. Em planilhas, a estratégia de chunk é sheet (uma unidade por aba).
Chunks	Lista paginada dos chunks gerados para o documento. Visível apenas para usuários super-admin. Em planilhas, a aba é rotulada Abas/Planilhas, exibindo nome da aba, nº de linhas e colunas.

O rodapé do modal expõe Baixar e Excluir como ações principais, ao lado de Fechar.

---

Indexação Idempotente

Documentos produzidos automaticamente (ex.: por agentes e workflows) utilizam um fluxo de upsert em vez de um insert cego:

• Um conjunto de upsertKeys (tipicamente source mais identificadores de negócio como meeting_title, meeting_date, organizer_email, document_type) é comparado contra entradas de storage existentes.
• Match encontrado → o arquivo no Storage é sobrescrito in-place, os embeddings antigos são removidos e a reindexação produz um novo conjunto de chunks, preservando o storage_id e o created_at originais.
• Sem match → uma nova entrada de Storage é criada normalmente.
• Conteúdo idêntico → a duplicidade é detectada durante a indexação, a linha de storage órfã criada nesse meio-tempo é removida e a listagem mantém a entrada original intacta.

Isso torna re-execuções da mesma fonte seguras e evita que a listagem fique cheia de duplicidades.

---

Estratégia de Chunking

Antes de um documento ser indexado, o Prodgy o divide em chunks. Por padrão, a plataforma escolhe automaticamente a melhor estratégia analisando o conteúdo — títulos, falas por interlocutor, blocos de código, quebras de página, tamanho e assim por diante.

Os nós de Base de Conhecimento nos workflows (operações Salvar no storage e Upsert no storage) expõem um campo opcional Estratégia de chunking que permite sobrepor essa escolha automática quando um comportamento específico é necessário — por exemplo, manter o resumo de uma reunião como bloco único em vez de deixá-lo ser dividido por título.

Opção	Comportamento
Automático (baseado no conteúdo)	Padrão. O Prodgy analisa o conteúdo e seleciona a estratégia. Idêntico ao comportamento anterior.
Bloco único	Armazena o documento inteiro como um único chunk.
Por título	Divide por títulos Markdown / seções.
Por interlocutor	Divide por falas de cada participante (transcrições de reunião).
Por página	Divide por quebras de página (PDFs).
Por bloco de código	Divide por blocos de código.
Semântico	Agrupa trechos semanticamente relacionados.
Por sentença	Divide por limites de sentença.
Tamanho fixo	Divide em janelas de tamanho fixo.

Nota

Manter o campo em Automático (ou vazio) preserva o comportamento atual, então agentes e workflows existentes não são afetados. Esta opção está disponível apenas no editor de nós do workflow — não é exposta na tela de upload manual de documentos.

Dica

O agente Meeting Scriber usa Bloco único para o resumo da reunião, de modo que o resumo é armazenado como um documento coeso em vez de fragmentado.