모델 엔드포인트 관리 참조

이 페이지에는 google_ml_integration 확장 프로그램에서 모델 엔드포인트를 등록하고 관리하기 위해 제공하는 다양한 함수의 매개변수가 나와 있습니다. 이 페이지에는 모델 엔드포인트 관리를 사용하여 관리할 수 있는 보안 비밀도 표시됩니다. 프로덕션 환경에서 AI 모델을 사용하려면 Cloud SQL을 사용하여 생성형 AI 애플리케이션 빌드를 참고하세요.

모델

이 참조를 사용하여 모델 엔드포인트를 관리할 수 있는 함수의 매개변수를 알아보세요.

google_ml.create_model()

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

  CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');
매개변수 필수 설명
MODEL_ID 모든 모델 엔드포인트에 필요 사용자가 정의한 모델 엔드포인트의 고유 ID입니다.
REQUEST_URL

기본 지원이 포함된 텍스트 임베딩 모델 엔드포인트의 경우 선택사항

 다른 텍스트 임베딩 및 일반 모델 엔드포인트를 추가할 때의 모델별 엔드포인트입니다.

함수가 내장 모델 엔드포인트에 대해 생성하는 요청 URL은 클러스터의 프로젝트 및 리전 또는 위치를 참조합니다. 다른 프로젝트를 참조하려면 model_request_url를 명시적으로 지정해야 합니다.

맞춤 호스팅된 모델 엔드포인트의 경우 인터넷을 통해 모델 엔드포인트에 액세스할 수 있는지 확인합니다.
PROVIDER_ID 기본 지원이 포함된 텍스트 임베딩 모델 엔드포인트에 필요 모델 엔드포인트의 제공업체입니다. 기본값은 custom입니다. Cloud SQL의 경우 Vertex AI 모델 엔드포인트의 경우 google, OpenAI 모델 엔드포인트의 경우 open_ai, Anthropic 모델 엔드포인트의 경우 anthropic, Hugging Face 모델 엔드포인트의 경우 hugging_face, 맞춤 호스팅 모델 엔드포인트의 경우 custom로 제공자를 설정합니다.
MODEL_TYPE 일반 모델 엔드포인트의 경우 선택사항 모델 유형입니다. 이 값은 텍스트 임베딩 모델 엔드포인트의 경우 text_embedding로, 다른 모든 모델 엔드포인트의 경우 generic로 설정할 수 있습니다.
MODEL_QUALIFIED_NAME OpenAI 모델 엔드포인트에 필요하며 다른 모델 엔드포인트에는 선택사항입니다. 모델 엔드포인트에 여러 버전이 있거나 모델 엔드포인트에서 정의하는 경우의 정규화된 이름입니다(예: textembedding-gecko@001 또는 textembedding-gecko@002). textembedding-gecko@001 모델은 모델 엔드포인트 관리에 사전 등록되어 있으므로 textembedding-gecko@001를 모델 ID로 사용하여 임베딩을 생성할 수 있습니다.
AUTH_TYPE 모델 엔드포인트에 특정 인증 요구사항이 없는 한 선택사항 모델 엔드포인트에서 사용하는 인증 유형입니다. Vertex AI 모델의 경우 cloudsql_service_agent_iam로, 다른 제공업체의 경우 secret_manager로 설정할 수 있습니다.
AUTH_ID Vertex AI 모델 엔드포인트에는 설정하지 마세요. Secret Manager에 비밀을 저장하는 다른 모든 모델 엔드포인트에는 필요합니다. 설정하고 나중에 모델 엔드포인트를 등록할 때 사용하는 비밀 ID입니다.
GENERATE_HEADER_FUNCTION 선택사항 맞춤 헤더를 생성하도록 설정한 함수 이름입니다. 이 함수의 서명은 google_ml.predict_row() 함수에 따라 다릅니다. HTTP 헤더 생성 함수를 참고하세요.
INPUT_TRANSFORM_FUNCTION 내장 지원이 있는 텍스트 임베딩 모델 엔드포인트의 경우 선택사항입니다. 일반 모델 엔드포인트에는 설정하지 마세요. 해당 예측 함수의 입력을 모델별 입력으로 변환하는 함수입니다. 변환 함수를 참고하세요.
OUTPUT_TRANSFORM_FUNCTION 내장 지원이 있는 텍스트 임베딩 모델 엔드포인트의 경우 선택사항입니다. 일반 모델 엔드포인트에는 설정하지 마세요. 모델별 출력을 예측 함수 출력으로 변환하는 함수입니다. 변환 함수를 참고하세요.

google_ml.alter_model()

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

    CALL
    google_ml.alter_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

google_ml.drop_model()

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

  CALL google_ml.drop_model('MODEL_ID');
매개변수 설명
MODEL_ID 사용자가 정의한 모델 엔드포인트의 고유 ID입니다.

google_ml.list_model()

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

  SELECT google_ml.list_model('MODEL_ID');
매개변수 설명
MODEL_ID 사용자가 정의한 모델 엔드포인트의 고유 ID입니다.

google_ml.model_info_view

다음은 모든 모델 엔드포인트의 모델 엔드포인트 정보를 나열하는 데 사용되는 google_ml.model_info_view 뷰를 호출하는 방법을 보여줍니다.

  SELECT * FROM google_ml.model_info_view;

보안 비밀

이 참조를 사용하여 비밀을 관리할 수 있는 함수의 매개변수를 알아보세요.

google_ml.create_sm_secret()

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

    CALL
    google_ml.create_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => '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의 버전 번호입니다.

google_ml.alter_sm_secret()

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

  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => '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의 버전 번호입니다.

google_ml.drop_sm_secret()

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

  CALL google_ml.drop_sm_secret('SECRET_ID');
매개변수 설명
SECRET_ID 설정하고 나중에 모델 엔드포인트를 등록할 때 사용하는 비밀 ID입니다.

예측 함수

이 참조를 사용하여 임베딩을 생성하거나 예측을 호출할 수 있는 함수의 매개변수를 알아보세요.

google_ml.embedding()

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

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');
매개변수 설명
MODEL_ID 사용자가 정의한 모델 엔드포인트의 고유 ID입니다.
CONTENT 벡터 임베딩으로 변환할 텍스트입니다.

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

google_ml.predict_row()

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

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');
매개변수 설명
MODEL_ID 사용자가 정의한 모델 엔드포인트의 고유 ID입니다.
REQUEST_BODY JSON 형식의 예측 함수 매개변수입니다.

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

변환 함수

이 참조를 사용하여 입력 및 출력 변환 함수의 매개변수를 알아보세요.

입력 변환 함수

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

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
매개변수 설명
INPUT_TRANSFORM_FUNCTION 상응하는 예측 함수의 입력을 모델 엔드포인트별 입력으로 변환하는 함수입니다.

출력 변환 함수

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

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];
매개변수 설명
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 입력을 예상합니다. 이 필드는 입력 배열을 허용합니다. google_ml.embedding() 함수는 행 수준 함수이므로 한 번에 하나의 텍스트 입력을 예상합니다. 따라서 단일 요소로 배열을 빌드하는 입력 변환 함수를 만들어야 합니다.

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

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

입력 변환 함수

CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;

출력 변환 함수

CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
RETURN transformed_output;
END;
$$;

HTTP 헤더 생성 함수

다음은 다른 텍스트 임베딩 모델 엔드포인트를 등록할 때 google_ml.embedding() 예측 함수와 함께 사용할 수 있는 헤더 생성 함수의 서명을 보여줍니다.

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

google_ml.predict_row() 예측 함수의 서명은 다음과 같습니다.

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;
매개변수 설명
GENERATE_HEADERS 커스텀 헤더를 생성하는 함수입니다. 모델 엔드포인트를 등록하는 동안 헤더 생성 함수에서 생성된 승인 헤더를 전달할 수도 있습니다.

헤더 생성 함수 예시

HTTP 헤더로 사용되는 JSON 키-값 쌍으로 출력을 생성하는 함수를 만드는 방법을 더 잘 이해하려면 맞춤 호스팅 텍스트 삽입 모델 엔드포인트를 참고하세요.

다음 cURL 요청 예에서는 모델 엔드포인트에서 사용하는 version HTTP 헤더를 전달합니다.

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

모델은 version 필드를 통해 텍스트 입력을 예상하고 버전 값을 JSON 형식으로 반환합니다. 다음 예는 이 텍스트 임베딩 모델 엔드포인트가 모델 엔드포인트 관리에 등록될 때 사용되는 헤더 생성 함수를 보여줍니다.

CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN json_build_object('version', '2024-01-01')::JSON;
END;
$$;

요청 URL 생성

요청 URL 생성 함수를 사용하여 내장 지원이 있는 모델 엔드포인트의 요청 URL을 추론합니다. 다음은 이 함수의 서명을 보여줍니다.

CREATE OR REPLACE FUNCTION GENERATE_REQUEST_URL(provider google_ml.model_provider, model_type google_ml.MODEL_TYPE, model_qualified_name VARCHAR(100), model_region VARCHAR(100) DEFAULT NULL)
매개변수 설명
GENERATE_REQUEST_URL 기본 제공 지원이 있는 모델 엔드포인트의 확장 프로그램에서 생성된 요청 URL을 생성하는 함수입니다.