Cloud SQL에서 원격 AI 모델 등록 및 호출 개요

이 페이지에서는 Cloud SQL에서 AI 모델 엔드포인트를 등록하고 모델 엔드포인트 관리로 예측을 호출하는 방법을 설명합니다. 프로덕션 환경에서 AI 모델을 사용하려면 벡터 임베딩 생성 및 관리를 참고하세요.

개요

모델 엔드포인트 관리를 사용하면 모델 엔드포인트를 등록하고, Cloud SQL 인스턴스에서 모델 엔드포인트 메타데이터를 관리하고, SQL 쿼리를 사용하여 모델과 상호작용할 수 있습니다. 이러한 모델을 사용하여 벡터 임베딩을 생성하거나 예측을 호출할 수 있습니다.

모델 엔드포인트 관리를 사용하여 다음 모델 유형을 등록할 수 있습니다.

  • Vertex AI 텍스트 임베딩 모델
  • Trusted Cloud by S3NS내의 네트워크에 호스팅되는 맞춤 호스팅 텍스트 임베딩 모델

  • JSON 기반 API가 있는 일반 모델. 이러한 모델의 예는 다음과 같습니다.

    • Vertex AI Model Garden의 gemini-flash 모델
    • OpenAI 모델의 open_ai 모델
    • Trusted Cloud by S3NS내의 네트워크에 호스팅된 모델

작동 방식

모델 엔드포인트 관리를 사용하여 다음을 준수하는 모델 엔드포인트를 등록할 수 있습니다.

  • 모델 입력 및 출력은 JSON 형식을 지원합니다.
  • REST 프로토콜을 사용하여 모델을 호출할 수 있습니다.

모델 엔드포인트를 모델 엔드포인트 관리에 등록하면 모델 엔드포인트 관리가 모델 참조로 고유한 모델 ID를 각 엔드포인트에 등록합니다. 이 모델 ID를 사용하여 다음과 같이 모델을 쿼리할 수 있습니다.

  • 텍스트 프롬프트를 숫자 벡터로 변환하는 임베딩을 생성합니다. 인스턴스에서 벡터 임베딩 지원을 사용 설정하면 생성된 임베딩을 벡터 데이터로 저장할 수 있습니다. 자세한 내용은 인스턴스에서 벡터 임베딩 사용 설정 및 사용 중지를 참고하세요.

  • 트랜잭션 내에서 SQL을 사용하여 모델을 호출하려면 예측을 호출합니다.

Cloud SQL 인스턴스로 원격 AI 모델을 등록하고 호출하려면 인스턴스에 유지보수 버전 MYSQL_VERSION.R20250531.01_14 이상이 설치되어 있어야 합니다. 인스턴스에서 MYSQL_VERSION.R20250531.01_14보다 이전 유지보수 버전을 실행하는 경우 Cloud SQL과 Vertex AI의 통합에 설명된 대로 다음 함수만 사용할 수 있습니다.

인스턴스를 유지보수 버전 MYSQL_VERSION.R20250531.01_14 이상으로 업그레이드하려면 셀프서비스 유지보수를 참고하세요. 인스턴스를 업그레이드한 후 다음 함수를 사용할 수 있습니다.

또한 등록된 모델 제공업체와 함께 다음 함수를 사용할 수 있습니다.

필수 데이터베이스 사용자 권한

원격 AI 모델을 등록하고 호출하려면 mysql.* 권한에 SELECT 및 EXECUTE가 부여된 MySQL 데이터베이스 사용자로 로그인해야 합니다.

기본적으로 cloudsqlsuperuser 역할이 있는 사용자는 이러한 권한을 보유하거나 사용자를 만들어 필요한 권한을 부여할 수 있습니다.

Cloud SQL의 cloudsqlsuperuser 역할에 대한 자세한 내용은 MySQL 8.0 사용자 권한 및 MySQL 8.4 사용자 권한을 참고하세요.

주요 개념

모델 엔드포인트 관리를 사용하기 전에 모델에 연결하고 이를 사용하는 데 필요한 개념을 파악하세요.

모델 제공업체

모델 제공업체는 지원되는 모델 호스팅 제공업체입니다. 다음 표에는 사용하는 모델 제공업체에 따라 설정해야 하는 모델 제공업체 값이 나와 있습니다.

모델 제공업체 함수에서 다음으로 설정
Vertex AI(Gemini 포함) google
Anthropic anthropic
Hugging Face hugging_face
OpenAI open_ai
Vertex AI, Anthropic, Hugging Face, OpenAI
외부에서 호스팅되는 기타 모델		 custom

기본 모델 제공업체는 custom입니다.

모델 유형

모델 유형은 AI 모델 유형입니다. 모델 엔드포인트를 등록할 때 엔드포인트의 text_embedding 또는 generic 모델 유형을 설정할 수 있습니다.

Vertex AI를 모델 제공업체로 사용하는 경우 엔드포인트가 자동으로 지원되므로 모델 엔드포인트를 등록할 필요가 없습니다. 기본적으로 Vertex AI에서는 text-embedding-005 모델을 사용합니다.

기타 텍스트 임베딩 모델
기타 텍스트 임베딩 모델의 경우 모델에서 지원하는 입력 및 출력 형식을 처리하는 변환 함수를 만들어야 합니다. 원하는 경우 모델에 필요한 커스텀 헤더를 생성하는 HTTP 헤더 생성 함수를 사용할 수 있습니다.

이러한 모델의 모델 유형은 text_embedding입니다.

일반 모델
모델 엔드포인트 관리는 텍스트 임베딩 모델 외에도 다른 모든 모델 유형의 등록도 지원합니다. 일반 모델의 예측을 호출하려면 mysql.ml_predict_row() 함수를 사용하세요. 해당 모델의 특정 요청 엔드포인트 및 HTTP 헤더와 같은 모델 엔드포인트 메타데이터를 설정할 수 있습니다.
일반 모델 엔드포인트를 등록할 때는 변환 함수를 전달할 수 없습니다. 예측을 호출할 때 함수의 입력이 JSON 형식이고 JSON 출력을 파싱하여 최종 출력을 가져오는지 확인합니다.
이러한 모델의 모델 유형은 generic입니다. generic은 기본 모델 유형이므로 이 유형의 모델 엔드포인트를 등록하는 경우 모델 유형을 설정하는 것은 선택사항입니다.
Vertex AI에서 모델 엔드포인트 관리는 gemini-2.5-flash 모델에 대한 사전 등록된 지원을 포함합니다.

인증 방식

MySQL용 Cloud SQL 인스턴스에서 벡터 임베딩 지원을 사용 설정한 다음 모델에 액세스할 인증 방법을 지정할 수 있습니다. 이러한 메서드를 설정하는 것은 선택사항이며 모델에 액세스하기 위해 인증해야 하는 경우에만 필요합니다.

Vertex AI 모델의 경우 Cloud SQL 서비스 계정이 인증에 사용됩니다. 다른 모델의 경우 Secret Manager에 보안 비밀로 저장된 API 키 또는 Bearer 토큰을 mysql.ml_create_sm_secret_registration() SQL 함수와 함께 사용할 수 있습니다.

다음 표에는 설정할 수 있는 인증 방법이 나와 있습니다.

인증 방법 함수에서 다음으로 설정 모델 제공업체
Cloud SQL 서비스 에이전트 auth_type_cloudsql_service_agent_iam Vertex AI 제공업체
Secret Manager auth_type_secret_manager Vertex AI 외부에서 호스팅되는 모델

예측 함수

mysql.ml_embedding()
등록된 텍스트 임베딩 모델 엔드포인트를 호출하여 임베딩을 생성합니다. Vertex AI의 모든 임베딩 모델에 대한 기본 제공 지원이 포함되어 있습니다.
기본 제공 지원이 없는 텍스트 임베딩 모델의 경우 입력 및 출력 파라미터는 모델에 고유하며 함수에서 모델을 호출하려면 변환이 필요합니다. 예측 함수의 입력을 모델별 입력으로 변환하는 변환 입력 함수와 모델별 출력을 예측 함수 출력으로 변환하는 변환 출력 함수를 만듭니다.
mysql.ml_predict_row()
엔드포인트에서 예측을 호출하는 JSON 기반 API를 지원하는 경우 등록된 일반 모델 엔드포인트를 호출합니다.

변환 함수

변환 함수는 입력을 모델이 이해하는 형식으로 수정하고 모델 응답을 예측 함수가 예상하는 형식으로 변환합니다. 변환 함수는 기본 제공 지원 없이 text-embedding 모델 엔드포인트를 등록할 때 사용됩니다. 변환 함수의 서명은 모델 유형의 예측 함수에 따라 다릅니다.

generic 모델 엔드포인트를 등록할 때는 변환 함수를 사용할 수 없습니다.

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

// define custom model specific input/output transform functions.
CREATE FUNCTION IF NOT EXISTS input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

// the returned BLOB should be of type VECTOR
CREATE FUNCTION IF NOT EXISTS output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

변환 함수를 만드는 방법에 관한 자세한 내용은 변환 함수 예시를 참조하세요.

HTTP 헤더 생성 함수

HTTP 헤더 생성 함수는 HTTP 헤더로 사용되는 JSON 키-값 쌍으로 출력을 생성합니다. 예측 함수의 서명은 헤더 생성 함수의 서명을 정의합니다.

다음 예시는 mysql.ml_embedding() 예측 함수의 서명을 보여줍니다.

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

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

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON DETERMINISTIC;

헤더 생성 함수를 만드는 방법에 관한 자세한 내용은 헤더 생성 함수 예시를 참조하세요.

제한사항

  • 모델 등록 또는 보안 비밀 관리 함수를 실행하면 세션에서 열린 트랜잭션이 암시적으로 커밋됩니다. 예측 함수는 트랜잭션을 암시적으로 커밋하지 않습니다.

  • mysqldump를 사용하여 데이터베이스를 내보내거나 가져오면 모델 엔드포인트 카탈로그가 내보내지지 않습니다.

  • 변환 함수가 포함된 사용자 데이터베이스의 이름에는 마침표 문자('.')가 포함될 수 없습니다. 예를 들어 my.sql이라는 데이터베이스는 지원되지 않습니다.

  • 모델 엔드포인트 관리는 MySQL용 Cloud SQL 버전 8.0.36 이상에서만 사용할 수 있습니다.

다음 단계