Organizando Itens da Base

Abra Admin → Bases de Conhecimento e selecione uma base para consultar e manter seus itens. A rota exige a capability bases.view; criar, editar, importar, otimizar e mover conteúdo exige bases.write, enquanto excluir exige bases.delete.

Entender a tela

No cabeçalho, pessoas com permissão de escrita podem editar o nome e a descrição da base diretamente. Pressione Enter ou saia do campo para salvar; Escape descarta a alteração local. Os limites são 100 caracteres para o nome e 500 para a descrição.

Os indicadores de Itens, Chunks e Tokens somam todos os itens carregados, inclusive os que ainda estão pendentes, processando ou com erro. Eles medem o volume cadastrado, não apenas o conteúdo disponível para o agente.

A tabela no desktop e os cartões no celular mostram nome, prévia, tipo, tamanho, status e data de criação. Os tipos visíveis são Texto, Arquivo e Crawl. Use Importar CSV, Exportar CSV ou Adicionar Item no topo conforme a tarefa.

Buscar e abrir conteúdo

Buscar por nome ou conteúdo filtra localmente os itens que já foram carregados pela tela, com limite de 200 caracteres na consulta. O filtro compara o nome e o campo de conteúdo do item. Em arquivos processados cujo texto existe apenas nos chunks privados, a busca da lista pode encontrar o nome, mas não necessariamente uma frase interna do documento.

Abra o menu de três pontos de uma linha para ver as ações disponíveis. Um perfil de somente leitura recebe um botão direto Visualizar. O modal de visualização prioriza a revisão ativa do otimizador; quando necessário, reconstrói o texto de um arquivo a partir dos chunks privados. Nele, use Copiar conteúdo e, para itens de crawl com URL, Abrir original.

Acompanhar o processamento

Estado	Significado	Conduta
Pendente	O item aguarda processamento.	Espere antes de testar a recuperação.
Processando	Extração, divisão em chunks ou indexação está em andamento.	Acompanhe a porcentagem e não crie uma cópia.
Processado	A indexação terminou e o item pode participar da busca do agente.	Valide com perguntas reais.
Erro	A ingestão falhou.	Confira a fonte; edite um item de texto ou remova e recrie um arquivo.

Somente Processado está pronto para recuperação. Ao salvar um item de texto, ele volta a Pendente e inicia outra indexação. O processador grava os novos vetores antes de remover os antigos; isso evita uma janela sem índice, mas o conteúdo anterior pode continuar recuperável até a troca terminar.

Adicionar ou editar itens

Adicionar Item abre três abas: Bloco de Texto, Arquivo e Site. Importar CSV cria vários itens de texto. Consulte formatos, limites, crawl e importação em Upload de Documentos.

No menu da linha, Editar aparece somente para itens cuja origem é Texto. O editor permite alterar nome e conteúdo Markdown, respeitando 100 caracteres no nome e 100.000 no conteúdo. Ele alerta antes de sair com mudanças não salvas. Para alterar a fonte de um item de Arquivo, remova o item e envie o documento correto; itens de crawl são administrados pelo respectivo crawl.

Melhorar itens com o otimizador

O SquadOS avalia a estrutura dos itens e pode mostrar Pode melhorar ou Difícil de consultar. A ausência do selo pode significar que o item está pronto, já foi otimizado ou que a avaliação não terminou; valide sempre pela busca real do agente.

Com bases.write, abra o menu e selecione Otimizar com IA. Quando mais de um item precisa de melhoria, um aviso também oferece Sim, otimizar para executar o lote ou Agora não para dispensá-lo. Se o plano não inclui knowledge_optimizer, a ação leva a Ver planos.

A avaliação identifica problemas de estrutura. A transformação reorganiza o conteúdo, reduz ruído e pode acrescentar vocabulário de busca sem enviar o corpo inteiro ao modelo auxiliar: ele recebe apenas um esqueleto estrutural e amostras limitadas. Esse uso é pago pela plataforma e não debita os créditos da organização.

Em um PDF, o otimizador trabalha sobre o texto que a indexação extraiu do documento, e não sobre o arquivo original. Por isso, o item precisa estar Processado: enquanto ele está pendente ou processando, a ação avisa que o item ainda está sendo processado. Se o PDF não tiver texto indexado, por exemplo porque a indexação terminou com Erro, a ação informa que não encontrou o conteúdo do item. Nesse caso, remova o item e envie o documento de novo antes de otimizar.

Depois da operação, confira o relatório de chunks, campos removidos, vocabulário e linhas desalinhadas. Voltar ao original só fica disponível nesse relatório atual. Recarregar a página descarta o relatório, e uma otimização em lote conserva somente o relatório do último item concluído; portanto, revise e decida sobre a reversão antes de sair da tela.

Selecionar, mover e excluir

Marque os checkboxes para abrir a barra de seleção. Mover Selecionados pede uma base de destino da mesma organização. Excluir Selecionados aparece para quem tem bases.delete e exige confirmação. Para um item só, use Remover no menu da linha, com a mesma regra.

Mover altera primeiro o vínculo dos itens no banco e depois atualiza os vetores. Se houver falha nessa segunda etapa, a interface atual ainda pode informar sucesso. Depois de mover, abra a base de destino e teste uma pergunta que dependa do conteúdo; se o resultado ainda vier da base anterior ou não aparecer, interrompa novas movimentações e peça verificação técnica.

Excluir não apaga o item na hora: ele vai para a aba Lixo da base, ao lado de Itens, e fica lá por sete dias. O item sai das respostas dos agentes imediatamente, porque o SquadOS apaga os vetores dele; o registro e o arquivo de origem continuam guardados durante o prazo. Um item em Processando não pode ser excluído: espere o processamento terminar.

Na aba Lixo, cada item mostra o tipo e a data em que será apagado definitivamente. Restaurar devolve o item para Itens como Pendente: ele é indexado de novo e volta às respostas dos agentes quando chegar a Processado. Pode restaurar quem tem bases.delete e, no modelo de departamentos, também quem recebeu Editar nessa base. Ter só Excluir na base permite mandar o item para o Lixo, mas não restaurá-lo. Sem permissão para restaurar, a aba lista os itens sem o botão.

Quando o prazo vence, o SquadOS apaga definitivamente o registro e o arquivo de origem, e o item não pode mais ser restaurado. Não existe botão para apagar antes do prazo. Já Excluir base, no menu de três pontos do cabeçalho, apaga a base e todos os itens dela, inclusive os que estão no Lixo, e não pode ser desfeita.

Exportar CSV

Exportar CSV abre Exportar a base como CSV e exige apenas bases.view. Clique em Baixar CSV: o SquadOS monta o arquivo no servidor e o download começa sozinho. Se o navegador não iniciar o download, use Baixar o arquivo.

O arquivo traz todos os itens ativos da base, inclusive os que vieram de arquivo ou de crawl. Cada item sai com o texto que a indexação usa: a versão otimizada, quando existe; senão, o texto salvo do item ou o texto extraído do arquivo de origem. Em PDF, é o texto que a indexação extraiu do documento. Os documentos originais não vão no CSV; para guardá-los, mantenha uma cópia fora do SquadOS.

O nome do arquivo é o nome da base em minúsculas, sem acentos e com hífens, por exemplo politicas-de-troca.csv. Ele usa ponto e vírgula (;) como separador, UTF-8 com BOM, para o Excel abrir a acentuação corretamente, e as colunas id;title;content.

O CSV sai completo ou não sai. Se algum item estiver pendente ou processando, tiver terminado com Erro ou não tiver um texto que possa entrar no arquivo, nenhum arquivo é gerado: o modal lista esses itens, cada um com o motivo e a correção. Acima de 50 itens, use Baixar relatório completo. Resolva os itens indicados e exporte de novo.

Depois de editar o arquivo, envie-o em Importar CSV com a opção Sincronizar base (exige bases.write e bases.delete) para deixar a base igual a ele; os itens de texto que não estiverem no arquivo vão para a aba Lixo e ficam lá por sete dias, e os itens de Arquivo e de Crawl ficam como estão. Mantenha a coluna id como veio: ela liga cada linha ao item da base, e uma linha sem id vira um item novo.

Valores que começam com =, +, -, @, tabulação ou retorno de carro saem com um apóstrofo na frente, para a planilha não executá-los como fórmula. Na sincronização, o SquadOS remove esse apóstrofo das linhas com id, e o conteúdo volta igual ao original.

Manter a base confiável

Use uma base por domínio e evite misturar políticas sem relação.
Dê nomes específicos: o nome acompanha cada chunk e também influencia a recuperação.
Use headings e mantenha condições, exceções e vigência junto da regra principal.
Remova versões revogadas e duplicatas para não oferecer respostas contraditórias.
Depois de editar, otimizar, mover ou excluir, espere Processado e teste perguntas reais no agente conectado.
Consulte AutoLearn para transformar lacunas recorrentes em itens revisados. Veja Oportunidades de Aprendizado.