자습서 1: Snowpark Container Services 서비스 생성¶

소개¶

공통 설정 을 완료하면 서비스를 만들 준비가 된 것입니다. 이 자습서에서는 입력으로 제공한 텍스트를 단순히 화면에 표시하는 (echo_service 라는) 서비스를 만듭니다. 예를 들어 입력 문자열이 “Hello World”인 경우 이 서비스는 “I said, Hello World”를 반환합니다.

이 자습서는 다음 두 부분으로 구성됩니다.

파트 1: 서비스를 만들고 테스트합니다. 이 자습서에 제공된 코드를 다운로드하고 단계별 지침을 따릅니다.

1. 이 자습서를 위한 서비스 코드를 다운로드합니다.

2. Snowpark Container Services용 Docker 이미지를 만들어 자기 계정의 리포지토리에 업로드합니다.

3. 서비스를 만들고 서비스 사양 파일과 서비스를 실행할 컴퓨팅 풀을 제공합니다.

4. 서비스와 통신하기 위한 서비스 함수를 만듭니다.

5. 서비스를 사용합니다. 서비스에 에코 요청을 보내고 응답을 확인합니다.

파트 2: 서비스를 이해합니다. 이 섹션에서는 서비스 코드의 개요를 제공하고 다양한 구성 요소가 어떻게 협력하는지 강조합니다.

1: 서비스 코드 다운로드¶

Echo 서비스를 생성하기 위한 코드(Python 애플리케이션)가 제공됩니다.

1. zip 파일 을 디렉토리에 다운로드합니다.

2. 이 파일의 압축을 풀면 각 자습서마다 하나의 디렉터리가 포함된 것을 알 수 있습니다. Tutorial-1 디렉터리에는 다음 파일이 있습니다.

   • Dockerfile

   • echo_service.py

   • templates/basic_ui.html

2: 이미지 만들기 및 업로드¶

Snowpark Container Services가 지원하는 linux/amd64 플랫폼의 이미지를 만든 다음, 해당 이미지를 계정의 이미지 리포지토리에 업로드합니다(공통 설정 참조).

리포지토리(리포지토리 URL 및 레지스트리 호스트 이름)에 대한 정보가 있어야 이미지를 만들어 업로드할 수 있습니다. 자세한 내용은 레지스트리 및 리포지토리 를 참조하십시오.

리포지토리에 대한 정보 얻기

1. 리포지토리 URL을 가져오려면 SHOW IMAGE REPOSITORIES SQL 명령을 실행하십시오.

   SHOW IMAGE REPOSITORIES;
   

   Copy

   • 출력의 repository_url 열은 URL을 제공합니다. 아래에 예가 나와 있습니다.

     <orgname>-<acctname>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository
     

   • 리포지토리 URL의 호스트 이름은 레지스트리 호스트 이름입니다. 아래에 예가 나와 있습니다.

     <orgname>-<acctname>.registry.snowflakecomputing.com
     

이미지를 만들어 리포지토리에 업로드하기

1. 터미널 창을 열고 압축을 푼 파일이 포함된 디렉터리로 변경합니다.

2. Docker 이미지를 만들려면 Docker CLI를 사용하여 다음 docker build 명령을 실행하십시오. 이 명령은 현재 작업 디렉터리(.)를 이미지 만들기에 사용할 파일의 PATH 로 지정합니다.

   docker build --rm --platform linux/amd64 -t <repository_url>/<image_name> .
   

   Copy

   • image_name 의 경우 my_echo_service_image:latest 를 사용합니다.

   예

   docker build --rm --platform linux/amd64 -t myorg-myacct.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest .
   

   Copy

3. Snowflake 계정의 리포지토리에 이미지를 업로드합니다. Docker가 사용자를 대신하여 리포지토리에 이미지를 업로드하려면 먼저 Snowflake로 Docker를 인증해야 합니다.

   1. Snowflake 레지스트리로 Docker를 인증하려면 다음 명령을 실행하십시오.

      docker login <registry_hostname> -u <username>
      

      Copy

      • username 의 경우 Snowflake 사용자 이름을 지정합니다. Docker가 비밀번호를 묻는 메시지를 표시합니다.

   2. 이미지를 업로드하려면 다음 명령을 실행하십시오.

      docker push <repository_url>/<image_name>
      

      Copy

      예

      docker push myorg-myacct.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
      

      Copy

3: 서비스 만들기¶

이 섹션에서는 서비스를 만들고 서비스와 통신하기 위한 서비스 함수도 만듭니다.

서비스를 만들려면 다음이 필요합니다.

• 컴퓨팅 풀. Snowflake는 지정된 컴퓨팅 풀에서 서비스를 실행합니다. 공통 설정의 일부로 컴퓨팅 풀을 생성했습니다.

• 서비스 사양. 이 사양에서는 Snowflake에 서비스 구성과 실행에 필요한 정보를 제공합니다. 자세한 내용은 Snowpark Container Services: 서비스 사용하기 섹션을 참조하십시오. 이 자습서에서는 CREATE SERVICE 명령에 사양을 인라인으로 제공합니다. 또한 사양을 Snowflake 스테이지의 파일에 저장하고 자습서 2에 표시된 대로 CREATE SERVICE 명령에 파일 정보를 제공할 수도 있습니다.

서비스 함수는 서비스와 통신하는 데 사용할 수 있는 방법 중 하나입니다. 서비스 함수는 서비스 엔드포인트와 연결하는 사용자 정의 함수(UDF)입니다. 서비스 함수가 실행되면 서비스 엔드포인트에 요청을 보내고 응답을 받습니다.

1. 컴퓨팅 풀이 준비되었는지, 서비스를 생성할 수 있는 올바른 컨텍스트에 있는지 확인하십시오.

   1. 이전에는 공통 설정 단계에서 컨텍스트를 설정했습니다. 이 단계에서 SQL 문의 올바른 컨텍스트에 있는지 확인하려면 다음을 실행하십시오.

   USE ROLE test_role;
   USE DATABASE tutorial_db;
   USE SCHEMA data_schema;
   USE WAREHOUSE tutorial_warehouse;
   

   Copy

   1. 공통 설정 에서 생성한 컴퓨팅 풀이 준비되었는지 확인하려면 DESCRIBE COMPUTE POOL 을 실행하고 state 가 ACTIVE 또는 IDLE 인지 확인하십시오. state 가 STARTING 이면 state 가 ACTIVE 또는 IDLE 로 변경될 때까지 기다려야 합니다.

   DESCRIBE COMPUTE POOL tutorial_compute_pool;
   

   Copy

2. 서비스를 생성하려면 test_role 을 사용하여 다음 명령을 실행합니다.

   CREATE SERVICE echo_service
     IN COMPUTE POOL tutorial_compute_pool
     FROM SPECIFICATION $$
       spec:
         containers:
         - name: echo
           image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
           env:
             SERVER_PORT: 8000
             CHARACTER_NAME: Bob
           readinessProbe:
             port: 8000
             path: /healthcheck
         endpoints:
         - name: echoendpoint
           port: 8000
           public: true
         $$
      MIN_INSTANCES=1
      MAX_INSTANCES=1;
   

   Copy

   참고

   해당 이름의 서비스가 이미 존재하는 경우 DROP SERVICE 명령을 사용하여 이전에 생성된 서비스를 삭제한 다음 이 서비스를 생성합니다.

3. 방금 만든 서비스에 대한 자세한 정보를 얻으려면 다음 SQL 명령을 실행하십시오. 자세한 내용은 Snowpark Container Services: 서비스 사용하기 섹션을 참조하십시오.

   • 계정의 서비스를 나열하려면 SHOW SERVICES 명령을 실행하십시오.

     SHOW SERVICES;
     

     Copy

   • 서비스 상태를 확인하려면 시스템 함수 SYSTEM$GET_SERVICE_STATUS를 호출하십시오.

     SELECT SYSTEM$GET_SERVICE_STATUS('echo_service');
     

     Copy

   • 서비스에 대한 정보를 얻으려면 DESCRIBE SERVICE 명령을 실행하십시오.

     DESCRIBE SERVICE echo_service;
     

     Copy

4. 서비스 함수를 생성하려면 다음 명령을 실행합니다.

   CREATE FUNCTION my_echo_udf (InputText varchar)
     RETURNS varchar
     SERVICE=echo_service
     ENDPOINT=echoendpoint
     AS '/echo';
   

   Copy

   다음 사항을 참고하십시오.

   • SERVICE 속성은 UDF를 echo_service 서비스와 연결합니다.

   • ENDPOINT 속성은 UDF를 서비스 내의 echoendpoint 엔드포인트와 연결합니다.

   • AS ‘/echo’는 에코 서버의 HTTP 경로를 지정합니다. 서비스 코드(echo_service.py)에서 이 경로를 찾을 수 있습니다.

4: 서비스 사용¶

먼저, 이 섹션의 SQL 문에 대한 컨텍스트를 설정하고 다음을 실행합니다.

USE ROLE test_role;
USE DATABASE tutorial_db;
USE SCHEMA data_schema;
USE WAREHOUSE tutorial_warehouse;

이제 Echo 서비스와 통신할 수 있습니다.

1. 서비스 함수 사용: 쿼리에서 서비스 함수를 호출할 수 있습니다. 예제 서비스 함수(my_echo_udf)는 단일 문자열이나 문자열 목록을 입력으로 받을 수 있습니다.

   예 1.1: 단일 문자열 전달

   • my_echo_udf 서비스 함수를 호출하려면 다음 SELECT 문을 실행하여 하나의 입력 문자열('hello')을 전달합니다.

     SELECT my_echo_udf('hello!');
     

     Copy

     Snowflake는 서비스 엔드포인트(echoendpoint)에 POST 요청을 보냅니다. 요청을 받으면 서비스는 응답에 입력 문자열을 그대로 표시합니다.

     +--------------------------+
     | **MY_ECHO_UDF('HELLO!')**|
     |------------------------- |
     | Bob said hello!          |
     +--------------------------+
     

   예 1.2: 문자열 목록 전달

   문자열 목록을 서비스 함수에 전달하면 Snowflake는 이러한 입력 문자열을 일괄 처리하고 일련의 POST 요청을 서비스에 보냅니다. 서비스가 모든 문자열을 처리한 후 Snowflake는 결과를 결합하여 반환합니다.

   다음 예에서는 테이블 열을 서비스 함수에 대한 입력으로 전달합니다.

   1. 여러 문자열이 포함된 테이블을 만듭니다.

      CREATE TABLE messages (message_text VARCHAR)
        AS (SELECT * FROM (VALUES ('Thank you'), ('Hello'), ('Hello World')));
      

      Copy

   2. 테이블이 만들어졌는지 확인합니다.

      SELECT * FROM messages;
      

      Copy

   3. 서비스 함수를 호출하려면 다음 SELECT 문을 실행하여 테이블 행을 입력으로 전달합니다.

      SELECT my_echo_udf(message_text) FROM messages;
      

      Copy

      출력:

      +---------------------------+
      | MY_ECHO_UDF(MESSAGE_TEXT) |
      |---------------------------|
      | Bob said Thank you        |
      | Bob said Hello            |
      | Bob said Hello World      |
      +---------------------------+
      

2. 웹 브라우저 사용: 이 서비스는 엔드포인트를 공개적으로 노출합니다(CREATE SERVICE 명령에 제공된 인라인 사양 참조). 따라서 서비스가 인터넷에 노출하는 웹 UI에 로그인한 후 웹 브라우저에서 서비스에 요청을 보낼 수 있습니다.

   1. 서비스가 노출하는 공용 엔드포인트의 URL을 찾습니다.

      SHOW ENDPOINTS IN SERVICE echo_service;
      

      Copy

      응답의 ingress_url 열은 URL을 제공합니다.

      예

      p6bye-myorg-myacct.snowflakecomputing.app
      

   2. 엔드포인트 URL에 /ui 를 추가하고 웹 브라우저에 붙여넣습니다. 그러면 서비스가 ui() 함수를 실행하게 됩니다(echo_service.py 참조).

      엔드포인트 URL에 처음 액세스하면 Snowflake에 로그인하라는 메시지가 표시됩니다. 이 테스트에서는 서비스를 만드는 데 사용한 것과 동일한 사용자를 사용하여 사용자에게 필요한 권한이 있는지 확인하십시오.

      

   3. Input 상자에 문자열 “Hello”를 입력하고 Return 을 누릅니다.

      

   참고

   프로그래밍 방식으로 수신 엔드포인트에 액세스할 수 있습니다. 샘플 코드는 공용 엔드포인트 액세스 및 인증 섹션을 참조하십시오. Snowflake가 서비스 코드의 ui() 함수 요청을 라우팅할 수 있도록 코드의 엔드포인트 URL에 /ui 를 추가해야 합니다.

5: 정리¶

자습서 2 또는 자습서 3 을 계속 진행할 계획이 없다면 생성한 청구 가능한 리소스를 제거해야 합니다. 자세한 내용은 자습서 3 의 5단계를 참조하십시오.

6: 서비스 코드 검토¶

이 섹션에서는 다음 주제를 다룹니다.

• 자습서 1 코드 검토: Echo 서비스를 구현하는 코드 파일을 검토합니다.

• 서비스 함수 이해하기: 이 섹션에서는 이 자습서의 서비스 함수가 서비스와 연결되는 방식을 설명합니다.

• 로컬에서 이미지 만들기 및 테스트하기. 이 섹션에서는 Docker 이미지를 Snowflake 계정의 리포지토리에 업로드하기 전에 로컬에서 이미지를 테스트하는 방법을 설명합니다.

from flask import Flask
from flask import request
from flask import make_response
from flask import render_template
import logging
import os
import sys

SERVICE_HOST = os.getenv('SERVER_HOST', '0.0.0.0')
SERVER_PORT = os.getenv('SERVER_PORT', 8080)
CHARACTER_NAME = os.getenv('CHARACTER_NAME', 'I')


def get_logger(logger_name):
  logger = logging.getLogger(logger_name)
  logger.setLevel(logging.DEBUG)
  handler = logging.StreamHandler(sys.stdout)
  handler.setLevel(logging.DEBUG)
  handler.setFormatter(
    logging.Formatter(
      '%(name)s [%(asctime)s] [%(levelname)s] %(message)s'))
  logger.addHandler(handler)
  return logger


logger = get_logger('echo-service')

app = Flask(__name__)


@app.get("/healthcheck")
def readiness_probe():
  return "I'm ready!"


@app.post("/echo")
def echo():
  '''
  Main handler for input data sent by Snowflake.
  '''
  message = request.json
  logger.debug(f'Received request: {message}')

  if message is None or not message['data']:
    logger.info('Received empty message')
    return {}

  # input format:
  #   {"data": [
  #     [row_index, column_1_value, column_2_value, ...],
  #     ...
  #   ]}
  input_rows = message['data']
  logger.info(f'Received {len(input_rows)} rows')

  # output format:
  #   {"data": [
  #     [row_index, column_1_value, column_2_value, ...}],
  #     ...
  #   ]}
  output_rows = [[row[0], get_echo_response(row[1])] for row in input_rows]
  logger.info(f'Produced {len(output_rows)} rows')

  response = make_response({"data": output_rows})
  response.headers['Content-type'] = 'application/json'
  logger.debug(f'Sending response: {response.json}')
  return response


@app.route("/ui", methods=["GET", "POST"])
def ui():
  '''
  Main handler for providing a web UI.
  '''
  if request.method == "POST":
    # getting input in HTML form
    input_text = request.form.get("input")
    # display input and output
    return render_template("basic_ui.html",
      echo_input=input_text,
      echo_reponse=get_echo_response(input_text))
  return render_template("basic_ui.html")


def get_echo_response(input):
  return f'{CHARACTER_NAME} said {input}'

if __name__ == '__main__':
  app.run(host=SERVICE_HOST, port=SERVER_PORT)

ARG BASE_IMAGE=python:3.10-slim-buster
FROM $BASE_IMAGE
COPY echo_service.py ./
COPY templates/ ./templates/
RUN pip install --upgrade pip && \\
pip install flask
CMD ["python", "echo_service.py"]

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Welcome to echo service!</title>
  </head>
  <body>
    <h1>Welcome to echo service!</h1>
    <form action="{{ url_for("ui") }}" method="post">
      <label for="input">Input:<label><br>
      <input type="text" id="input" name="input"><br>
    </form>
    <h2>Input:</h2>
    {{ echo_input }}
    <h2>Output:</h2>
    {{ echo_reponse }}
  </body>
</html>

spec:
  containers:
  - name: echo
    image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
    env:
      SERVER_PORT: 8000
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8000
      path: /healthcheck
  endpoints:
  - name: echoendpoint
    port: 8000
    public: true

CREATE FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE=echo_service
  ENDPOINT=echoendpoint
  AS '/echo';

다음에는 무엇을 해야 합니까?¶

이제 작업을 실행하는 자습서 2 를 테스트할 수 있습니다.