벡터 임베딩 REST API

Cortex REST API를 통해 AI_EMBED 함수를 사용하여 :doc:`벡터 임베딩 </user-guide/snowflake-cortex/vector-embeddings>`을 수행하기 위해 엔드포인트에 액세스할 수 있습니다.

인증 설정하기

Cortex REST API 에 인증하려면 Snowflake를 사용하여 Snowflake REST APIs 인증하기 에 설명된 방법을 사용할 수 있습니다.

토큰을 포함할 Authorization 헤더(예: JSON 웹 토큰(JWT), OAuth 토큰 또는 프로그래밍 방식 액세스 토큰)를 설정합니다.

팁

Cortex REST API 요청을 위한 전용 사용자 생성을 고려하십시오.

승인 설정하기

REST API 요청을 전송하려면 기본 역할에 SNOWFLAKE.CORTEX_USER 데이터베이스 역할을 부여해야 합니다. 대부분의 경우 PUBLIC 역할에 SNOWFLAKE.CORTEX_USER 권한이 자동으로 부여되고 모든 역할이 PUBLIC을 상속하므로 사용자에게는 이미 이 권한이 있습니다.

Snowflake 관리자가 이 권한 부여를 취소한 경우 다시 부여해야 합니다.

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

중요

REST API 요청은 사용자의 기본 역할을 사용하므로 해당 역할에는 필요한 권한이 있어야 합니다. :doc:`ALTER USER … SET DEFAULT_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
(북부 버지니아)
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.

요청에 대한 승인입니다. 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

배열

임베딩을 생성할 텍스트 문자열 목록입니다. 목록에는 최대 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