Inicializando Dados Cromáticos Persistentes

import { ChromaClient } from 'chromadb'

Inicializando o Cliente

const client = new ChromaClient();

Operações Comuns do Cliente

await client.reset() // Limpar o banco de dados

Trabalhando com Coleções

O Chromadb usa o conceito de coleção para gerenciar conjuntos de dados vetoriais, que podem ser comparados a tabelas no MySQL.

Criando, Visualizando e Deletando Coleções

O Chroma utiliza o nome da coleção na URL, portanto existem algumas restrições de nomenclatura:

  • O comprimento do nome deve estar entre 3 e 63 caracteres.
  • O nome deve começar e terminar com letras minúsculas ou números, e pode conter pontos, hífens e sublinhados no meio.
  • O nome não pode conter dois pontos consecutivos.
  • O nome não pode ser um endereço IP válido.

Para criar uma coleção, o nome da coleção e uma função de cálculo vetorial opcional (também conhecida como função de incorporação) precisam ser especificados. Se uma função de incorporação for fornecida, ela deve ser fornecida sempre que a coleção for acessada.

Nota: A função de incorporação é usada para calcular vetores de texto.

import { ChromaClient } from 'chromadb'

Criar e referenciar uma coleção, conforme mostrado abaixo:

let collection = await client.createCollection({nome: "minha_colecao", embeddingFunction: emb_fn})

let collection2 = await client.getCollection({nome: "minha_colecao", embeddingFunction: emb_fn})

A função de incorporação recebe texto como entrada e retorna dados vetoriais calculados.

Nota: Iniciantes podem aprender sobre modelos de incorporação de texto a partir deste tutorial.

Coleções existentes podem ser referenciadas usando .getCollection por nome e também podem ser excluídas usando .deleteCollection.

const collection = await client.getCollection({nome: "tizi365"}) // Referenciar a coleção tizi365
await client.deleteCollection({nome: "minha_colecao"}) // Excluir a coleção

Funções Comuns da Coleção

await collection.peek() // Retorna os primeiros 10 registros de dados na coleção
await collection.count() // Retorna o número total de registros de dados na coleção

Ajustando Métodos de Cálculo de Distância Vetorial

O createCollection também inclui um parâmetro opcional metadata, onde o valor de hnsw:space pode ser definido para personalizar o método de cálculo de distância para o espaço vetorial.

Nota: Os dados vetoriais representam a semelhança entre vetores calculando a distância espacial entre eles, com distâncias mais próximas indicando maior semelhança e vice-versa.

let collection = client.createCollection("nome_da_colecao", undefined, metadata={ "hnsw:space": "cosseno" })

As opções válidas para hnsw:space são "l2", "ip", ou "cosseno". O padrão é "l2".

Adicionar Dados a uma Coleção

Use .add para adicionar dados à coleção Chroma.

Adicione dados diretamente sem especificar vetores de documentos:

await collection.add({
    ids: ["id1", "id2", "id3", ...],
    metadados: [{"capítulo": "3", "versículo": "16"}, {"capítulo": "3", "versículo": "5"}, {"capítulo": "29", "versículo": "11"}, ...],
    documentos: ["lorem ipsum...", "doc2", "doc3", ...],
})
// Explicação dos Parâmetros
// ids - obrigatório
// embeddings - opcional
// metadados - opcional
// documentos - opcional

Se o Chroma receber uma lista de documentos, ele usará automaticamente a função de incorporação da coleção para calcular vetores para os documentos (se uma função de incorporação não foi fornecida ao criar a coleção, o valor padrão será usado). O Chroma também armazenará os próprios documentos. Se um documento for muito grande para ser usado com a função de incorporação selecionada, ocorrerá uma exceção.

Cada documento deve ter um ID único. Adicionar o mesmo ID duas vezes resultará apenas no armazenamento do valor inicial. Uma lista opcional de dicionários de metadados (metadados) pode ser fornecida para cada documento para armazenar informações adicionais para filtrar dados durante consultas.

Alternativamente, você pode fornecer diretamente uma lista de dados vetoriais relacionados a documentos, e o Chroma usará os dados vetoriais que você fornecer sem calcular automaticamente o vetor.

await collection.add({
    ids: ["id1", "id2", "id3", ...],
    embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...],
    metadados: [{"capítulo": "3", "versículo": "16"}, {"capítulo": "3", "versículo": "5"}, {"capítulo": "29", "versículo": "11"}, ...],
    documentos: ["lorem ipsum...", "doc2", "doc3", ...],
})

Se as dimensões (comprimento) dos dados vetoriais fornecidos não corresponderem às dimensões da coleção, ocorrerá uma exceção.

Você também pode armazenar documentos em outro lugar e simplesmente fornecer os dados vetoriais e a lista de metadados para o Chroma. Você pode usar ids para associar os vetores aos documentos armazenados em outro lugar.

await collection.add({
    ids: ["id1", "id2", "id3", ...],
    embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...],
    metadados: [{"capítulo": "3", "versículo": "16"}, {"capítulo": "3", "versículo": "5"}, {"capítulo": "29", "versículo": "11"}, ...],
})

Observação: A função principal do banco de dados vetoriais é a busca de similaridade semântica com base em dados vetoriais. Para reduzir o tamanho do banco de dados vetoriais e melhorar a eficiência, podemos escolher armazenar dados vetoriais e algumas condições de atributos filtráveis no banco de dados vetoriais. Outros dados, como conteúdo de artigos, podem ser armazenados em bancos de dados como o MYSQL, desde que estejam associados por IDs.

Consulta de Dados da Coleção

O método .query pode ser utilizado para consultar o conjunto de dados do Chroma de várias maneiras.

Você pode fazer uma consulta usando um conjunto de query_embeddings (dados vetoriais).

Dica: Para obter query_embeddings, em cenários de desenvolvimento reais, a consulta do usuário geralmente é primeiro calculada em um vetor de consulta por meio de um modelo de incorporação de texto e, em seguida, esse vetor é usado para consultar conteúdo semelhante.

const resultado = await collection.query({
    queryEmbeddings: [[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
    nResults: 10,
    where: {"campo_metadados": "é_igual_a_isso"},
})
// ordem de entrada
// query_embeddings - opcional
// n_results - obrigatório
// where - opcional
// query_texts - opcional

A consulta irá retornar os top n_resultados resultados para cada vetor de consulta (query_embedding) em ordem. Um dicionário de filtro where opcional pode ser fornecido para filtrar resultados com base nos metadados associados a cada documento. Além disso, um dicionário de filtro where_document opcional pode ser fornecido para filtrar resultados com base no conteúdo do documento.

Se os query_embeddings fornecidos não forem consistentes com as dimensões da coleção, ocorrerá uma exceção. Para garantir a consistência do vetor, é recomendável usar o mesmo modelo de incorporação de texto para calcular vetores.

Você também pode fazer uma consulta usando um conjunto de textos de consulta. O Chroma calculará primeiro o vetor para cada texto de consulta usando a função de incorporação da coleção e, em seguida, executará a consulta usando os vetores de texto gerados.

await collection.query({
    nResults: 10, // n_resultados
    where: {"campo_metadados": "é_igual_a_isso"}, // where
    queryTexts: ["doc10", "assim falou zaratustra", ...], // query_text
})

Você também pode usar .get para consultar dados da coleção por id.

await collection.get({
    ids: ["id1", "id2", "id3", ...], //ids
    where: {"estilo": "estilo1"} // where
})

.get também suporta filtros where e where_document. Se nenhum id for fornecido, ele retornará todos os dados na coleção que correspondem aos filtros where e where_document.

Especificação dos Campos Retornados

Ao usar get ou query, você pode usar o parâmetro include para especificar os campos de dados a serem retornados, incluindo dados vetoriais, documentos e quaisquer dados nos metadados. Por padrão, o Chroma retorna documentos, metadados e distâncias vetoriais. Você pode especificar os campos a serem retornados passando uma matriz de nomes de campo para o parâmetro includes de get ou query.

collection.get(
    include=["documentos"]
)

collection.query(
    query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
    include=["documentos"]
)

Uso de Filtros Where

O Chroma suporta a filtragem de consultas com base em metadados e conteúdo do documento. O filtro where é usado para filtrar os metadados, e o filtro where_document é usado para filtrar o conteúdo do documento. Abaixo, explicamos como escrever expressões de condição de filtro.

Filtragem por Metadados

Para filtrar metadados, um dicionário de filtro where deve ser fornecido para a consulta. O dicionário deve ter a seguinte estrutura:

{
    "campo_metadados": {
        <Operador>: <Valor>
    }
}

A filtragem de metadados suporta os seguintes operadores:

  • $eq - Igual (string, inteiro, float)
  • $ne - Diferente (string, inteiro, float)
  • $gt - Maior que (int, float)
  • $gte - Maior ou igual a (int, float)
  • $lt - Menor que (inteiro, float)
  • $lte - Menor ou igual a (int, float)

Usar o operador $eq é equivalente a usar o filtro where.

{
    "campo_metadados": "string_pesquisada"
}


{
    "campo_metadados": {
        "$eq": "string_pesquisada"
    }
}

Filtragem do Conteúdo do Documento

Para filtrar o conteúdo do documento, um dicionário de filtro where_document deve ser fornecido para a consulta. O dicionário deve ter a seguinte estrutura:

{
    "$contém": "string_pesquisada"
}

Utilizando operadores lógicos

Também é possível utilizar os operadores lógicos $and e $or para combinar múltiplos filtros.

O operador $and irá retornar resultados que correspondam a todos os filtros na lista.

{
    "$and": [
        {
            "campo_metadados": {
                <Operador>: <Valor>
            }
        },
        {
            "campo_metadados": {
                <Operador>: <Valor>
            }
        }
    ]
}

O operador $or irá retornar resultados que correspondam a qualquer condição de filtro na lista.

{
    "$or": [
        {
            "campo_metadados": {
                <Operador>: <Valor>
            }
        },
        {
            "campo_metadados": {
                <Operador>: <Valor>
            }
        }
    ]
}

Atualizando Dados

O Chroma também suporta a operação upsert, que pode atualizar dados existentes e inserir novos dados se os dados não existirem.

await collection.upsert({
    ids: ["id1", "id2", "id3"],
    embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2]],
    metadados: [{"capítulo": "3", "verso": "16"}, {"capítulo": "3", "verso": "5"}, {"capítulo": "29", "verso": "11"}],
    documentos: ["doc1", "doc2", "doc3"]
})

Deletando Dados

O Chroma suporta o uso do .delete para excluir dados da coleção por id.

await collection.delete({
    ids: ["id1", "id2", "id3",...], //ids
    where: {"capítulo": "20"} //onde
})