이 페이지에는 AlloyDB Omni 버전 15.7.0에 관한 문서가 표시됩니다.
AlloyDB Omni 문서 버전으로 이동하여 다른 버전을 선택합니다.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

모델 엔드포인트 관리 참조

이 페이지에는 google_ml_integration 확장 프로그램에서 모델 엔드포인트를 등록하고 관리하기 위해 제공하는 다양한 함수의 매개변수와 모델 엔드포인트 관리를 통해 비밀의 매개변수가 나와 있습니다.

확장 프로그램 사용을 시작하려면 먼저 google_ml_integration.enable_model_support 데이터베이스 플래그를 on로 설정해야 합니다.

자세한 내용은 AI 모델용 AlloyDB Omni에서 모델 엔드포인트 관리 사용을 참고하세요.

모델

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

`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`	기본 지원이 포함된 다른 텍스트 임베딩 모델 엔드포인트의 경우 선택사항	다른 텍스트 임베딩 및 일반 모델 엔드포인트를 추가할 때의 모델별 엔드포인트입니다. PostgreSQL용 AlloyDB의 경우 `https` URL을 제공합니다. 함수가 내장 모델 엔드포인트에 대해 생성하는 요청 URL은 클러스터의 프로젝트 및 리전 또는 위치를 참조합니다. 다른 프로젝트를 참조하려면 `model_request_url`를 명시적으로 지정해야 합니다. Vertex AI 모델 엔드포인트의 요청 URL 목록은 Vertex AI 모델 엔드포인트 요청 URL을 참고하세요. 맞춤 호스팅 모델 엔드포인트의 경우 AlloyDB가 있는 네트워크에서 모델 엔드포인트에 액세스할 수 있는지 확인합니다.
`PROVIDER_ID`	기본 지원이 포함된 텍스트 임베딩 모델 엔드포인트에 필요	모델 엔드포인트의 제공업체입니다. 기본값은 `custom`입니다. 다음 중 하나로 설정합니다. Vertex AI 모델 엔드포인트의 경우 `google` OpenAI 모델 엔드포인트의 경우 `open_ai` Hugging Face 모델 엔드포인트의 경우 `hugging_face` Anthropic 모델 엔드포인트의 경우 `anthropic` 다른 제공업체의 경우 `custom`
`MODEL_TYPE`	일반 모델 엔드포인트의 경우 선택사항	모델 유형입니다. 다음 중 하나로 설정합니다. 텍스트 임베딩 모델 엔드포인트의 경우 `text_embedding` 다른 모든 모델 엔드포인트의 경우 `generic`
`MODEL_QUALIFIED_NAME`	기본 지원이 포함된 텍스트 임베딩 모델에 필요하며 다른 모델 엔드포인트의 경우 선택사항입니다.	기본 지원이 포함된 텍스트 임베딩 모델의 정규화된 전체 이름입니다. 사전 등록된 모델에 사용해야 하는 Vertex AI 정규화된 이름은 사전 등록된 Vertex AI 모델을 참고하세요. 기본 지원이 포함된 OpenAI 모델에 사용해야 하는 정규화된 이름은 기본 지원이 포함된 모델을 참고하세요.
`AUTH_TYPE`	모델 엔드포인트에 특정 인증 요구사항이 없는 한 선택사항	모델 엔드포인트에서 사용하는 인증 유형입니다. 인증에 Secret Manager를 사용하는 경우 Vertex AI 모델의 경우 `alloydb_service_agent_iam`로, 다른 제공업체의 경우 `secret_manager`로 설정할 수 있습니다. 인증 헤더를 사용하는 경우 이 값을 설정할 필요가 없습니다.
`AUTH_ID`	Vertex AI 모델 엔드포인트에는 설정하지 마세요. Secret Manager에 비밀을 저장하는 다른 모든 모델 엔드포인트에는 필요합니다.	설정하고 나중에 모델 엔드포인트를 등록할 때 사용하는 비밀 ID입니다.
`GENERATE_HEADER_FUNCTION`	선택사항	맞춤 헤더를 생성하는 함수의 이름입니다. Anthropic 모델의 경우 모델 엔드포인트 관리는 기본 버전에 사용할 수 있는 `google_ml.anthropic_claude_header_gen_fn` 함수를 제공합니다. 이 함수의 서명은 사용하는 예측 함수에 따라 다릅니다. 헤더 생성 함수를 참고하세요.
`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입니다.
`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');

각 매개변수에 설정해야 하는 값에 관한 자세한 내용은 보안 비밀 만들기를 참고하세요.

`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 쿼리의 예는 AlloyDB Omni용 변환 함수 예를 참고하세요.

`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": ["AlloyDB 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": ["AlloyDB 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;
$$;

API 키를 사용하는 헤더 생성 함수

다음 예에서는 API 키를 사용하여 인증을 설정하는 방법을 보여줍니다.

임베딩 모델

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

API_KEY를 모델 제공업체의 API 키로 바꿉니다.

일반 모델

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'anthropic-version', '2023-06-01')::JSON;
END;
$$;

API_KEY를 모델 제공업체의 API 키로 바꿉니다.

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

지원되는 모델

모델 엔드포인트 관리를 사용하여 텍스트 임베딩 또는 일반 모델 엔드포인트를 등록할 수 있습니다. 모델 엔드포인트 관리에는 사전 등록된 Vertex AI 모델과 내장 지원이 포함된 모델도 포함됩니다. 다양한 모델 유형에 관한 자세한 내용은 모델 유형을 참고하세요.

사전 등록된 Vertex AI 모델

모델 유형	모델 ID	확장 프로그램 버전
`generic`	`gemini-1.5-pro:streamGenerateContent` `gemini-1.5-pro:generateContent` `gemini-1.0-pro:generateContent`	버전 1.4.2 이상
`text_embedding`	`textembedding-gecko` `text-embedding-gecko@001`	버전 1.3 이상

기본 지원이 포함된 모델

Vertex AI

정규화된 모델 이름	모델 유형
`text-embedding-gecko@001`	`text-embedding`
`text-embedding-gecko@003`	`text-embedding`
`text-embedding-004`	`text-embedding`
`text-embedding-005`	`text-embedding`
`text-embedding-preview-0815`	`text-embedding`
`text-multilingual-embedding-002`	`text-embedding`

OpenAI

정규화된 모델 이름	모델 유형
`text-embedding-ada-002`	`text-embedding`
`text-embedding-3-small`	`text-embedding`
`text-embedding-3-large`	`text-embedding`

Anthropic

정규화된 모델 이름	모델 유형
`claude-3-opus-20240229`	`generic`
`claude-3-sonnet-20240229`	`generic`
`claude-3-haiku-20240307`	`generic`

모델 엔드포인트 관리 참조

모델

google_ml.create_model() 함수

google_ml.alter_model()

google_ml.drop_model() 함수

google_ml.list_model() 함수

뷰 google_ml.model_info_view개

보안 비밀

google_ml.create_sm_secret() 함수

google_ml.alter_sm_secret() 함수

google_ml.drop_sm_secret() 함수

예측 함수

google_ml.embedding() 함수

google_ml.predict_row() 함수

변환 함수

입력 변환 함수

출력 변환 함수

변환 함수 예시

입력 변환 함수

출력 변환 함수

HTTP 헤더 생성 함수

헤더 생성 함수 예시

API 키를 사용하는 헤더 생성 함수

임베딩 모델

일반 모델

요청 URL 생성

지원되는 모델

사전 등록된 Vertex AI 모델

기본 지원이 포함된 모델

Vertex AI

OpenAI

Anthropic

`google_ml.create_model()` 함수

`google_ml.alter_model()`

`google_ml.drop_model()` 함수

`google_ml.list_model()` 함수

뷰 `google_ml.model_info_view`개

`google_ml.create_sm_secret()` 함수

`google_ml.alter_sm_secret()` 함수

`google_ml.drop_sm_secret()` 함수

`google_ml.embedding()` 함수

`google_ml.predict_row()` 함수