Upload de Documentos

Uma base pode receber conteúdo por quatro caminhos:

Bloco de Texto, para escrever ou colar um item;
Arquivo, para extrair o texto de um documento;
Site, para descobrir e sincronizar páginas de uma URL (disponível nos planos pagos);
Importar CSV, para criar vários itens de texto em lote ou deixar a base igual a uma planilha.

Os três primeiros ficam em Bases de Conhecimento → abra a base → Adicionar Item. A importação em lote usa Importar CSV no topo da própria base. É necessário ter a capability bases.write; a capability bases.view permite consultar a base, mas não adicionar ou editar itens.

Adicionar um bloco de texto

A aba inicial da tela Adicionar Item é Bloco de Texto.

Em Nome do Item, escreva um nome que identifique o assunto, com até 100 caracteres.
Em Conteúdo, escreva ou cole até 100.000 caracteres. O editor aceita Markdown.
Selecione Adicionar Item.

O item é criado como Pendente e segue para extração, divisão em trechos e indexação. O nome não serve apenas para organizar a lista: ele acompanha os trechos no índice e pode ajudar a busca. Prefira Política de devolução — Brasil a Documento 1.

Enviar um arquivo

Na aba Arquivo, o SquadOS aceita um arquivo por envio, com no máximo 10 MB.

Conteúdo	Extensões aceitas
PDF	`.pdf`
Word	`.docx`
Excel	`.xlsx`
HTML	`.html`, `.htm`
JSON	`.json`
CSV ou TSV	`.csv`, `.tsv`
Markdown	`.md`, `.markdown`
Texto simples	`.txt`

Preencha Nome do Item ou escolha o arquivo para usar automaticamente o nome dele, sem a extensão.
Arraste o documento para a área de upload ou use o seletor de arquivo.
Confira se não apareceu uma mensagem de tamanho, formato ou conteúdo incompatível.
Selecione Enviar Arquivo.

O arquivo fica em armazenamento privado. O processador baixa a fonte, extrai sua estrutura, divide o conteúdo e cria o índice pesquisável. Arquivos antigos do Office, apresentações, ebooks, mensagens de email e imagens não entram diretamente: a própria interface orienta converter o material para um formato aceito ou colar o texto.

Depois da extração, use Visualizar para ler o conteúdo recuperado. A ação Editar existe somente para itens criados como Bloco de Texto; para mudar a fonte de um item de Arquivo, remova-o e envie o documento correto. O nome e o texto extraído continuam disponíveis no modal de visualização.

Indexar um site

Use a aba Site para transformar páginas públicas de um domínio em itens da base. A sincronização de site está disponível nos planos pagos: em uma organização no plano Grátis, a aba mostra o convite Sincronização de site com o botão Ver planos no lugar do formulário.

Informe a URL inicial.
Escolha a Frequência de sincronização: Manual, Diária, Semanal ou Mensal.
Se necessário, abra Avançado para definir um nome, limitar por prefixo de caminho, excluir caminhos e alterar o máximo de páginas. O valor inicial é 500.
Selecione Visualizar páginas.
Confira a quantidade encontrada, as páginas que restaram depois das exclusões, o custo em créditos e o saldo da organização.
Selecione Confirmar e iniciar crawl.

A confirmação fica indisponível quando nenhuma página efetiva foi encontrada ou quando o saldo não cobre o custo. Uma frequência diferente de Manual cria sincronizações futuras, que também podem consumir créditos. O site precisa estar acessível ao coletor; páginas que exigem JavaScript ou um domínio sem sitemap podem não aparecer no preview.

Cada site sincroniza uma vez por dia

Um mesmo site sincroniza no máximo uma vez a cada 24 horas, tanto pelo agendamento quanto por Sincronizar agora. Enquanto a janela estiver fechada, o cartão do site exibe Sincroniza de novo seguido do tempo restante, e Sincronizar agora fica indisponível.

O limite não altera a frequência escolhida: Semanal e Mensal continuam valendo como estão, e Diária já respeita o intervalo de 24 horas. Uma tentativa que não chega a iniciar a coleta — quando o coletor recusa o endereço, por exemplo — não consome a janela do dia.

Sites de uma organização no plano Grátis

Sites criados antes continuam listados e o conteúdo já indexado permanece na base, disponível para os agentes. Eles deixam de sincronizar: o cartão exibe Sincronização pausada: disponível nos planos pagos e Sincronizar agora fica indisponível até a organização passar para um plano pago.

Importar vários itens por CSV

Importar CSV, no topo da base, abre Importar itens por CSV. O botão aparece para quem tem bases.write. Primeiro escolha, em O que fazer com o arquivo:

Adicionar itens (bases.write): acrescenta os itens do arquivo. O que já está na base continua como está.
Sincronizar base (bases.write e bases.delete): deixa a base igual ao arquivo. O item que não estiver nele vai para a lixeira e fica lá por sete dias. A opção só aparece para quem tem as duas capabilities.

Depois envie o arquivo. O SquadOS lê e analisa o arquivo no servidor e mostra o que vai mudar antes de alterar qualquer item: a análise não grava nada na base, e nada muda até você confirmar.

Formato do arquivo

ponto e vírgula (;) como separador;
texto em UTF-8;
a primeira linha é title;content ou id;title;content, nessa ordem;
uma linha por item, com o mesmo número de colunas do cabeçalho;
aspas duplas quando o campo tiver ponto e vírgula, aspas ou quebra de linha;
duas aspas duplas ("") para representar uma aspa dentro de um campo já entre aspas.

O título é obrigatório e aceita até 100 caracteres; os espaços nas pontas são removidos. O conteúdo é obrigatório, aceita até 100.000 caracteres e é gravado exatamente como está no arquivo, com espaços e quebras de linha. Linhas em branco são ignoradas. O arquivo pode ter até 50 MB, sem limite de linhas; um arquivo maior é recusado no envio.

Exemplo mínimo:

title;content
"Prazo de devolução";"A devolução pode ser solicitada em até 30 dias."
"Atendimento";"De segunda a sexta, das 8h às 18h."

Adicionar itens

Cada linha vira um item de texto novo. Use o cabeçalho title;content; a coluna id só é aceita vazia. Um id preenchido em qualquer linha bloqueia o arquivo inteiro, porque atualizar itens que já existem é papel de Sincronizar base. Neste modo, o modal oferece Baixar planilha de exemplo.

Sincronizar base

Comece pela exportação desta base: ela já traz o id de cada item. Baixe o arquivo em Exportar CSV, edite-o e envie-o com o cabeçalho id;title;content. Na sincronização:

uma linha com id atualiza o título ou o conteúdo daquele item. O id precisa ser de um item desta base e aparecer uma vez só no arquivo;
uma linha sem id vira um item novo;
um item de texto que está no Lixo volta para a base quando o id dele está no arquivo, já com as mudanças da linha;
um item de texto que não está no arquivo vai para a lixeira e fica lá por sete dias; para recuperá-lo, use Restaurar na aba Lixo da base. Um item que já estava no Lixo continua lá, com o prazo original;
itens que vieram de Arquivo ou de Site não são editados pelo CSV. A linha deles precisa manter o título e o conteúdo da exportação, e, se não estiverem no arquivo, eles são preservados, sem ir para a lixeira. Para mudar um desses itens, troque a fonte: envie o documento correto ou sincronize o site.

Uma diferença só no tipo de quebra de linha, como a que o Excel grava ao salvar, não conta como mudança de conteúdo. Quando o conteúdo de um item otimizado muda pelo CSV, o texto do arquivo substitui a versão otimizada.

A exportação coloca um apóstrofo na frente dos valores que começam com =, +, -, @, tabulação ou retorno de carro, para a planilha não executá-los como fórmula. A sincronização remove esse apóstrofo somente nas linhas com id, e o conteúdo volta igual ao original. Em uma linha sem id, e em Adicionar itens, um apóstrofo no começo do valor é mantido como parte do texto.

Corrigir problemas do arquivo

Qualquer problema impede a importação inteira: nada é aplicado, nem as linhas corretas. O modal informa quantos problemas impedem a importação e mostra uma tabela com Linha, Campo, Valor, Problema e Como corrigir. A linha é a do arquivo: o cabeçalho é a linha 1, e as linhas em branco também contam.

A análise segue até o fim do arquivo, então o relatório traz todos os problemas de uma vez. A tela mostra os 50 primeiros; acima disso, use Baixar relatório completo. Os motivos mais comuns são cabeçalho diferente do esperado, linha com número errado de colunas, título ou conteúdo vazio ou longo demais, id repetido, id que não pertence a esta base e item que ainda está sendo processado. Corrija a planilha, selecione Voltar e envie o arquivo de novo.

Conferir a prévia e aplicar

Quando o arquivo passa na análise, a prévia mostra sempre as sete categorias do plano, mesmo as que ficaram em zero: Adicionados, Sem mudança, Título atualizado, Conteúdo atualizado, Restaurados, Para a lixeira e Arquivos e rastreamentos preservados. Se algum item for para a lixeira, o modal lista os nomes. Quando uma categoria passa de 50 itens, Baixar a prévia completa traz a lista inteira. Se o arquivo descreve a base exatamente como ela está, a prévia avisa que nada vai mudar.

Para aplicar, selecione Adicionar itens ou Sincronizar base. Na sincronização, o primeiro clique pede a confirmação e o segundo aplica. O plano é aplicado de uma vez: ou ele vale inteiro, ou nada muda. Se a base mudou depois da prévia, o SquadOS não aplica o arquivo e volta para o envio; exporte a base de novo, refaça suas edições e envie o arquivo outra vez.

O recibo mostra Adicionados, Atualizados, Restaurados, Na lixeira, Sem mudança e Preservados. Itens novos, restaurados ou com título ou conteúdo alterado passam pelo processamento e entram na busca assim que ele termina; o recibo avisa quantos ainda estão sendo processados.

Entender os estados

Estado	Significado	O que fazer
Pendente	O item aguarda um processador.	Aguarde; editar também retorna o item a este estado.
Processando	A fonte está sendo extraída ou os trechos estão sendo indexados.	Não faça outro upload do mesmo conteúdo.
Processado	A ingestão e a gravação do índice terminaram.	Teste perguntas reais no agente.
Erro	A extração ou a indexação falhou.	Confira a fonte; edite um item de texto ou remova e recrie um arquivo.

Processado não garante que qualquer pergunta encontrará a resposta. Ele confirma a ingestão, não a qualidade da recuperação. Para uma validação útil:

conecte a base em Agentes → abra o agente → Conhecimento → Bases de conhecimento;
salve o agente;
faça perguntas com a linguagem real dos clientes;
confirme se o trecho recuperado sustenta a resposta;
melhore nomes, headings e conteúdo quando a informação estiver indexada, mas difícil de localizar.

Veja o fluxo completo em Conectando a Agentes.

Depois de criar um bloco ou enviar um arquivo, o SquadOS também pode avaliar a estrutura e abrir o otimizador. Sim, otimizar aplica a transformação; Não, usar como está mantém o conteúdo recebido. Quando o plano permite otimização, fechar o diálogo também aceita a otimização, conforme o aviso da própria tela. Consulte avaliação, relatório e reversão em Organizando Itens da Base.

Preparar conteúdo que o agente consiga usar

Dê ao item um nome específico e coerente com o vocabulário do cliente.
Use headings para separar assuntos; eles acompanham os trechos indexados.
Mantenha cada política junto de suas condições, exceções e data de validade.
Separe documentos extensos quando tratam de assuntos sem relação.
Remova versões revogadas e duplicatas para evitar respostas contraditórias.
Depois de uma importação importante, valide a jornada de pergunta e resposta — não apenas o status da tabela.