Esercitazione: Usare una eventhouse come database vettoriale con incorporamenti SLM

In questa esercitazione si apprenderà come generare incorporamenti di testo ed eseguire la ricerca semantica in una eventhouse usando la funzione definita dall'utente slm_embeddings_fl(). A differenza del plug-in ai_embeddings, che richiede un Azure endpoint OpenAI esterno, slm_embeddings_fl() esegue modelli di linguaggio piccoli in locale all'interno della sandbox kusto Python. È possibile incorporare e cercare i dati interamente all'interno della casa eventi, senza dipendenze esterne o costi per richiesta.

Questo scenario illustra la ricerca semantica su un set di descrizioni degli articoli tecnologici. Le descrizioni degli articoli vengono incorporate usando uno SLM locale, archiviano i vettori risultanti in una tabella eventhouse e quindi eseguono una query di ricerca in linguaggio naturale per trovare gli articoli più semanticamente simili.

In particolare, in questa esercitazione:

Prerequisiti

• Un spazio di lavoro con una capacità abilitata a Microsoft Fabric.
• Una eventhouse nell'area di lavoro.
• Il plug-in Python abilitato sul database eventhouse con l'immagine sandbox Python 3.11.7 o 3.11.7 DL.
• Un lakehouse nella stessa area di lavoro del tuo eventhouse, per ospitare i file artefatto del modello SLM.

Preparare gli artefatti del lakehouse

La slm_embeddings_fl() funzione usa file di artefatti del modello che è necessario scaricare e archiviare nella Fabric lakehouse prima di poter farvi riferimento nelle query KQL.

1. Scaricare i file di artefatti seguenti dagli URL elencati:

   • [embedding_engine.zip](https://artifactswestus.z22.web.core.windows.net/models/SLM/embedding_engine.zip)
   • [harrier-v1-270m.zip](https://artifactswestus.z22.web.core.windows.net/models/SLM/harrier-v1-270m.zip)
   • [jina-v2-small.zip](https://artifactswestus.z22.web.core.windows.net/models/SLM/jina-v2-small.zip)
   • [e5-small-v2.zip](https://artifactswestus.z22.web.core.windows.net/models/SLM/e5-small-v2.zip)

2. Caricare i file scaricati in una cartella del tuo lakehouse. Ad esempio, caricarli in una cartella denominata models/SLM/ all'interno della sezione File del lakehouse.

3. Annotare il percorso OneLake della cartella. I percorsi usano il formato : https://onelake.dfs.fabric.microsoft.com/<WorkspaceName>/<LakehouseName>.Lakehouse/Files/models/SLM/

   Utilizzare questo percorso di base quando si installa l'UDF nella sezione successiva.

Preparare l'ambiente eventhouse

In questo passaggio si crea una tabella nella casa eventi con le colonne e i criteri di codifica necessari per archiviare i dati vettoriali incorporati.

1. Vai alla home page del tuo spazio di lavoro in Real-Time Intelligence.

2. Selezionare l'eventhouse che hai creato nei prerequisiti.

3. Selezionare il database di destinazione. Se non si dispone di un database, crearne uno selezionando Aggiungi database.

4. Espandere l'albero del database, selezionare il set di query incorporato ed eseguire il comando KQL seguente per creare una tabella denominata Articoli:

   .create table Articles (id:string, article_title:string, description:string, content_vector:dynamic)
   

5. Eseguire il comando seguente per impostare i Vector16 criteri di codifica nella colonna vettoriale:

   .alter column Articles.content_vector policy encoding type='Vector16'
   

Installare la funzione slm_embeddings_fl()

Installa la slm_embeddings_fl() UDF come funzione memorizzata nel tuo database. Sostituire <OneLakePath> con il percorso OneLake di base annotato nella sezione precedente. È possibile commentare o eliminare le righe relative ad artefatti esterni per i modelli che non intendi utilizzare. Queste righe si trovano nella parte inferiore di questo UDF. In questa esercitazione si utilizza il modello harrier-v1-270m, quindi sono necessari solo embedding_engine.zip e harrier-v1-270m.zip. Installa la slm_embeddings_fl() UDF come funzione memorizzata nel tuo database. Sostituire <OneLakePath> con il percorso OneLake di base annotato nella sezione precedente. È possibile commentare o eliminare le righe che si riferiscono ad artefatti esterni per i modelli che non si prevede di utilizzare. (Queste righe si trovano nella parte inferiore di questa UDF.) In questa esercitazione si utilizza il modello harrier-v1-270m, quindi sono necessari solo embedding_engine.zip e harrier-v1-270m.zip.

.create-or-alter function with (folder = "Packages\\AI", docstring = "Embedding using local SLM")
slm_embeddings_fl(tbl:(*), text_col:string, embeddings_col:string, batch_size:int=32, model_name:string='harrier-v1-270m', prefix:string='query:')
{
    let kwargs = bag_pack('text_col', text_col, 'embeddings_col', embeddings_col, 'batch_size', batch_size, 'model_name', model_name, 'prefix', prefix);
    let code = ```if 1:
    from sandbox_utils import Zipackage
    Zipackage.install('embedding_engine.zip')
    from embedding_factory import create_embedding_engine
    text_col = kargs["text_col"]
    embeddings_col = kargs["embeddings_col"]
    batch_size = kargs["batch_size"]
    model_name = kargs["model_name"]
    prefix = kargs["prefix"]
    Zipackage.install(f'{model_name}.zip')
    engine = create_embedding_engine(model_name, cache_dir="C:\\Temp")
    work_dir = os.environ.get("UPLOAD_PATH")
    embeddings = engine.encode(df[text_col].tolist(), batch_size=batch_size, prefix=prefix)    # prefix is used only for E5
    result = df
    result[embeddings_col] = list(embeddings)```;
    tbl
    | evaluate hint.distribution=per_node python(typeof(*), code, kwargs,
        external_artifacts = bag_pack(
            'embedding_engine.zip', '<OneLakePath>embedding_engine.zip;impersonate',
            'harrier-v1-270m.zip', '<OneLakePath>harrier-v1-270m.zip;impersonate',
            'jina-v2-small.zip', '<OneLakePath>jina-v2-small.zip;impersonate',
            'e5-small-v2.zip', '<OneLakePath>e5-small-v2.zip;impersonate'))
}

Per altri dettagli sui parametri della funzione e sui modelli supportati, vedere slm_embeddings_fl().

Incorporare e inserire documenti

Ora che l'UDF è installata, puoi usarla per generare embedding dei tuoi documenti e archiviarli nella tabella Articles.

Eseguire la query KQL seguente per incorporare un set di descrizioni di articoli di tecnologia di esempio e scriverli nella tabella:

.set-or-append Articles <|
datatable(id:string, article_title:string, description:string)
    "1", "Introduction to machine learning", "Machine learning enables computers to learn from data and improve over time without being explicitly programmed.",
    "2", "Getting started with Python", "Python is a versatile, high-level programming language popular for data science, automation, and web development.",
    "3", "Real-time analytics with Eventhouse", "eventhouse provides fast, scalable analytics on large volumes of streaming and historical data using KQL.",
    "4", "Understanding vector embeddings", "Embeddings convert text and other data into dense numerical vector representations that capture semantic meaning.",
    "5", "Neural networks explained", "Neural networks are computational models inspired by the brain, capable of learning complex patterns from large datasets.",
    "6", "Building RAG pipelines", "Retrieval-Augmented Generation combines vector search with language model generation to produce grounded, accurate responses.",
    "7", "Semantic search techniques", "Semantic search goes beyond keyword matching to find results that are conceptually similar to the user's query.",
    "8", "Data ingestion best practices", "Efficient data ingestion requires choosing the right format, batch size, and compression strategy for your workload."
]
| extend content_vector=dynamic(null)
| invoke slm_embeddings_fl('description', 'content_vector', model_name='harrier-v1-270m', prefix='passage:')

Generare un incorporamento per il termine di ricerca

Dopo aver archiviato gli articoli incorporati nella casa eventi, è possibile incorporare una query di ricerca in linguaggio naturale usando lo stesso modello e trovare gli articoli più simili.

Eseguire la query seguente per incorporare il termine di ricerca e recuperarne il vettore:

let searchTerm = "How do I find similar text using vectors?";
print query=searchTerm
let searchTerm = "How do I find similar text using embedding vectors?";
| invoke slm_embeddings_fl('query', 'query_vector', model_name='harrier-v1-270m', prefix='query:')
| project query_vector

Verificare la somiglianza

Eseguire la query KQL seguente per calcolare la somiglianza del coseno tra il termine di ricerca e ogni articolo nella tabella Articoli e restituire le corrispondenze principali:

let searchTerm = "How do I find similar text using vectors?";
let searchVector = toscalar(
    print query=searchTerm
    | extend query_vector=dynamic(null)
    | invoke slm_embeddings_fl('query', 'query_vector', model_name='harrier-v1-270m', prefix='query:')
    | project query_vector
);
Articles
| extend similarity = series_cosine_similarity(searchVector, content_vector, 1.0, 1.0)
| project title, description, similarity
| top 3 by similarity desc
| project article_title, description, similarity

La query restituisce i tre articoli più semanticamente simili al termine di ricerca, classificati in base al punteggio di somiglianza del coseno:

È possibile modificare il termine di ricerca ed eseguire nuovamente la query per esplorare risultati diversi.

Pulire le risorse

Al termine dell'esercitazione, eliminare le risorse create per evitare di incorrere in costi aggiuntivi. Per rimuovere le risorse, seguire questa procedura:

1. Naviga alla home page dell'area di lavoro.
2. Eliminare la tabella Articles dal database eventhouse oppure eliminare il database o la eventhouse usata in questa esercitazione.
3. Rimuovere i file degli artefatti del modello dal tuo lakehouse se non sono più necessari.