모델 엔드포인트 관리 참조

프리뷰

이 제품에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

MySQL   |  PostgreSQL   |  SQL Server

이 페이지에는 Cloud SQL에서 모델 엔드포인트를 등록하고 관리하기 위해 제공하는 다양한 함수의 파라미터가 나와 있습니다. 이 페이지에는 모델 엔드포인트 관리를 사용하여 관리할 수 있는 보안 비밀도 나와 있습니다.

참고: 모델 엔드포인트 관리에 대한 자세한 내용은 Cloud SQL에서 원격 AI 모델 등록 및 호출을 참고하세요.

모델

이 참조를 사용하여 모델 엔드포인트를 관리할 수 있는 함수의 파라미터를 알아봅니다.

mysql.ml_create_model_registration()

다음은 mysql.ml_create_model_registration() 함수를 사용하여 모델 엔드포인트 메타데이터를 등록하는 방법을 보여줍니다.

  CALL
    mysql.ml_create_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

매개변수	필수	설명
MODEL_ID	모든 모델 엔드포인트에 필수	개발자가 정의한 모델 엔드포인트의 고유 ID입니다.
REQUEST_URL	Vertex AI 모델의 경우 NULL일 수 있습니다.	다른 텍스트 임베딩과 일반 모델 엔드포인트를 추가할 때의 모델별 엔드포인트입니다. 함수가 기본 제공 모델 엔드포인트에 생성하는 요청 URL은 클러스터의 프로젝트 및 리전이나 위치를 참조합니다. 다른 프로젝트를 참조하려면 model_request_url을 명시적으로 지정해야 합니다. 커스텀 호스팅 모델 엔드포인트의 경우 인터넷을 통해 모델 엔드포인트에 액세스할 수 있는지 확인합니다.
PROVIDER_ID	기본 제공 지원이 포함된 텍스트 임베딩 모델 엔드포인트에 필수	모델 엔드포인트 제공업체입니다. 기본값은 custom입니다. Cloud SQL의 경우 제공업체를 google(Vertex AI 모델 엔드포인트의 경우), open_ai(OpenAI 모델 엔드포인트의 경우), anthropic(Anthropic 모델 엔드포인트의 경우), hugging_face(Hugging Face 모델 엔드포인트의 경우) 또는 custom(커스텀 호스팅 모델 엔드포인트의 경우)으로 설정합니다.
MODEL_TYPE	일반 모델 엔드포인트의 경우 NULL일 수 있음	모델 유형입니다. 이 값을 텍스트 임베딩 모델 엔드포인트의 경우 text_embedding로, 다른 모든 모델 엔드포인트의 경우 generic으로 설정할 수 있습니다.
MODEL_QUALIFIED_NAME	OpenAI 모델 엔드포인트에는 필수, 다른 모델 엔드포인트의 경우에는 NULL일 수 있음	모델 엔드포인트에 버전이 여러 개 있거나 모델 엔드포인트에서 버전을 정의하는 경우의 정규화된 이름입니다(예: textembedding-gecko@001 또는 textembedding-gecko@002). textembedding-gecko@001 모델은 모델 엔드포인트 관리에 사전 등록되어 있으므로 textembedding-gecko@001을 모델 ID로 사용하여 임베딩을 생성할 수 있습니다.
AUTH_TYPE	모델 엔드포인트에 특정 인증 요구사항이 없는 한 NULL일 수 있음	모델 엔드포인트에서 사용하는 인증 유형입니다. Vertex AI 모델의 경우 auth_type_cloudsql_service_agent_iam으로, 다른 제공업체의 경우 auth_type_secret_manager로 설정할 수 있습니다.
AUTH_ID	Vertex AI 엔드포인트의 경우 NULL로 전달, Secret Manager에 보안 비밀을 저장하는 다른 모든 모델 엔드포인트에는 필수	개발자가 설정하고 이후 모델 엔드포인트를 등록할 때 사용되는 보안 비밀 ID입니다.
GENERATE_HEADER_FUNCTION	NULL일 수 있음	커스텀 헤더를 생성하도록 설정한 함수 이름입니다. 이 함수의 서명은 mysql.ml_predict_row() 함수에 따라 다릅니다. HTTP 헤더 생성 함수를 참조하세요.
INPUT_TRANSFORM_FUNCTION	기본 제공 지원이 있는 텍스트 임베딩 모델 엔드포인트의 경우 선택사항, 일반 모델 엔드포인트에 설정 금지	해당 예측 함수의 입력을 모델별 입력으로 변환하는 함수입니다. 변환 함수를 참조하세요.
OUTPUT_TRANSFORM_FUNCTION	기본 제공 지원이 있는 텍스트 임베딩 모델 엔드포인트의 경우 선택사항, 일반 모델 엔드포인트에 설정 금지	모델별 출력을 예측 함수 출력으로 변환하는 함수입니다. 변환 함수를 참조하세요.

mysql.ml_alter_model_registration()

다음은 모델 엔드포인트 메타데이터를 업데이트하는 데 사용되는 mysql.ml_alter_model_registration() SQL 함수를 호출하는 방법을 보여줍니다.

    CALL
    mysql.ml_alter_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

mysql.ml_drop_model_registration()

다음은 모델 엔드포인트를 삭제하는 데 사용되는 mysql.ml_drop_model_registration() SQL 함수를 호출하는 방법을 보여줍니다.

  CALL mysql.ml_drop_model_registration('MODEL_ID');

매개변수	설명
MODEL_ID	개발자가 정의한 모델 엔드포인트의 고유 ID입니다.

mysql.ml_list_registered_model()

다음은 모델 엔드포인트 정보를 나열하는 데 사용되는 mysql.ml_list_registered_model() SQL 함수를 호출하는 방법을 보여줍니다.

  SELECT mysql.ml_list_registered_model('MODEL_ID');

매개변수	설명
MODEL_ID	개발자가 정의한 모델 엔드포인트의 고유 ID입니다.

mysql.cloudsql_ml_models

다음은 모든 모델 엔드포인트의 모델 엔드포인트 정보를 나열하는 데 사용되는 mysql.cloudsql_ml_models 테이블을 쿼리하는 방법을 보여줍니다.

  SELECT * FROM mysql.cloudsql_ml_models;

보안 비밀

이 참조를 사용하여 보안 비밀을 관리할 수 있는 함수의 파라미터를 알아봅니다.

mysql.ml_create_sm_secret_registration()

다음은 Secret Manager에서 만든 보안 비밀을 추가하는 데 사용되는 mysql.ml_create_sm_secret_registration() SQL 함수를 호출하는 방법을 보여줍니다.

    CALL
    mysql.ml_create_sm_secret_registration(
      'SECRET_ID',
      'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

매개변수	설명
SECRET_ID	개발자가 설정하고 이후 모델 엔드포인트를 등록할 때 사용되는 보안 비밀 ID입니다.
PROJECT_ID	보안 비밀이 포함된 Google Cloud 프로젝트의 ID입니다. 이 프로젝트는 Cloud SQL 인스턴스가 포함된 프로젝트와 다를 수 있습니다.
SECRET_MANAGER_SECRET_ID	보안 비밀을 만들 때 Secret Manager에 설정된 보안 비밀 ID입니다.
VERSION_NUMBER	보안 비밀 ID의 버전 번호입니다.

mysql.ml_alter_sm_secret_registration()

다음은 보안 비밀 정보를 업데이트하는 데 사용되는 mysql.ml_alter_sm_secret_registration() SQL 함수를 호출하는 방법을 보여줍니다.

  CALL
    mysql.ml_alter_sm_secret_registration(
      'SECRET_ID',
      'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

매개변수	설명
SECRET_ID	개발자가 설정하고 이후 모델 엔드포인트를 등록할 때 사용되는 보안 비밀 ID입니다.
PROJECT_ID	보안 비밀이 포함된 Google Cloud 프로젝트의 ID입니다. 이 프로젝트는 Cloud SQL 인스턴스가 포함된 프로젝트와 다를 수 있습니다.
SECRET_MANAGER_SECRET_ID	보안 비밀을 만들 때 Secret Manager에 설정된 보안 비밀 ID입니다.
VERSION_NUMBER	보안 비밀 ID의 버전 번호입니다.

mysql.ml_drop_sm_secret_registration()

다음은 보안 비밀을 삭제하는 데 사용되는 mysql.ml_drop_sm_secret_registration() SQL 함수를 호출하는 방법을 보여줍니다.

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

매개변수	설명
SECRET_ID	개발자가 설정하고 이후 모델 엔드포인트를 등록할 때 사용되는 보안 비밀 ID입니다.

예측 함수

이 참조를 사용하여 임베딩을 생성하거나 예측을 호출할 수 있는 함수의 파라미터를 알아봅니다.

mysql.ml_embedding()

다음은 임베딩을 생성하는 방법을 보여줍니다.

SELECT
  mysql.ml_embedding(
    'MODEL_ID',
    'CONTENT');

매개변수	설명
MODEL_ID	개발자가 정의한 모델 엔드포인트의 고유 ID입니다.
CONTENT	벡터 임베딩으로 변환할 텍스트입니다.

텍스트 임베딩을 생성하는 SQL 쿼리의 예시는 예시를 참조하세요.

mysql.ml_predict_row()

다음은 예측을 호출하는 방법을 보여줍니다.

SELECT
  mysql.ml_predict_row(
    'MODEL_ID',
    'REQUEST_BODY');

매개변수	설명
MODEL_ID	개발자가 정의한 모델 엔드포인트의 고유 ID입니다.
REQUEST_BODY	JSON 형식의 예측 호출의 파라미터입니다.

예측을 호출하는 SQL 쿼리의 예시는 예시를 참조하세요.

변환 함수

이 참조를 사용하여 입력 및 출력 변환 함수의 파라미터를 알아봅니다.

입력 변환 함수

다음은 텍스트 임베딩 모델 엔드포인트의 예측 함수 서명을 보여줍니다.

  CREATE FUNCTION IF NOT EXISTS
  INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

매개변수	설명
INPUT_TRANSFORM_FUNCTION	해당 예측 함수 입력을 모델 엔드포인트별 입력으로 변환하는 함수입니다.

출력 변환 함수

다음은 텍스트 임베딩 모델 엔드포인트의 예측 함수 서명을 보여줍니다.

  CREATE FUNCTION IF NOT EXISTS
  OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

매개변수	설명
OUTPUT_TRANSFORM_FUNCTION	모델 엔드포인트별 출력을 예측 함수 출력으로 변환하는 함수입니다.

변환 함수 예시

모델 엔드포인트의 변환 함수를 만드는 방법을 더 잘 이해하려면 JSON 입력과 출력이 필요한 커스텀 호스팅 텍스트 임베딩 모델 엔드포인트를 사용하는 것이 좋습니다.

다음 예시 curl 요청은 프롬프트와 모델 엔드포인트를 기반으로 임베딩을 만듭니다.

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["Cloud SQL Embeddings"]}'

다음과 같은 응답 예시가 반환됩니다.

[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]

이 입력과 응답을 바탕으로 다음을 추론할 수 있습니다.

• 모델은 prompt 필드를 통해 JSON 입력을 예상합니다. 이 필드는 입력 배열을 허용합니다. mysql.ml_embedding() 함수는 행 수준 함수이므로 한 번에 텍스트 입력 하나를 예상합니다. 따라서 단일 요소로 배열을 빌드하는 입력 변환 함수를 만들어야 합니다.

• 모델의 응답은 모델에 입력된 프롬프트마다 하나씩 있는 임베딩 배열입니다. mysql.ml_embedding() 함수는 행 수준 함수이므로 한 번에 입력 하나를 반환합니다. 따라서 배열에서 임베딩을 추출하는 데 사용할 수 있는 출력 변환 함수를 만들어야 합니다.

다음 예시에서는 이 모델 엔드포인트가 모델 엔드포인트 관리에 등록될 때 사용되는 입력 및 출력 변환 함수를 보여줍니다.

입력 변환 함수

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC

BEGIN
  RETURN JSON_OBJECT('prompt', JSON_ARRAY(input_text));
END $$

출력 변환 함수

CREATE FUNCTION IF NOT EXISTS cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS BLOB
DETERMINISTIC

BEGIN
  RETURN STRING_TO_VECTOR(
         JSON_EXTRACT(
              content,
              '$.predictions[0].embeddings.values'
            )
    );

END $$
DELIMITER ;

HTTP header generation function

The following shows signature for the header generation function that can be used with the `mysql.ml_embedding()` prediction function when registering other text embedding model endpoints.

  CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

For the mysql.ml_predict_row() prediction function, the signature is as follows:

CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON DETERMINISTIC;

Parameter	Description
GENERATE_HEADERS	The function to generate custom headers. You can also pass the authorization header generated by the header generation function while registering the model endpoint.

Header generation function example

To better understand how to create a function that generates output in JSON key value pairs that are used as HTTP headers, consider a custom-hosted text embedding model endpoint.

The following example curl request passes the version HTTP header, which is used by the model endpoint:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["Cloud SQL Embeddings"]}'

The model expects text input through the version field and returns the version value in JSON format. The following example shows the header generation function that is used for this text embedding model endpoint when it is registered with model endpoint management:

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC
BEGIN
  RETURN JSON_OBJECT('version', '2024-01-01');
END;
$$
DELIMITER ;