Lernprogramm: Verwenden eines Ereignishauses als Vektordatenbank mit SLM-Einbettungen

In diesem Lernprogramm erfahren Sie, wie Sie Texteinbettungen generieren und semantische Suche in einem Eventhouse mithilfe der benutzerdefinierten Funktion slm_embeddings_fl() (UDF) durchführen. Im Gegensatz zum ai_embeddings-Plug-In, das einen externen Azure OpenAI-Endpunkt erfordert, slm_embeddings_fl() werden kleine Sprachmodelle (SLMs) lokal in der Kusto-Python-Sandbox ausgeführt. Sie können Daten vollständig in Ihr Eventhouse einbetten und durchsuchen, ohne externe Abhängigkeiten oder Kosten pro Anforderung.

In diesem Szenario wird die semantische Suche über eine Reihe von Beschreibungen von Technologieartikeln veranschaulicht. Sie betten die Artikelbeschreibungen mithilfe eines lokalen SLM ein, speichern die resultierenden Vektoren in einer Eventhouse-Tabelle und führen dann eine Suchabfrage für natürliche Sprachen aus, um die semantisch ähnlichsten Artikel zu finden.

Im Einzelnen werden Sie in diesem Tutorial:

Voraussetzungen

• Ein Arbeitsbereich mit einer Microsoft Fabric-fähigen Kapazität.
• Ein Eventhouse in Ihrem Arbeitsbereich.
• Das Python-Plugin, das in Ihrer Eventhouse-Datenbank mit dem Python-Sandbox-Image 3.11.7 oder 3.11.7 DL aktiviert ist.
• Ein Lakehouse im selben Arbeitsbereich wie Ihr Eventhouse zum Speichern der Artefaktdateien des SLM-Modells.

Vorbereiten der Seehausartefakte

Die slm_embeddings_fl() Funktion verwendet Modellartefaktedateien, die Sie in Ihrem Fabric Lakehouse herunterladen und speichern müssen, bevor Sie in KQL-Abfragen darauf verweisen können.

1. Laden Sie die folgenden Artefaktdateien aus den aufgeführten URLs herunter:

   • [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. Laden Sie die heruntergeladenen Dateien in einen Ordner in Ihrem Seehaus hoch. Laden Sie sie beispielsweise in einen Ordner mit dem Namen models/SLM/ im Abschnitt Dateien Ihres Lakehouses hoch.

3. Notieren Sie sich den OneLake-Pfad für den Ordner. Pfade verwenden das Format: https://onelake.dfs.fabric.microsoft.com/<WorkspaceName>/<LakehouseName>.Lakehouse/Files/models/SLM/

   Verwenden Sie diesen Basispfad, wenn Sie die UDF im nächsten Abschnitt installieren.

Vorbereiten Ihrer Eventhouse-Umgebung

In diesem Schritt erstellen Sie eine Tabelle in Ihrem Eventhouse mit den erforderlichen Spalten und Codierungsrichtlinien, um die eingebetteten Vektordaten zu speichern.

1. Navigieren Sie in Echtzeitsintelligenz zur Homepage Ihres Arbeitsbereichs.

2. Wählen Sie das Eventhouse aus, das Sie in den Voraussetzungen erstellt haben.

3. Wählen Sie die Zieldatenbank aus. Wenn Sie nicht über eine Datenbank verfügen, erstellen Sie eine datenbank, indem Sie "Datenbank hinzufügen" auswählen.

4. Erweitern Sie die Datenbankstruktur, wählen Sie das eingebettete Abfrageset aus, und führen Sie den folgenden KQL-Befehl aus, um eine Tabelle namens "Artikel" zu erstellen:

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

5. Führen Sie den folgenden Befehl aus, um die Vector16 Codierungsrichtlinie für die Vektorspalte festzulegen:

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

Installieren der funktion slm_embeddings_fl()

Installieren Sie die slm_embeddings_fl() UDF als gespeicherte Funktion in Ihrer Datenbank. Ersetzen Sie <OneLakePath> durch den OneLake-Basispfad, den Sie im vorherigen Abschnitt notiert haben. Sie können die Zeilen kommentieren oder löschen, die auf externe Artefakte für Modelle verweisen, die Sie nicht verwenden möchten. (Diese Zeilen befinden sich unten in dieser UDF.) In diesem Lernprogramm verwenden Sie das harrier-v1-270m Modell, sodass Sie nur benötigen embedding_engine.zip und harrier-v1-270m.zip. Installieren Sie die slm_embeddings_fl() UDF als gespeicherte Funktion in Ihrer Datenbank. Ersetzen Sie <OneLakePath> durch den OneLake-Basispfad, den Sie im vorherigen Abschnitt notiert haben. Sie können die Zeilen kommentieren oder löschen, die auf externe Artefakte für Modelle verweisen, die Sie nicht verwenden möchten. (Diese Zeilen befinden sich unten in dieser UDF.) In diesem Lernprogramm verwenden Sie das harrier-v1-270m Modell, sodass Sie nur benötigen embedding_engine.zip und 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'))
}

Weitere Informationen zu den Funktionsparametern und unterstützten Modellen finden Sie unter slm_embeddings_fl().

Einbetten und Aufnehmen von Dokumenten

Nachdem die UDF installiert ist, können Sie sie verwenden, um Einbettungen für Ihre Dokumente zu generieren und in der Artikeltabelle zu speichern.

Führen Sie die folgende KQL-Abfrage aus, um eine Reihe von Beispieltechnologieartikelbeschreibungen einzubetten und in die Tabelle zu schreiben:

.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:')

Generieren einer Einbettung für den Suchbegriff

Nachdem Sie die eingebetteten Artikel in Ihrem Eventhouse gespeichert haben, können Sie eine Suchabfrage für natürliche Sprachen mithilfe desselben Modells einbetten und die ähnlichsten Artikel finden.

Führen Sie die folgende Abfrage aus, um den Suchbegriff einzubetten und seinen Vektor abzurufen:

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

Ähnlichkeit abfragen

Führen Sie die folgende KQL-Abfrage aus, um die Kosinusähnlichkeit zwischen dem Suchbegriff und jedem Artikel in der Artikeltabelle zu berechnen und die wichtigsten Übereinstimmungen zurückzugeben:

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

Die Abfrage gibt die drei Artikel zurück, die ihrem Suchbegriff am semantischsten ähneln und nach Kosinus-Ähnlichkeitsbewertung bewertet werden:

Sie können den Suchbegriff ändern und die Abfrage erneut ausführen, um unterschiedliche Ergebnisse zu untersuchen.

Bereinigen von Ressourcen

Wenn Sie das Lernprogramm abgeschlossen haben, löschen Sie die von Ihnen erstellten Ressourcen, um zusätzliche Kosten zu vermeiden. Um die Ressourcen zu löschen, gehen Sie wie folgt vor:

1. Navigieren Sie zu Ihrer Arbeitsbereichs-Homepage.
2. Löschen Sie die Tabelle "Artikel " aus der Eventhouse-Datenbank, oder löschen Sie die in diesem Lernprogramm verwendete Datenbank oder das Ereignishaus.
3. Entfernen Sie die Modellartefaktedateien aus Ihrem Seehaus, wenn sie nicht mehr benötigt werden.