Freigeben über

ai_embed_text Plug-In (Vorschau)

  • Artikel

Gilt für: ✅Azure Data Explorer

Das ai_embed_text Plug-In ermöglicht das Einbetten von Text mithilfe von Sprachmodellen, wodurch verschiedene KI-bezogene Szenarien wie Rag-Anwendungen (Retrieval Augmented Generation) und semantische Suche ermöglicht werden. Das Plug-In unterstützt Azure OpenAI Service-Einbettungsmodelle, auf die mit verwalteter Identität zugegriffen wird.

Voraussetzungen

Syntax

evaluateai_embed_text (text, connectionString [ options [, , IncludeErrorMessages]])

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name Type Erforderlich BESCHREIBUNG
text string ✔️ Der einzubettende Text. Der Wert kann ein Spaltenverweis oder ein konstanter Skalar sein.
connectionString string ✔️ Die Verbindungszeichenfolge für das Sprachmodell im Format<ModelDeploymentUri>;<AuthenticationMethod>; ersetzen <ModelDeploymentUri> und <AuthenticationMethod> durch den AI-Modellbereitstellungs-URI bzw. die Authentifizierungsmethode.
Optionen dynamic Die Optionen, die Aufrufe des Einbettungsmodellendpunkts steuern. Weitere Informationen finden Sie unter Optionen.
IncludeErrorMessages bool Gibt an, ob Fehler in einer neuen Spalte in der Ausgabetabelle ausgegeben werden sollen. Standardwert. false.

Optionen

In der folgenden Tabelle werden die Optionen beschrieben, die steuern, wie die Anforderungen an den Einbettungsmodellendpunkt gestellt werden.

Name Typ Beschreibung
RecordsPerRequest int Gibt die Anzahl der Datensätze an, die pro Anforderung verarbeitet werden sollen. Standardwert. 1.
CharsPerRequest int Gibt die maximale Anzahl von Zeichen an, die pro Anforderung verarbeitet werden sollen. Standardwert: 0 (unbegrenzt). Azure OpenAI zählt Token, wobei jedes Token ungefähr in vier Zeichen übersetzt wird.
RetriesOnThrottling int Gibt die Anzahl der Wiederholungsversuche an, wenn die Drosselung auftritt. Standardwert. 0.
GlobalTimeout timespan Gibt die maximale Wartezeit für eine Antwort des Einbettungsmodells an. Standardwert: null
ModelParameters dynamic Parameter, die für das Einbettungsmodell spezifisch sind, z. B. Einbetten von Dimensionen oder Benutzerbezeichnern für Überwachungszwecke. Standardwert. null.
ReturnSuccessfulOnly bool Gibt an, ob nur die erfolgreich verarbeiteten Elemente zurückgegeben werden sollen. Standardwert. false. Wenn der Parameter IncludeErrorMessages auf true festgelegt ist, wird diese Option immer auf false.

Konfigurieren von Richtlinien für verwaltete Identitäten und Beschriftung

Um das ai_embed_text Plug-In zu verwenden, müssen Sie die folgenden Richtlinien konfigurieren:

  • verwaltete Identität: Zulassen, dass die vom System zugewiesene verwaltete Identität bei Azure OpenAI-Diensten authentifiziert wird.
  • Beschriftung: Autorisieren der DOMÄNE des AI-Modellendpunkts.

Verwenden Sie zum Konfigurieren dieser Richtlinien die Befehle in den folgenden Schritten:

  1. Konfigurieren der verwalteten Identität:

    .alter-merge cluster policy managed_identity
```
[
  {
    "ObjectId": "system",
    "AllowedUsages": "AzureAI"
  }
]
```

  2. Konfigurieren sie die Popuprichtlinie:

    .alter-merge cluster policy callout
```
[
    {
        "CalloutType": "azure_openai",
        "CalloutUriRegex": "https://[A-Za-z0-9\\-]{3,63}\\.openai\\.azure\\.com/.*",
        "CanCall": true
    }
]
```

Gibt zurück

Gibt die folgenden neuen Einbettungsspalten zurück:

  • Eine Spalte mit dem Suffix _embedding , die die Einbettungswerte enthält
  • Wenn für die Rückgabe von Fehlern konfiguriert ist, ist eine Spalte mit dem Suffix _embedding_error , die Fehlerzeichenfolgen enthält oder leer bleibt, wenn der Vorgang erfolgreich ist.

Je nach Eingabetyp gibt das Plug-In unterschiedliche Ergebnisse zurück:

  • Spaltenverweis: Gibt einen oder mehrere Datensätze mit zusätzlichen Spalten zurück, die dem Namen der Bezugsspalte vorangestellt sind. Wenn z. B. die Eingabespalte "TextData" heißt, werden die Ausgabespalten TextData_embedding benannt und, wenn die Rückgabe von Fehlern konfiguriert ist, TextData_embedding_error.
  • Konstanter Skalar: Gibt einen einzelnen Datensatz mit zusätzlichen Spalten zurück, die nicht präfixiert sind. Die Spaltennamen sind _embedding und, wenn dies für die Rückgabe von Fehlern konfiguriert ist, _embedding_error.

Beispiele

Im folgenden Beispiel wird der Text Embed this text using AI mithilfe des Azure OpenAI Embedding-Modells eingebettet.

let expression = 'Embed this text using AI';
let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
evaluate ai_embed_text(expression, connectionString)

Im folgenden Beispiel werden mehrere Texte mithilfe des Azure OpenAI Embedding-Modells eingebettet.

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
let options = dynamic({
    "RecordsPerRequest": 10,
    "CharsPerRequest": 10000,
    "RetriesOnThrottling": 1,
    "GlobalTimeout": 2m
});
datatable(TextData: string)
[
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
]
| evaluate ai_embed_text(TextData, connectionString, options , true)

Bewährte Methoden

Azure OpenAI-Einbettungsmodelle unterliegen einer starken Drosselung, und häufige Aufrufe dieses Plug-Ins erreichen schnell Drosselungsgrenzwerte.

Um das ai_embed_text Plug-In effizient zu verwenden und gleichzeitig Drosselung und Kosten zu minimieren, befolgen Sie die folgenden bewährten Methoden:

  • Größe der Steuerelementanforderung: Anpassen der Anzahl von Datensätzen (RecordsPerRequest) und Zeichen pro Anforderung (CharsPerRequest).
  • Timeout für Steuerelementabfragen: Legen Sie GlobalTimeout einen Wert fest, der niedriger als das Abfragetimeout ist, um sicherzustellen, dass der Fortschritt bei erfolgreichen Aufrufen bis zu diesem Punkt nicht verloren geht.
  • Behandeln Sie Geschwindigkeitsbeschränkungen ordnungsgemäßer: Festlegen von Wiederholungsversuchen bei Drosselung (RetriesOnThrottling).

Zugehöriger Inhalt