Documentos#

Para trabalhar com Documentos, são necessarias a permissão da Funcao para ler Documentos e acesso aos arquivos selecionados. Criar, alterar e excluir itens exige as permissoes correspondentes. A coluna "Object Folder" está disponivel com permissão para ler Pastas de objetos.

A tela Documentos permite carregar arquivos próprios no armazenamento de documentos do Sherpa AI Server e organizá-los em pastas.

Neste armazenamento, há uma estrutura de pastas em múltiplos níveis, onde cada pasta pode ter um número ilimitado de anexos (tanto subpastas quanto arquivos).

A tabela abaixo descreve a tela principal Documentos com as configurações de aparência da interface padrão. Os rótulos e a metainformação ficam ocultos na lista. As condições para exibi-los são explicadas adiante. As ações disponíveis dependem das permissões do Usuário.

№ p/p	Elemento da interface	Descrição
1.	modo "Tabela"	Modo de exibição de documentos como linhas de tabela.
2.	modo "Blocos"	Modo de exibição de documentos como cartões compactos.
3.	modo "Blocos grandes"	Modo de exibição de documentos como cartões ampliados.
4.	botão "Criar pasta"	Permite criar uma nova pasta para armazenar documentos.
5.	botão "Carregar arquivos"	Permite carregar arquivos na pasta selecionada.
6.	botão "Baixar arquivos"	Permite baixar os arquivos selecionados.
7.	botão "Excluir selecionados"	Exclui os arquivos e as pastas selecionados após a confirmação. Para excluir uma pasta ou um arquivo, é possível clicar no botão na respectiva linha e confirmar a ação.
8.	botão "Atualizar"	Permite atualizar forçadamente a tabela na tela Documentos.
9.	botão "Processamento de documentos"	Abre a janela pop-up "Configurações de documentos" para configurar o reconhecimento de imagens em PDFs e a indexação.
10.	campo "Pesquisa por documentos"	Pesquisa arquivos por nome, descrição e conteúdo, e pastas por nome. Para filtrar por extensão, é possível utilizar o filtro separado.
11.	lista suspensa "Tags"	Permite filtrar documentos por tags.
12.	lista "Combinação de tags"	Exibida ao selecionar duas ou mais tags. "Qualquer tag selecionada" encontra arquivos com pelo menos uma tag selecionada e é a opção padrão. "Todas as tags selecionadas" encontra arquivos com todas as tags selecionadas.
13.	campo "Extensão"	Permite filtrar documentos por extensão de arquivo.
14.	coluna "Nome"	Exibe o nome da pasta ou arquivo. Para pastas, é usada a ícone de pasta.
14.1.	seta de expansão da pasta	Permite expandir a pasta e visualizar os itens anexados.
14.2.	checkbox de seleção de item	Permite selecionar a pasta ou arquivo para realizar ações em grupo.
15.	coluna "Descrição"	Exibe a descrição do documento ou pasta, se fornecida.
16.	coluna "Extensão"	Mostra a extensão do arquivo.
17.	coluna "Tags"	Mostra as tags atribuídas ao documento.
18.	coluna "Criado"	Exibe a data e hora de criação do item.
19.	coluna "Modificado"	Exibe a data e hora da última modificação do item.
20.	coluna "Tamanho"	Exibe o tamanho do arquivo. Para pastas, o valor pode não ser especificado.
21.	coluna "Status"	Exibe o status atual de processamento ou disponibilidade do documento. Valores possíveis: "Aguardando processamento"; "Em processamento"; "Pronto"; "Erro" (a razão é exibida no arquivo); "Aguardando indexação manual"; "Não indexado".
22.	coluna "Pasta de objetos"	Exibe a pasta de objetos à qual o documento ou pasta pertence.
23.	botão "Visualizar"	Abre a visualização de um arquivo em formato compatível. Não é exibido para pastas.
24.	botão "Reindexar pasta"	Inicia a reindexação da pasta selecionada. Não é exibido para arquivos.
25.	botão de edição	Permite alterar as configurações da pasta ou arquivo selecionado.
26.	botão de exclusão	Permite excluir a pasta ou arquivo selecionado.

Por que um documento foi encontrado#

É necessário digitar uma consulta em Pesquisar documentos. Passe o cursor sobre o ícone de informação de um resultado ou toque nele para ver se a correspondência veio do nome do arquivo, da descrição, da extensão, do nome da pasta, do texto do documento ou do significado. A dica mostra todos os motivos aplicáveis, sem pontuações numéricas.

Você pode acessar o ícone pelo teclado ou tocá-lo em uma tela sensível ao toque. É necessário selecionar Visualizar na linha ou no bloco para abrir o documento. Se a busca retornou um trecho de texto, a prévia o destaca. Sem trecho, o documento abre sem destaque.

Criar pasta#

Para criar uma nova pasta na tabela na tela Documentos, é possível clicar no botão "Criar pasta" e preencher o formulário que se abrir.

O formulário contém os seguintes elementos:

• "Nome" * — um campo de texto obrigatório para inserir o nome da pasta.
• "Analisador de pastas" — uma lista suspensa para selecionar um analisador que processa automaticamente os arquivos da pasta.
• "Descrição" — um campo de texto para descrever o conteúdo da pasta.
• "Pastas de objetos" — seleção da pasta utilizada para processar pastas e arquivos em conversas com os Assistentes.

Edição de pasta#

Para visualizar e editar as propriedades de uma pasta específica, selecione-a na lista e clicar no botão . Em seguida, abrirá uma janela pop-up com as configurações da pasta, onde você pode fazer as alterações necessárias. Além dos campos preenchidos ao criar a pasta, ao editar, o formulário mostrará o GUID (identificador único atribuído à pasta após sua criação). Este campo não pode ser editado.

Carregar arquivos#

Para carregar um ou mais arquivos em uma pasta específica, é possível marcar a caixa de seleção na linha da pasta selecionada e, em seguida, é possível clicar no botão "Carregar arquivos".

Na janela que se abrir, é possível selecionar os arquivos desejados e clicar no botão "Abrir".

Durante o carregamento dos arquivos, aparecerá uma janela pop-up com o progresso do carregamento de cada um dos arquivos.

Após o carregamento de todos os arquivos selecionados, é possível clicar no botão "OK".

Nos uploads .pdf, .docx, .xlsx e .pptx, o conteúdo deve corresponder à extensão. Se a janela mostrar erro de validação, confira o formato e renomeie o arquivo para corresponder ao conteúdo ou envie um documento válido. Arquivos Office têm limite de 256 MiB após descompactação e 64 MiB para o componente XML principal; reduza um documento válido se ele ultrapassar esses limites. Os demais formatos ainda não passam por essa verificação.

Durante o processamento, esse arquivo terá o status "Em processamento", em seguida, os dados do arquivo processado são adicionados ao armazenamento, após o que o status mudará para "Pronto". Se a indexação não for realizada (por exemplo, se a digitalização não tiver camada de texto e o reconhecimento não estiver configurado), aparecerá o status "Erro" com a razão.

Visualizar um arquivo#

Para abrir um arquivo sem baixá-lo, expanda a pasta e clique no botão de visualização (ícone de olho) na linha do arquivo. Os botões de ação ficam na última coluna da tabela. Se ela for mais larga que a janela do navegador, role para a direita até essa coluna.

O arquivo é aberto em uma janela. Se o botão estiver desabilitado, verifique se sua função tem permissão para ler documentos e se o formato é compatível: DOCX, XLS, XLSX, PPTX, PDF, TXT, CSV, PNG, JPG, JPEG, GIF.

Para usar o teclado, navegue até a coluna de ações. Tab e Shift+Tab movem o foco entre os botões habilitados. É necessário pressionar Enter ou a barra de espaço no botão de visualização para abrir o arquivo. Botões desabilitados são ignorados; após o último botão, Tab continua pela tabela.

Baixar arquivos#

Após selecionar arquivos usando as caixas de seleção na tabela de documentos, o botão "Baixar arquivos" se torna ativo e pode ser usado para baixar os arquivos selecionados.

Após clicar no botão "Baixar arquivos", o sistema automaticamente cria e baixa um arquivo compactado com os arquivos selecionados. O arquivo compactado inclui apenas os documentos que foram marcados com caixas de seleção na tabela de documentos.

Adicionar uma tag a vários arquivos#

Adicionar uma tag exige permissão para alterar Documentos e acesso aos arquivos selecionados. O botão está disponível quando ativado nas configurações de aparência da interface. Os nomes citados são da interface inglesa.

Uma tag é adicionada da seguinte forma:

1. Os arquivos necessários são selecionados pelas caixas de seleção na tela Documentos. Para selecionar vários cartões no computador, Ctrl deve ser mantido pressionado, ou Command no macOS. Em telas de até 768 px, os cartões podem ser tocados em sequência. A ação fica indisponível se a seleção incluir uma pasta.

2. O botão "Add tag to selected" abre sua janela.

   

   

3. Uma tag existente deve ser selecionada em "Select a tag", seguida de "Add". "Cancel" fecha a janela sem alterações.

A mesma janela abre por "Add tag to selected" no menu de contexto da tabela ou dos cartões. Em um arquivo selecionado, a ação vale para toda a seleção. Em um arquivo não selecionado, vale apenas para esse arquivo.

A tag é adicionada a cada arquivo. As tags e marcas anteriores são mantidas, e repetir a ação não cria duplicatas. As tags aparecem separadas por vírgulas, em separado das marcas.

A mensagem mostra o número de arquivos atualizados. Se alguns falharem, seus nomes são listados. Após verificar o acesso, "Retry these files" pode ser usado.

Criar uma nova tag também exige permissão para criar Documentos. Ela pode ser criada por "New tag" no cartão de um arquivo.

Pesquisa e filtros de documentos#

Os filtros de tags, rótulos, extensão e metainformação ficam na aba de filtro do menu de cada coluna. Tags e rótulos são selecionados em uma lista; as extensões são selecionadas por grupos de tipos de arquivo e a metainformação procura texto contido no campo. A regra de qualquer uma ou todas as tags selecionadas fica na aba principal do menu da coluna de tags. As condições são mantidas ao alternar a visualização de documentos.

Quando um filtro é aplicado, o botão do menu da coluna correspondente fica destacado. O destaque desaparece quando o filtro é redefinido. Isso se aplica às visualizações de documentos e indexação.

As configurações de marca podem ocultar as colunas de rótulos e metainformação. Os valores salvos continuam disponíveis; as colunas ocultas podem ser ativadas pelo menu de colunas. A metainformação pode ser editada na ficha do arquivo.

Nos resultados da pesquisa, o botão de explicação mostra os motivos da correspondência e o trecho de texto disponível. O trecho é destacado na pré-visualização; uma correspondência apenas pelo nome ou pela pasta pode não incluir um trecho.

Grupos de extensões#

Os grupos de extensões abaixo correspondem à configuração padrão. O administrador pode alterá-los nas configurações de aparência.

A aba de filtro do menu da coluna "Extensão" inclui os grupos PDF, Word, Excel, PowerPoint, texto, imagens, áudio e vídeo. Word inclui DOC e DOCX; Excel inclui XLS e XLSX. A seta de cada grupo permite expandir as extensões e selecionar formatos individuais ou o grupo inteiro. Os grupos e formatos selecionados aparecem no cabeçalho da coluna após fechar o menu.

O filtro de extensões combina com a pesquisa, as tags e as demais condições. É necessário selecionar todos os valores da lista para remover a restrição por tipo de arquivo. A visualização de indexação possui o mesmo filtro da coluna "Extensão".

Indexação de documentos#

O botão "Indexação", com um ícone de pulso, fica ao lado dos três botões de visualização de documentos acima da tabela. Ele abre uma lista plana de arquivos de todas as pastas acessíveis. Para voltar às pastas e arquivos, selecione tabela, blocos ou blocos grandes no mesmo grupo de botões. A visualização ativa fica destacada. Os botões de visualização ficam à esquerda acima da tabela, e os botões de ação à direita.

A barra de status ocupa toda a largura da tela. Ao passar o ponteiro, uma dica mostra o total de Documentos acessíveis, os contadores de cada status e as explicações. O foco do teclado também abre a dica; os status não são botões. Os contadores respeitam as Pastas de objetos selecionadas no cabeçalho e as permissões do usuário. Eles não dependem da página atual nem da pasta expandida. A barra também aparece na visualização em blocos.

Documentos com status "Erro" não são incluídos na pesquisa. Para encontrar esses arquivos em todas as pastas acessíveis:

1. É necessário abrir a tela Documentos e selecione o botão "Indexação" acima da tabela.
2. É necessário abrir o menu da coluna de status, alterne para a aba de filtro e selecione "Erro". Se necessário, selecione vários valores, como "Erro" e "Em processamento".
3. Os filtros da lista estão integrados nos menus das colunas: nome, descrição, status, tags, rótulos, extensão, metainformação, Pastas de objetos, datas e tamanho. Alterne as páginas; o tamanho da página é de 20, 50 ou 100 arquivos.
4. É necessário selecionar o caminho na coluna de pasta para abrir o arquivo na visualização "Documentos". A cadeia de pastas é expandida e o arquivo é selecionado.
5. Para um arquivo com status "Erro", utilize o ícone de repetir a indexação. O arquivo retorna à fila de processamento. Essa ação exige permissão para atualizar Documentos.

No telefone, a lista é exibida como cartões. O botão de atualização atualiza a lista e os contadores. Os status também são atualizados automaticamente enquanto a tela está aberta; a página atual é preservada.

A dica da barra indica quando não há arquivos ou quando não há erros nem processamento ativo. Se o carregamento falhar, use o botão de atualização novamente.

Configurações dos documentos#

O botão Processamento de documentos abre as configurações de toda a conta para futuras indexações. O lápis na linha de uma pasta abre as Propriedades da pasta.

Na aba Indexação, Atualmente nesta conta mostra o modelo atual (ou o embed-server integrado), a dimensão do vetor e qualquer transição pendente. Se o modelo não estiver na lista, seu GUID será exibido; verifique o acesso antes de alterá-lo. Alterar o modelo ou a dimensão substitui os vetores e coloca os arquivos na fila; alterar apenas o OCR não remove vetores.

Mudança de modelo de indexação ou dimensão#

O roteiro passo a passo e exemplos de transição estão disponíveis nas instruções para mudar o modelo de indexação.

A dimensão do embedding deve coincidir com o número de componentes do vetor que o modelo escolhido retorna. Por exemplo, se o modelo cria um vetor de 1024 números, especifique 1024. O valor padrão é 384; números inteiros de 32 a 2000 são permitidos.

Para o modelo de indexação, é necessário exatamente uma instância ativa: diferentes instâncias podem criar vetores incompatíveis sob o mesmo nome de modelo. É necessário criar o modelo e a instância na seção de modelos, e atribua-o como padrão para indexação aqui, nas configurações de Documentos.

1. É necessário abrir Documentos → Processamento de documentos → Indexação.

2. É necessário selecionar o "Indexing model" disponível e especifique sua Dimensão do embedding real. Alterar apenas o número no campo não muda o modelo.

   

3. É necessário clicar em Salvar. O sistema verifica o modelo, a dimensão dos vetores e o índice de pesquisa. Se a verificação falhar, o modelo, a dimensão e os vetores anteriores permanecem. Configurações de reconhecimento de PDF alteradas ao mesmo tempo podem ter sido salvas separadamente; reabra-as após um erro. As dimensões 384 e 1024 são preparadas na atualização do servidor; outras exigem preparação prévia do administrador. Após a verificação, o servidor substitui os vetores usando o texto salvo sem repetir o OCR. Arquivos sem trechos salvos são lidos novamente. Os arquivos automáticos entram na fila e as amostras de respostas dos assistentes são reindexadas. Os modos manual e sem indexação permanecem. Os arquivos originais são preservados.

4. É necessário aguardar a conclusão do processamento dos arquivos. Enquanto a troca em si não estiver concluída, a pesquisa por conteúdo estará temporariamente indisponível; enquanto os arquivos estão sendo reindexados, os resultados podem ser incompletos. O status de um arquivo processado automaticamente muda de Aguardando processamento através de Em processamento para Pronto. Para um arquivo com status Aguardando indexação manual, abra-o e clique em Reindexar, depois aguarde o status Pronto.

Trechos adicionados por POST /api/v1/files/{file_guid}/chunks mantêm o texto e recebem novos vetores quando apenas o modelo ou a dimensão muda. Alterar o tamanho ou a sobreposição é rejeitado se esses trechos não tiverem arquivo de origem. É necessário salvar o texto e os metadados fora do sistema, remova os trechos ou seu arquivo e repita a alteração.

Ao alterar Tamanho do chunk ou Sobreposição de chunks, um ícone de aviso aparece ao lado do campo. Passe o cursor sobre ele ou selecione-o com o teclado para ler a explicação. Salvar remove os trechos antigos e lê novamente os arquivos com indexação automática. Digitalizações exigem OCR de novo, o que pode aumentar muito o tempo de reindexação. Se o modelo ou a dimensão também mudar, novos vetores serão criados depois da leitura dos arquivos.

Se, após o processamento, um arquivo exibir Erro, abra a causa e verifique a disponibilidade do modelo escolhido e sua dimensão. Após resolver a causa, clique em Reindexar neste arquivo. Se for necessário reprocessar todos os arquivos, use o botão separado Excluir todos os vetores e reindexar. Re-salvar o mesmo modelo e dimensão após a troca concluída não inicia uma nova indexação.

Se a troca foi interrompida e a janela de configurações mostra que não foi concluída, repita o salvamento do mesmo modelo e dimensão: o servidor concluirá a limpeza e colocação de arquivos na fila sem uma nova troca; a indexação de arquivos continuará em segundo plano. Até a conclusão da troca, não selecione outro par de modelo e dimensão.

Tags e pesquisa de documentos#

A pesquisa exige permissão para ler Documentos e acesso aos arquivos. As tags são selecionadas no menu da coluna "Tags" na tela Documentos.

Os arquivos podem ser filtrados por tags da seguinte forma:

1. Abrir o menu da coluna "Tags" e sua aba de filtro, e selecionar os valores necessários.

   

2. Na aba principal desse menu, selecionar "Any selected tag" ou "All selected tags". A primeira regra e o padrão e mantem arquivos com pelo menos uma tag selecionada. A segunda mantem somente arquivos com todas as tags selecionadas.

   

3. Para remover a condição de tags, redefinir o filtro da coluna "Tags" ou selecionar todos os seus valores. As outras condições de pesquisa permanecem. Desmarcar todos os valores produz uma lista de arquivos vazia.

Por exemplo, selecionar "Contrato" e "Assinado" com "All selected tags" mantem um arquivo com ambas as tags. Um arquivo apenas com "Contrato" e excluido. Os outros filtros continuam reduzindo a lista.

Para atribuir tags, é possível abrir o arquivo com "Editar", selecionar tags existentes ou criar uma nova e salvar os detalhes. Para editar, é necessária permissão de alteração de documentos. Para filtrar, basta permissão de leitura. Se o arquivo necessário não aparecer nos resultados da pesquisa na tela Documentos, é possível verificar suas tags nos detalhes do arquivo e o modo selecionado na lista "Combinação de tags" dessa tela.

Por padrão, os rótulos ficam ocultos na tela Documentos: não aparecem no filtro, na coluna, nos cartões nem na edição do arquivo. O administrador pode exibir os rótulos novamente definindo hide_document_marks como false nas configurações de aparência da interface. Os rótulos existentes permanecem atribuídos após a edição. Integrações ainda podem lê-los e usar o filtro mark_guids da API.

Metainformação do arquivo#

O campo "Metainformação" permanece nos detalhes do arquivo. Para preencher ou alterar, é possível abrir os detalhes do arquivo usando "Editar" na tela Documentos, informar um valor como "Série 17" e salvar. Após abrir novamente os detalhes do arquivo, o valor informado permanece no campo "Metainformação". O campo "Metainformação" fica vazio quando não há valor. A edição requer permissão para alterar documentos.

Por padrão, o filtro e a coluna independentes de metainformação ficam ocultos na tela Documentos. Se hide_document_metainfo_in_list for definido como false na configuração de aparência da interface, eles são exibidos. Os valores salvos e o campo metainfo da API continuam disponíveis para integrações. O parâmetro metainfo da API de pesquisa procura uma substring nesse campo: série encontra "Série 17". Esse campo não afeta a indexação do conteúdo nem a classificação dos resultados.

Gerenciar o catálogo de tags#

Uma tag permanece no catálogo da Conta após ser removida de um arquivo. A tag é gerenciada na janela "Manage tags". Os controles citados são da interface inglesa.

A visualização exige permissão para ler Documentos. Adicionar, renomear e excluir exige as permissões correspondentes da Função para criar, alterar e excluir. Sem elas, a lista é somente leitura. O nome não pode ser vazio nem ter mais de 64 caracteres. Nomes duplicados não são permitidos no catálogo.

O catálogo pode ser aberto na tela Documentos, na tabela ou visualização "Indexing", pelo botão de lápis junto ao filtro da coluna "Tags". Em telas estreitas, ele fica junto aos botões de visualização acima da tabela.

A janela "Manage tags" abre com as tags da Conta.

A janela oferece as seguintes ações independentes:

• Para adicionar, um nome deve ser informado em "New tag", seguido de "Add".

• Para renomear, o nome deve ser alterado na linha, seguido de "Save".

• "Delete" na linha abre a confirmação. "Yes" confirma a exclusão e "No" a cancela.

  

  Após confirmar, a tag desaparece do catálogo e da exibição dos arquivos da Conta. Os arquivos não são excluídos.

  

• "Close" retorna a Documentos. O catálogo, a lista de arquivos e os valores dos filtros são atualizados.

Se a tag excluída estava selecionada no filtro, essa condição é removida. Um erro mantém as alterações sem aplicação na janela. A mensagem deve ser verificada antes de repetir a ação.

Erros de indexação de PDF#

Para iniciar a reindexação e alterar as configurações, é necessária a permissão da Função para alterar Documentos. O motivo da falha aparece na coluna "Status" e na dica de ferramenta. Falhas desconhecidas mantêm a mensagem genérica "indexação não realizada".

Um PDF com páginas digitalizadas exige que o reconhecimento esteja ativado: Tesseract ou "Saved model". Uma imagem que ultrapassa um pouco a borda da página não impede o OCR da parte visível. Com o OCR desativado, somente a camada de texto é extraída; uma digitalização sem camada de texto não pode ser indexada.

Após resolver a causa, é necessário abrir o arquivo e clicar no botão "Re-index". O processamento bem-sucedido resulta no status "Ready", sem a causa do erro anterior. Se a falha se repetir, é necessário informar ao administrador o nome do arquivo e o texto da coluna "Status". Alterar uma configuração por si só não confirma que a indexação foi bem-sucedida.