ベクトル埋め込みREST API

Cortex REST APIを使用すると、:doc:`/sql-reference/functions/ai_embed`関数を使用して:doc:`ベクトル埋め込み</user-guide/snowflake-cortex/vector-embeddings>`を実行するためのエンドポイントにアクセスできます。

認証の設定

Cortex REST API への認証コードには、 Snowflakeでの Snowflake REST APIs 認証 で説明されている方法を使用できます。

トークン（例：JSONウェブトークン（JWT）、OAuthトークン、または:doc:Programmaticアクセストークン</user-guide/programmatic-access-tokens>）を含めるように``Authorization``ヘッダーを設定します。

Tip

Cortex REST API リクエスト専用のユーザーを作ることを検討します。

認証の設定

RESTAPIリクエストを送信するには、既定のロールに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 リクエストはユーザーの既定のロールを使用するので、そのロールは必要な権限を持っていなければなりません。ユーザーの既定のロールは、:doc:`ALTERUSER ... SETDEFAULT_ROLE</sql-reference/sql/alter-user>`を使用して変更できます。

ALTER USER my_user SET DEFAULT_ROLE=my_role

エンドポイント形式

/api/v2/cortex/inference:embed エンドポイントにリクエストして、テキストの埋め込みを作成することができます。リクエストは以下の形式です。

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

ここで、 account_identifier は、Snowsightへのアクセスに使用する アカウント識別子 です。

モデルの可用性

次の表は、 REST API を使用してプロンプトを表示できる EMBED 関数モデルを示しています。

EMBED 関数モデル
モデル
AWS US西部2
（オレゴン）
AWS US東部1
（N.バージニア）
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 関数モデル
モデル
の数
dimensions
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。

リクエストの認証。token`はJSONウェブトークン（JWT）、OAuthトークン、または:doc:`プログラムによるアクセストークン</user-guide/programmatic-access-tokens>）です。詳細については、 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はトークンを調べてトークンのタイプを決定します。

このヘッダーはオプションですが、このヘッダーを指定することもできます。ヘッダーは以下の値のいずれかにセットできます。

必須 JSON 引数

引数

型

説明

text

array

埋め込みを生成する文字列のリスト。リストには最大1280文字列を含めることができ、それぞれの文字列の長さは最大4096文字です。

model

string

埋め込みを作成するために使用するモデル。

ステータスコード

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、2番目の文字列のインデックスは1、といった具合です。

先の例では、"foo "が0インデックス、"bar "が1インデックスに相当します。"foo"の埋め込みは埋め込みリストの1番目の要素で、"bar"の埋め込みは埋め込みリストの2番目の要素です。

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、2番目の文字列のインデックスは1、といった具合です。

先の例では、"foo "が0インデックス、"bar "が1インデックスに相当します。"foo"の埋め込みは埋め込みリストの1番目の要素で、"bar"の埋め込みは埋め込みリストの2番目の要素です。

使用量のクォータ

次の表は、 EMBED 関数の使用クォータを示しています。

EMBED 関数クォータ
モデル
1分あたりの処理トークン数（TPM）
毎分（TPM）
1分あたりのリクエスト数（RPM）
分（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