Ricerca per significato, non per metadati: Filtraggio semantico di immagini con 4D.Vector

Settembre 8, 2025 9 Tempo di lettura

I vostri utenti non pensano in nomi di file o gerarchie di cartelle. Pensano per idee.

“Un robot dipinto ad acquerello”.
“Una spiaggia assolata piena di colori”.
“Qualcosa che assomiglia a Monna Lisa… ma dal futuro”.

Non importa se l’idea proviene da un’immagine, da un ordine di un cliente, da un’e-mail o da un documento 4D Write Pro, la sfida è la stessa: come si fa a fornire risultati che corrispondano all’intento, non solo alle parole chiave?

Con 4D.Vector e 4D AI Kit, la vostra applicazione può finalmente dare un senso al significato. In questo post, lo illustreremo con la ricerca semantica della somiglianza delle immagini. Ecco la chiave: non stiamo lavorando con immagini grezze, ma con le loro descrizioni. Lo stesso approccio funziona per qualsiasi tipo di dati testuali presenti nelle applicazioni.

DEMO_AI_Vector_ImageSearch

Perché i vettori e l’intelligenza artificiale cambiano tutto

La ricerca tradizionale ha un solo compito: trovare i termini esatti. Ma gli utenti non sanno sempre quale termine esatto usare. Descrivono cose. Esprimono intenzioni. Pensano in un linguaggio umano, bello e disordinato.

Per far funzionare la ricerca nel modo in cui pensano i vostri utenti, non basta la corrispondenza delle stringhe. È necessaria la comprensione, ed è qui che entrano in gioco le incorporazioni vettoriali.

Che cos’è esattamente un embedding?

Un embedding è il modo in cui si trasforma un input disordinato e non strutturato (una frase, una richiesta o un’immagine) in un vettore strutturato di numeri. Non è solo un elenco di token o parole chiave. È un’istantanea matematica del significato.

Quando si invia la frase “un robot dipinto ad acquerello” al modello text-embedding-ada-002 di OpenAI, questo restituisce alcune centinaia di valori in virgola mobile. Ognuno di essi cattura qualcosa: l’argomento, lo stato d’animo, lo stile, le relazioni semantiche che sono state inserite in quella frase. Frasi simili producono vettori simili. Quelle dissimili? Si posizionano più distanti.

Pensate a questo come a un posizionamento del significato su una mappa. Più due frasi sono vicine in questo spazio ad alta densità, più sono simili, indipendentemente dalla formulazione. Questa è la base per costruire ricerche, raccomandazioni, clustering e categorizzazioni basate sul significato.

Un caso d’uso reale: la ricerca di immagini in base al significato

Nella nostra pagina dimostrativa, gli utenti possono effettuare ricerche semantiche. Digitano una richiesta o ne scelgono una da un elenco e l’applicazione restituisce immagini classificate in base alla loro corrispondenza con l’idea.

L’interfaccia utente è volutamente minimale:

Un campo di testo per le richieste personalizzate
Un menu a tendina di suggerimenti predefiniti
Una matrice che mostra le immagini, ordinate in base alla somiglianza con la richiesta.

Ecco la chiave: non stiamo vettorializzando le immagini grezze. Invece, ogni immagine viene analizzata daOpenAIVision di AIKit , che genera una didascalia e una descrizione in linguaggio naturale. Questa descrizione viene incorporata in un 4D.Vector e memorizzata.

In questo modo, tutto viene confrontato a livello di significato, non di pixel.

Nota: questo esempio utilizza 4D Qodly Pro, ma la stessa logica si applica perfettamente anche ai moduli 4D standard. Infatti, tutto il codice viene eseguito all’interno di metodi e funzioni 4D. L’unica differenza è la modalità di visualizzazione dei risultati: in un modulo 4D classico o in una pagina Qodly.

Come si genera il vettore

Quando si digita un prompt e si fa clic su“Usa prompt personalizzato“, 4D esegue la funzione calculate() dalla classe VectorManagement:

exposed shared Function calculate($prompt : Text) : cs.PicturesSelection

Questa funzione inizia con l’acquisizione della chiave API OpenAI dalla memoria (Storage.OpenAI.key), che deve essere inserita nel primo campo di input della scheda Info. Se si è saltato questo campo e si è fatto clic su Usa prompt personalizzato, apparirà una finestra modale che chiederà di inserire la chiave prima di continuare:

If (Storage.OpenAI.key#"")
	$apiKey:=Storage.OpenAI.key
Else 
	$apiModal:=Web Form.setApiKeyModal
	$apiModal.show()
End if

Nota: questo esempio utilizza OpenAI per le operazioni di IA, ma è possibile utilizzare qualsiasi provider compatibile con OpenAI, anche un modello locale con Ollama. Qui usiamo OpenAI perché è semplice da configurare e non richiede un’installazione locale. Se volete seguirci, richiedete una chiave OpenAI qui.

Successivamente, si chiama la funzione generateVector() all’interno della classe AIManagement:

var $vector := cs.AIManagement.new($apiKey).generateVector($prompt)

Cosa succede qui?

Si utilizza il modello text-embedding-ada-002 di OpenAI, ottimizzato per testi brevi, per trasformare il messaggio in un vettore ad alta dimensione. Utilizzando il metodo .create() si invia il prompt e il modello text-embedding-ada-002 come richiesta a OpenAI e si restituisce una struttura JSON contenente il vettore. Il vettore viene poi avvolto in un oggetto 4D.Vector, che ci dà qualcosa da confrontare e ordinare in modo nativo in 4D.

property clientAI : Object

Class constructor($openAIKey : Text)
  This.clientAI := cs.AIKit.OpenAI.new($openAIKey)

Function generateVector($text : Text) : 4D.Vector
  var $model := "text-embedding-ada-002"
  var $result := This.clientAI.embeddings.create($text; $model)
  return $result.vector

A questo punto, si è tradotto il prompt dell’utente in un formato strutturato che 4D può utilizzare per un confronto semantico.

Dal prompt ai risultati classificati

Con il vettore in mano, ora lo si confronta con tutti i vettori di descrizioni di immagini memorizzati nel database:

var $pictureList := This._calculateVectors($vector)

All’interno di _calculateVectors, ecco cosa succede:

For each ($picture; $pictureList)
  $picture.cosineSimilarity := $vector.cosineSimilarity($picture.vector)
  $picture.dotSimilarity := $vector.dotSimilarity($picture.vector)
  $picture.euclideanDistance := $vector.euclideanDistance($picture.vector)
  $picture.save()
End for each

Ogni misura di somiglianza fornisce un obiettivo diverso:

La somiglianza del coseno misura quanto due vettori puntino nella stessa direzione. Ideale per classificare la somiglianza semantica.
Il prodotto dei punti tiene conto sia della direzione che della grandezza. È utile quando si vuole valutare quanto “fortemente” due vettori si allineano.
Ladistanza euclidea è la distanza grezza tra due punti nello spazio. Quanto più piccola è la distanza, tanto più simili sono i due punti.

Se siete alle prime armi con la matematica vettoriale in 4D, il primo post di questa serie spiega come creare e confrontare i vettori con questi metodi e quando usarli.

Una volta che tutti i punteggi di somiglianza sono stati calcolati e memorizzati nelle entità immagine, si ordina la somiglianza in base al coseno e si restituiscono i risultati:

return $pictureList.orderBy("cosineSimilarity desc")

Ciò significa che le immagini concettualmente più rilevanti appaiono per prime, indipendentemente dal nome del file, dalla descrizione o dai metadati.

Cosa succede se l’utente sceglie un prompt predefinito?

Se l’utente sceglie un prompt dall’elenco a discesa e fa clic su Usa prompt selezionato, si salta completamente la fase di incorporamento:

exposed shared Function calculateWithSelectedPrompt($prompt : cs.PromptsEntity) : cs.PicturesSelection
  var $pictureList:=This._calculateVectors($prompt.Vector)
  return $pictureList.orderBy("cosineSimilarity desc")

Non è necessaria alcuna ulteriore chiamata a OpenAI: il vettore del prompt è già salvato nel database. È sufficiente riutilizzare il 4D.Vector memorizzato nella classe di dati Prompts quando il prompt è stato creato per la prima volta.

Proprio come le descrizioni delle immagini, ogni prompt viene vettorizzato una volta e poi memorizzato per essere riutilizzato. Questo permette di:

Nessuna chiamata API → Risultati immediati, nessun ritardo di rete
Nessun costo di token → Più conveniente, soprattutto in scala.
Funziona offline → Tutto viene eseguito localmente, senza dipendere da un servizio esterno.

DAL CARICAMENTO DELL’IMMAGINE ALLA DESCRIZIONE VETTORIALE

Quando qualcuno carica un’immagine, non si incorporano i pixel. Si descrive invece l’immagine con OpenAI Vision e si incorpora la descrizione.

Nella funzione vectorizeImageDescription sono definite due richieste: una per una breve didascalia e una per una descrizione più completa. Entrambi sono realizzati in modo da restituire frasi singole e scorrevoli, ottimizzate per l’incorporamento:

// --- Prompts (single, fluent, embedding-friendly) ---
$captionPrompt:="You are a precise visual captioner. "+\
	"Write one short, clear English sentence (12–20 words) that summarizes the main subject of the image. "+\
	"Keep it straightforward and descriptive, not poetic. Output only the sentence."

$descriptionPrompt:="You are a detailed scene describer. "+\
	"Write a longer English paragraph (80–150 words) that expands on the caption. "+\
	"Include context, secondary elements (icons, arrows, checklists, text, logos), and atmosphere so nothing important is missed. "+\
	"Avoid repeating the caption verbatim. Output only the description."

Utilizzando queste richieste, OpenAI Vision analizza l’immagine. Ciò avviene in due fasi:

.create() istanzia un VisionHelper legato all’immagine caricata.
.prompt() invia un’istruzione in linguaggio naturale insieme all’immagine all’API OpenAI Chat, restituendo una didascalia o una descrizione.

// --- Get caption ---
$caption:=$client.chat.vision.create($imageData).prompt($captionPrompt).choice.message.text
	
// --- Get description ---
$description:=$client.chat.vision.create($imageData).prompt($descriptionPrompt).choice.message.text

A questo punto, si dispone di una didascalia e di una descrizione. Queste vengono salvate insieme all’immagine stessa e, soprattutto, la descrizione viene vettorializzata per la ricerca semantica:

// --- Save entity ---
$pictureEntity:=ds.Pictures.new()
$pictureEntity.picture:=$imageToUpload.picture
$pictureEntity.prompt:=$caption
$pictureEntity.description:=$description
$pictureEntity.vector:=cs.AIManagement.new($apiKey).generateVector($description+$caption)
$status:=$pictureEntity.save()

Cosa si vede nell’interfaccia utente

Una volta effettuato il confronto, la matrice si aggiorna istantaneamente. Le immagini vengono classificate in base al punteggio di somiglianza.

Si cerca: “acquerello di un robot” – e si vedono immagini con texture morbide e forme robotiche:

Si passa a: “una scena di spiaggia vivace e soleggiata con elementi colorati” – e otterrete una serie di risultati completamente diversi, ma ugualmente pertinenti:

Che si tratti di immagini digitate o caricate, si confrontano sempre idee, non pixel o nomi di file.

Cosa ottiene uno sviluppatore

L’uso dei vettori con l’intelligenza artificiale sblocca un valore reale e immediato nelle vostre applicazioni 4D:

Ricerca più intelligente: Gli utenti possono cercare in base al significato, non alle parole chiave. Nessun tag, nessun filtro: solo risultati pertinenti.
Logica nativa: Tutto viene eseguito all’interno di 4D. Non c’è bisogno di motori di ricerca esterni o di strumenti di terze parti.
Modello riutilizzabile: Funziona per immagini, documenti, prodotti, biglietti, qualsiasi cosa si voglia confrontare per concetti.
Basso livello di configurazione, alto impatto: Poche righe di codice per ottenere classifiche, filtri e raccomandazioni basate sull’intelligenza artificiale.
Più economico e più veloce: Incorporare una volta, memorizzare il vettore e riutilizzare per sempre. Nessuna chiamata API ripetuta o costi di token.
Base pronta per l’IA: Non si tratta solo di aggiungere la ricerca, ma di gettare le basi per chatbot, raccomandazioni e flussi di lavoro più intelligenti.

Con 4D.Vector e 4D AI Kit, non c’è bisogno di costruire l’intelligenza, ma di inserirla.

Pensieri finali

Non si tratta di aggiungere l’intelligenza artificiale alla propria applicazione, ma di inserirla nella logica di base.

Con 4D.Vector e 4D AI Kit, la vostra app è in grado di comprendere l’intento, non solo l’input. Di far emergere il significato, non solo le corrispondenze.

Gli strumenti sono pronti. Il codice è leggero. Il valore è reale. Tutto ciò di cui avete bisogno ora… è una richiesta.