Inizializzazione dei dati cromatici persistenti

import { ChromaClient } from 'chromadb'

Inizializzazione del client

const client = new ChromaClient();

Operazioni comuni del client

await client.reset() // Cancella il database

Lavorare con le collezioni

Chromadb utilizza il concetto di collezione per gestire insiemi di dati vettoriali, che possono essere paragonati alle tabelle in MySQL.

Creazione, Visualizzazione ed Eliminazione delle Collezioni

Chroma utilizza il nome della collezione nell'URL, quindi ci sono alcune restrizioni di denominazione:

  • La lunghezza del nome deve essere compresa tra 3 e 63 caratteri.
  • Il nome deve iniziare e finire con lettere minuscole o numeri e può contenere punti, trattini e trattini bassi in mezzo.
  • Il nome non può contenere due punti consecutivi.
  • Il nome non può essere un indirizzo IP valido.

Per creare una collezione è necessario specificare il nome della collezione e, facoltativamente, una funzione di calcolo vettoriale (nota anche come funzione di embedding). Se viene fornita una funzione di embedding, questa deve essere fornita ogni volta che la collezione viene acceduta.

Nota: La funzione di embedding viene utilizzata per calcolare vettori di testo.

import { ChromaClient } from 'chromadb'

Creare e fare riferimento a una collezione come mostrato di seguito:

let collection = await client.createCollection({name: "m
### Aggiunta di dati a una collezione

Utilizza **`.add`** per aggiungere dati alla collezione di Chroma.

Aggiungi dati direttamente senza specificare i vettori dei documenti:

```jsx
await collection.add({
    ids: ["id1", "id2", "id3", ...],
    metadati: [{"capitolo": "3", "versetto": "16"}, {"capitolo": "3", "versetto": "5"}, {"capitolo": "29", "versetto": "11"}, ...],
    documenti: ["lorem ipsum...", "doc2", "doc3", ...],
})
// Spiegazione dei parametri
// ids - richiesto
// embeddings - opzionale
// metadati - opzionale
// documenti - opzionale

Se Chroma riceve una lista di documenti, utilizzerà automaticamente la funzione di embedding della collezione per calcolare i vettori per i documenti (se non è stata fornita alcuna funzione di embedding durante la creazione della collezione, verrà utilizzato il valore predefinito). Chroma memorizzerà anche i documenti stessi. Se un documento è troppo grande per essere utilizzato con la funzione di embedding selezionata, si verificherà un'eccezione.

Ogni documento deve avere un ID univoco (ids). Aggiungere lo stesso ID due volte porterà a memorizzare solo il valore iniziale. È possibile fornire una lista opzionale di dizionari di metadati (metadati) per ogni documento per memorizzare informazioni aggiuntive per filtrare i dati durante le query.

In alternativa, è possibile fornire direttamente una lista di dati vettoriali correlati ai documenti e Chroma utilizzerà i dati vettoriali forniti senza calcolare automaticamente il vettore.

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], ...],
    metadati: [{"capitolo": "3", "versetto": "16"}, {"capitolo": "3", "versetto": "5"}, {"capitolo": "29", "versetto": "11"}, ...],
    documenti: ["lorem ipsum...", "doc2", "doc3", ...],
})

Se le dimensioni dei dati vettoriali forniti (lunghezza) non corrispondono alle dimensioni della collezione, si verificherà un'eccezione.

È inoltre possibile memorizzare i documenti altrove e semplicemente fornire i dati vettoriali e la lista di metadati a Chroma. È possibile utilizzare gli ID per associare i vettori ai documenti memorizzati altrove.

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], ...],
    metadati: [{"capitolo": "3", "versetto": "16"}, {"capitolo": "3", "versetto": "5"}, {"capitolo": "29", "versetto": "11"}, ...],
})

Nota: La funzione principale del database vettoriale è la ricerca di similarità semantica basata sui dati vettoriali. Per ridurre le dimensioni del database vettoriale e migliorarne l'efficienza, possiamo scegliere di memorizzare i dati vettoriali e alcune condizioni attributive filtrabili nel database vettoriale. Altri dati, come il contenuto degli articoli, possono essere memorizzati in database come MYSQL, purché siano associati tramite gli ID.

Query di dati della collezione

Il metodo .query può essere utilizzato per interrogare il dataset Chroma in modi multipli.

È possibile effettuare query utilizzando un insieme di query_embeddings (dati vettoriali).

Suggerimento: Per ottenere query_embeddings, in scenari di sviluppo effettivi, la query dell'utente viene di solito prima calcolata in un vettore di query attraverso un modello di embedding del testo, e poi questo vettore viene utilizzato per interrogare contenuti simili.

const result = await collection.query({
    queryEmbeddings: [[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
    nResults: 10, // nRisultati
    where: {"campo_metadati": "è_uguale_a_questo"},
})
// ordine input
// query_embeddings - opzionale
// n_results - richiesto
// where - opzionale
// query_texts - opzionale

La query restituirà i primi n_risultati risultati per ogni vettore di query (query_embedding) in ordine. È possibile fornire un dizionario filtro where opzionale per filtrare i risultati in base ai metadati associati a ciascun documento. Inoltre, è possibile fornire un dizionario filtro where_document opzionale per filtrare i risultati in base al contenuto del documento.

Se i query_embeddings forniti non sono consistenti con le dimensioni della collezione, si verificherà un'eccezione. Per garantire la consistenza dei vettori, si consiglia di utilizzare lo stesso modello di embedding del testo per il calcolo dei vettori.

È inoltre possibile effettuare query utilizzando un insieme di testi di query. Chroma calcolerà prima il vettore per ciascun testo di query utilizzando la funzione di embedding della collezione e quindi eseguirà la query utilizzando i vettori di testo generati.

await collection.query({
    nResults: 10, // n_risultati
    where: {"campo_metadati": "è_uguale_a_questo"}, // where
    queryTexts: ["doc10", "così parlò Zarathustra", ...], // query_text
})

È inoltre possibile utilizzare .get per interrogare i dati della collezione per id.

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

.get supporta anche filtri where e where_document. Se non viene fornito alcun id, restituirà tutti i dati nella collezione che corrispondono ai filtri where e where_document.

Specifica dei campi restituiti

Quando si utilizza get o query, è possibile utilizzare il parametro include per specificare i campi dati da restituire, inclusi i dati vettoriali, i documenti e qualsiasi dato nei metadati. Per impostazione predefinita, Chroma restituisce documenti, metadati e distanze vettoriali. È possibile specificare i campi da restituire passando un array di nomi di campi al parametro includes di get o query.

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

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

Utilizzo dei filtri where

Chroma supporta filtri delle query basati sui metadati e sul contenuto del documento. Il filtro where è utilizzato per filtrare i metadati e il filtro where_document è utilizzato per filtrare il contenuto del documento. Di seguito, spieghiamo come scrivere espressioni di condizione del filtro.

Filtraggio per metadati

Per filtrare i metadati, è necessario fornire un dizionario filtro where per la query. Il dizionario deve avere la seguente struttura:

{
    "campo_metadati": {
        <Operatore>: <Valore>
    }
}

Il filtraggio dei metadati supporta i seguenti operatori:

  • $eq - Uguale (stringa, intero, float)
  • $ne - Non uguale (stringa, intero, float)
  • $gt - Maggiore di (int, float)
  • $gte - Maggiore o uguale a (int, float)
  • $lt - Minore di (intero, float)
  • $lte - Minore o uguale a (int, float)

L'utilizzo dell'operatore $eq è equivalente all'utilizzo del filtro where.

{
    "campo_metadati": "stringa_ricerca"
}


{
    "campo_metadati": {
        "$eq": "stringa_ricerca"
    }
}

Filtraggio del contenuto del documento

Per filtrare il contenuto del documento, è necessario fornire un dizionario filtro where_document per la query. Il dizionario deve avere la seguente struttura:

{
    "$contains": "stringa_ricerca"
}

Utilizzo degli operatori logici

È possibile utilizzare anche gli operatori logici $and e $or per combinare più filtri.

L'operatore $and restituirà i risultati che corrispondono a tutti i filtri nell'elenco.

{
    "$and": [
        {
            "campo_metadati": {
                <Operatore>: <Valore>
            }
        },
        {
            "campo_metadati": {
                <Operatore>: <Valore>
            }
        }
    ]
}

L'operatore $or restituirà i risultati che corrispondono a qualsiasi condizione di filtro nell'elenco.

{
    "$or": [
        {
            "campo_metadati": {
                <Operatore>: <Valore>
            }
        },
        {
            "campo_metadati": {
                <Operatore>: <Valore>
            }
        }
    ]
}

Aggiornamento dei dati

Chroma supporta anche l'operazione di upsert, che può aggiornare i dati esistenti e inserire nuovi dati se i dati non esistono.

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]],
    metadati: [{"capitolo": "3", "versetto": "16"}, {"capitolo": "3", "versetto": "5"}, {"capitolo": "29", "versetto": "11"}],
    documenti: ["doc1", "doc2", "doc3"]
})

Cancellazione dei dati

Chroma supporta l'uso di .delete per eliminare i dati dalla raccolta per ID.

await collection.delete({
    ids: ["id1", "id2", "id3",...], //ids
    where: {"capitolo": "20"} //dove
})