Cortex LLM REST API¶

Snowflake Cortex LLM 函数使用 SQL 或 Python，提供由各种大型语言模型 (LLMs) 支持的自然语言处理功能。有关更多信息，请参阅大型语言模型 (LLM) 函数 (Snowflake Cortex)。

您可以使用 Snowflake Cortex LLM REST API 来调用您选择的 LLM 推理。您可以使用任何可以发出 HTTP POST 请求的编程语言进行请求。此功能允许您将最先进的 AI 功能带入您的应用程序。使用此 API 不需要仓库。

Cortex LLM REST API 将生成的词元作为服务器发送事件 (https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) 流式传回给用户。

成本注意事项¶

Snowflake Cortex LLM REST API 请求会产生计算成本，具体取决于处理的词元数。请参阅 Snowflake 服务使用表，以了解每个函数的每百万个词元消耗的 credit 成本。词元是 Snowflake Cortex LLM 函数处理的最小文本单位，大约等于四个字符的文本。原始输入或输出文本与词元的等价性可能因模型而异。

COMPLETE 函数根据输入提示生成新文本。输入和输出词元都会产生计算成本。如果您使用 COMPLETE 来提供对话或聊天用户体验，系统会处理所有先前的提示和响应，以生成每个新的响应，并产生相应的成本。

模型可用性¶

下表包含 Cortex LLM REST API 中可用的模型。

函数（模型）	AWS US 西部 2 （俄勒冈）	AWS US 东部 1 （弗吉尼亚北部）	AWS 欧洲中部 1 （法兰克福）	AWS 欧洲西部 1 （爱尔兰）	AWS AP 东南部 2 （悉尼）	AWS AP 东北部 1 （东京）	Azure 东部 US 2 （弗吉尼亚）	Azure 西欧（荷兰）	AWS （跨区域）
COMPLETE (`claude-3-5-sonnet`)	✔								✔
COMPLETE (`llama4-maverick`)	处于预览版
COMPLETE (`llama3.1-8b`)	✔	✔	✔			✔	✔	✔	✔
COMPLETE (`llama3.1-70b`)	✔	✔	✔	✔	✔	✔	✔	✔	✔
COMPLETE (`llama3.1-405b`)	✔	✔					✔		✔
COMPLETE (`llama3.2-1b`)	✔								✔
COMPLETE (`llama3.2-3b`)	✔								✔
COMPLETE (`deepseek-r1`)									✔
COMPLETE (`mistral-7b`)	✔	✔	✔			✔	✔	✔	✔
COMPLETE (`mistral-large`)	✔	✔	✔			✔	✔	✔	✔
COMPLETE (`mistral-large2`)	✔	✔	✔	✔	✔	✔	✔	✔	✔
COMPLETE (`snowflake-llama-3.3-70b`)	✔								✔

您还可以在任何支持的区域，使用任何微调模型。

使用量配额¶

为了确保所有 Snowflake 客户的高性能标准，Snowflake Cortex LLM REST API 请求受使用配额的限制。超出配额的请求可能会被限制。Snowflake 可能会偶尔调整这些配额。以下表中的配额按账户应用，并且对每个模型独立应用。

函数（模型）	每分钟处理的词元 (TPM)	每分钟的请求 (RPM)	最大输出（词元）
COMPLETE (`deepseek-r1`)	100,000	50	4,096
COMPLETE (`llama3.1-8b`)	400,000	200	4,096
COMPLETE (`llama3.1-70b`)	200,000	100	4,096
COMPLETE (`llama3.1-405b`)	100,000	50	4,096
COMPLETE (`mistral-7b`)	400,000	200	4,096
COMPLETE (`mistral-large2`)	200,000	100	4,096

COMPLETE 端点¶

/api/v2/cortex/inference:complete 端点执行 SQL COMPLETE 函数。其形式如下：

POST https://<account_identifier>.snowflakecomputing.cn/api/v2/cortex/inference:complete

其中，account_identifier 是您用来访问 Snowsight 的账户标识符。

备注

目前，仅支持 COMPLETE 函数。Cortex LLM REST API 的未来版本可能会支持其他函数。

设置身份验证¶

对 Cortex LLM REST API 进行身份验证使用密钥对身份验证。这需要创建一个 RSA 密钥对，并将其公钥分配给用户，这必须使用 SECURITYADMIN 角色（或授予了 SECURITYADMIN 权限的其他角色，例如 ACCOUNTADMIN）完成。有关分步说明，请参阅配置密钥对身份验证。

小技巧

考虑为 Cortex LLM REST API 请求创建专用用户。

要发出 API 请求，请使用私钥创建 JSON Web 词元 (https://jwt.io/) (JWT)，并将其传递到请求的标头。

设置授权¶

创建密钥对并将其公钥分配给用户后，该用户的默认角色需要具有 snowflake.cortex_user 数据库角色，该角色包含使用 LLM 函数的权限。在大多数情况下，用户已经拥有此权限，因为该权限会自动授予给 PUBLIC 角色，且所有角色都会继承 PUBLIC。

如果 Snowflake 管理员希望选择个人用户，则其可能已经从 PUBLIC 撤销 snowflake.cortex_user，并且必须将此角色授予应该能够使用 Cortex LLM REST API 的用户，如下所示。

GRANT DATABASE ROLE snowflake.cortex_user TO ROLE MY_ROLE;
GRANT ROLE MY_ROLE TO USER MY_USER;

Copy

重要

REST API 请求使用用户的默认角色，因此该角色必须具有必要的权限。您可以使用以下方式更改用户的默认角色：ALTER USER ...SET DEFAULT ROLE。

ALTER USER MY_USER SET DEFAULT_ROLE=MY_ROLE

Copy

提交请求¶

您通过 POSTing 到 API 的 REST 端点，向 Cortex LLM REST API 发出请求。 Authorization 标头必须包含通过公钥生成的 JSON Web 令牌，您可以使用 snowsql 通过以下命令实现。生成的 JWT 一小时后过期。

snowsql -a <account_identifier> -u <user> --private-key-path <path>/rsa_key.p8 --generate-jwt

Copy

请求主体是指定模型、提示或对话历史记录和选项的 JSON 对象。请参阅以下 API 参考了解详情。

API 参考¶

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

使用指定的大型语言模型完成提示或对话。请求主体是包含实参的 JSON 对象。

此端点对应于 :doc:`COMPLETE </sql-reference/functions/complete-snowflake-cortex>`SQL 函数。

必要标头¶

Authorization: Bearer jwt。: 请求的授权。jwt 是有效的 JSON Web 令牌。
Content-Type: application/json: 指定请求的主体是 JSON 格式。
Accept: application/json, text/event-stream: 指定响应将包含 JSON（错误情况）或服务器发送的事件。

可选标头¶

X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT

定义授权令牌的类型。

如果您省略了 X-Snowflake-Authorization-Token-Type 标头，Snowflake 将通过检查令牌来确定令牌类型。

即使此标头可选，您可以选择指定此标头。您可以将标头设置为 ``OAUTH``（用于 OAuth）或 ``KEYPAIR_JWT``（用于密钥对身份验证）。

必要 JSON 实参¶

实参	类型	描述
`model`	字符串	要使用的模型的标识符（请参阅选择模型）。有关可能的值，请参阅模型可用性。或者，您可以使用任何 `database.schema.model` 格式的微调模型的完全限定名称。备注 `claude-3-5-sonnet` 不支持 COMPLETE 结构化输出。
`messages`	数组	用于生成补全的提示或对话历史记录。按时间顺序排列的，代表对话的对象数组。每个对象必须包含一个 `content` 密钥，并且还可能包含 `role` 密钥。 `content`：包含系统消息、用户提示或模型先前响应的字符串。 `role`：表示消息角色的字符串，可以是以下之一：`'system'`、`'user'` 或 `'assistant'`。请参阅 :ref:` COMPLETE 角色表 <label-sql-functions-complete-cortex-role-content>`，了解有关这些角色的更详细描述。对于由单个用户消息组成的提示，`role` 可以省略；然后假定为 `user`。

实参

类型

描述

model

字符串

要使用的模型的标识符（请参阅选择模型）。有关可能的值，请参阅模型可用性。

或者，您可以使用任何 database.schema.model 格式的微调模型的完全限定名称。

备注

claude-3-5-sonnet 不支持 COMPLETE 结构化输出。

messages

数组

用于生成补全的提示或对话历史记录。按时间顺序排列的，代表对话的对象数组。每个对象必须包含一个 content 密钥，并且还可能包含 role 密钥。

content：包含系统消息、用户提示或模型先前响应的字符串。
role：表示消息角色的字符串，可以是以下之一：'system'、'user' 或 'assistant'。

请参阅 :ref:` COMPLETE 角色表 <label-sql-functions-complete-cortex-role-content>`，了解有关这些角色的更详细描述。

对于由单个用户消息组成的提示，role 可以省略；然后假定为 user。

可选 JSON 实参¶

实参	类型	默认值	描述
`guardrails`	对象	`null`	一个对象，用于控制是否对请求使用 Cortex Guard 限制。该对象包含两个字段： `enabled`：一个布尔值，用于控制是否对请求使用限制。如果此字段不存在或不是 `true`，则不使用限制。 `response_when_unsafe`：一个字符串，用于确定当 Cortex Guard 模型判定响应不安全时的处理方式。返回的是该字符串而非实际生成内容。默认：“由 Cortex Guard 过滤的响应”
`max_tokens`	整数	4096	一个介于 1 和 4096（含 1 和 4096）之间的值，用于控制要输出的最大令牌数。词元达到此数量后，输出将被截断。
`top_p`	数字	1.0	从 0 到 1（含）的值，通过限制模型输出的可能词元集来控制语言模型的多样性。
`temperature`	数字	0.0	从 0 到 1（含）的值，通过影响每个步骤中选择哪个可能的词元来控制语言模型输出的随机

工具配置¶

重要

工具使用仅支持 Claude 3.5 Sonnet。

tool_spec 字段包含一系列可用的工具。下表显示可用字段：

工具规格¶
字段	类型	描述
`tool_spec.type`	字符串	工具的类型。类型和名称的组合是唯一的标识符。
`tool_spec.name`	字符串	工具名称。类型和名称的组合是唯一的标识符。
`tool_spec.description`	字符串	对所考虑使用工具的描述。
`tool_spec.input_schema`	对象	工具输入的 JSON 架构。
`tool_spec.input_schema.type`	字符串	输入架构对象的类型。
`tool_spec.input_schema.properties`	对象	每个输入参数的定义。
`tool_spec.input_schema.required`	数组	所需输入参数的列表。

tool_choice 字段配置工具选择行为。它有以下字段：

工具选择¶
字段	类型	描述
`type`	字符串	选择工具的方式。有效值： `"auto"`：模型决定是否调用您提供的工具。 `"required"`：使用一个或多个工具。 `"tool"`：使用您指定的工具。
`name`	数组	正在使用的工具的名称。仅在 `type` 为 `"tool"` 时有效。

tool_use 表示模型请求使用特定工具。它包含工具标识符和执行的输入参数。它有以下字段：

工具使用¶
字段	类型	描述
`type`	字符串	将其标识为工具使用请求。
`tool_use`	对象	工具使用请求详细信息的容器。

每个对象包含以下键：

工具使用请求键¶
字段	类型	描述	必填
`tool_use_id`	字符串	此工具使用请求的唯一标识符。	是
`name`	字符串	正在使用的工具的名称。	是
`input`	对象	正在使用的工具的名称。	是

工具结果¶

表示工具执行的结果。包含工具执行的输入参数和输出结果。

工具结果¶
字段	类型	描述
`type`	字符串	将其标识为工具结果。
`tool_results`	字符串	此工具使用请求的唯一标识符。

每个结果可以包含以下键：

工具结果键¶
字段	类型	描述	必填
`tool_use_id`	字符串	用于将此结果与对应工具使用请求相关联的唯一标识符。	是
`name`	字符串	运行的工具的名称。它必须与 `tools` 数组中的工具名称匹配。	是
`content`	数组	工具执行生成的内容元素的数组。	是
`id`	字符串	工具执行实例的可选标识符。	否
`status`	字符串	工具执行的状态指示器。	否
`Results`	对象	采用任意结构的附加结果数据。将 `Additional properties` 设置为 `True`。	是

输出¶

使用服务器发送事件 (SSEs) 生成词元后发送。每个 SSE 事件均使用 message 类型并包含具有以下结构的 JSON 对象。

键	值类型	描述
`id`	字符串	请求的唯一 ID，请求响应中发送的所有事件具有相同的值。
`created`	数字	生成响应时的 UNIX 时间戳（自 1970 年 1 月 1 日午夜以来的秒数）。
`model`	字符串	模型使用的标识符。
`choices`	数组	模型的响应。每个响应都是一个对象，包含 `delta` 键，其值是一个对象，该对象的 `content` 键包含模型生成的输出。如果响应被 Cortex Guard 阻止，则对象包含一个 `finish_reason` 键，其值为 `"prohibited_content"`。目前，该数组始终包含一个选项。
`'usage`	对象	此请求的词元使用情况，包括： `prompt_tokens`：提示中的令牌数。 `completion_tokens`：完成中的词元数。 `guard_tokens`：Cortex Guard 处理消耗的词元数。如果未启用限制，则此字段不存在。 `total_tokens`：提示和完成中的词元总数。

状态代码¶

Snowflake Cortex LLM REST API 使用以下 HTTP 状态代码来指示成功完成或各种错误条件。

200 OK: 请求成功完成。响应的主体包含模型的输出。
400 invalid options object: 可选实参有无效值。
400 unknown model model_name: 指定的模型不存在。
400 schema validation failed: 与不正确的响应架构结构相关的错误。请修正架构并重试。
400 max tokens of count exceeded: 请求超出了模型支持的最大词元数（请参阅模型限制）。
400 all requests were throttled by remote service: 由于使用率很高，请求已受到限流。请稍后再试。
402 budget exceeded: 超出了模型消耗预算。
403 Not Authorized: 账户未启用 REST API，或调用用户的默认角色没有 snowflake.cortex_user 数据库角色。
429 too many requests: 由于已超出使用量配额，请求遭到拒绝。请稍后重试请求。
503 inference timed out: 请求耗时太长。

基本示例¶

以下示例使用 curl 发出 COMPLETE 请求。使用此命令中的适当值替换 jwt、prompt 和 account_identifier。

curl -X POST \
    -H "Authorization: Bearer <jwt>" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{
    "model": "mistral-large",
    "messages": [
        {
            "content": "<prompt>"
        }
    ],
    "top_p": 0,
    "temperature": 0
    }' \
https://<account_identifier>.snowflakecomputing.cn/api/v2/cortex/inference:complete

Copy

输出¶

data: {
data:  "id": "65c5e2ac-529b-461e-8a8c-f80655e6bd3f",
data:  "created": 1723493954,
data:  "model": "mistral-7b",
data:  "choices": [
data:    {
data:      "delta": {
data:        "content": "Cor"
data:        }
data:      }
data:     ],
data:  "usage": {
data:    "prompt_tokens": 57,
data:    "completion_tokens": 1,
data:    "total_tokens": 58
data:  }
data: }

data: {
data:  "id": "65c5e2ac-529b-461e-8a8c-f80655e6bd3f",
data:  "created": 1723493954,
data:  "model": "mistral-7b",
data:  "choices": [
data:    {
data:      "delta": {
data:        "content": "tex"
data:        }
data:      }
data:     ],
data:  "usage": {
data:    "prompt_tokens": 57,
data:    "completion_tokens": 2,
data:    "total_tokens": 59
data:  }
data: }

工具调用思维链示例¶

以下示例使用 curl 在思维链过程中发出 COMPLETE 请求。在这种情况下，工具用于获取 CA 旧金山的天气信息。

请求¶

curl -X POST \
    -H "Authorization: Bearer <jwt>" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{
    "model": "claude-3-5-sonnet",
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?"
      }
    ],
    "tools": [
      {
        "tool_spec": {
          "type": "generic",
          "name": "get_weather",
          "input_schema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              }
            },
            "required": [
              "location"
            ]
          }
        }
      }
    ],
    "max_tokens": 4096,
    "top_p": 1,
    "stream": true
    }' \
https://<account_identifier>.snowflakecomputing.cn/api/v2/cortex/inference:complete

Copy

响应¶

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content":"I","content_list":[{"text":"I","type":"text"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content":"'ll","content_list":[{"text":"'ll","type":"text"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content":" help you","content_list":[{"text":" help you","type":"text"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content":" check the","content_list":[{"text":" check the","type":"text"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content":" weather in","content_list":[{"text":" weather in","type":"text"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content":" San Francisco.","content_list":[{"text":" San Francisco.","type":"text"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content_list":[{"name":"get_weather","tool_use_id":"tooluse_Iwuh-FEeTC-Iefsxu2ueKQ"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content_list":[{"input":"{\"location\""}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content_list":[{"input":": \"San"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content_list":[{"input":" Francisco"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{"content_list":[{"input":", CA\"}"}]}}],"usage":{}}

data: {"id":"78fe5630-95b1-4960-ac2b-7eb85536b08e","model":"claude-3-5-sonnet","choices":[{"delta":{}}],"usage":{"prompt_tokens":390,"completion_tokens":53,"total_tokens":443}}

用户端执行 get_weather 工具并将结果提供给模型。

后续请求¶

curl -X POST \
    -H "Authorization: Bearer <jwt>" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{
    "model": "claude-3-5-sonnet",
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?"
      },
      {
        "role": "assistant",
        "content": "I'll help you check the weather in San Francisco.",
        "content_list": [
          {
            "type": "tool_use",
            "tool_use": {
              "tool_use_id": "tooluse_Iwuh-FEeTC-Iefsxu2ueKQ",
              "name": "get_weather",
              "input": {
                "location": "San Francisco, CA"
              }
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?",
        "content_list": [
          {
            "type": "tool_results",
            "tool_results": {
              "tool_use_id": "tooluse_Iwuh-FEeTC-Iefsxu2ueKQ",
              "name": "get_weather",
              "content": [
                {
                  "type": "text",
                  "text": "\"temperature\": \"69 fahrenheit\""
                }
              ]
            }
          }
        ]
      }
    ],
    "tools": [
      {
        "tool_spec": {
          "type": "generic",
          "name": "get_weather",
          "input_schema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              }
            },
            "required": [
              "location"
            ]
          }
        }
      }
    ],
    "max_tokens": 4096,
    "top_p": 1,
    "stream": true
    }' \
https://<account_identifier>.snowflakecomputing.cn/api/v2/cortex/inference:complete

Copy

最终响应¶

data: {"id":"07ffa851-4c47-4cea-9b7e-017a4cddc21d","model":"claude-3-5-sonnet","choices":[{"delta":{"content":"\n\nBase","content_list":[{"type":"text","text":"\n\nBase"}]}}],"usage":{}}

data: {"id":"07ffa851-4c47-4cea-9b7e-017a4cddc21d","model":"claude-3-5-sonnet","choices":[{"delta":{"content":"d on the weather data,","content_list":[{"type":"text","text":"d on the weather data,"}]}}],"usage":{}}

data: {"id":"07ffa851-4c47-4cea-9b7e-017a4cddc21d","model":"claude-3-5-sonnet","choices":[{"delta":{"content":" it's currently 69 ","content_list":[{"type":"text","text":" it's currently 69 "}]}}],"usage":{}}

data: {"id":"07ffa851-4c47-4cea-9b7e-017a4cddc21d","model":"claude-3-5-sonnet","choices":[{"delta":{"content":"degrees Fahrenheit in San Francisco,","content_list":[{"type":"text","text":"degrees Fahrenheit in San Francisco,"}]}}],"usage":{}}

data: {"id":"07ffa851-4c47-4cea-9b7e-017a4cddc21d","model":"claude-3-5-sonnet","choices":[{"delta":{"content":" CA.","content_list":[{"type":"text","text":" CA."}]}}],"usage":{}}

data: {"id":"07ffa851-4c47-4cea-9b7e-017a4cddc21d","model":"claude-3-5-sonnet","choices":[{"delta":{}}],"usage":{"prompt_tokens":466,"completion_tokens":26,"total_tokens":492}}

结构化输出示例¶

此示例演示了使用 curl 检索遵循指定 JSON 架构的结构化响应。

curl --location --request POST 'https://<account_identifier>.snowflakecomputing.cn/api/v2/cortex/inference:complete' \
  --header 'Authorization: Bearer <jwt>' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "mistral-large2",
    "messages": [{ "content": "Please prepare me a data set consisting of 3 people and their ages" }],
    "max_tokens": 1000,
    "response_format": {
      "type": "json",
      "schema": {
        "type": "object",
        "properties": {
          "people": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "age": {
                  "type": "number"
                }
              },
              "required": ["name", "age"]
            }
          }
        },
        "required": ["people"]
      }
    }
  }'

Copy

Python API¶

要安装 Python API，请使用：

pip install snowflake-ml-python

Copy

从 1.6.1 版本开始，Python API 包含在 snowflake-ml-python 包内。

示例¶

要使用 Python API，首先创建一个 Snowflake 会话（请参阅为 Snowpark Python 创建会话）。然后调用 Complete API。

from snowflake.snowpark import Session
from snowflake.cortex import Complete

session = Session.builder.configs(...).create()

stream = Complete(
  "mistral-7b",
  "What are unique features of the Snowflake SQL dialect?",
  session=session,
  stream=True)

for update in stream:
  print(update)

Copy

备注

Python API 的流模式目前在存储过程和 Snowsight 中不起作用。