Coleções

O conceito de coleções no banco de dados de vetores Qdrant pode ser análogo à estrutura de tabelas no MYSQL, usada para armazenar uniformemente o mesmo tipo de dados vetoriais. Cada dado armazenado em uma coleção é referido como um ponto no Qdrant. Aqui, um ponto é semelhante ao conceito matemático de espaço geométrico, representando a representação de um vetor no espaço geométrico (apenas considere-o como um dado).

Na mesma coleção, o vetor de cada ponto deve ter as mesmas dimensões e ser comparado usando uma única métrica. Vetores nomeados podem ser usados para incluir múltiplos vetores em um único ponto, sendo que cada vetor tem suas próprias dimensões e requisitos de métrica.

Métricas de distância são usadas para medir a similaridade entre vetores. A escolha da métrica depende de como os vetores são obtidos, principalmente do método usado para treinar os codificadores de redes neurais.

O Qdrant suporta os seguintes tipos populares de métricas:

  • Produto ponto: Dot
  • Similaridade de cosseno: Cosine
  • Distância euclidiana: Euclid

Para melhorar a eficiência da pesquisa, a similaridade de cosseno é alcançada através do produto ponto de vetores normalizados. Ao serem carregados, os vetores são automaticamente normalizados. Além das métricas e tamanhos de vetor, cada coleção também usa seu próprio conjunto de parâmetros para controlar a otimização da coleção, a construção de índices e a limpeza. Essas configurações podem ser alteradas a qualquer momento por meio das solicitações correspondentes.

Configurando Multi-Inquilinato

Quantas coleções devem ser criadas? Na maioria dos casos, você só precisa usar uma única coleção com particionamento baseado em carga. Esse método é conhecido como multi-inquilinato. Para a maioria dos usuários, isso é eficiente, mas requer configurações adicionais. Aprenda a configurar o multi-inquilinato.

Quando devem ser criadas múltiplas coleções? Quando você tem um número limitado de usuários e requer isolamento. Essa abordagem é mais flexível, mas pode ser mais cara, pois a criação de um grande número de coleções pode levar a sobrecarga de recursos. Além disso, você precisa garantir que elas não interfiram umas com as outras de forma alguma, inclusive em termos de desempenho.

Criando uma coleção

PUT /coleções/{nome_da_coleção}

{
    "vetores": {
      "tamanho": 300,
      "distância": "Cosseno"
    }
}

Além das opções obrigatórias, valores personalizados também podem ser especificados para as seguintes opções de coleção:

  • hnsw_config - Para detalhes do índice, consulte a seção de índices.
  • wal_config - Configuração relacionada ao log de gravação antecipada. Para informações mais detalhadas sobre o LGA, consulte-o.
  • optimizers_config - Para detalhes do otimizador, consulte a seção de otimizadores.
  • shard_number - Define quantos fragmentos a coleção deve ter. Para mais informações, consulte a seção de implantação distribuída.
  • on_disk_payload - Define a localização para armazenar dados da carga. Se definido como true, ele armazenará apenas a carga no disco. Isso pode ser muito útil para limitar o uso de RAM ao lidar com cargas grandes.
  • quantization_config - Para informações detalhadas sobre quantização, consulte quantização.

Os parâmetros padrão para parâmetros opcionais da coleção são definidos no arquivo de configuração.

Para mais informações sobre parâmetros de coleção e vetor, consulte a definição do esquema e o arquivo de configuração.

Disponível a partir da v1.2.0

Os vetores são armazenados na RAM para obter acesso muito rápido. O parâmetro on_disk pode ser definido na configuração do vetor. Se definido como verdadeiro, todos os vetores serão armazenados no disco. Isso permitirá o uso de mapeamento de memória, adequado para a importação de grandes quantidades de dados.

Criando uma coleção a partir de outra coleção

Disponível a partir da v1.0.0

Uma coleção pode ser inicializada a partir de outra coleção existente.

Isso pode ser útil para experimentar rapidamente diferentes configurações do mesmo conjunto de dados.

Ao definir a configuração do vetor na nova coleção, certifique-se de que os vetores tenham o mesmo tamanho e função de distância que na coleção original.

PUT /coleções/{nome_da_coleção}

{
    "vetores": {
      "tamanho": 300,
      "distância": "Cosseno"
    },
    "init_from": {
       "coleção": {nome_da_coleção_origem}
    }
}

Coleção de múltiplos vetores

Disponível a partir da v0.10.0

Cada registro pode ter múltiplos vetores. Essa funcionalidade permite armazenar múltiplos vetores em uma coleção. Para distinguir os vetores dentro de um registro, defina seus nomes únicos ao criar a coleção. Cada vetor nomeado sob este esquema possui sua própria distância e tamanho:

PUT /collections/{nome_da_colecao}

{
    "vetores": {
        "imagem": {
            "tamanho": 4,
            "distancia": "Ponto"
        },
        "texto": {
            "tamanho": 8,
            "distancia": "Cosseno"
        }
    }
}

Em alguns casos especiais, uma coleção sem armazenamento de vetores também pode ser criada.

Disponível a partir da v1.1.1

Para cada vetor nomeado, você pode opcionalmente especificar hnsw_config ou quantization_config para se desviar da configuração da coleção. Isso pode ser usado para otimizar o desempenho da pesquisa no nível do vetor.

Disponível a partir da v1.2.0

Os vetores são armazenados na memória para acesso rápido. Para cada vetor, on_disk pode ser definido como true para sempre armazenar todos os vetores no disco. Isso habilitará o mapeamento de memória, adequado para a ingestão de grandes quantidades de dados.

Excluindo uma coleção

DELETE /collections/{nome_da_colecao}

Atualizar parâmetros da coleção

Atualizações dinâmicas de parâmetros podem ser úteis, como um carregamento inicial mais eficiente de vetores. Por exemplo, é possível desativar a indexação durante o upload e ativá-la imediatamente após a conclusão do upload. Dessa forma, você não desperdiçará recursos computacionais extras para reconstruir o índice.

O comando a seguir ativa a indexação para um segmento contendo vetores maiores que 10000 kB:

PATCH /collections/{nome_da_colecao}

{
    "optimizers_config": {
        "indexing_threshold": 10000
    }
}

Os seguintes parâmetros podem ser atualizados:

  • optimizers_config - Consulte descrições detalhadas dos otimizadores.
  • hnsw_config - Consulte descrições detalhadas do índice.
  • quantization_config - Consulte descrições detalhadas da quantização.
  • vetores - Configuração para vetores específicos, incluindo suas respectivas configurações hnsw_config, quantization_config e on_disk.
  • params - Outros parâmetros da coleção, incluindo write_consistency_factor e on_disk_payload.

A especificação completa da API está localizada nas definições de esquema.

Disponível desde a v1.4.0

O Qdrant 1.4 adiciona suporte para atualizar mais parâmetros da coleção em tempo de execução. O índice HNSW, quantização e configuração de disco agora podem ser alterados sem recriar a coleção. Os segmentos (com dados de índice e quantização) serão reconstruídos automaticamente em segundo plano para corresponder aos parâmetros atualizados.

No exemplo a seguir, a coleção inteira e os parâmetros de índice HNSW e quantização para my_vector são atualizados:

PATCH /collections/{nome_da_colecao}

{
    "vetores": {
        "meu_vetor": {
            "hnsw_config": {
                "m": 32,
                "ef_construct": 123
            },
            "quantization_config": {
                "produto": {
                    "compressao": "x32",
                    "sempre_ram": true
                }
            },
            "on_disk": true
        }
    },
    "hnsw_config": {
        "ef_construct": 123
    },
    "quantization_config": {
        "escalar": {
            "tipo": "int8",
            "quantil": 0.8,
            "sempre_ram": false
        }
    }
}

Nota: Para atualizar os parâmetros do vetor em uma coleção sem vetores nomeados, um nome vazio ("") pode ser usado.

As chamadas para este endpoint podem bloquear enquanto aguardam a conclusão dos otimizadores existentes. Não recomendamos usar esse recurso em um banco de dados de produção, pois reconstruir o índice pode introduzir um grande overhead.

Informação da Coleção

O Qdrant permite a determinação dos parâmetros de configuração para uma coleção existente, de forma a compreender melhor a distribuição de pontos e a situação da indexação.

GET /collections/{nome_da_colecao}

{
    "result": {
        "status": "green",
        "optimizer_status": "ok",
        "vectors_count": 1068786,
        "indexed_vectors_count": 1024232,
        "points_count": 1068786,
        "segments_count": 31,
        "config": {
            "params": {
                "vectors": {
                    "size": 384,
                    "distance": "Cosseno"
                },
                "shard_number": 1,
                "replication_factor": 1,
                "write_consistency_factor": 1,
                "on_disk_payload": false
            },
            "hnsw_config": {
                "m": 16,
                "ef_construct": 100,
                "full_scan_threshold": 10000,
                "max_indexing_threads": 0
            },
            "optimizer_config": {
                "deleted_threshold": 0.2,
                "vacuum_min_vector_number": 1000,
                "default_segment_number": 0,
                "max_segment_size": null,
                "memmap_threshold": null,
                "indexing_threshold": 20000,
                "flush_interval_sec": 5,
                "max_optimization_threads": 1
            },
            "wal_config": {
                "wal_capacity_mb": 32,
                "wal_segments_ahead": 0
            }
        },
        "payload_schema": {}
    },
    "status": "ok",
    "time": 0.00010143
}

Se vetores forem inseridos na coleção, o campo status pode mudar para "yellow" durante a otimização e voltar para "green" assim que todos os pontos forem processados com sucesso.

Os seguintes estados de cor podem ser encontrados:

  • ? green: Coleção está pronta
  • ? yellow: Coleção está passando por otimização
  • ? red: O mecanismo encontrou um erro irreparável

Algumas outras propriedades de interesse incluem:

  • points_count - Número total de objetos (vetores e suas cargas) armazenados na coleção
  • vectors_count - Número total de vetores na coleção. Se cada objeto tiver vários vetores, isso pode não ser igual a points_count.
  • indexed_vectors_count - Número total de vetores armazenados no índice HNSW. O Qdrant não armazena todos os vetores no índice, apenas aqueles que podem criar segmentos de índice com base na configuração fornecida.

Indexação de Vetores em HNSW

Em alguns casos, você pode encontrar que o valor de indexed_vectors_count é menor que vectors_count. Este é um comportamento intencional dependendo da configuração do otimizador. Um novo segmento de índice será criado se o tamanho dos vetores não indexados exceder o indexing_threshold (em KB). Se a sua coleção é muito pequena ou a dimensão do vetor é baixa, os segmentos HNSW podem não ser criados, e indexed_vectors_count pode ser igual a 0.

Você pode reduzir o valor de indexing_threshold nos parâmetros da coleção para criar um novo segmento de índice na coleção existente.

Aliases da Coleção

Em um ambiente de produção, pode haver a necessidade de alternar facilmente entre diferentes versões de vetores, como a atualização para uma nova versão de redes neurais.

Nesses casos, pode não ser viável interromper o serviço e reconstruir a coleção usando os novos vetores. Um alias é um nome adicional para uma coleção existente. A consulta pode ser totalmente executada usando o alias em vez do nome da coleção.

Assim, uma segunda coleção pode ser construída em segundo plano, e então o alias pode ser trocado da coleção antiga para a nova coleção. Como as mudanças de alias são atômicas, as solicitações simultâneas não são afetadas durante o processo de troca.

Criar Alias

POST /collections/aliases

{
    "actions": [
        {
            "create_alias": {
                "alias_name": "production_collection",
                "collection_name": "example_collection"
            }
        }
    ]
}

Excluir Alias

POST /collections/aliases

{
    "actions": [
        {
            "delete_alias": {
                "alias_name": "production_collection"
            }
        }
    ]
}

Trocar Coleção

Múltiplas operações de alias podem ser executadas atomicamente. Por exemplo, você pode usar o seguinte comando para trocar a coleção subjacente:

POST /collections/aliases

{
    "actions": [
        {
            "delete_alias": {
                "alias_name": "production_collection"
            }
        },
        {
            "create_alias": {
                "alias_name": "production_collection",
                "collection_name": "new_collection"
            }
        }
    ]
}

Lista de Sinônimos da Coleção

GET /coleções/{nome_da_coleção}/sinônimos

Listar Todos os Sinônimos

GET /sinônimos

Listar Todas as Coleções

GET /coleções