Vektoreinbettung mit der REST API¶

Die Cortex REST API ermöglicht Ihnen den Zugriff auf einen Endpunkt für die Ausführung von Vektoreinbettungen mithilfe der Funktion AI_EMBED.

Einrichten der Authentifizierung¶

Um sich bei der Cortex REST API zu authentifizieren, können Sie die unter Authentifizierung von Snowflake REST APIs mit Snowflake beschriebenen Methoden verwenden.

Stellen Sie den Authorization-Header ein, um Ihr Token einzufügen (z. B. ein JSON-Web-Token (JWT), ein OAuth-Token oder ein programmgesteuertes Zugriffstoken).

Tipp

Erwägen Sie die Einrichtung eines eigenen Benutzers für Cortex REST API-Anfragen.

Festlegen der Autorisierung¶

Um eine REST API-Anfrage zu senden, muss Ihrer Standardrolle die Datenbankrolle SNOWFLAKE.CORTEX_USER zugewiesen werden. In den meisten Fällen verfügen die Benutzer bereits über diese Berechtigung, da SNOWFLAKE.CORTEX_USER der Rolle PUBLIC automatisch erteilt wird und alle Rollen PUBLIC erben.

Wenn Ihr Snowflake-Admin diese Berechtigung widerrufen hat, muss sie erneut erteilt werden:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE my_role;
GRANT ROLE my_role TO USER my_user;

Wichtig

REST API-Anfragen verwenden die Standardrolle des Benutzers, sodass diese Rolle über die erforderlichen Berechtigungen verfügen muss. Sie können die Standardrolle eines Benutzenden mit ALTER USER … SET DEFAULT_ROLE ändern.

ALTER USER my_user SET DEFAULT_ROLE=my_role

Endpunktformat¶

Sie können Anfragen an den Endpunkt /api/v2/cortex/inference:embed stellen, um Einbettungen für Ihren Text zu erstellen. Die Anfrage hat die folgende Form:

POST https://<account_identifier>.snowflakecomputing.com/api/v2/cortex/inference:embed

wobei account_identifier der Kontobezeichner ist, den Sie für den Zugriff auf Snowsight verwenden.

Verfügbarkeit der Modelle¶

Die folgende Tabelle zeigt die EMBED-Funktionsmodelle, die Sie über die REST API abfragen können.

EMBED-Funktionsmodelle¶
Modell	AWS US West 2 (Oregon)	AWS US East 1 (N. Virginia)	AWS Europe Central 1 (Frankfurt)	AWS Europe West 1 (Ireland)	AWS AP Southeast 2 (Sydney)	AWS AP Northeast 1 (Tokio)	Azure East US 2 (Virginia)	Azure West Europe (Niederlande)
`snowflake-arctic-embed-m-v1.5`	✔	✔	✔	✔	✔	✔	✔	✔
`snowflake-arctic-embed-m`	✔	✔	✔	✔	✔	✔	✔	✔
`e5-base-v2`	✔	✔	✔			✔	✔	✔
`snowflake-arctic-embed-l-v2.0`	✔	✔	✔	✔	✔	✔	✔	✔

Die folgende Tabelle zeigt die Anzahl der Dimensionen, die jedes Modell zurückgeben kann.

EMBED-Funktionsmodelle¶
Modell	Anzahl von Dimensionen
`snowflake-arctic-embed-m-v1.5`	768
`snowflake-arctic-embed-m`	768
`e5-base-v2`	768
`snowflake-arctic-embed-l-v2.0`	1024

API-Referenz¶

POST /api/v2/cortex/inference:embed¶

Erzeugt eine Einbettung für den von Ihnen angegebenen Text.

Erforderliche Header

Authorization: Bearer token.: Autorisierung für die Anforderung. token ist ein JSON-Web-Token (JWT), ein OAuth-Token oder ein programmgesteuertes Zugriffstoken). Weitere Details dazu finden Sie unter Authentifizierung von Snowflake REST APIs mit Snowflake.
Content-Type: application/json: Gibt an, dass der Body der Anfrage im JSON-Format vorliegt.
Accept: application/json: Gibt an, dass die Antwort JSON enthält.

Optionale Header¶

X-Snowflake-Authorization-Token-Type: type

Definiert die Art des Tokens für die Autorisierung.

Wenn Sie die Kopfzeile X-Snowflake-Authorization-Token-Type weglassen, bestimmt Snowflake den Token-Typ, indem es das Token untersucht.

Auch wenn diese Kopfzeile optional ist, können Sie sie angeben. Sie können die Kopfzeile auf einen der folgenden Werte setzen:

KEYPAIR_JWT (für Schlüsselpaar-Authentifizierung)
OAUTH (für OAuth)
PROGRAMMATIC_ACCESS_TOKEN (für programmatische Zugriffstokens)

Erforderliche JSON-Argumente¶


Argument	Typ	Beschreibung
`text`	Array	Eine Liste von Text-Zeichenfolgen, für die Sie Einbettungen generieren möchten. Die Liste kann bis zu 1280 Zeichenfolgen enthalten, die jeweils bis zu 4096 Zeichen lang sein können.
`model`	string	Das Modell, das Sie für die Erstellung der Einbettungen verwenden.

Statuscodes¶

Die Snowflake Cortex LLM REST API verwendet die folgenden HTTP-Statuscodes, um den erfolgreichen Abschluss oder verschiedene Fehlerzustände anzuzeigen.

200 OK: Anfrage erfolgreich abgeschlossen. Der Body der Antwort enthält die Ausgabe des Modells.
400 invalid options object: Die optionalen Argumente haben ungültige Werte.
400 unknown model model_name: Das angegebene Modell ist nicht vorhanden.
400 schema validation failed: Fehler im Zusammenhang mit der falschen Struktur des Antwortschemas. Korrigieren Sie das Schema und versuchen Sie es erneut.
400 max tokens of count exceeded: Die Anfrage hat die maximale Anzahl der vom Modell unterstützten Token überschritten (siehe Modelleinschränkungen).
400 all requests were throttled by remote service: Die Anfrage wurde aufgrund einer hohen Nutzung gedrosselt. Versuchen Sie es später noch einmal.
402 budget exceeded: Das Budget für den Modellverbrauch wurde überschritten.
403 Not Authorized: Konto nicht für REST API aktiviert, oder die Standardrolle des aufrufenden Benutzers hat nicht die Datenbankrolle snowflake.cortex_user.
429 too many requests: Die Anfrage wurde abgelehnt, weil das Nutzungskontingent überschritten wurde. Bitte versuchen Sie Ihre Anfrage später.
503 embed timed out: Die Anfrage hat zu lange gedauert.

Beispiel einer CURL-Anfrage¶

Das folgende Beispiel verwendet curl, um eine EMBED-Anfrage an das e5-base-v2-Modell zu stellen. Ersetzen Sie token und account_identifier durch die entsprechenden Werte in diesem Befehl.

curl --location "<account_url>/api/v2/cortex/inference:embed" \
--header 'X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer <token>" \
--data '{
"text": ["foo", "bar"],
"model": "e5-base-v2"
}'

Ausgabe¶

Im Folgenden sehen Sie die Ausgabe der Anfrage, wobei der Inhalt des Einbettungsarrays abgeschnitten ist:

{
  "object" : "list",
  "data" : [ {
    "object" : "embedding",
    "embedding" : [ [ -0.02102863, 0.0051381723, -0.0071509206, -0.032512695, 0.056507032, ... ] ],
    "index" : 0
  }, {
    "object" : "embedding",
    "embedding" : [ [ -0.03859099, -0.0025452692, 0.002827513, -0.023107057, 0.039019972, ... ] ],
    "index" : 1
  } ],
  "model" : "e5-base-v2",
  "usage" : {
    "total_tokens" : 6
  }
}

Jede Einbettung hat einen Index, der der Text-Zeichenfolge in einer Liste in der Anfrage entspricht. Der Index ist 0-basiert, d. h. die erste Text-Zeichenfolge in der Liste hat den Index 0, die zweite Text-Zeichenfolge hat den Index 1 usw.

Im vorangegangenen Beispiel entspricht „foo“ dem Index 0 und „bar“ dem Index 1. Die Einbettung für „foo“ ist das erste Element in der Liste der Einbettungen, und die Einbettung für „bar“ ist das zweite Element in der Liste der Einbettungen.

Beispiel einer Python-Anfrage¶

Das folgende Beispiel verwendet die Python API, um eine EMBED-Anfrage an das e5-base-v2-Modell zu stellen. Ersetzen Sie token und account_identifier durch die entsprechenden Werte in diesem Befehl.

from snowflake.core import Root
from snowflake.snowpark.context import get_active_session

def embed_service():
    # Initialize Snowflake session and root
    session = get_active_session()
    root = Root(session)

    # Send embed_request request and process response
    response = root.cortex_embed_service.embed("e5-base-v2", ['foo', 'bar'])
    print(response)

if __name__ == "__main__":
    embed_service()

Ausgabe¶

Im Folgenden sehen Sie die Ausgabe der Anfrage, wobei der Inhalt des Einbettungsarrays abgeschnitten ist:

{
  "object" : "list",
  "data" : [ {
    "object" : "embedding",
    "embedding" : [ [ -0.02102863, 0.0051381723, -0.0071509206, -0.032512695, 0.056507032, ... ] ],
    "index" : 0
  }, {
    "object" : "embedding",
    "embedding" : [ [ -0.03859099, -0.0025452692, 0.002827513, -0.023107057, 0.039019972, ... ] ],
    "index" : 1
  } ],
  "model" : "e5-base-v2",
  "usage" : {
    "total_tokens" : 6
  }
}

Nutzungskontingente¶

Die folgende Tabelle zeigt die Nutzungsquoten für die Funktion EMBED.

EMBED-Funktionsquoten¶
Modell	Verarbeitete Token pro Minute (TPM)	Anfragen pro Minute (RPM)	Maximale Ausgabe (Token)
`snowflake-arctic-embed-m-v1.5`	400,000	200	4,096
`snowflake-arctic-embed-m`	400,000	200	4,096
`e5-base-v2`	400,000	200	4,096
`nv-embed-qa-4`	400,000	200	4,096
`multilingual-e5-large`	400,000	200	4,096
`voyage-multilingual-2`	400,000	200	4,096