向量嵌入 REST API

Cortex REST API 提供了一个端点，让您可以使用 AI_EMBED 函数来执行 向量嵌入。

设置身份验证

要向 Cortex REST API 进行身份验证，可以使用 使用 Snowflake 对 Snowflake REST APIs 进行身份验证 中所述的方法。

设置 Authorization 标头以包含您的令牌（例如，JSON 网络令牌 [JWT])、OAuth 令牌或 程序化访问令牌）。

小技巧

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

设置授权

要发送 REST API 请求，您的默认角色必须被授予 SNOWFLAKE.CORTEX_USER 数据库角色。在大多数情况下，用户已经拥有此权限，因为 SNOWFLAKE.CORTEX_USER 会自动授予给 PUBLIC 角色，且所有角色都会继承 PUBLIC。

如果您的 Snowflake 管理员已撤销此授权，则必须重新授予：

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

重要

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

ALTER USER my_user SET DEFAULT_ROLE=my_role

端点格式

您可以向 /api/v2/cortex/inference:embed 端点发出请求，为您的文本创建嵌入。因此，请求采用以下形式：

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

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

模型可用性

下表显示了您可以使用 REST API 提示的 EMBED 函数模型。

EMBED 函数模型
模型
AWS US 西部 2
（俄勒冈）
AWS US 东部 1
（弗吉尼亚北部）
AWS 欧洲中部 1
（法兰克福）
AWS 欧洲西部 1
（爱尔兰）
AWS AP 东南部 2
（悉尼）
AWS AP 东北部 1
（东京）
Azure 东部 US 2
（弗吉尼亚）
Azure 西欧
（荷兰）
snowflake-arctic-embed-m-v1.5

✔

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-m

✔

✔

✔

✔

✔

✔

✔

✔
e5-base-v2

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-l-v2.0

✔

✔

✔

✔

✔

✔

✔

✔

下表显示了每个模型可以返回的维度数。

EMBED 函数模型
模型
维度
数量
snowflake-arctic-embed-m-v1.5

768
snowflake-arctic-embed-m

768
e5-base-v2

768
snowflake-arctic-embed-l-v2.0

1024

API 参考

POST /api/v2/cortex/inference:embed

为您指定的文本创建嵌入。

必要标头

Authorization: Bearer token。

对请求的授权。 是 Web 令牌 ()、 令牌或 编程访问令牌 。有关详细信息，请参阅 使用 Snowflake 对 Snowflake REST APIs 进行身份验证。

Content-Type: application/json

指定请求的主体是 JSON 格式。

Accept: application/json

指定响应包含 JSON。

可选标头

X-Snowflake-Authorization-Token-Type: type

定义授权令牌的类型。

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

即使此标头可选，您也可以选择指定此标头。您可以将标头设置为以下值之一：

  • ``KEYPAIR_JWT``（适用于密钥对身份验证）

  • ``OAUTH``（适用于 OAuth）

  • ``PROGRAMMATIC_ACCESS_TOKEN``（适用于 编程访问令牌）

必要 JSON 实参

实参

类型

描述

text

数组

您要为其生成嵌入的文本字符串列表。该列表最多可包含 1280 个字符串，每个字符串的最长长度可达 4096 个字符。

model

字符串

用来创建嵌入的模型。

状态代码

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 embed timed out

请求耗时太长。

CURL 请求示例

以下示例使用 curl 向 e5-base-v2 模型发出 EMBED 请求。使用适当值替换此命令中的 token 和 account_identifier。

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"
}'

输出

以下是请求的输出，其中嵌入数组的内容被截断：

{
  "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
  }
}

每个嵌入都有一个索引，该索引与请求列表中的文本字符串相对应。索引从 0 开始，因此列表中第一个文本字符串的索引为 0，第二个文本字符串的索引为 1，依此类推。

在前面的示例中，“foo”对应于索引 0，“bar”对应于索引 1。“foo”的嵌入是嵌入列表中的第一个元素，“bar”的嵌入是嵌入列表中的第二个元素。

Python 请求示例

以下示例使用 Python API 向 e5-base-v2 模型发出 EMBED 请求。使用适当值替换此命令中的 token 和 account_identifier。

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()

输出

以下是请求的输出，其中嵌入数组的内容被截断：

{
  "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
  }
}

每个嵌入都有一个索引，该索引与请求列表中的文本字符串相对应。索引从 0 开始，因此列表中第一个文本字符串的索引为 0，第二个文本字符串的索引为 1，依此类推。

在前面的示例中，“foo”对应于索引 0，“bar”对应于索引 1。“foo”的嵌入是嵌入列表中的第一个元素，“bar”的嵌入是嵌入列表中的第二个元素。

使用量配额

下表显示了 EMBED 函数的使用配额。

EMBED 函数配额
模型
每分钟
处理的词元 (TPM)
每分钟的
请求 (RPM)
最大输出（词元）
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