Alterar o modelo de indexação de documentos#

Este guia explica como alterar o modelo que cria vetores para a pesquisa em documentos. Ao alterar o modelo ou a dimensão dos vetores, o Sherpa AI Server limpa os vetores antigos e indexa os documentos novamente. A pesquisa por conteúdo pode ficar indisponível durante a alteração, e os resultados podem ficar incompletos até o processamento dos arquivos terminar. Programe a alteração para um momento adequado. Os nomes de navegação estão traduzidos neste guia; a interface da versão 2.5.1 está disponível em russo e inglês. A seguir, os status e o botão de reindexação são citados como aparecem na interface em inglês.

Antes de começar#

• Para alterar essas configurações, são necessárias as permissões documents:update e ai_models:read. Criar um modelo ou uma instância também requer ai_models:create. Configurar uma instância do vLLM pela API requer ai_models:update.
• Verifique a dimensão real dos vetores do novo modelo. Informe o número retornado por ele: um inteiro de 32 a 2000. Ao atualizar de 2.5.0 para 2.5.1, prepare os índices 384 e 1024. Se a versão atual for anterior à 2.5.0, combine primeiro o caminho de atualização com a equipe de suporte. Para outra dimensão, um administrador deve preparar o índice de pesquisa antes.
• Um modelo do tipo Indexação ou Multimodal deve ter exatamente uma instância ativa. Várias instâncias do mesmo modelo podem retornar vetores incompatíveis.
• Não altere o endereço ou o caminho da instância ativa do modelo de indexação atual para apontá-la para outra fonte de vetores: o sistema rejeita essa alteração. Crie um modelo e uma instância separados e selecione o novo modelo nas configurações de indexação de documentos.
• Se os documentos contiverem trechos adicionados somente pela API, sem arquivo de origem, leia “Se a alteração for rejeitada” abaixo. A reindexação comum não consegue restaurar esses trechos.

Exemplo: BGE-M3 com vLLM#

Em um servidor com GPU, inicie uma instância separada do vLLM para o modelo de indexação. Este exemplo usa vLLM 0.27.1 e BAAI/bge-m3 (o vLLM deve estar instalado e os arquivos do modelo devem estar disponíveis):

vllm serve BAAI/bge-m3 --runner pooling --pooler-config.task embed \
  --hf-overrides '{"architectures":["BgeM3EmbeddingModel"]}' \
  --host 0.0.0.0 --port 8001

No servidor vLLM, confirme que cada vetor contém 1024 números (é necessário ter jq):

curl -fsS http://127.0.0.1:8001/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"BAAI/bge-m3","input":["test"]}' \
  | jq '.data[0].embedding | length'

Em Modelos, crie um novo modelo do tipo Indexação e uma única instância local ativa. Informe BAAI/bge-m3 como caminho do modelo, 8001 como porta e um endereço do vLLM acessível a partir do contêiner do Sherpa AI Server. Se o vLLM estiver em outro servidor, use o nome de rede ou o endereço IP dele. 127.0.0.1 dentro do contêiner do Sherpa aponta para o próprio contêiner. Deixe o subcaminho da API vazio.

Antes de selecionar esse modelo para indexação, configure a instância pela API do Sherpa AI Server com a permissão ai_models:update: faça GET /api/v1/models/{model_guid}/instances/{instance_guid}, copie o objeto data.connection_params inteiro, adicione "embed_format": "openai" e envie o objeto completo atualizado por PATCH para o mesmo endereço como {"connection_params": {…}}. Faça GET novamente e confirme que data.connection_params.embed_format é openai. O PATCH substitui todo o objeto de parâmetros; preserve todos os campos existentes de conexão e autenticação.

Essa configuração envia as solicitações do Sherpa para /v1/embeddings. Sem ela, uma instância local usa /v2/embed com um valor de input_type que o BGE-M3 rejeita no vLLM 0.27.1. Depois de configurar a instância, não a salve pelo formulário Modelos: o formulário não mostra embed_format e o remove ao salvar. O teste de conexão do formulário verifica apenas a disponibilidade do servidor; o Sherpa verifica os vetores reais ao salvar as configurações de indexação. Depois, siga as etapas abaixo para selecionar o novo modelo e a dimensão 1024.

Alterar o modelo#

1. Abra Modelos e verifique se o modelo desejado e sua única instância ativa estão disponíveis. Se o modelo não existir e você tiver ai_models:create, clique em Criar na lista de modelos, crie um modelo do tipo Indexação ou Multimodal, clique em Criar na lista de instâncias e adicione uma instância. Caso contrário, procure um administrador.
2. Abra Documentos → Configurações → Indexação. Selecione o Modelo de indexação e informe a Dimensão do embedding real. Alterar apenas o número não altera o modelo.
3. Clique em Salvar uma vez. O servidor verifica o modelo, a dimensão retornada e se o índice de pesquisa está preparado. Após a verificação, ele salva o novo modelo e a dimensão, limpa os vetores antigos e coloca na fila os documentos configurados para indexação automática. Os arquivos originais são preservados. Não é necessário clicar separadamente em Delete all vectors and reindex. Selecionar outro modelo também inicia a alteração quando a dimensão permanece a mesma.
4. Aguarde o processamento dos documentos: Pending → Processing → Ready. Se um arquivo mostrar Awaiting manual indexing, abra-o e clique em Re-index; depois, aguarde Ready. Arquivos com status Not indexed não são indexados. O servidor reindexa automaticamente os exemplos de respostas dos assistentes.
5. Pesquise o conteúdo de um documento conhecido e confirme que os arquivos necessários chegaram a Ready. Se um arquivo mostrar Error, leia e resolva a causa. Depois, clique em Re-index para esse arquivo. Para processar todos os arquivos novamente, use Delete all vectors and reindex separadamente.

Exemplos#

• 384 → 1024. Selecione um novo modelo que retorne vetores de dimensão 1024, informe 1024 e clique em Salvar. Aguarde a reindexação dos arquivos e verifique a pesquisa.
• 1024 → 384. Selecione um modelo que retorne vetores de dimensão 384, informe 384 e siga as mesmas etapas.
• 384 → 384, outro modelo. Selecione outro modelo, mantenha 384 e clique em Salvar. A alteração do modelo inicia a reindexação mesmo que a dimensão não mude.

Se a alteração for rejeitada ou interrompida#

Se a verificação inicial falhar porque o modelo está indisponível, a dimensão está incorreta ou o índice não foi preparado, corrija a causa e salve novamente. Se a alteração for rejeitada por causa de trechos adicionados somente pela API, o modelo, a dimensão e os vetores anteriores serão preservados. Salve o texto e os metadados desses trechos fora do sistema; depois, peça a um administrador para removê-los ou exclua o arquivo que os contém se ele não for mais necessário. Após concluir a alteração do modelo, adicione novamente os trechos salvos pela API se necessário.

Se a transição já começou, mas permanece pendente ou foi interrompida, reabra as configurações e salve o mesmo modelo e a mesma dimensão. O servidor concluirá a limpeza e colocará os arquivos na fila; a indexação em si ocorre em segundo plano. Não selecione outro par de modelo e dimensão enquanto a transição não terminar.

Se você também alterou as configurações de reconhecimento de PDF, o tamanho dos trechos ou a sobreposição entre eles, reabra as configurações após um erro e confira esses campos: eles podem ter sido salvos separadamente. Isso não significa que o modelo e a dimensão tenham sido alterados com sucesso.

Para administradores: outra dimensão#

Para uma dimensão diferente de 384 ou 1024, prepare o índice da conta após as migrações da versão 2.5.1 e antes de salvar o novo modelo. O SQL completo, as verificações e os comandos para a instalação padrão do cliente estão na seção “Dimensões adicionais após a atualização” do guia de preparação de índices. Copie o SQL da página para um arquivo local e informe o ID numérico da conta e a dimensão real do modelo. Depois que o comando terminar com sucesso, o usuário pode clicar em Salvar.