Manuale di riferimento MALDA™

Il linguaggio di programmazione AI-First - Versione 1.0.11

Indice / 15. VectorDB

15. VectorDB

VectorDB è una classe built-in per memorizzare e cercare vettori ad alta dimensionalità usando la similarità del coseno. È pensata per la similarity search efficiente in applicazioni come la ricerca semantica, i sistemi di raccomandazione e gli embedding del machine learning.

15.1 Creare un VectorDB

Le istanze VectorDB si creano con il costruttore new VectorDB(...):

// Define a vector calculator function
function calculateVector(data) {
    // Your vector calculation logic here
    // Must return an array of numbers matching the dimension
    return [1.0, 2.0, 3.0, /* ... */];
}

// Create a VectorDB with dimension 127 and double precision
var v = new VectorDB(127, "double");

// Or with single precision (more memory efficient)
var v2 = new VectorDB(256, "single");

// Initialize with the calculator function
v.init(calculateVector);
v2.init(calculateVector);

Parametri del costruttore:

Inizializzare la funzione calculator:

Dopo aver creato un VectorDB, devi chiamare init(calculatorFunction) per impostare la funzione calculator che calcolerà i vettori a partire dai dati:

var db = new VectorDB(26, "double");
db.init(calculateVector);  // Set the calculator function

La funzione calculator viene usata da add(data) e searchSimilar(data, topN) per calcolare automaticamente i vettori a partire dai dati.

15.2 Aggiungere vettori

Il metodo add() supporta due modi per aggiungere vettori:

15.2.1 Aggiunta con calcolo automatico del vettore

Se una funzione calculator è impostata tramite init(), puoi aggiungere i dati direttamente e il vettore verrà calcolato in automatico:

var v = new VectorDB(26, "double");
v.init(calculateVector);

// Add data - vector is calculated automatically
v.add("Hello");
v.add("World");
v.add(dict { "type": "string", "value": "Example" });

15.2.2 Aggiunta con vettore esplicito

Puoi anche fornire il vettore in modo esplicito:

var v = new VectorDB(3, "double");

// Add a vector with associated data
v.add([1.0, 2.0, 3.0], "document1");
v.add([4.0, 5.0, 6.0], "document2");
v.add([7.0, 8.0, 9.0], dict { "id": "doc3", "title": "Example" });

Parametri:

15.3 Ricerca per similarità

Usa searchSimilar(data, topN) per trovare i vettori più simili usando la similarità del coseno. La funzione calculator deve essere impostata tramite init():

var v = new VectorDB(128, "double");
v.init(calculateVector);

// Add some vectors
v.add("document1");
v.add("document2");
v.add("document3");

// Search for similar vectors
var results = v.searchSimilar("query text", 5);

// Results is an array of objects with:
// - vector: The original vector array
// - data: The associated data
// - similarity: Cosine similarity score (0.0 to 1.0)
foreach (var result in results) {
    print("Data: " + result.data);
    print("Similarity: " + result.similarity);
}

Come funziona:

15.4 Serializzazione binaria

VectorDB supporta la serializzazione binaria efficiente per la persistenza e i dataset di grandi dimensioni:

var v = new VectorDB(127, "double");
v.init(calculateVector);

// Add vectors...
v.add("data1");
v.add("data2");

// Serialize to binary file
v.serialize("vectordb.bin");

// Later, deserialize (calculator function is NOT stored)
var v2 = v.deserialize("vectordb.bin");

// Re-initialize with the calculator function
v2.init(calculateVector);

Note importanti:

15.5 Esempio completo

// Define a simple vector calculator
function simpleVectorCalc(text) {
    // Simple example: create a vector from text length and first few characters
    var vec = [];
    var len = length(text);
    for (var i = 0; i < 10; i = i + 1) {
        if (i < len) {
            var char = substring(text, i, 1);
            vec.append(charCodeAt(char, 0) / 100.0);
        } else {
            vec.append(0.0);
        }
    }
    return vec;
}

// Create VectorDB
var db = new VectorDB(10, "double");

// Initialize with calculator function
db.init(simpleVectorCalc);

// Add documents - vectors calculated automatically
db.add("Hello world");
db.add("Hello there");
db.add("Goodbye world");

// Search for similar documents
var results = db.searchSimilar("Hello", 2);
print("Top 2 similar documents:");
for (var i = 0; i < results.length; i = i + 1) {
    print("  " + (i + 1) + ". " + results[i].data + " (similarity: " + results[i].similarity + ")");
}

// Serialize for later use
db.serialize("my_vectordb.bin");

// Deserialize later
var db2 = db.deserialize("my_vectordb.bin");

// Re-initialize with calculator function
db2.init(simpleVectorCalc);

15.6 Embedding di testo built-in

MALDA fornisce funzioni built-in di text embedding che si possono usare come funzioni calculator di VectorDB. Queste funzioni calcolano gli embedding al volo da stringhe di testo o da file, senza richiedere reti neurali.

Importante: usare le funzioni di embedding con VectorDB

Quando usi le funzioni built-in di embedding (come embedBagOfWords, embedHash, ecc.) con VectorDB, devi creare una funzione wrapper che fornisce i parametri richiesti (come la dimensione). Questo perché:

Pattern di esempio:

// Create wrapper function with dimension
function myEmbed(text) {
    return embedBagOfWords(text, 100);  // dimension is "baked in"
}

// Use wrapper with VectorDB
var db = new VectorDB(100, "double");
db.init(myEmbed);
db.add("Hello");  // myEmbed is called automatically
var results = db.searchSimilar("world", 5);  // myEmbed is called automatically

Bag-of-Words Embedding

embedBagOfWords(text, dimension?, vocabulary?) crea vettori di frequenza delle parole:

// Create a wrapper function that provides the dimension
function bagOfWordsEmbed(text) {
    return embedBagOfWords(text, 1000);
}

// Use the wrapper function with VectorDB
var db = new VectorDB(1000, "double");
db.init(bagOfWordsEmbed);
db.add("Hello world");
db.add("Hello there");
var results = db.searchSimilar("world", 5);

// With custom vocabulary
var vocab = ["machine", "learning", "artificial", "intelligence"];
function vocabEmbed(text) {
    return embedBagOfWords(text, vocab.length, vocab);
}
var db2 = new VectorDB(vocab.length, "double");
db2.init(vocabEmbed);

Parametri:

Character N-Grams Embedding

embedCharacterNGrams(text, n?, dimension?) crea vettori di frequenza degli n-grammi di caratteri:

// Character trigrams (default n=3)
function ngramEmbed(text) {
    return embedCharacterNGrams(text, 3, 500);
}
var db = new VectorDB(500, "double");
db.init(ngramEmbed);
db.add("Hello");

Parametri:

Hash-based Embedding

embedHash(text, dimension?) crea vettori di feature basati su hash:

// Hash-based embedding (compact, fixed dimension)
// Create a wrapper function that provides the dimension
function hashEmbed(text) {
    return embedHash(text, 128);
}

var db = new VectorDB(128, "double");
db.init(hashEmbed);
db.add("Hello world");
db.add("Hello there");

Parametri:

TF-IDF Embedding

embedTFIDF(text, corpus?, dimension?) crea vettori TF-IDF (Term Frequency-Inverse Document Frequency):

// TF-IDF with corpus for IDF calculation
var corpus = ["file1.txt", "file2.txt", "file3.txt"];
function tfidfEmbed(text) {
    return embedTFIDF(text, corpus, 1000);
}
var db = new VectorDB(1000, "double");
db.init(tfidfEmbed);
db.add("machine learning");

// TF-IDF without corpus (uses only TF)
function tfidfEmbedNoCorpus(text) {
    return embedTFIDF(text, null, 1000);
}
var db2 = new VectorDB(1000, "double");
db2.init(tfidfEmbedNoCorpus);

Parametri:

Embedding da file

embedFromFile(filePath, method, ...) legge un file e ne calcola l'embedding:

// Embed from file using different methods
var vec1 = embedFromFile("document.txt", "bagOfWords", 1000);
var vec2 = embedFromFile("document.txt", "characterNGrams", 3, 500);
var vec3 = embedFromFile("document.txt", "hash", 128);
var vec4 = embedFromFile("document.txt", "tfidf", corpus, 1000);

// Embed multiple files
var filePaths = ["doc1.txt", "doc2.txt", "doc3.txt"];
var embeddings = embedFromFiles(filePaths, "bagOfWords", 1000);
// Returns array of vectors, one per file

Parametri:

Caratteristiche degli embedding

Esempio completo di embedding

// Example: Document search with TF-IDF
var documents = [
    "Machine learning is a subset of AI",
    "Vector databases enable semantic search",
    "Natural language processing uses neural networks"
];

// Create corpus for IDF calculation
var corpus = documents;

function tfidfEmbed(text) {
    return embedTFIDF(text, corpus, 1000);
}

// Create VectorDB with TF-IDF embeddings
var db = new VectorDB(1000, "double");
db.init(tfidfEmbed);

// Add documents - vectors calculated automatically
for (var i = 0; i < documents.length; i = i + 1) {
    db.add(documents[i]);
}

// Search for similar documents
var results = db.searchSimilar("artificial intelligence", 3);
for (var i = 0; i < results.length; i = i + 1) {
    print((i + 1) + ". " + results[i].data + " (similarity: " + formatNumber(results[i].similarity, 4) + ")");
}

15.6.1 Embedding di reti neurali con LLamaSharp

Le funzioni built-in di embedding (bag-of-words, hash, TF-IDF) sono veloci e non richiedono dipendenze esterne, ma gli embedding di reti neurali dai modelli LLM offrono una comprensione semantica superiore. MALDA supporta gli embedding di reti neurali tramite la classe LlamaEmbedder, che usa LLamaSharp per generare embedding da modelli GGUF locali.

Perché usare gli embedding di reti neurali?

Gli embedding di reti neurali offrono diversi vantaggi rispetto agli embedding testuali tradizionali:

Quando usare gli embedding neurali e quando quelli built-in:

Usare LlamaEmbedder con VectorDB

// Load an embedding model (e.g., nomic-embed-text-v1.5, bge-small, etc.)
var embedder = new LlamaEmbedder("path/to/embedding-model.gguf");

// Create a wrapper function for VectorDB
function neuralEmbed(text) {
    return embedder.getEmbeddings(text);
}

// Create VectorDB with dimension matching your model
// Common dimensions: 384 (nomic-embed-text), 768 (bge-small), 1024, 4096
var db = new VectorDB(384, "single");  // Match your model's output dimension
db.init(neuralEmbed);

// Add documents - embeddings calculated using neural network
db.add("Machine learning is transforming industries");
db.add("Artificial intelligence enables new capabilities");
db.add("Neural networks learn from data");

// Semantic search - finds conceptually similar content
var results = db.searchSimilar("AI technology", 3);
// Will find "Artificial intelligence enables new capabilities" even though
// "AI" doesn't appear in the stored text

Usare LlamaEmbedder con GraphMemory

// Initialize embedder
var embedder = new LlamaEmbedder("path/to/embedding-model.gguf");

// Create embedding function
function neuralEmbed(text) {
    return embedder.getEmbeddings(text);
}

// Initialize GraphMemory with custom embedding function
var memory = new GraphMemory();
memory.initialize(384, "single", neuralEmbed);  // 3rd parameter: embedding function

// Store facts - uses neural embeddings for better semantic understanding
memory.remember("I work as a software engineer");
memory.remember("I develop applications using Python");

// Query with semantic understanding
var results = memory.query("What is my profession?", 5);
// Will find both facts because "software engineer" and "develop applications"
// are semantically related to "profession"

Scelta del modello:

Considerazioni sulle prestazioni:

15.7 Retriever (asRetriever)

Le istanze VectorDB possono esporre un retriever per le pipeline RAG orientate ai documenti. Chiama asRetriever(options?) per ottenere un oggetto con i metodi get e getFormatted:

function embedText(text) {
    return embedBagOfWords(text, 16);
}

var vdb = new VectorDB(16, "single");
vdb.init(embedText);

indexInto(vdb, [
    { content: "GraphMemory stores facts.", metadata: { source: "memory.md" } }
]);

var retriever = vdb.asRetriever({ topK: 3, minScore: 0.1 });

// get(query) → array of { content, metadata } documents
var docs = "GraphMemory" |> retriever.get;

// getFormatted(query) → single string for prompt context
var context = question |> retriever.getFormatted;

Opzioni:

Quando i documenti vengono indicizzati con indexInto, i metadata (incluso source) vengono preservati nei risultati di ricerca e inclusi da formatRetrievedDocs.

Combinalo con i prompt e le pipe — vedi Examples/Prompts/rag_pipeline.malda e 7. Espressioni (operatore pipe).

15.8 Casi d'uso

VectorDB è utile per:

15.8.1 Applicazioni reali di VectorDB

I database vettoriali stanno trasformando i settori in tutto il mondo. Ecco 10 applicazioni principali:

  1. Motori di ricerca potenziati

    I database vettoriali abilitano la ricerca semantica, che capisce il vero significato delle query dell'utente, tenendo conto di sinonimi e contesto. Il risultato sono risultati di ricerca più pertinenti e personalizzati.

    Esempio: Spotify usa i database vettoriali per potenziare la funzione di ricerca analizzando le feature audio e le abitudini di ascolto come vettori, raccomandando musica allineata ai tuoi gusti anche quando cerchi con termini descrittivi.

  2. Rilevamento delle frodi

    Le istituzioni finanziarie usano i database vettoriali per analizzare i pattern delle transazioni in tempo reale. Rappresentando le transazioni come vettori con punti dati come importo, località e comportamento dell'utente, possono identificare anomalie e attività sospette.

    Esempio: PayPal usa questi database per prevenire le frodi identificando pattern insoliti che si discostano dal comportamento normale e segnalando azioni sospette dopo aver analizzato grandi volumi di informazioni transazionali legittime passate.

  3. Raccomandazioni di prodotti

    Le piattaforme di e-commerce crescono sulle raccomandazioni personalizzate. I database vettoriali analizzano la cronologia degli acquisti, gli attributi dei prodotti e le recensioni dei clienti come vettori per raccomandare prodotti con alta accuratezza.

    Esempio: Amazon analizza acquisti passati, comportamento di navigazione e recensioni dei prodotti come vettori per suggerire articoli che probabilmente interessano i clienti, mantenendoli coinvolti e aumentando le vendite.

  4. Sistemi di raccomandazione musicale

    L'industria musicale usa i database vettoriali per analizzare feature audio come ritmo, melodia e genere come vettori, consentendo ai servizi di streaming di raccomandare musica che si adatta perfettamente al gusto individuale.

    Esempio: Le funzionalità di music discovery di SoundCloud sono alimentate da database vettoriali, usando le feature audio dei brani che hai ascoltato e i vettori delle preferenze dell'utente per fornire raccomandazioni nella stessa palette sonora.

  5. Computer vision e riconoscimento delle immagini

    I database vettoriali sono la spina dorsale delle applicazioni che analizzano immagini e video. Memorizzando e cercando le feature delle immagini come vettori, abilitano task come il riconoscimento facciale, il rilevamento di oggetti e la moderazione dei contenuti.

    Esempio: Facebook usa i database vettoriali per la funzione di riconoscimento facciale, convertendo i tratti del viso in vettori e confrontandoli con un database di profili utente per suggerire automaticamente i tag delle foto.

  6. Drug discovery

    L'industria farmaceutica usa i database vettoriali per accelerare la drug discovery. Questi database memorizzano e analizzano le strutture molecolari come vettori ad alta dimensionalità, consentendo ai ricercatori di trovare rapidamente potenziali candidati farmacologici.

    Esempio: GlaxoSmithKline (GSK) sfrutta i database vettoriali nei propri sforzi di drug discovery, analizzando le proprietà dei farmaci esistenti e dei potenziali target come vettori per identificare molecole con gli effetti terapeutici desiderati.

  7. Piattaforme di apprendimento personalizzato

    Il settore dell'istruzione usa i database vettoriali per memorizzare i dati di performance degli studenti, gli stili di apprendimento e gli attributi dei contenuti come vettori, abilitando piattaforme di apprendimento personalizzato che raccomandano materiali e si adattano alle esigenze individuali.

    Esempio: Duolingo utilizza i database vettoriali per personalizzare le esperienze di apprendimento linguistico, analizzando i progressi sulle lezioni, i punti di forza e le debolezze come vettori per adattare i percorsi di apprendimento che massimizzano i progressi.

  8. Ricerca genomica

    La ricerca genomica genera dataset enormi. I database vettoriali li analizzano rappresentando i geni e le loro interazioni come vettori, consentendo ai ricercatori di identificare pattern e relazioni che potrebbero sbloccare nuove conoscenze mediche.

    Esempio: Broad Institute sfrutta i database vettoriali per analizzare i dati genetici nella ricerca sul cancro, rappresentando mutazioni geniche e profili dei pazienti come vettori per identificare pattern correlati a tipi specifici di cancro.

  9. Natural Language Processing (NLP)

    I database vettoriali memorizzano e recuperano word embedding, rappresentazioni numeriche che catturano il significato e le connessioni tra le parole, abilitando applicazioni NLP avanzate.

    Esempio: Netflix utilizza i database vettoriali per potenziare il sistema di raccomandazione di serie e film, analizzando descrizioni, informazioni sul cast e abitudini di visione come vettori per raccomandare contenuti allineati alle preferenze.

  10. Cybersecurity

    I database vettoriali sono strumenti cruciali nella lotta alle minacce informatiche. Memorizzando i dati del traffico di rete come vettori, possono analizzarli in tempo reale per rilevare anomalie o intrusioni che altrimenti passerebbero inosservate.

    Esempio: Cloudflare utilizza i database vettoriali per rilevare gli attacchi distributed denial-of-service (DDoS), analizzando i pattern del traffico di rete come vettori per identificare picchi insoliti di traffico che possono indicare un attacco.

15.9 Considerazioni sulle prestazioni

Vedi anche

← Precedente: 14. Grafi Successivo: 16. Supporto database→