Cortex Chat Completions API¶

Die Cortex Chat Completions API ist eine modellunabhängige Obermenge der OpenAI Chat Completions APIund ermöglicht die Kompatibilität mit einem großen Ökosystem von Tools, Bibliotheken und Drittanbieter-AI-Anwendungen.

Die Cortex Chat Completions API ist eine Begleit-API zur Cortex REST API mit erweiterter Unterstützung für OpenAI-Modelle. Weitere Details zur Cortex REST API finden Sie unter Cortex REST API.

Erste Schritte mit dem OpenAI SDK¶

Wichtig

Stellen Sie sicher, dass Sie eine offizielle Version von OpenAI SDK verwenden, wie in der `OpenAI Bibliotheksdokumentation<https://platform.openai.com/docs/libraries>`_ angegeben, z. B. in einer der folgenden Sprachen:

Python
TypeScript/JavaScript

Um zu beginnen, benötigen Sie:

Ihre Snowflake-Konto-URL. Diese wird verwendet, um die Basis-URL für den OpenAI-Client zu erstellen.
Ein programmgesteuertes Snowflake Zugriffstoken (PAT). Dies wird für die Authentifizierung bei den Cortex Chat Completions API verwendet. Weitere Informationen zum Erstellen eines PAT-Objekts finden Sie unter Generierung eines programmatischen Zugriffstokens.
Ein gültiger Modellname, der in der Anforderung verwendet werden soll. Eine Liste der unterstützten Modelle finden Sie unter Verfügbarkeit der Modelle.

Einfache Code-Beispiele¶

Die folgenden Beispiele zeigen, wie Sie Anforderungen an die OpenAI SDKs mit Python, JavaScript/TypeScript und curl stellen.

Verwenden Sie den folgenden Code, um den Einstieg in die Arbeit mit der Python SDK zu erleichtern:

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

response = client.chat.completions.create(
model="<model_name>",
messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {
        "role": "user",
        "content": "How does a snowflake get its unique pattern?"
    }
  ]
)

print(response.choices[0].message)

Copy

Geben Sie im obigen Code Werte für Folgendes an:

base_url: Ersetzen Sie <account-identifier> durch Ihren Snowflake-Kontobezeichner.
api_key: Ersetzen Sie <SNOWFLAKE_PAT> durch Ihren Snowflake PAT (programmgesteuertes Zugriffstoken).
model: Ersetzen Sie <model_name> durch den Namen des Modells, das Sie verwenden möchten. Eine Liste der unterstützten Modelle finden Sie unter Verfügbarkeit der Modelle.

Verwenden Sie den folgenden Code, um den Einstieg in JavaScript/TypeScript SDK zu erleichtern:

import OpenAI from "openai";

const openai = new OpenAI({
  apikey="SNOWFLAKE_PAT",
  baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

const response = await openai.chat.completions.create({
  model: "claude-3-7-sonnet",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    {
        role: "user",
        content: "How does a snowflake get its unique pattern?",
    },
  ],
});

console.log(response.choices[0].message);

Copy

Geben Sie im obigen Code Werte für Folgendes an:

baseURL: Ersetzen Sie <account-identifier> durch Ihren Snowflake-Kontobezeichner.
apikey: Ersetzen Sie SNOWFLAKE_PAT durch Ihren Snowflake Personal Access Token (PAT).
model: Ersetzen Sie <model_name> durch den Namen des Modells, das Sie verwenden möchten. Eine Liste der unterstützten Modelle finden Sie unter Verfügbarkeit der Modelle.

Verwenden Sie den folgenden curl-Befehl, um eine Anfrage an das Snowflake-gehostete Modell zu stellen:

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <SNOWFLAKE_PAT>" \
-d '{
  "model": "<model_name>",
  "messages": [
      {"role": "user", "content": "How does a snowflake get its unique pattern?"}
  ]
}'

Copy

Geben Sie im obigen Code Werte für Folgendes an:

<account-identifier>: Ersetzen Sie <account-identifier> durch Ihren Snowflake-Kontobezeichner.
<SNOWFLAKE_PAT>: Ersetzen Sie <SNOWFLAKE_PAT> durch Ihren Snowflake Personal Access Token (PAT).
<model_name>: Ersetzen Sie <model_name> durch den Namen des Modells, das Sie verwenden möchten. Eine Liste der unterstützten Modelle finden Sie unter Verfügbarkeit der Modelle.

Antworten streamen¶

Sie können Antworten von der REST API durch Einstellen des Parameters stream auf True in der Anforderung streamen.

Der folgende Python-Code streamt eine Antwort von der REST API:

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
)

response = client.chat.completions.create(
  model="<model_name>",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {
        "role": "user",
        "content": "How does a snowflake get its unique pattern?"
    }
  ],
  stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content, end="", flush=True)

Copy

Der folgende JavaScript/TypeScript-Code streamt eine Antwort von der REST API:

import OpenAI from "openai";

const openai = new OpenAI({
    apikey="SNOWFLAKE_PAT",
    baseURL: "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1"
});

const stream = await openai.chat.completions.create({
    model: "<model_name>",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      {
          role: "user",
          content: "How does a snowflake get its unique pattern?",
      }
    ],
    stream:true,
});


for await (const event of stream) {
  console.log(event);
}

Copy

Der folgende curl-Befehl streamt eine Antwort von dem in Snowflake gehosteten Modell:

curl "https://<account-identifier>.snowflakecomputing.com/api/v2/cortex/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SNOWFLAKE_PAT" \
-d '{
  "model": "<model_name>",
  "messages": [
      {"role": "user", "content": "How does a snowflake get its unique pattern?"}
  ],
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}'

Copy

Einschränkungen¶

Im Folgenden finden Sie Einschränkungen bei der Verwendung der OpenAI SDK mit von Snowflake gehosteten Modellen:

Es werden nur Chat Completions unterstützt.
Wenn nicht gesetzt, ist der max_completion_tokens Standardwert 4096. Das theoretische Maximum für die Cortex Chat Completions API ist 131.072. Jedes Modell hat seine eigenen Grenzwerte für Ausgabetoken, die unter 131.072 liegen können.
Der Toolaufruf wird für OpenAI- und Claude-Modelle unterstützt. Ein Beispiel für die effektive Nutzung des Tool-Aufrufs finden Sie unter Tool-Aufruf mit Beispiel einer Gedankenkette.
Audio wird nicht unterstützt.
Bildverstehen wird nur für OpenAI- und Claude-Modelle unterstützt. Pro Konversation begrenzt auf 20 Bilder mit max. Anforderungsgröße von 20 MiB.
Nur Claude-Modelle unterstützen kurzlebige Cache-Kontrollpunkte für das Caching von Eingabeaufforderungen. OpenAI-Modelle unterstützen implizites Caching.
Nur Claude-Modelle unterstützen die Rückgabe des Reasonings in der Antwort.
Fehlermeldungen werden von Snowflake und nicht von OpenAI generiert. Es wird empfohlen, gemeldete Fehler nur zu Protokollierungs- und Debugging-Zwecken zu verwenden.

Detaillierte Kompatibilitätstabelle¶

Die folgenden Tabellen fassen zusammen, welche Felder und Header für Anfragen und Antworten bei Verwendung der Cortex Chat Completions API mit verschiedenen von Snowflake gehosteten Modellen unterstützt werden.

Anforderungsfelder¶
Feld	OpenAI-Modelle	Claude-Modelle	Andere Modelle
`model`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`messages`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`messages[].audio`	❌-Fehler	❌ Ignoriert	❌ Ignoriert
`messages[].role`	✔ unterstützt	✔ Nur Benutzer/Assistent/System	✔ Nur Benutzer/Assistent/System
`messages[].content` (string)	✔ unterstützt	✔ unterstützt	✔ unterstützt
`messages[].content[]` (array)	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`messages[].content[].text`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`messages[].content[].type`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`messages[].content[].image_url`	✔ unterstützt	✔ unterstützt	❌-Fehler
`messages[].content[].cache_control`	❌ Ignoriert	✔ unterstützt (nur ephemere)	❌ Ignoriert
`messages[].content[].file`	❌-Fehler	❌-Fehler	❌ Ignoriert
`messages[].content[].input_audio`	❌-Fehler	❌ Ignoriert	❌ Ignoriert
`messages[].content[].refusal`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`messages[].function_call`	✔ unterstützt (veraltet)	❌ Ignoriert	❌ Ignoriert
`messages[].name`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`messages[].refusal`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`messages[].tool_call_id`	✔ unterstützt	✔ unterstützt	❌ Ignoriert
`messages[].tool_calls`	✔ unterstützt	✔ nur `function`-Tools	❌ Ignoriert
`messages[].reasoning_details`	❌ Ignoriert	✔ OpenRouter-Format `reasoning.text`	❌ Ignoriert
`audio`	❌-Fehler	❌ Ignoriert	❌ Ignoriert
`frequency_penalty`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`logit_bias`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`logprobs`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`max_tokens`	❌ Fehler (veraltet)	❌ Fehler (veraltet)	❌ Fehler (veraltet)
`max_completion_tokens`	✔ unterstützt (Standardeinstellung 4096, max. 131072)	✔ unterstützt (Standardeinstellung 4096, max. 131072)	✔ unterstützt (Standardeinstellung 4096, max. 131072)
`metadata`	❌ Ignoriert	❌ Ignoriert	❌ Ignoriert
`modalities`	❌ Ignoriert	❌ Ignoriert	❌ Ignoriert
`n`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`parallel_tool_calls`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`prediction`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`presence_penalty`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`prompt_cache_key`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`reasoning_effort`	✔ unterstützt	❌ ignoriert (verwenden Sie das `reasoning`-Objekt)	❌ Ignoriert
`reasoning`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`reasoning.effort`	✔ unterstützt (überschreibt `reasoning_effort`)	✔ wird in `reasoning.max_tokens` konvertiert	❌ Ignoriert
`reasoning.max_tokens`	❌ Ignoriert	✔ unterstützt	❌ Ignoriert
`response_format`	✔ unterstützt	✔ Only `json_schema`	❌ Ignoriert
`safety_identifier`	❌ Ignoriert	❌ Ignoriert	❌ Ignoriert
`service_tier`	❌-Fehler	❌-Fehler	❌-Fehler
`stop`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`store`	❌-Fehler	❌-Fehler	❌-Fehler
`stream`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`stream_options`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`stream_options.include_obfuscation`	❌ Ignoriert	❌ Ignoriert	❌ Ignoriert
`stream_options.include_usage`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`temperature`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`tool_choice`	✔ unterstützt	✔ nur `function`-Tools	❌ Ignoriert
`tools`	✔ unterstützt	✔ nur `function`-Tools	❌-Fehler
`top_logprobs`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`top_p`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`verbosity`	✔ unterstützt	❌ Ignoriert	❌ Ignoriert
`web_search_options`	❌-Fehler	❌ Ignoriert	❌ Ignoriert

Antwortfelder¶
Feld	OpenAI-Modelle	Claude-Modelle	Andere Modelle
`id`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`object`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`created`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`model`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`choices`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`choices[].index`	✔ unterstützt	✔ nur einfache Auswahl	✔ nur einfache Auswahl
`choices[].finish_reason`	✔ unterstützt	❌ nicht unterstützt	✔ nur `stop`
`choices[].logprobs`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message` (nicht Streaming)	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`choices[].message.content`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`choices[].message.role`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`choices[].message.refusal`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message.annotations`	❌ nicht unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message.audio`	❌ nicht unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message.function_call`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].message.tool_calls`	✔ unterstützt	✔ nur `function`-Tools	❌ nicht unterstützt
`choices[].message.reasoning`	❌ nicht unterstützt	✔ OpenRouter-Format	❌ nicht unterstützt
`choices[].delta` (Streaming)	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`choices[].delta.content`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`choices[].delta.role`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].delta.refusal`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].delta.function_call`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`choices[].delta.tool_calls`	✔ unterstützt	✔ nur `function`-Tools	❌ nicht unterstützt
`choices[].delta.reasoning`	❌ nicht unterstützt	✔ OpenRouter-Format	❌ nicht unterstützt
`usage`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`usage.prompt_tokens`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`usage.completion_tokens`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`usage.total_tokens`	✔ unterstützt	✔ unterstützt	✔ unterstützt
`usage.prompt_tokens_details`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`usage.prompt_tokens_details.audio_tokens`	❌ nicht unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`usage.prompt_tokens_details.cached_tokens`	✔ Nur Lesecache	✔ Lese- und Schreibcache	❌ nicht unterstützt
`usage.completion_tokens_details`	Siehe Unterfelder	Siehe Unterfelder	Siehe Unterfelder
`usage.completion_tokens_details.accepted_prediction_tokens`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`usage.completion_tokens_details.audio_tokens`	❌ nicht unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`usage.completion_tokens_details.reasoning_tokens`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`usage.completion_tokens_details.rejected_prediction_tokens`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`service_tier`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt
`system_fingerprint`	✔ unterstützt	❌ nicht unterstützt	❌ nicht unterstützt

Header der Anforderung¶
Header	Unterstützung
`Authorization`	✔ erforderlich
`Content-Type`	✔ unterstützt (`application/json`)
`Accept`	✔ unterstützt (`application/json`, `text/event-stream`)

Antwort-Header¶
Header	Unterstützung
`openai-organization`	❌ nicht unterstützt
`openai-version`	❌ nicht unterstützt
`openai-processing-ms`	❌ nicht unterstützt
`x-ratelimit-limit-requests`	❌ nicht unterstützt
`x-ratelimit-limit-tokens`	❌ nicht unterstützt
`x-ratelimit-remaining-requests`	❌ nicht unterstützt
`x-ratelimit-remaining-tokens`	❌ nicht unterstützt
`x-ratelimit-reset-requests`	❌ nicht unterstützt
`x-ratelimit-reset-tokens`	❌ nicht unterstützt
`retry-after`	❌ nicht unterstützt

Mehr erfahren¶

Eine vollständige Sammlung von Anwendungsbeispielen erhalten Sie unter OpenAI Chat Completion API-Referenz oder OpenAI Cookbook.

Zusätzlich zur Kompatibilität mit der Chat Completions API unterstützt Snowflake OpenRouter-kompatible Features für Claude-Modelle. Diese Features werden als zusätzliche Felder auf der Anforderung angezeigt.

Verwenden Sie für das Zwischenspeichern von Eingabeaufforderungen das Feld cache_control. Siehe OpenRouter-Dokumentation zu Caching von Eingabeaufforderungen für weitere Informationen.
Verwenden Sie für Reasoning-Token das Feld reasoning. Siehe OpenRouter-Dokumentation zum Reasoning für weitere Informationen.