API: ModelAdapter 참조

모델 어댑터는 Foundry와 저장된 모델 아티팩트 간의 통신 계층을 제공하는 발행된 Python 라이브러리로, 어떤 모델이든 Foundry에서 로드, 초기화, 추론 실행을 가능하게 합니다.

ModelAdapter를 구현하려면 아래에 나열된 클래스를 이해해야 합니다:

ModelAdapter 구현

ModelAdapter 클래스는 모든 모델 어댑터 구현이 확장해야 하는 추상 기본 클래스입니다. 모든 모델 어댑터가 구현해야 하는 네 가지 추상 메소드는 다음과 같습니다:

1. load()
2. save()
   • load()와 save()는 기본 시리얼라이저로 정의된 모델 어댑터에는 필요하지 않음을 주의하세요.
3. api()
4. 단일 출력을 위한 predict(), 다중 출력을 위한 run_inference()

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
import palantir_models as pm
import models_api.models_api_executable as executable_api

class ExampleModelAdapter(pm.ModelAdapter):

    @classmethod
    def load(
        cls,
        state_reader: pm.ModelStateReader,
        container_context: Optional[executable_api.ContainerizedApplicationContext] = None,
        external_model_context: Optional[executable_api.ExternalModelExecutionContext] = None
    ) -> "pm.ModelAdapter":
        """
        파이썬 또는 바이너리 모델:
            이 메소드는 Foundry가 ModelAdapter를 역직렬화하기 위해 호출하는 메소드입니다. 이 ModelAdapter의 저자는 save 메소드에서 모델이 저장/직렬화된 동일한 위치에서 모델의 상태를 로드하고 모델을 초기화하는 로직을 작성해야 합니다.

        컨테이너 모델:
            이 메소드는 Foundry가 컨테이너를 이 ModelAdapter의 사이드카로 실행한 후 호출하는 메소드입니다. 이 ModelAdapter의 저자는 컨테이너 컨텍스트의 내용을 사용하여 어댑터가 필요로 하는 클래스 변수를 초기화해야 합니다. 예를 들어, 사용자는 #run_inference 내에서 컨테이너에 POST 요청을 보내기 위해 관련 서비스 URI를 추출하는 경우가 많습니다.

        외부 호스팅 모델:
            이 메소드는 모델 어댑터가 초기화될 때 Foundry가 호출하는 메소드입니다. 이 ModelAdapter의 저자는 외부 호스팅 모델에 대한 초기 연결을 초기화하고 유지 관리하고 필요한 모델 구성을 초기화하는 로직을 작성해야 합니다.

        :param state_reader: 모델 파일을 읽는 데 사용할 수 있는 ModelStateReader 객체입니다.
        :param container_context: 이것은 컨테이너 백업 모델에만 제공되며 기본적으로 None입니다. 컨테이너 컨텍스트는 컨테이너 이름에서 서비스 URI로의 매핑과 공유 디렉토리 마운트 경로를 포함합니다.
        :param external_model_context: 이것은 외부 호스팅 모델에만 제공되며 기본적으로 None입니다. external_model_context는 사용자가 이 Model Adapter를 사용하는 외부 호스팅 모델을 생성할 때 정의하는 구성에 대한 참조를 포함합니다.

        :return: ModelAdapter의 인스턴스.
        """

    def save(self, state_writer: pm.ModelStateWriter) -> None:
        """
        이것은 Foundry가 모델 어댑터를 직렬화하기 위해 호출하는 메소드입니다. 이 메소드는 이 ModelAdapter가 Foundry에서 새로 훈련되거나 다시 조정된 모델을 래핑하는 데 사용되는 경우에만 필요합니다.

        이 ModelAdapter의 저자는 모델의 상태와 관련 메타데이터를 ModelStateWriter에 저장하는 로직을 작성해야 합니다.

        :param state_writer: 모델이 직렬화되어 저장되는 ModelStateWriter 객체입니다.
        """

    @classmethod
    def api(cls) -> pm.ModelApi:
        """
        이것은 이 모델의 예상 입력 및 출력 데이터 구조를 정의합니다.

        :return: 모델의 ModelApi 객체
        """

    def run_inference(self, inputs, outputs) -> None:
        """
        이 메소드는 ModelAdapater.api 메소드에서 정의된 관련 입력 및 출력으로 호출됩니다.

        관련 모델에서 추론을 실행합니다.

        :param inputs: ModelAdapater.api 메소드에서 정의된 입력의 namedtuple입니다.
        :param outputs: ModelAdapater.api 메소드에서 정의된 출력의 namedtuple입니다.
          출력은 run_inference 메소드에서 작성해야 합니다.
        """

    def predict(self, *args, **kwargs) -> Union[Tabular, Parameter]:
        """
        이 메소드는 다중 (>=1) 입력에서 단일 출력 (테이블 또는 매개변수) 모델에 대한 추론을 수행하는 데 사용됩니다.
        입력은 api() 메소드에서 정의하는 이름으로 이 메소드의 서명에 작성되어야 합니다. 결과 출력은 이 메소드에서 반환됩니다.

        참고로 predict()가 사용되면 run_inference() 메소드는 사용자에 의해 정의되지 않습니다.
        """

모델 save() 및 load()

palantir_models_serializers 라이브러리는 모델 직렬화(저장)와 역직렬화(로드)를 위한 기본 직렬화 도구를 많이 제공하며 일반적인 모델링 프레임워크에서 사용할 수 있습니다.

일부 경우 사용자가 모델 직렬화나 역직렬화에 대한 사용자 정의 로직을 구현하려고 할 수 있습니다. 예를 들어 사용중인 모델링 프레임워크에 대해 기본 직렬화 도구가 없거나 모델이 어느 시점에 메모리에 로드되는 것에 대해 수동으로 제어할 필요가 있을 때 이러한 경우가 필요할 수 있습니다.

이와 같은 복잡한 경우에는 아래의 save 및 load 구현을 참조하십시오.

저장하기

ModelStateWriter

ModelStateWriter는 ModelAdapter.save 메소드에 제공되어 ModelAdapter가 모델 아티팩트를 Foundry 저장소에 저장/직렬화할 수 있습니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# ModelStateWriter는 palantir_models.models에서 가져올 수 있습니다.

from io import IOBase
from typing import ContextManager

class ModelStateWriter:
    def open(self, asset_file_path: str, mode: str = "wb") -> ContextManager[IOBase]:
        """
        모델 아티팩트와 매개변수를 직렬화하기 위해 파일과 유사한 객체를 연다.
        """

    def put_file(self, local_file_path, asset_file_path=None):
        """
        이 모델의 저장소에 로컬 파일을 넣습니다.
        :param asset_file_path: 제공되면, 파일이 저장소의 이 경로에 위치하게 됩니다.
            그렇지 않으면 파일이 저장소의 루트 디렉터리에 위치하게 됩니다.
        """

    def put_directory(self, local_root_path, asset_root_path = "/"):
        """
        로컬 디렉터리와 그 내용을 이 모델의 저장소에 넣습니다.
        :param asset_root_path: 이 디렉터리를 저장소의 루트 경로에 상대적인 경로로 위치시킵니다.
        """

save() 메소드는 모델 어댑터가 model.publish()를 통해 변환에서 발행될 때마다 호출되며, 이때 ModelStateWriter의 내용이 패키지화되어 새로 생성된 모델 버젼에 의해 참조되는 아티팩트 저장소에 지속되는 zip 파일로 패키지화됩니다.

예시: ModelStateWriter

다음 예시는 모델을 model.pkl 파일로 저장합니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 필요한 패키지와 모듈을 불러옵니다.
from palantir_models.models import ModelAdapter, ModelStateWriter

# 예시 모델 어댑터 클래스를 정의합니다.
class ExampleModelAdapter(ModelAdapter):
    def __init__(self, model):
        # 생성자를 통해 모델 객체를 초기화합니다.
        self.model = model

    # ...

    def save(self, state_writer: ModelStateWriter):
        # 모델 상태 저장을 위한 메서드입니다.
        # 모델 객체를 pkl 파일로 저장합니다.
        with state_writer.open("model.pkl", "wb") as model_outfile:
            pickle.dump(self.model, model_outfile)

    # ...

Load

ModelStateReader

ModelStateReader는 저장된 모델 아티팩트를 읽고/역직렬화하여 모델을 초기화할 수 있도록 ModelAdapter.load 메소드에 제공됩니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# ModelStateReader는 palantir_models.models에서 가져올 수 있습니다.
from tempfile import TemporaryDirectory

class ModelStateReader:
    def open(self, asset_file_path: str, mode: str = "rb") -> ContextManager[IOBase]:
        """
        모델 아티팩트와 파라미터를 역직렬화하기 위해 파일과 같은 객체를 연다.
        """

    def extract_to_temp_dir(self, root_dir: str = None) -> AnyStr:
        """
        이 모델과 관련된 모델 아티팩트가 포함된 TempDirectory를 반환합니다.
        :param root_dir: 지정된 경우, 추출할 루트 디렉토리
        """

    def extract(self, destination_path: str = None) -> None:
        """
        리포지토리를 제공된 로컬 디렉터리 경로로 추출합니다.
        :param destination_path: 지정된 경우, 리포지토리가 추출될 디렉터리
        """

load() 메소드는 모델 어댑터가 인스턴스화될 때마다 호출됩니다(ModelInput을 통한 변환 또는 모델을 기반으로 하는 라이브 또는 배치 배포를 시작할 때). 이 메소드는 ModelStateWriter가 작성하는 것과 동일한 아티팩트 저장소에 액세스하고, ModelStateReader를 통해 내용에 액세스할 수 있게 합니다. 변환 또는 추론 로직이 실행되기 전에 load()가 호출됩니다.

예시: ModelStateReader

다음 예시는 모델 파일을 로드하고 이를 사용하여 초기화된 모델 어댑터 인스턴스를 반환합니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
from palantir_models.models import ModelAdapter, ModelStateReader

class ExampleModelAdapter(ModelAdapter):
    def __init__(self, model):
        self.model = model

    @classmethod
    def load(cls, state_reader: ModelStateReader):
        # 상태 리더로부터 "model.pkl" 파일을 로드하여 모델을 얻습니다.
        with state_reader.open("model.pkl", "rb") as model_infile:
            model = pickle.load(model_infile)
        return cls(model)

    ...

save() 메소드와 함께 사용할 때, 이 메소드는 save() 메소드에서 저장된 동일한 model.pkl 오브젝트를 검색합니다. ModelStateReader 오브젝트는 컨테이너화된 모델에게 제공되며, 사용자가 업로드한 zip 파일에 의해 지원됩니다.

컨테이너화된 애플리케이션 컨텍스트

컨테이너화된 애플리케이션 컨텍스트는 선택 사항이며, 모델이 컨테이너 이미지 또는 이미지들에 의해 지원될 경우에만 ModelAdapter.load 메소드에 제공됩니다. 컨텍스트 오브젝트는 공유 디렉토리 마운트 경로와 컨테이너 이름에서 서비스 URI로의 매핑을 포함합니다. 각 컨테이너는 여러 개의 서비스 URI를 가질 수 있으며, 여러 개의 오픈 포트를 가지는 것이 유효합니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
# 이 클래스 유형은 작성된 어댑터 내에서 가져올 필요가 없습니다.
class ContainerizedApplicationContext:
    def services(self) -> Dict[str, List[str]]:
        """
        개별 컨테이너 이름에서 컨테이너가 제공하는 서비스 URI의 목록으로의 매핑입니다.
        """
    def shared_empty_dir_mount_path(self) -> str:
        """
        모든 컨테이너와 모델 어댑터에서 사용 가능한 공유 빈 디렉토리의 마운트 경로입니다.
        이 디렉토리는 컨테이너와 모델 엔트리 포인트에서 읽고 쓸 수 있습니다.
        """

예시로 채워진 서비스 변수는 다음과 같이 보일 수 있습니다:

Copied!
1
2
3
4
5
6
{
    # 컨테이너1은 로컬호스트 8080 포트를 사용합니다.
    "container1": ["localhost:8080"],
    # 컨테이너2는 로컬호스트 8080 포트와 8081 포트를 사용합니다.
    "container2": ["localhost:8080", "localhost:8081"],
}

예시: ContainerizedApplicationContext

다음 예시에서는 제공된 ContainerizedApplicationContext에서 특정 볼륨 경로, 호스트, 포트를 사용하여 모델 어댑터를 초기화합니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from palantir_models.models import ModelAdapter, ModelStateReader
import models_api.models_api_executable as executable_api

# 예제 모델 어댑터 클래스 선언
class ExampleModelAdapter(ModelAdapter):
    # 생성자 함수
    def __init__(self, shared_volume_path, model_host_and_port):
        self.shared_volume_path = shared_volume_path
        self.model_host_and_port = model_host_and_port

    # 클래스 메소드 load 정의
    @classmethod
    def load(cls, state_reader, container_context: executable_api.ContainerizedApplicationContext):
        # 공유 볼륨 경로 가져오기
        shared_volume_path = container_context.shared_empty_dir_mount_path
        # 모델 호스트 및 포트 가져오기
        model_host_and_port = container_context.services["container1"][0]
        # 클래스 인스턴스 생성 및 반환
        return cls(shared_volume_path, model_host_and_port)

    ...

외부모델컨텍스트

외부모델컨텍스트는 선택 사항이며, 모델이 외부에서 호스팅되는 모델인 경우에만 ModelAdapter.load 메서드에 제공됩니다. 컨텍스트 오브젝트는 외부에서 호스팅되는 모델을 나타내는 오브젝트와 이 외부 호스팅 모델에 연결하는 데 필요한 사용자 정의 복호화된 시크릿 맵을 포함합니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 이 클래스 타입은 작성된 어댑터 내에서 가져올 필요가 없음을 주의하십시오
class ExternalModelContext:
    def external_model(self) -> models_api_external_ExternalModel:
        """
        외부에 호스팅된 모델을 대표하는 객체는 특히 base_url과 connection_configuration을 포함합니다.
        """

    def resolved_credentials(self) -> Dict[str, str]:
        """
        이 외부에 호스팅된 모델과 연결하는 데 필요한 사용자 정의 복호화된 비밀 값의 매핑입니다.
        """

# 이 클래스 타입은 작성된 어댑터 내에서 가져올 필요가 없음을 주의하십시오
class models_api_external_ExternalModel:
    def base_url(self) -> str:
        """
        이 외부에 호스팅된 모델이 호스팅되는 위치를 나타내는 사용자 정의 url입니다.
        """

    def connection_configuration(self) -> Dict[str, str]:
        """
        암호화되지 않은 설정 필드의 사용자 정의 사전입니다.
        이것은 모델 이름, 추론 매개변수 또는 예측 임계값과 같은 특정 설정 세부 사항을 저장하기 위한 것입니다.
        """

예시: ExternalApplicationContext

다음 예시는 외부로 호스팅된 모델에 요청을 실행하는 모델 어댑터를 초기화합니다. 외부로 호스팅된 모델을 사용하는 방법에 대한 자세한 정보는 관련 문서를 읽어보세요.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
from palantir_models.models import ModelAdapter, ModelStateReader
import models_api.models_api_executable as executable_api

class ExampleModelAdapter(ModelAdapter):
    def __init__(self, url, credentials_map, configuration_map):
        # "연결 구성" 맵에서 모델 구성 추출
        model_name = configuration_map['model_name']
        model_parameter = configuration_map['model_parameter']

        # "자격증명 구성" 맵에서 모델 자격증명 추출
        secret_key = credentials_map['secret_key']

        # 모델 로드 시간에 http 클라이언트 초기화
        self.client = ExampleClient(url, model_name, model_parameter, secret_key)

    @classmethod
    def load(
            cls,
            state_reader: ModelStateReader,
            container_context: Optional[executable_api.ContainerizedApplicationContext] = None,
            external_model_context: Optional[executable_api.ExternalModelExecutionContext] = None,
            ) -> "ModelAdapter":
        return cls(
            url=external_model_context.external_model.base_url,
            credentials_map=external_model_context.resolved_credentials,
            configuration_map=external_model_context.external_model.connection_configuration,
        )

    ...

모델 API

모델 어댑터의 api() 메서드는 이 모델 어댑터의 추론 로직을 실행하기 위해 예상되는 입력과 결과물을 명시합니다. 입력과 결과물은 별도로 지정됩니다.

예시 api()

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# palantir 모델을 import 합니다
import palantir_models as pm

# ExampleModelAdapter라는 클래스를 생성합니다. 이 클래스는 pm.ModelAdapter를 상속받습니다.
class ExampleModelAdapter(pm.ModelAdapter):
    ...

    # api라는 클래스 메소드를 정의합니다.
    @classmethod
    def api(cls):
        # 입력 데이터는 'df_in'이라는 이름의 pandas DataFrame 형태이며, 
        # 이 DataFrame은 'input_feature'라는 이름의 float 타입 칼럼을 포함합니다.
        inputs = {
            "df_in": pm.Pandas([('input_feature', float)])
        }
        # 출력 데이터는 'df_out'이라는 이름의 pandas DataFrame 형태이며, 
        # 이 DataFrame은 'output_feature'라는 이름의 int 타입 칼럼을 포함합니다.
        outputs = {
            "df_out": pm.Pandas([('output_feature', int)])
        }
        # 입력 데이터와 출력 데이터를 반환합니다.
        return inputs, outputs

    ...

모델 입력

ModelInput 유형에는 ModelAdapter.api 메소드에서 정의할 수 있는 입력 유형이 포함됩니다. 모델 어댑터는 다음의 입력 유형을 지원합니다:

1. 테이블 형식
2. 파라미터
3. 파일 시스템
4. 미디어 레퍼런스

참고: 미디어 레퍼런스 지원은 현재 베타 상태이며, 파이썬 변환에서 추론만 지원합니다. 모델이 있는 미디어 레퍼런스는 자동 평가, 배치 배포, 또는 Modelling Objective 애플리케이션에서의 실시간 배포를 지원하지 않습니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
# DFType, and ModelInput은 palantir_models.models.api에서 가져올 수 있습니다.

class ModelInput:
    Tabular = TabularInput
    FileSystem = FileSystemInput
    Parameter = ParameterInput
    MediaReference = MediaReferenceInput

class TabularInput:
    def __init__(self, name: str, df_type: DFType = DFType.SPARK, columns: List[ModelApiColumn]):
        """
        ModelAdapter가 탭 형식 입력을 기대한다고 지정하는 데 사용됩니다.
        이 입력 유형은 해당하는 경우 `df_type`에서 지정한 유형으로 탭 형식 입력을 변환합니다.
        Pandas 데이터프레임, Spark 데이터프레임 및 TransformInputs이 탭 형식 입력 유형으로 허용됩니다.
        """

class ParameterInput:
    def __init__(self, name: str, type: type, default = None):
        """
        ModelAdapter가 'type' 유형의 상수 값 매개변수를 기대한다고 지정하는 데 사용됩니다.
        매개변수 입력에 사용 가능한 유형은 str, int, float, bool, list, set, dict, tuple입니다.
        .transform()에 args로 직접 전달되지 않는 경우 제공된 기본값이 사용됩니다.
        """

class FileSystemInput:
    def __init__(self, name: str):
        """
        ModelAdapter가 파일 시스템 입력을 기대한다고 지정하는 데 사용됩니다.
        """

class MediaReferenceInput:
    def __init__(self, name: str):
        """
        ModelAdapter가 미디어 참조를 입력으로 기대한다고 지정하는 데 사용됩니다.
        """

class DFType(Enum):
    SPARK = "spark"
    PANDAS = "pandas"

class ModelApiColumn(NamedTuple):
    """
    탭 형식 입력의 열 이름과 유형을 지정하는 데 사용됩니다.
    """
    name: str
    type: type
    required: bool = True

표 형식 입력

TabularInput은 model.transform()에 제공되는 입력이 표 형식임을 나타냅니다. 이 모델 어댑터의 추론 로직에 대한 입력의 유형은 api() 메소드에서 지정한 df_type 파라미터가 됩니다. 필요한 경우 적절한 유형 변환을 수행합니다. 다음 표 형식이 허용됩니다:

1. TransformInput
2. Pandas DataFrame
3. Spark DataFrame
   • 참고: Spark 데이터프레임은 df_type=DFType.SPARK을 지정하는 어댑터 API의 표 형식 입력에서만 지원됩니다. DFType.PANDAS를 지정하는 표 형식 입력에 대한 변환은 Spark 데이터프레임에서 지원되지 않습니다.

열 유형

TabularInputs는 또한 표 형식 입력의 예상 열 스키마를 설명하는 ModelApiColumn 목록을 지정합니다. type 파라미터는 다음 중 하나가 될 수 있습니다:

1. str
2. int
3. float
4. bool
5. list
6. dict
7. set
8. tuple
9. datetime.date
10. datetime.time
11. datetime.datetime
12. typing.Any
13. MediaReference

typing 라이브러리의 List, Dict, Set, Tuple 유형 별칭도 허용됩니다. 몇 가지 예는 다음과 같습니다:

• List[str], Set[str]
• Dict[str, float]
• Tuple[int, int]

열 유형은 강제되지 않으며 이 모델 어댑터의 예상 열 유형이 무엇인지 소비자에게 신호를 보내는 방법입니다. 예외는 열의 각 요소가 미디어 참조 문자열이어야 하며 이 모델 어댑터의 추론 로직에 전달되기 전에 각 요소를 MediaReference 객체로 변환하는 MediaReference 유형입니다.

파라미터 입력

ParameterInput은 model.transform()에 제공되는 입력이 파라미터 유형임을 나타냅니다. 파라미터는 type 파라미터로 지정된 유형의 상수 값을 갖는 입력입니다. 다음 유형이 파라미터 입력에 허용됩니다:

1. str
2. int
3. float
4. bool
5. list
6. dict
7. set
8. tuple
9. typing.Any

파라미터 유형은 강제되며 지정된 유형과 일치하지 않는 model.transform()의 어떤 파라미터 입력이라도 오류를 발생시킵니다.

파라미터 입력은 모델 어댑터의 api() 메소드에서 정의된 파라미터 입력에 해당하는 model.transform() 입력이 제공되지 않은 경우 default 값을 지정할 수도 있습니다.

파일 시스템 입력

FileSystemInput은 model.transform()에 제공되는 입력이 파일 시스템 유형임을 나타냅니다. FileSystemInput의 입력 유형으로는 TransformInputs만이 지원됩니다.

미디어 참조 입력

MediaReferenceInput은 model.transform()에 제공되는 입력이 미디어 참조임을 나타냅니다. 미디어 참조는 str 유형이어야 하며 전체 미디어 참조 객체 정의를 포함해야 합니다. 모델 어댑터는 이 미디어 참조 문자열을 참조되는 미디어 항목과 상호 작용하는 방법을 포함하는 MediaReference 객체로 변환합니다.

모델 결과물

ModelOutput은 ModelAdapter.api 메소드에서 정의된 결과물 유형을 포함합니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# ModelOutput은 palantir_models.models.api에서 가져올 수 있습니다

class ModelOutput:
    FileSystem = FileSystemOutput  # 파일 시스템 출력을 나타냅니다
    Paramter = ParameterOutput  # 파라미터 출력을 나타냅니다

class TabularOutput:
    def __init__(self, name: str):
        """
        ModelAdapter가 탭 형식의 출력을 생성하도록 지정하는 데 사용됩니다.
        탭 형식의 출력 유형으로는 Pandas 또는 Spark 데이터프레임만 지원됩니다.
        """

class ParameterOutput:
    def __init__(self, name: str, type: type, default = None):
        """
        ModelAdapter가 'type' 타입의 상수 값을 생성하도록 지정하는 데 사용됩니다.
        파라미터 출력에 사용 가능한 유형은 다음과 같습니다: str, int, float, bool, list, set, dict, tuple.
        `run_inference()`를 통해 작성되지 않는 경우 제공된 기본값이 사용됩니다.
        """

두 가지 사용 가능한 모델 결과물은 입력 counterparts와 유사하게 작동합니다. 주요 차이점 중 하나는 TabularOutput이 df_type 파라미터를 가지고 있지 않다는 점입니다. 이는 Pandas 및 Spark 데이터프레임 모두를 수용할 수 있습니다.

모델 추론

predict() 메소드

표 형식이거나 파라미터 형식의 단일 출력을 가진 모델의 경우, 모델 어댑터의 추론 로직을 정의하기 위해 run_inference() 메소드 대신 predict() 메소드를 사용할 수 있습니다. 이 메소드의 인수는 모델 어댑터의 api() 메소드에서 정의된 입력 오브젝트의 이름이 됩니다. 인수가 정의된 순서와 동일한 순서를 유지할 필요는 없지만 이름은 일치해야 합니다.

predict() 메소드 예시

다음 예시는 다중 표 형식 입력, 단일 표 형식 출력 모델 어댑터에 대한 predict() 메소드를 정의합니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import palantir_models as pm

class ExampleModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        # 입력 데이터 형식을 정의합니다. 여기서는 두 개의 pandas DataFrame을 입력으로 사용합니다.
        inputs = {"input_1": pm.Pandas(), "input_2": pm.Pandas()}
        # 출력 데이터 형식을 정의합니다. 여기서는 pandas DataFrame을 출력으로 사용합니다.
        outputs = {"output_dataframe": pm.Pandas()}
        # 정의된 입력과 출력 형식을 반환합니다.
        return inputs, outputs

    def predict(self, input_1, input_2):
        # input_1과 input_2를 이용해 어떤 추론 로직을 수행하고 결과를 DataFrame으로 반환합니다.
        resulting_dataframe = ... 
        return resulting_dataframe

위의 예시에서, 두 입력값(input_1 과 input_2)은 predict() 메소드의 시그니처에서 이름으로 참조됩니다. 함수가 반환하는 데이터프레임 resulting_dataframe은 output_dataframe이라는 단일 결과물로 작성됩니다.

run_inference() 메소드

다중 결과물 모델 또는 파일 시스템에 쓰기를 하는 모델의 경우, run_inference() 메소드를 통해 사용자 지정 추론 로직을 정의해야 합니다. 이 메소드는 inputs 와 outputs 두 개의 인수를 받습니다. 이 두 인수 모두 api() 메소드에서 정의된 입력값과 결과물의 name 파라미터에 해당하는 NamedTuples입니다.

입력값

이름으로 입력값을 참조하면, 동일한 이름의 api() 입력값에 대응되는 model.transform()으로 전달된 오브젝트에 접근합니다.

예시: 입력값

다음 ModelAdapter 정의가 주어진 경우:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
from palantir_models as pm

class ExampleModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        # API 입력값을 정의합니다. 이 때 입력값은 "df_in"이라는 이름의 Pandas 데이터프레임이며,
        # 이 데이터프레임은 ("input_feature", float) 형태의 데이터를 포함합니다.
        inputs = {
            "df_in": pm.Pandas([("input_feature", float)])
        }
        # API 출력값을 정의합니다. 이 때 출력값은 "df_out_one"과 "df_out_two"라는 이름의 Pandas 데이터프레임입니다.
        # "df_out_one" 데이터프레임은 ("feature_one", int) 형태의 데이터를,
        # "df_out_two" 데이터프레임은 ("output_feature_1", int), ("output_feature_2", float) 형태의 데이터를 포함합니다.
        outputs = {
            "df_out_one": pm.Pandas([("feature_one", int)]),
            "df_out_two": pm.Pandas([("output_feature_1", int),
                                     ("output_feature_2", float)])
        }
        return inputs, outputs

    def run_inference(self, inputs, outputs):
        # 입력값을 변수에 할당합니다.
        my_input_df = inputs.df_in

        # 출력값을 변수에 할당합니다.
        my_output_one = outputs.df_out_one
        my_output_two = outputs.df_out_two
    
    ...

다음의 .transform() 호출:

Copied!
1
2
3
4
5
6
7
8
@transform(
    my_input_data=Input(...),  # 입력 데이터
    my_output_data_one=Output(...),  # 출력 데이터 1
    my_output_data_two=Output(...),  # 출력 데이터 2
    my_model=ModelInput(...)  # 모델 입력
)
def compute(my_input_data, my_output_data_one, my_output_data_two, my_model): 
    my_model_outputs = my_model.transform(my_input_data)  # 모델을 사용하여 입력 데이터 변환

my_input_df 객체는 모델 어댑터의 run_inference() 메서드에 있는 것으로, 이름이 "input_dataframe"인 입력에 대한 참조이며 Pandas 유형의 테이블 입력입니다. 이는 전달되는 my_input_data TransformInput의 Pandas 표현과 동일합니다.

결과물

이름으로 결과물을 참조하면 해당 이름의 api() 결과물에 해당하는 쓰기 가능한 객체가 제공됩니다. 이러한 객체 각각에는 각 결과물에 기록될 데이터를 지정하는 .write() 메서드가 있습니다.

예시: 결과물

다음 ModelAdapter 정의가 주어진 경우:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
from palantir_models as pm

class ExampleModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        # 입력 데이터 프레임
        inputs = {
            "input_dataframe": pm.Pandas([('input_feature', float)])
        }
        # 출력 데이터 프레임
        outputs = {
            "output_dataframe_one": pm.Pandas([('output_feature', int)]),
            "output_dataframe_two": pm.Pandas([('output_feature', int)]),
        }
        return inputs, outputs

    def run_inference(self, inputs, outputs):
        # 입력 데이터 프레임 처리
        my_input_df = inputs.input_dataframe
        # 입력 데이터 프레임에 대한 작업을 수행하고 새로운 데이터 프레임 반환
        my_output_dataframe_one = do_something_to_input_and_return_a_new_dataframe(my_input_df)
        # 입력 데이터 프레임에 대한 다른 작업을 수행하고 새로운 데이터 프레임 반환
        my_output_dataframe_two = do_something_else_to_input_and_return_a_new_dataframe(my_input_df)
        # 결과 데이터 프레임 저장
        outputs.output_dataframe_one.write(my_output_dataframe_one)
        outputs.output_dataframe_two.write(my_output_dataframe_two)
    
    ...

다음 .transform() 호출:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
@transform(
    my_input_data=Input(...),  # 입력 데이터를 설정합니다.
    my_output_data_one=Output(...),  # 출력 데이터 1을 설정합니다.
    my_output_data_two=Output(...),  # 출력 데이터 2를 설정합니다.
    my_model=ModelInput(...)  # 모델 입력을 설정합니다.
)
def compute(my_input_data, my_output_data_one, my_output_data_two, my_model):
    my_model_outputs = my_model.transform(my_input_data)  # 모델을 사용하여 입력 데이터를 변환합니다.
    my_output_dataframe_one = my_model_outputs.output_dataframe_one  # 출력 데이터 프레임 1을 설정합니다.
    my_output_dataframe_two = my_model_outputs.output_dataframe_two  # 출력 데이터 프레임 2를 설정합니다.
    my_output_data_one.write_pandas(my_output_dataframe_one)  # 출력 데이터 1을 pandas 데이터 프레임 형식으로 작성합니다.
    my_output_data_two.write_pandas(my_output_dataframe_two)  # 출력 데이터 2를 pandas 데이터 프레임 형식으로 작성합니다.

변환에서의 my_output_dataframe_one과 my_output_dataframe_two 오브젝트는 모델 어댑터의 run_inference() 메서드에서 output_dataframe_one과 output_dataframe_two 출력에 작성된 오브젝트와 동일합니다 (이 경우, my_output_dataframe_one과 my_output_dataframe_two).

미디어 출처

Foundry에서의 미디어 출처 정보는 여기에서 찾을 수 있습니다.

모델 어댑터의 api()에서 파라미터 입력 또는 MediaReference 유형의 탭 입력 칼럼이 지정된 경우, model.transform()을 통해 제공된 미디어 출처 문자열은 MediaReference 오브젝트로 변환됩니다. 이 오브젝트 유형은 미디어 출처와 상호 작용하는 메서드를 제공합니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class MediaReference:
    @property
    def media_reference(self):
        """
        원시 미디어 참조 문자열.
        """

    @property
    def media_item_rid(self):
        """
        미디어 참조에서 추출된 미디어 항목 rid.
        """

    def get_media_item(self):
        """
        파일과 유사한 객체로 미디어 항목을 반환합니다.
        """

    def get_media_item_via_access_pattern(self, access_pattern_name, access_pattern_path):
        """
        파일과 유사한 객체로 미디어 항목의 접근 패턴을 반환합니다.
        미디어 세트의 지속성 정책에 따라 계산된 접근 패턴이 캐시될 수 있습니다.
        """

    def transform_media_item(self, output_path, transformation):
        """
        변환을 미디어 항목에 적용하고 파일과 유사한 객체로 반환합니다.
        출력 경로는 변환에 제공됩니다.
        변환 계산은 Mio에서 수행되며, 이 Spark 모듈에서는 수행되지 않습니다.
        """

    def get_media_item_metadata(self):
        """
        미디어 항목 메타데이터(너비, 높이 등)를 반환합니다.
        """