API Cortex Chat Completions¶

L’API Cortex Chat Completions est un sur-ensemble agnostique de l’API Chat Completions OpenAI, permettant la compatibilité avec un vaste écosystème d’outils, de bibliothèques et de d’applications AI tierces.

L’APICortex Chat Completions est une API complémentaire à l’API REST Cortex avec une prise en charge accrue des modèles OpenAI. Pour en savoir plus sur l’API REST Cortex, voir API REST Cortex.

Premiers pas avec le SDK OpenAI¶

Important

Assurez-vous que vous utilisez une version officielle de SDK OpenAI comme spécifié dans la bibliothèque OpenAI, utilisant notamment l’un des langages suivants :

Python
TypeScript/JavaScript

Pour commencer, vous avez besoin des éléments suivants :

Votre URL de compte Snowflake . Elle sera utilisée pour construire l’URL de base pour le client OpenAI.
Un jeton d’accès programmatique Snowflake (PAT). Il sera utilisé comme authentificateur auprès de l’API Cortex Chat Completions. Pour plus d’informations sur la création d’un PAT, voir Génération d’un jeton d’accès programmatique.
Un nom de modèle valide à utiliser dans la requête. Pour une liste des modèles pris en charge, voir Disponibilité du modèle.

Exemples de code simples¶

Les exemples suivants montrent comment adresser des requêtes aux SDKs OpenAI avec Python, JavaScript/TypeScript et curl.

Utilisez le code suivant pour vous aider à démarrer avec le SDK Python :

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

Dans le code précédent, spécifiez des valeurs pour les éléments suivants :

base_url : Remplacer <account-identifier> avec votre identificateur de compte Snowflake.
api_key : Remplacer <SNOWFLAKE_PAT> avec votre jeton d’accès programmatique Snowflake (PAT).
model : Remplacer <model_name> avec le nom du modèle que vous souhaitez utiliser. Pour une liste des modèles pris en charge, voir Disponibilité du modèle.

Utilisez le code suivant pour vous aider à démarrer avec le SDK JavaScript/TypeScript :

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

Dans le code précédent, spécifiez des valeurs pour les éléments suivants :

baseURL : Remplacer <account-identifier> avec votre identificateur de compte Snowflake.
apikey : Remplacer SNOWFLAKE_PAT avec votre jeton d’accès personnel Snowflake (PAT).
model : Remplacer <model_name> avec le nom du modèle que vous souhaitez utiliser. Pour une liste des modèles pris en charge, voir Disponibilité du modèle.

Utiliser les commandes curl suivantes pour effectuer une requête au modèle hébergé par Snowflake :

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

Dans le code précédent, spécifiez des valeurs pour les éléments suivants :

<account-identifier> : Remplacer <account-identifier> avec votre identificateur de compte Snowflake.
<SNOWFLAKE_PAT> : Remplacer <SNOWFLAKE_PAT> avec votre jeton d’accès personnel Snowflake (PAT).
<model_name> : Remplacer <model_name> avec le nom du modèle que vous souhaitez utiliser. Pour une liste des modèles pris en charge, voir Disponibilité du modèle.

Réponses de flux¶

Vous pouvez diffuser les réponses depuis l’API REST en définissant le paramètre stream sur True dans la requête.

Le code Python suivant diffuse une réponse de l’API REST :

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

Le code JavaScript/TypeScript suivant diffuse une réponse de l’API REST :

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

La commande curl suivante diffuse une réponse du modèle hébergé par Snowflake :

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

Limitations¶

Les limitations suivantes s’appliquent à l’utilisation du SDK OpenAI avec les modèles hébergés par Snowflake :

Seuls les achèvements de chat sont pris en charge.
Si non défini, la valeur max_completion_tokens par défaut est 4 096. Le maximum théorique pour l’API Cortex Chat Completions est 131 072. Chaque modèle a ses propres limites de jetons de sortie qui peuvent être inférieures à 131 072.
L’appel d’outil est pris en charge pour les modèles OpenAI et Claude. Pour un exemple qui utilise efficacement l’appel d’outil, voir Appel d’outils avec exemple de chaîne de pensée.
L’audio n’est pas pris en charge.
La compréhension de l’image est prise en charge pour les modèles OpenAI et Claude uniquement. Les images sont limitées à 20 par conversation avec une taille maximale de requête de 20 MiB.
Seuls les modèles Claude prennent en charge des points de contrôle de cache éphémères pour la mise en cache rapide. Les modèles OpenAI prennent en charge la mise en cache implicite.
Seuls les modèles Claude prennent en charge le renvoi de leurs détails de raisonnement dans la réponse.
Les messages d’erreur sont générés par Snowflake et non par OpenAI. Il est recommandé d’utiliser les erreurs signalées uniquement à des fins de journalisation et de débogage.

Graphique de compatibilité détaillée¶

Les tableaux suivants résument les champs et en-têtes de requête et de réponse pris en charge lors de l’utilisation de l’API Cortex Chat Completions avec différents modèles hébergés par Snowflake.

Champs de demande¶
Champ	Modèles OpenAI	Modèles Claude	Autres modèles
`model`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`messages`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`messages[].audio`	❌ Erreur	❌ Ignoré	❌ Ignoré
`messages[].role`	✔ pris en charge	✔ Uniquement utilisateur/assistant/système	✔ Uniquement utilisateur/assistant/système
`messages[].content` (string)	✔ pris en charge	✔ pris en charge	✔ pris en charge
`messages[].content[]` (tableau)	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`messages[].content[].text`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`messages[].content[].type`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`messages[].content[].image_url`	✔ pris en charge	✔ pris en charge	❌ Erreur
`messages[].content[].cache_control`	❌ Ignoré	✔ Pris en charge (éphémère uniquement)	❌ Ignoré
`messages[].content[].file`	❌ Erreur	❌ Erreur	❌ Ignoré
`messages[].content[].input_audio`	❌ Erreur	❌ Ignoré	❌ Ignoré
`messages[].content[].refusal`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`messages[].function_call`	✔ Pris en charge (obsolète)	❌ Ignoré	❌ Ignoré
`messages[].name`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`messages[].refusal`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`messages[].tool_call_id`	✔ pris en charge	✔ pris en charge	❌ Ignoré
`messages[].tool_calls`	✔ pris en charge	✔ Uniquement outils `function`	❌ Ignoré
`messages[].reasoning_details`	❌ Ignoré	✔ Format OpenRouter `reasoning.text`	❌ Ignoré
`audio`	❌ Erreur	❌ Ignoré	❌ Ignoré
`frequency_penalty`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`logit_bias`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`logprobs`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`max_tokens`	❌ Erreur (obsolète)	❌ Erreur (obsolète)	❌ Erreur (obsolète)
`max_completion_tokens`	✔ Pris en charge (4 096 par défaut, 131 072 max)	✔ Pris en charge (4 096 par défaut, 131 072 max)	✔ Pris en charge (4 096 par défaut, 131 072 max)
`metadata`	❌ Ignoré	❌ Ignoré	❌ Ignoré
`modalities`	❌ Ignoré	❌ Ignoré	❌ Ignoré
`n`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`parallel_tool_calls`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`prediction`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`presence_penalty`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`prompt_cache_key`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`reasoning_effort`	✔ pris en charge	❌ Ignoré (utiliser l’objet `reasoning`)	❌ Ignoré
`reasoning`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`reasoning.effort`	✔ Pris en charge (remplace `reasoning_effort`)	✔ Converti en `reasoning.max_tokens`.	❌ Ignoré
`reasoning.max_tokens`	❌ Ignoré	✔ pris en charge	❌ Ignoré
`response_format`	✔ pris en charge	✔ Only `json_schema`	❌ Ignoré
`safety_identifier`	❌ Ignoré	❌ Ignoré	❌ Ignoré
`service_tier`	❌ Erreur	❌ Erreur	❌ Erreur
`stop`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`store`	❌ Erreur	❌ Erreur	❌ Erreur
`stream`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`stream_options`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`stream_options.include_obfuscation`	❌ Ignoré	❌ Ignoré	❌ Ignoré
`stream_options.include_usage`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`temperature`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`tool_choice`	✔ pris en charge	✔ Uniquement outils `function`	❌ Ignoré
`tools`	✔ pris en charge	✔ Uniquement outils `function`	❌ Erreur
`top_logprobs`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`top_p`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`verbosity`	✔ pris en charge	❌ Ignoré	❌ Ignoré
`web_search_options`	❌ Erreur	❌ Ignoré	❌ Ignoré

Champs de réponse¶
Champ	Modèles OpenAI	Modèles Claude	Autres modèles
`id`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`object`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`created`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`model`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`choices`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`choices[].index`	✔ pris en charge	✔ Choix unique seulement	✔ Choix unique seulement
`choices[].finish_reason`	✔ pris en charge	❌ Non pris en charge	✔ Uniquement `stop`
`choices[].logprobs`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message` (non streaming)	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`choices[].message.content`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`choices[].message.role`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`choices[].message.refusal`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message.annotations`	❌ Non pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message.audio`	❌ Non pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message.function_call`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].message.tool_calls`	✔ pris en charge	✔ Uniquement outils `function`	❌ Non pris en charge
`choices[].message.reasoning`	❌ Non pris en charge	✔ Format OpenRouter	❌ Non pris en charge
`choices[].delta` (streaming)	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`choices[].delta.content`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`choices[].delta.role`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].delta.refusal`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].delta.function_call`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`choices[].delta.tool_calls`	✔ pris en charge	✔ Uniquement outils `function`	❌ Non pris en charge
`choices[].delta.reasoning`	❌ Non pris en charge	✔ Format OpenRouter	❌ Non pris en charge
`usage`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`usage.prompt_tokens`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`usage.completion_tokens`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`usage.total_tokens`	✔ pris en charge	✔ pris en charge	✔ pris en charge
`usage.prompt_tokens_details`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`usage.prompt_tokens_details.audio_tokens`	❌ Non pris en charge	❌ Non pris en charge	❌ Non pris en charge
`usage.prompt_tokens_details.cached_tokens`	✔ Uniquement lectures du cache	✔ Lecture + écriture du cache	❌ Non pris en charge
`usage.completion_tokens_details`	Voir les sous-champs	Voir les sous-champs	Voir les sous-champs
`usage.completion_tokens_details.accepted_prediction_tokens`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`usage.completion_tokens_details.audio_tokens`	❌ Non pris en charge	❌ Non pris en charge	❌ Non pris en charge
`usage.completion_tokens_details.reasoning_tokens`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`usage.completion_tokens_details.rejected_prediction_tokens`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`service_tier`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge
`system_fingerprint`	✔ pris en charge	❌ Non pris en charge	❌ Non pris en charge

En-têtes de requête¶
En-tête	Assistance
`Authorization`	✔ Obligatoire
`Content-Type`	✔ Pris en charge (`application/json`)
`Accept`	✔ Pris en charge (`application/json`, `text/event-stream`)

En-têtes de réponse¶
En-tête	Assistance
`openai-organization`	❌ Non pris en charge
`openai-version`	❌ Non pris en charge
`openai-processing-ms`	❌ Non pris en charge
`x-ratelimit-limit-requests`	❌ Non pris en charge
`x-ratelimit-limit-tokens`	❌ Non pris en charge
`x-ratelimit-remaining-requests`	❌ Non pris en charge
`x-ratelimit-remaining-tokens`	❌ Non pris en charge
`x-ratelimit-reset-requests`	❌ Non pris en charge
`x-ratelimit-reset-tokens`	❌ Non pris en charge
`retry-after`	❌ Non pris en charge

En savoir plus¶

Pour un répertoire complet d’exemples d’utilisation, veuillez consulter la référence API Chat Completions de OpenAI ou le livre de recettes OpenAI.

En plus de fournir une compatibilité avec l’API Chat Completions, Snowflake prend en charge les fonctionnalités compatibles OpenRouter pour les modèles Claude. Ces fonctionnalités sont exposées sous forme de champs supplémentaires dans la requête.

Pour la mise en cache des invites, utilisez le champ cache_control. Pour en savoir plus, consultez la documentation sur la mise en cache des invites OpenRouter.
Pour les jetons de raisonnement, utilisez le champ reasoning. Pour en savoir plus, consultez la documentation sur le raisonnement OpenRouter.