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.

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.

Caution

O otimizador troca a revisão ativa antes de solicitar a reindexação. Se a operação terminar com erro, reabra o item, confira o conteúdo exibido e espere o status voltar a Processado antes de considerar a versão disponível ao agente.

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. As mesmas regras valem para Excluir no menu de uma linha.

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 oferece desfazer. O registro sai da base imediatamente e a limpeza de vetores, chunks e arquivo de origem segue por uma fila assíncrona. Antes de confirmar uma exclusão importante, conserve a fonte original fora do SquadOS.

Exportar CSV

Exportar CSV gera <nome-da-base>-itens-AAAA-MM-DD.csv, com as colunas title;content. A confirmação informa quantos registros serão exportados e quantos serão ignorados.

O arquivo inclui somente itens cujo campo de conteúdo está preenchido. Ele pode omitir documentos cujo texto está apenas nos chunks privados e exporta o conteúdo original do registro, não necessariamente a revisão otimizada que aparece em Visualizar. Por isso, trate o CSV como exportação parcial para consulta ou migração de texto, não como backup completo da base.

Caution

Ao abrir o CSV em uma planilha, importe as colunas como texto. Valores iniciados por =, +, - ou @ não são neutralizados pelo exportador e podem ser interpretados como fórmulas.

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.