모델 엔드포인트 관리 참조

이 페이지에는 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의 경우 제공업체를 google(Vertex AI 모델 엔드포인트의 경우), open_ai(OpenAI 모델 엔드포인트의 경우), 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 보안 비밀이 포함된 Trusted Cloud by S3NS 프로젝트의 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 보안 비밀이 포함된 Trusted Cloud by S3NS 프로젝트의 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 형식으로 반환합니다. 다음 예시에서는 이 텍스트 임베딩 모델 엔드포인트가 모델 엔드포인트 관리에 등록될 때 사용되는 헤더 생성 함수를 보여줍니다.

sql 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을 생성하는 함수입니다.