Cortex Chat Completions API¶

Cortex Chat Completions API 是 OpenAI Chat Completions API 中与模型无关的超级集合，可与庞大的工具、库和第三方 AI 应用程序生态系统兼容。

Cortex Chat Completions API 是 Cortex REST API 的配套 API，增加了对 OpenAI 模型的支持。要了解有关 Cortex REST API 的更多信息，请参阅 Cortex REST API。

OpenAI SDK 入门¶

重要

确保使用 ` OpenAI 库文档 <https://platform.openai.com/docs/libraries (https://platform.openai.com/docs/libraries)>`_ 中指定的 OpenAI SDK 正式版本，例如以下语言之一：

Python
TypeScript/JavaScript

要开始使用，您需要：

您的 Snowflake 账户 URL。这将用于为 OpenAI 客户端构建基础 URL。
Snowflake 编程访问令牌 (PAT)。这将用于对 Cortex Chat Completions API 进行身份验证。有关创建 PAT 的更多信息，请参阅生成编程访问令牌。
在请求中使用的有效模型名称。有关支持的模型列表，请参阅模型可用性。

简单代码示例¶

以下示例显示如何使用 Python、JavaScript/TypeScript 和 curl 向 OpenAI SDKs 发出请求。

使用以下代码帮助您入门 Python SDK：

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.cn/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

在前面的代码中，为以下内容指定值：

base_url：选择使用时默认使用的角色和仓库。将 <account-identifier> 替换为您的 Snowflake 账户标识符。
api_key：选择使用时默认使用的角色和仓库。将 <SNOWFLAKE_PAT> 替换为您的 Snowflake 编程访问令牌 (PAT)。
model：选择使用时默认使用的角色和仓库。将 <model_name> 替换为要使用的模型的名称。有关支持的模型列表，请参阅模型可用性。

使用以下代码来帮助您开始使用 JavaScript/TypeScript SDK:

import OpenAI from "openai";

const openai = new OpenAI({
  apikey="SNOWFLAKE_PAT",
  baseURL: "https://<account-identifier>.snowflakecomputing.cn/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

在前面的代码中，为以下内容指定值：

baseURL：选择使用时默认使用的角色和仓库。将 <account-identifier> 替换为您的 Snowflake 账户标识符。
apikey：选择使用时默认使用的角色和仓库。将 SNOWFLAKE_PAT 替换为您的 Snowflake 个人访问令牌 (PAT)。
model：选择使用时默认使用的角色和仓库。将 <model_name> 替换为要使用的模型的名称。有关支持的模型列表，请参阅模型可用性。

使用以下 curl 命令向 Snowflake 托管的模型发出请求：

curl "https://<account-identifier>.snowflakecomputing.cn/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

在前面的代码中，为以下内容指定值：

<account-identifier>：将 <account-identifier> 替换为您的 Snowflake 账户标识符。
<SNOWFLAKE_PAT>：将 <SNOWFLAKE_PAT> 替换为您的 Snowflake 个人访问令牌 (PAT)。
<model_name>：将 <model_name> 替换为要使用的模型的名称。有关支持的模型列表，请参阅模型可用性。

流式传输响应¶

通过在请求中将 stream 参数设置为 True，您可以流式传输来自 REST API 的响应。

以下 Python 代码流式传输来自 REST API 的响应：

from openai import OpenAI

client = OpenAI(
  api_key="<SNOWFLAKE_PAT>",
  base_url="https://<account-identifier>.snowflakecomputing.cn/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

以下 JavaScript/TypeScript 代码流式传输来自 REST API 的响应：

import OpenAI from "openai";

const openai = new OpenAI({
    apikey="SNOWFLAKE_PAT",
    baseURL: "https://<account-identifier>.snowflakecomputing.cn/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

以下 curl 命令流式传输来自 Snowflake 托管模型的响应：

curl "https://<account-identifier>.snowflakecomputing.cn/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

限制¶

以下是将 OpenAI SDK 与 Snowflake 托管模型一起使用的限制：

仅支持 Chat Completions。
如果未设置，则 max_completion_tokens 默认为 4096。Cortex Chat Completions API 次数的理论最大值为 131,072。每个模型都有自己的输出令牌限制，可能小于 131,072。
OpenAI 和 Claude 模型支持工具调用。有关有效使用工具调用的示例，请参阅工具调用思维链示例。
音频不受支持。
仅支持 OpenAI 和 Claude 模型的图像理解。每次对话的图片限制为 20 张，最大请求大小为 20 MiB。
只有 Claude 模型支持使用临时缓存控制点进行即时缓存。OpenAI 模型支持隐式缓存。
只有 Claude 模型支持在响应中返回其推理细节。
错误消息是由 Snowflake 生成的，而不是 OpenAI。建议仅将报告的错误用于记录和调试目的。

详细的兼容性表¶

下表汇总了在不同 Snowflake 托管模型上使用 Cortex Chat Completions API 功能时支持哪些请求和响应字段及标头。

请求字段¶
字段	OpenAI 模型	Claude 模型	其他模型
`model`	✔ 支持	✔ 支持	✔ 支持
`messages`	查看子字段	查看子字段	查看子字段
`messages[].audio`	❌ 错误	❌ 已忽略	❌ 已忽略
`messages[].role`	✔ 支持	✔ 仅限用户/助手/系统	✔ 仅限用户/助手/系统
:code:`messages[].content`（字符串）	✔ 支持	✔ 支持	✔ 支持
`messages[].content[]` (数组)	查看子字段	查看子字段	查看子字段
`messages[].content[].text`	✔ 支持	✔ 支持	✔ 支持
`messages[].content[].type`	✔ 支持	✔ 支持	✔ 支持
`messages[].content[].image_url`	✔ 支持	✔ 支持	❌ 错误
`messages[].content[].cache_control`	❌ 已忽略	✔ 支持（仅限临时使用）	❌ 已忽略
`messages[].content[].file`	❌ 错误	❌ 错误	❌ 已忽略
`messages[].content[].input_audio`	❌ 错误	❌ 已忽略	❌ 已忽略
`messages[].content[].refusal`	✔ 支持	❌ 已忽略	❌ 已忽略
`messages[].function_call`	✔ 支持（已弃用）	❌ 已忽略	❌ 已忽略
`messages[].name`	✔ 支持	❌ 已忽略	❌ 已忽略
`messages[].refusal`	✔ 支持	❌ 已忽略	❌ 已忽略
`messages[].tool_call_id`	✔ 支持	✔ 支持	❌ 已忽略
`messages[].tool_calls`	✔ 支持	✔ 仅限 `function` 工具	❌ 已忽略
`messages[].reasoning_details`	❌ 已忽略	✔ OpenRouter 格式 `reasoning.text`	❌ 已忽略
`audio`	❌ 错误	❌ 已忽略	❌ 已忽略
`frequency_penalty`	✔ 支持	❌ 已忽略	❌ 已忽略
`logit_bias`	✔ 支持	❌ 已忽略	❌ 已忽略
`logprobs`	✔ 支持	❌ 已忽略	❌ 已忽略
`max_tokens`	❌ 错误（已弃用）	❌ 错误（已弃用）	❌ 错误（已弃用）
`max_completion_tokens`	✔ 支持（默认 4096，最大 131072）	✔ 支持（默认 4096，最大 131072）	✔ 支持（默认 4096，最大 131072）
`metadata`	❌ 已忽略	❌ 已忽略	❌ 已忽略
`modalities`	❌ 已忽略	❌ 已忽略	❌ 已忽略
`n`	✔ 支持	❌ 已忽略	❌ 已忽略
`parallel_tool_calls`	✔ 支持	❌ 已忽略	❌ 已忽略
`prediction`	✔ 支持	❌ 已忽略	❌ 已忽略
`presence_penalty`	✔ 支持	❌ 已忽略	❌ 已忽略
`prompt_cache_key`	✔ 支持	❌ 已忽略	❌ 已忽略
`reasoning_effort`	✔ 支持	❌ 已忽略（使用 `reasoning` 对象）	❌ 已忽略
`reasoning`	查看子字段	查看子字段	查看子字段
`reasoning.effort`	✔ 支持（覆盖 `reasoning_effort`）	✔ 转换为 `reasoning.max_tokens`	❌ 已忽略
`reasoning.max_tokens`	❌ 已忽略	✔ 支持	❌ 已忽略
`response_format`	✔ 支持	✔ 仅限 `json_schema` 和 `text`	❌ 已忽略
`safety_identifier`	❌ 已忽略	❌ 已忽略	❌ 已忽略
`service_tier`	❌ 错误	❌ 错误	❌ 错误
`stop`	✔ 支持	❌ 已忽略	❌ 已忽略
`store`	❌ 错误	❌ 错误	❌ 错误
`stream`	✔ 支持	✔ 支持	✔ 支持
`stream_options`	查看子字段	查看子字段	查看子字段
`stream_options.include_obfuscation`	❌ 已忽略	❌ 已忽略	❌ 已忽略
`stream_options.include_usage`	✔ 支持	✔ 支持	✔ 支持
`temperature`	✔ 支持	✔ 支持	✔ 支持
`tool_choice`	✔ 支持	✔ 仅限 `function` 工具	❌ 已忽略
`tools`	✔ 支持	✔ 仅限 `function` 工具	❌ 错误
`top_logprobs`	✔ 支持	❌ 已忽略	❌ 已忽略
`top_p`	✔ 支持	✔ 支持	✔ 支持
`verbosity`	✔ 支持	❌ 已忽略	❌ 已忽略
`web_search_options`	❌ 错误	❌ 已忽略	❌ 已忽略

响应字段¶
字段	OpenAI 模型	Claude 模型	其他模型
`id`	✔ 支持	✔ 支持	✔ 支持
`object`	✔ 支持	✔ 支持	✔ 支持
`created`	✔ 支持	✔ 支持	✔ 支持
`model`	✔ 支持	✔ 支持	✔ 支持
`choices`	查看子字段	查看子字段	查看子字段
`choices[].index`	✔ 支持	✔ 仅限单项选择	✔ 仅限单项选择
`choices[].finish_reason`	✔ 支持	❌ 不支持	✔ 仅限 `stop`
`choices[].logprobs`	✔ 支持	❌ 不支持	❌ 不支持
:code:`choices[].message`（非流式传输）	查看子字段	查看子字段	查看子字段
`choices[].message.content`	✔ 支持	✔ 支持	✔ 支持
`choices[].message.role`	✔ 支持	✔ 支持	✔ 支持
`choices[].message.refusal`	✔ 支持	❌ 不支持	❌ 不支持
`choices[].message.annotations`	❌ 不支持	❌ 不支持	❌ 不支持
`choices[].message.audio`	❌ 不支持	❌ 不支持	❌ 不支持
`choices[].message.function_call`	✔ 支持	❌ 不支持	❌ 不支持
`choices[].message.tool_calls`	✔ 支持	✔ 仅限 `function` 工具	❌ 不支持
`choices[].message.reasoning`	❌ 不支持	✔ OpenRouter 格式	❌ 不支持
:code:`choices[].delta`（流式传输中）	查看子字段	查看子字段	查看子字段
`choices[].delta.content`	✔ 支持	✔ 支持	✔ 支持
`choices[].delta.role`	✔ 支持	❌ 不支持	❌ 不支持
`choices[].delta.refusal`	✔ 支持	❌ 不支持	❌ 不支持
`choices[].delta.function_call`	✔ 支持	❌ 不支持	❌ 不支持
`choices[].delta.tool_calls`	✔ 支持	✔ 仅限 `function` 工具	❌ 不支持
`choices[].delta.reasoning`	❌ 不支持	✔ OpenRouter 格式	❌ 不支持
`usage`	查看子字段	查看子字段	查看子字段
`usage.prompt_tokens`	✔ 支持	✔ 支持	✔ 支持
`usage.completion_tokens`	✔ 支持	✔ 支持	✔ 支持
`usage.total_tokens`	✔ 支持	✔ 支持	✔ 支持
`usage.prompt_tokens_details`	查看子字段	查看子字段	查看子字段
`usage.prompt_tokens_details.audio_tokens`	❌ 不支持	❌ 不支持	❌ 不支持
`usage.prompt_tokens_details.cached_tokens`	✔ 仅缓存读取	✔ 缓存读取 + 写入	❌ 不支持
`usage.completion_tokens_details`	查看子字段	查看子字段	查看子字段
`usage.completion_tokens_details.accepted_prediction_tokens`	✔ 支持	❌ 不支持	❌ 不支持
`usage.completion_tokens_details.audio_tokens`	❌ 不支持	❌ 不支持	❌ 不支持
`usage.completion_tokens_details.reasoning_tokens`	✔ 支持	❌ 不支持	❌ 不支持
`usage.completion_tokens_details.rejected_prediction_tokens`	✔ 支持	❌ 不支持	❌ 不支持
`service_tier`	✔ 支持	❌ 不支持	❌ 不支持
`system_fingerprint`	✔ 支持	❌ 不支持	❌ 不支持

请求标头¶
标头	支持
`Authorization`	✔ 必填
`Content-Type`	✔ 支持 (`application/json`)
`Accept`	✔ 支持 (`application/json`, `text/event-stream`)

响应标头¶
标头	支持
`openai-organization`	❌ 不支持
`openai-version`	❌ 不支持
`openai-processing-ms`	❌ 不支持
`x-ratelimit-limit-requests`	❌ 不支持
`x-ratelimit-limit-tokens`	❌ 不支持
`x-ratelimit-remaining-requests`	❌ 不支持
`x-ratelimit-remaining-tokens`	❌ 不支持
`x-ratelimit-reset-requests`	❌ 不支持
`x-ratelimit-reset-tokens`	❌ 不支持
`retry-after`	❌ 不支持

了解详情¶

有关使用示例的完整汇编，请查阅 OpenAI 的 Chat Completions API 参考 (https://platform.openai.com/docs/guides/completions/) 或 OpenAI 操作手册 (https://cookbook.openai.com/)。

除了提供与 Chat Completions API 的兼容性外，Snowflake 还支持 Claude 模型的 OpenRouter 兼容功能。根据请求，这些功能将作为额外字段公开。

要进行提示缓存，请使用 cache_control 字段。有关更多信息，请参阅 OpenRouter提示缓存文档 (https://openrouter.ai/docs/features/prompt-caching)。
要获取推理令牌，请使用 reasoning 字段。有关更多信息，请参阅 OpenRouter 推理文档 (https://openrouter.ai/docs/use-cases/reasoning-tokens)。