Punti
I punti sono le entità fondamentali manipolate da Qdrant. Un punto è un record composto da un vettore e un payload opzionale.
È possibile cercare punti raggruppati in una collezione in base alla similarità dei vettori. Una descrizione più dettagliata del processo è fornita nella sezione Ricerca e Filtraggio.
Questa sezione introduce come creare e gestire vettori.
Qualsiasi operazione di modifica su un punto è asincrona e divisa in due fasi. Nella prima fase, l'operazione sarà scritta in un log di scrittura anticipata.
In questo momento, anche se la macchina perde alimentazione, il servizio non perderà i dati.
Suggerimento: I punti sono un concetto astratto in Qdrant, li puoi pensare come una riga di dati in una tabella MySQL.
Attesa dei Risultati
Se l'API viene chiamata con il parametro &wait=false, o non è specificato esplicitamente, il client riceverà un messaggio di conferma per la ricezione dei dati:
{
"result": {
"operation_id": 123,
"status": "acknowledged"
},
"status": "ok",
"time": 0.000206061
}
Questa risposta non garantisce il recupero immediato dei dati. Utilizza una forma di consistenza eventuale. Potrebbe richiedere del tempo durante il processo effettivo di aggiornamento della collezione. In realtà, questa richiesta potrebbe alla fine fallire. Se stai inserendo un gran numero di vettori, consigliamo anche di utilizzare richieste asincrone per sfruttare appieno le operazioni di pipeline.
Se la logica della tua applicazione richiede la disponibilità immediata per la ricerca dopo la risposta dell'API, usa il flag ?wait=true. In questo caso, l'API restituirà il risultato solo dopo che l'operazione è completata:
{
"result": {
"operation_id": 0,
"status": "completed"
},
"status": "ok",
"time": 0.000206061
}
ID Punto
Qdrant supporta l'uso di interi non firmati a 64 bit e UUID come identificatori per i punti.
Esempi di rappresentazioni di stringhe UUID sono le seguenti:
- Rappresentazione semplice:
936DA01F9ABD4d9d80C702AF85C822A8 - Rappresentazione con trattini:
550e8400-e29b-41d4-a716-446655440000 - URN:
urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4
Questo significa che in ogni richiesta, le stringhe UUID possono essere usate al posto degli ID numerici. Ad esempio:
PUT /collections/{collection_name}/points
{
"points": [
{
"id": "5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
"payload": {"color": "red"},
"vector": [0.9, 0.1, 0.1]
}
]
}
e
PUT /collections/{collection_name}/points
{
"points": [
{
"id": 1,
"payload": {"color": "red"},
"vector": [0.9, 0.1, 0.1]
}
]
}
sono entrambi validi.
Caricamento dei Punti Dati
Per ottimizzare le prestazioni, Qdrant supporta il caricamento batch dei punti dati. Ciò significa che è possibile caricare più punti dati nel servizio in una singola chiamata API. Il caricamento batch può ridurre significativamente l'overhead della connessione di rete.
L'API di Qdrant supporta due metodi di creazione batch: orientati ai record e orientati alle colonne. Internamente, queste opzioni sono indistinguibili e sono semplicemente per comodità nell'interazione.
Creazione dei punti dati utilizzando l'API REST:
PUT /collections/{nome_collezione}/punti
{
"batch": {
"ids": [1, 2, 3],
"payloads": [
{"colore": "rosso"},
{"colore": "verde"},
{"colore": "blu"}
],
"vettori": [
[0.9, 0.1, 0.1],
[0.1, 0.9, 0.1],
[0.1, 0.1, 0.9]
]
}
}
Oppure utilizzare il metodo equivalente utilizzando l'approccio orientato ai record:
PUT /collections/{nome_collezione}/punti
{
"punti": [
{
"id": 1,
"payload": {"colore": "rosso"},
"vettore": [0.9, 0.1, 0.1]
},
{
"id": 2,
"payload": {"colore": "verde"},
"vettore": [0.1, 0.9, 0.1]
},
{
"id": 3,
"payload": {"colore": "blu"},
"vettore": [0.1, 0.1, 0.9]
}
]
}
Tutte le API in Qdrant, compreso il caricamento dei punti dati, sono idempotenti. Ciò significa che eseguire lo stesso metodo consecutivamente è equivalente a un'esecuzione singola.
In questo scenario, ciò significa che quando si ricaricano i punti dati con lo stesso ID, i punti dati esistenti verranno sovrascritti.
La proprietà idempotente è utile per l'uso di code di messaggi che non forniscono garanzie precise di una sola volta. Anche in questo caso, Qdrant garantisce la coerenza dei dati.
Disponibile dalla versione v0.10.0
Se una collezione in fase di creazione ha più vettori, è possibile fornire dati per ciascun vettore denominandoli:
PUT /collections/{nome_collezione}/punti
{
"punti": [
{
"id": 1,
"vettore": {
"immagine": [0.9, 0.1, 0.1, 0.2],
"testo": [0.4, 0.7, 0.1, 0.8, 0.1, 0.1, 0.9, 0.2]
}
},
{
"id": 2,
"vettore": {
"immagine": [0.2, 0.1, 0.3, 0.9],
"testo": [0.5, 0.2, 0.7, 0.4, 0.7, 0.2, 0.3, 0.9]
}
}
]
}
Disponibile dalla versione v1.2.0
I vettori nominati sono opzionali. Durante il caricamento dei punti dati, alcuni vettori possono essere omessi. Ad esempio, è possibile caricare un punto dati solo con il vettore immagine e un altro solo con il vettore testo.
Nel modificare un punto dati con un ID esistente, il punto dati esistente viene prima eliminato e quindi reinserito con il vettore specificato. In altre parole, l'intero punto dati verrà sostituito e eventuali vettori non specificati verranno impostati su nullo. Se si desidera mantenere invariati i vettori esistenti e aggiornare solo i vettori specificati, fare riferimento all'aggiornamento dei vettori.
Modifica dei Punti Dati
Per modificare un punto dati, è possibile modificare il suo vettore o il suo payload. Esistono diversi metodi per realizzare ciò.
Aggiornamento Vettori
Disponibile dalla versione v1.2.0
Questo metodo aggiorna i vettori specificati ai punti indicati. I vettori non specificati rimarranno invariati. Tutti i punti forniti devono esistere.
API REST (Schema):
PUT /collections/{nome_collezione}/points/vectors
{
"points": [
{
"id": 1,
"vector": {
"image": [0.1, 0.2, 0.3, 0.4]
}
},
{
"id": 2,
"vector": {
"text": [0.9, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2]
}
}
]
}
Per aggiornare punti e sostituire tutti i vettori, fare riferimento all'operazione di caricamento dei punti.
Eliminazione Vettori
Disponibile dalla versione v1.2.0
Questo metodo elimina solo i vettori specificati dai punti indicati. Gli altri vettori rimarranno invariati. I punti non verranno eliminati.
API REST (Schema):
POST /collections/{nome_collezione}/points/vectors/delete
{
"points": [0, 3, 100],
"vectors": ["text", "image"]
}
Imposta Payload
Imposta i valori del payload dati sui punti.
API REST (Schema):
POST /collections/{nome_collezione}/points/payload
{
"payload": {
"proprietà1": "stringa",
"proprietà2": "stringa"
},
"points": [
0, 3, 100
]
}
Non è necessario conoscere l'id del punto da modificare. Un altro modo è utilizzare i filtri.
POST /collections/{nome_collezione}/points/payload
{
"payload": {
"proprietà1": "stringa",
"proprietà2": "stringa"
},
"filter": {
"must": [
{
"key": "colore",
"match": {
"value": "rosso"
}
}
]
}
}
Sovrascrivi Payload
Sostituisci completamente il payload esistente con il payload dato.
API REST (Schema):
PUT /collections/{nome_collezione}/points/payload
{
"payload": {
"proprietà1": "stringa",
"proprietà2": "stringa"
},
"points": [
0, 3, 100
]
}
Similmente a Imposta Payload, non è necessario conoscere l'id del punto da modificare. Un altro modo è utilizzare i filtri.
Elimina Chiavi Payload
API REST (Schema):
POST /collections/{nome_collezione}/points/payload/delete
{
"keys": ["colore", "prezzo"],
"points": [0, 3, 100]
}
In alternativa, è possibile utilizzare i filtri per eliminare le chiavi del payload dai punti.
POST /collections/{nome_collezione}/points/payload/delete
{
"keys": ["colore", "prezzo"],
"filter": {
"must": [
{
"key": "colore",
"match": {
"value": "rosso"
}
}
]
}
}
Cancella Payload
Questo metodo rimuove tutte le chiavi del payload dai punti specificati.
API REST (Schema):
POST /collections/{nome_collezione}/points/payload/clear
{
"points": [0, 3, 100]
}
Eliminare Punti
API REST (Schema):
POST /collections/{collection_name}/points/delete
{
"points": [0, 3, 100]
}
Un altro modo per specificare i punti da eliminare è utilizzando un filtro:
POST /collections/{collection_name}/points/delete
{
"filter": {
"must": [
{
"key": "color",
"match": {
"value": "red"
}
}
]
}
}
Questo esempio elimina tutti i punti con { "color": "red" } dalla collezione.
Recuperare Punti
Metodo per recuperare i punti tramite i loro ID:
API REST (Schema):
POST /collections/{collection_name}/points
{
"ids": [0, 3, 100]
}
Questo metodo ha parametri aggiuntivi with_vectors e with_payload. Utilizzando questi parametri, è possibile selezionare le parti dei risultati dei punti di cui si ha bisogno. L'esclusione aiuta ad evitare il trasferimento di dati inutili.
È inoltre possibile recuperare un singolo punto tramite l'API:
API REST (Schema):
GET /collections/{collection_name}/points/{point_id}
Scorrere
A volte è necessario recuperare tutti i punti memorizzati senza conoscere i loro ID, o scorrere i punti che soddisfano condizioni di filtro.
API REST (Schema):
POST /collections/{collection_name}/points/scroll
{
"filter": {
"must": [
{
"key": "color",
"match": {
"value": "red"
}
}
]
},
"limit": 1,
"with_payload": true,
"with_vector": false
}
Restituisce tutti i punti che corrispondono a color=red:
{
"result": {
"next_page_offset": 1,
"points": [
{
"id": 0,
"payload": {
"color": "red"
}
}
]
},
"status": "ok",
"time": 0.0001
}
L'API Scroll restituirà tutti i punti che corrispondono al filtro in modo paginato.
Tutti i punti risultanti sono ordinati per ID. Per interrogare la pagina successiva, è necessario specificare l'ID massimo trovato nel campo offset. Per comodità, questo ID viene restituito anche nel campo next_page_offset. Se il valore del campo next_page_offset è null, significa che è stata raggiunta l'ultima pagina.
Contare Punti
Disponibile dalla versione v0.8.4
A volte è utile conoscere solo quanti punti corrispondono alle condizioni di filtro senza effettuare effettivamente una ricerca.
Ad esempio, questo può essere utile nei seguenti scenari:
- Stimare le dimensioni del risultato per la ricerca suddivisa
- Determinare il numero di pagine per la paginazione
- Debug dell'esecuzione della query velocità
API REST (Schema):
POST /collections/{collection_name}/points/count
{
"filter": {
"must": [
{
"key": "color",
"match": {
"value": "red"
}
}
]
},
"exact": true
}
Restituisce il conteggio dei punti che corrispondono alle condizioni di filtro date:
{
"count": 3811
}
Aggiornamento batch
Disponibile dalla versione 1.5.0
È possibile eseguire operazioni batch su più punti. Questo include l'inserimento, l'aggiornamento e l'eliminazione di punti, vettori e payload.
Una richiesta di aggiornamento batch consiste in una serie di operazioni eseguite in sequenza. Le operazioni che possono essere incluse in un batch sono:
- Inserire o aggiornare punti:
upsertoUpsertOperation - Eliminare punti:
delete_pointsoDeleteOperation - Aggiornare vettori:
update_vectorsoUpdateVectorsOperation - Eliminare vettori:
delete_vectorsoDeleteVectorsOperation - Impostare il payload:
set_payloadoSetPayloadOperation - Sovrascrivere il payload:
overwrite_payloadoOverwritePayload - Eliminare il payload:
delete_payloadoDeletePayloadOperation - Cancella il payload:
clear_payloadoClearPayloadOperation
Nell'esempio seguente viene utilizzato un frammento di codice che utilizza tutte le operazioni.
API REST (Schema):
POST /collezioni/{nome_collezione}/punti/batch
{
"operazioni": [
{
"upsert": {
"punti": [
{
"id": 1,
"vettore": [1.0, 2.0, 3.0, 4.0],
"payload": {}
}
]
}
},
{
"update_vectors": {
"punti": [
{
"id": 1,
"vettore": [1.0, 2.0, 3.0, 4.0]
}
]
}
},
{
"delete_vectors": {
"punti": [1],
"vettore": [""]
}
},
{
"sovra_scrivi_payload": {
"payload": {
"test_payload": "1"
},
"punti": [1]
}
},
{
"set_payload": {
"payload": {
"test_payload_2": "2",
"test_payload_3": "3"
},
"punti": [1]
}
},
{
"elimina_payload": {
"chiavi": ["test_payload_2"],
"punti": [1]
}
},
{
"cancella_payload": {
"punti": [1]
}
},
{"delete": {"punti": [1]}}
]
}
Per utilizzare i punti in batch con un singolo tipo di operazione, utilizzare direttamente la funzionalità batch all'interno di quell'operazione.