EXECUTE INFERENCE JOB SERVICE

EXECUTE INFERENCE JOB SERVICE

Snowflake Model Registry의 모델에 대해 Snowpark Container Services(SPCS) 작업(job)으로 배치 추론(batch inference)을 실행하는 명령이에요. 이 명령은 snowflake-ml-python API의 run_batch 메서드에 해당하는 SQL 예요.

출처: 문서

본문

컴퓨팅 풀, 배치 추론 작업 명세, 입력 데이터 소스(쿼리 또는 스테이지), 실행할 모델을 제공해요. Snowflake는 입력에 대해 추론을 실행하고 결과를 명세에 지정한 출력 스테이지에 써요. 모든 컨테이너가 종료되면 작업이 완료돼요.

기본적으로 작업은 비동기로 실행돼요. 명령은 작업이 백그라운드에서 실행되는 동안 반환돼요. (모델의 컨테이너 이미지를 먼저 빌드해야 하면 명령은 이미지 빌드가 끝날 때까지 기다렸다가 반환해요.) DESCRIBE SERVICE 명령으로 작업 완료를 폴링한 다음 SYSTEM$WAIT_FOR_SERVICES 함수를 호출하여 작업 완료를 기다릴 수 있어요. 명령이 모든 컨테이너가 종료된 후에만 끝나도록 동기적으로 실행하려면 ASYNC = FALSE를 지정해요.

작업 서비스가 완료된 후 Snowflake는 비용을 줄이기 위해 작업 서비스에 할당된 리소스를 자동으로 정리해요. DESCRIBE SERVICE와 SHOW SERVICES 명령으로 최대 30일 동안 작업 메타데이터에 접근할 수 있어요. 30일이 지나면 Snowflake가 자동으로 작업을 삭제해요.

명령 파라미터는 특정 순서로 지정해야 해요.

구문 (Syntax)

EXECUTE INFERENCE JOB SERVICE
  IN COMPUTE POOL <compute_pool_name>
  WITH SPECIFICATION <specification_text>
  FROM { ( <subquery> ) | @[<namespace>.]<stage_name>[/<path>] }
  MODEL = [<db>.<schema>.]<model_name>
  [ VERSION = <version_or_alias> ]
  [ FUNCTION = '<function_name>' ]
  [ NAME = [<db>.<schema>.]<name> ]
  [ ASYNC = { TRUE | FALSE } ]
  [ REPLICAS = <num> ]

필수 파라미터 (Required parameters)

  • IN COMPUTE POOL compute_pool_name — 추론 작업을 실행할 계정의 컴퓨팅 풀 이름을 지정해요.
  • WITH SPECIFICATION specification_text — 인라인 YAML로 배치 추론 작업 명세를 지정해요. 명세 문자열의 시작과 끝을 구분하려면 한 쌍의 달러 기호($$)를 사용할 수 있어요.
  • FROM { ( subquery ) | @[namespace.]stage_name[/path] } — 추론의 입력 데이터를 다음 중 하나로 지정해요:
    • 입력 행을 생성하는 하위 쿼리; 예: ( SELECT id, feature_1 FROM my_table ).
    • 입력 파일을 참조하는 스테이지 경로; 예: @my_db.my_schema.my_stage/data/. 파일 기반 입력에는 스테이지 경로를 사용해요.
  • MODEL = [db.schema.]model_name — 추론을 실행할 Snowflake Model Registry의 모델을 지정해요. 데이터베이스와 스키마를 생략하면 Snowflake는 세션의 현재 데이터베이스와 스키마를 사용해요.

선택 파라미터 (Optional parameters)

  • VERSION = version_or_alias — 사용할 모델 버전(또는 버전 별칭)을 지정해요. 기본값: 모델의 기본 버전.
  • FUNCTION = 'function_name' — 호출할 모델 함수(메서드)의 이름을 지정해요. 예: 'predict'. 모델 버전에 사용 가능한 함수를 나열하려면 SHOW FUNCTIONS IN MODEL <model_name> VERSION <version>을 실행해요. 기본값: 단일 함수를 노출하는 모델의 경우 그 함수.
  • NAME = [db.schema.]name — 작업처럼 실행되는 서비스의 이름(즉 식별자)을 지정해요. 서비스가 생성되는 스키마 내에서 고유해야 해요. 특수 문자나 대소문자 구분 이름에 대한 따옴표 이름은 지원되지 않아요. 이 제약은 서비스를 만드는 데이터베이스와 스키마 이름에도 적용돼요. 기본값: 지정하지 않으면 Snowflake가 <db>.<schema>.BATCH_INFERENCE_<UUID> 형식의 이름을 생성해요.
  • ASYNC = { TRUE | FALSE } — 작업을 비동기로 실행할지 여부를 지정해요. TRUE면 명령이 작업이 실행되는 동안 반환돼요(필요한 경우 이미지 빌드 대기 후). FALSE면 명령은 모든 컨테이너가 종료된 후에만 끝나요. 기본값: TRUE
  • REPLICAS = num — 실행할 작업 복제본 수를 지정해요. 기본값: 1.

명세 (Specification)

명세는 배치 추론 작업이 어떻게 실행되고 결과를 어디에 쓸지 구성하는 YAML 문서예요. 다음 최상위 섹션을 지원해요. output만 필수예요.

  • output (필수) — 작업이 결과를 쓰는 위치를 구성해요.
    • stage_location (필수): 결과의 기본 스테이지 위치. Snowflake는 각 작업의 출력을 이 위치의 작업별 하위 디렉토리인 <stage_location>/<job_name>/에 써요. 여기서 <job_name>은 작업의 정규화되지 않은 이름이에요(NAME 파라미터에서 가져오거나, 지정하지 않으면 BATCH_INFERENCE_<UUID> 형식으로 자동 생성).
    • mode: 출력 위치에 이미 파일이 있을 때의 동작. error(기본값)는 작업을 실패시키고, overwrite는 기존 파일을 먼저 제거해요.
  • resources — 작업 컨테이너에 요청되는 컴퓨팅 리소스를 구성해요.
    • cpu_requests: CPU 기반 추론의 CPU 한도. 정수, 분수 또는 문자열 값. 생략하면 작업이 노드의 모든 vCPU를 사용해요.
    • memory_requests: 메모리 한도. 단위가 있는 정수 또는 분수 값(예: 8GiB 또는 512MiB). 생략하면 작업이 노드의 모든 메모리를 사용해요.
    • gpu_requests: GPU 기반 추론의 GPU 수. 정수 또는 문자열 값. 생략하면 작업이 CPU에서 실행돼요.
  • inference — 추론 실행을 조정해요.
    • num_workers: 요청을 병렬로 처리하는 서비스 인스턴스당 워커 수. CPU 기반 추론은 기본적으로 2 * vCPU + 1, GPU 기반 추론은 1.
    • max_batch_rows: 단일 배치에서 처리할 최대 행 수. 생략하면 자동 결정되며, 값이 클수록 처리량이 향상될 수 있어요.
    • engine_options: 추론 엔진 설정.
      • engine: 추론 엔진. DEFAULT, VLLM, PYTHON_GENERIC 중 하나.
      • engine_args_override: 재정의할 엔진 인자 목록(예: vLLM용 --max-model-len=18048).
  • input — 입력 행이 처리되는 방식을 구성해요.
    • params: 모델 추론 파라미터의 사전(예: LLM용 temperature 또는 top_k). 모델 함수에 키워드 인자로 전달돼요.
    • column_handling: 입력 열을 파일 처리 옵션에 매핑하여, 모델이 스테이지 경로 문자열 대신 파일의 내용을 받도록 해요. 각 열 이름에 대해 다음을 제공해요:
      • input_format: 열 값을 해석하는 방법. 지원 값: full_stage_path(값은 파일의 전체 스테이지 경로).
      • convert_to: 파일 내용이 모델에 전달되는 인코딩. raw_bytes, base64, base64_data_url 중 하나.
    • partition_column: 입력을 분할 기준으로 하는 열의 이름. 각 파티션은 독립적으로 처리되며, 파티션 모델에 유용해요.
  • image_build — 작업의 컨테이너 이미지 빌드를 구성해요.
    • image_repo: 작업의 컨테이너 이미지에 사용할 이미지 리포지토리. 생략하면 작업이 기본 리포지토리를 사용해요.
    • force_rebuild: 캐시된 이미지가 있어도 컨테이너 이미지를 다시 빌드할지 여부. 기본값: false.

예를 들어:

output:
  stage_location: "@my_db.my_schema.my_stage/results/"
resources:
  cpu_requests: "2"
  memory_requests: "8GiB"
inference:
  num_workers: 2
  max_batch_rows: 2048

접근 제어 요구사항 (Access control requirements)

이 작업을 실행하는 역할은 최소한 다음 권한을 가져야 해요:

Privilege Object Notes
CREATE SERVICE Schema 작업 서비스가 생성되는 스키마.
USAGE Compute pool
USAGE Model MODEL 절이 참조하는 모델.
READ Stage 입력 스테이지와 명세가 저장된 스테이지.
WRITE Stage 결과가 쓰이는 출력 스테이지(명세의 output.stage_location).
READ Image Repository 명세가 참조하는 이미지의 리포지토리.

스키마에서 객체를 운영하려면 부모 데이터베이스에 대한 권한이 하나 이상, 부모 스키마에 대한 권한이 하나 이상 필요해요.

사용 메모 (Usage notes)

  • EXECUTE INFERENCE JOB SERVICE를 호출할 때 구문에 표시된 순서대로 파라미터를 지정해요: 컴퓨팅 풀, 명세, 입력 소스(FROM), 모델, 그리고 나머지 선택 속성.
  • 완료를 표시하기 위해 작업은 출력 디렉토리에 _SUCCESS 완료 파일을 써요. 부분 결과를 읽지 않으려면 이 파일이 나타난 후에만 출력을 읽어요.
  • 메타데이터에 관해: Snowflake 서비스 사용 시 개인 데이터(User 객체 외), 민감한 데이터, 수출 통제 데이터 또는 기타 규제 데이터를 메타데이터로 입력하지 않도록 해야 해요.

예시 (Examples)

쿼리에서 배치 추론 실행

특정 모델 버전과 함수를 사용하여 하위 쿼리가 생성한 행에 대해 추론을 비동기(기본값)로 실행해요.

EXECUTE INFERENCE JOB SERVICE
  IN COMPUTE POOL my_compute_pool
  WITH SPECIFICATION $$
  output:
    stage_location: "@my_db.my_schema.my_stage/results/"
  $$
  FROM ( SELECT id, review_text FROM my_db.my_schema.reviews WHERE lang = 'en' )
  MODEL = my_db.my_schema.sentiment_model
  VERSION = v1
  FUNCTION = 'predict';

명령이 ASYNC 파라미터를 지정하지 않으므로 작업은 비동기로 실행되고 명령은 즉시 반환돼요.

GPU에서 스테이지의 배치 추론 실행

스테이지의 파일에 대해 GPU를 요청하고 vLLM 추론 엔진을 사용하여 추론을 동기적으로 실행해요.

EXECUTE INFERENCE JOB SERVICE
  IN COMPUTE POOL my_gpu_pool
  WITH SPECIFICATION $$
  resources:
    gpu_requests: "1"
  inference:
    engine_options:
      engine: VLLM
  output:
    stage_location: "@my_db.my_schema.my_stage/results/"
  $$
  FROM @my_db.my_schema.input_stage/images/
  MODEL = my_db.my_schema.image_classifier
  ASYNC = FALSE;

여러 복제본으로 배치 추론 작업 실행

명명된 작업 서비스로 추론 작업의 3개 복제본을 실행하고, 명세에서 워커 수와 배치 크기를 조정해요.

EXECUTE INFERENCE JOB SERVICE
  IN COMPUTE POOL my_pool
  WITH SPECIFICATION $$
  inference:
    num_workers: 2
    max_batch_rows: 2048
  output:
    stage_location: "@my_db.my_schema.my_stage/results/"
  $$
  FROM ( SELECT * FROM my_db.my_schema.input_table )
  MODEL = my_db.my_schema.my_model
  NAME = my_db.my_schema.my_inference_job
  REPLICAS = 3;

각 복제본의 상태를 찾으려면 SHOW SERVICE INSTANCES IN SERVICE 명령을 사용해요:

SHOW SERVICE INSTANCES IN SERVICE my_db.my_schema.my_inference_job;

출력에서 instance_id와 status 열이 복제본 번호와 그 상태를 보여줘요.

열 처리로 멀티모달 추론 실행

스테이지 경로로 참조되는 파일(이미지, 오디오, 비디오 등)에 대해 멀티모달 추론을 실행해요. 각 입력 행은 파일의 전체 스테이지 경로를 가지고 있고, input.column_handling은 Snowflake에게 그 파일을 읽어 모델에 내용을 전달하라고 지시해요. 처리할 열에 대해 input_format을 full_stage_path로, convert_to를 모델이 기대하는 인코딩(raw_bytes, base64, base64_data_url)으로 설정해요. column_handling 키는 입력 열 이름과 일치해요.

이 예시에서 FROM 하위 쿼리가 생성한 IMAGES 열은 @my_db.my_schema.my_stage/data/cat.jpeg 같은 전체 스테이지 경로를 보유해요.

EXECUTE INFERENCE JOB SERVICE
  IN COMPUTE POOL my_compute_pool
  WITH SPECIFICATION $$
  input:
    column_handling:
      IMAGES:
        input_format: full_stage_path
        convert_to: raw_bytes
  output:
    stage_location: "@my_db.my_schema.my_stage/results/"
  $$
  FROM ( SELECT images FROM my_db.my_schema.pet_images )
  MODEL = my_db.my_schema.image_classifier;

더 알아보기 (Learn more)