Driverless AI MOJO Scoring Pipeline - Java 런타임(Shapley 기여 포함)¶

실험이 완료되면 Driverless AI가 모델을 자동으로 MOJO(Model Objects, Optimized)로 변환합니다. MOJO Scoring Pipeline은 모든 Java 환경에 배치하여 실시간 채점을 할 수 있는 스코어링 엔진입니다(Python 및 R 래퍼를 사용한 C++ 스코어링 런타임에 대한 정보는 H2O MOJO c++ 스코어링 파이프라인 을 참조하십시오). 배포 옵션에 관해서는 H2O Mojo Deployment 를 참조하십시오.

MOJO는 실험과 연결되어 있습니다. Driverless AI가 업그레이드될 때 실험 및 MOJO는 자동으로 업그레이드되지 않습니다.

Notes:

이 스코어링 파이프라인은 현재 TensorFlow, BERT, RuleFit 또는 Image 모델에서 사용할 수 없습니다. TensorFlow/Bert는 C++ 런타임에서 지원됩니다.
이 스코어링 파이프라인의 자동 생성을 비활성화하려면, 실험을 빌드하는 동안 Make MOJO Scoring Pipeline 상세 설정을 Off 로 설정하십시오.
Reduce MOJO Size 상세 설정을 활성화하면, 실험을 빌드하는 동안 Driverless AI가 MOJO Scoring Pipeline의 크기 줄이기를 시도합니다. see 를 참조하십시오.
Shapely 기여는 다운로드된 실험 MOJO Scoring Pipeline(Java 런타임)과 함께 제공됩니다.
transformed features 및 original features 에 대한 Shapley contributions 는 현재 XGBoost(GBM, GLM, RF, DART), LightGBM, Zero-Inflated, Imbalanced, DecisionTree 모델(및 그 앙상블)에 available 합니다. ExtraTrees 메타 학습기를 포함한 앙상블(ensemble_meta_learner=〉extra_trees〉) 모델의 경우, MLI Python 채점 패키지를 사용하는 것이 좋습니다.

빠른 실행¶

예시 테스트 세트의 콘솔에서 다운로드한 MOJO Scoring Pipeline에서 빠른 출력을 얻으려면 다음 작업을 수행하십시오.

Java7 이상을 설치합니다.
다운로드한 mojo-pipeline 폴더에 Driverless AI 라이선스 파일(license.file)을 복사합니다.
mojo-pipeline 폴더에 명령을 입력합니다.
실험에서 생성된 pipeline.mojo 파일(mojo2-runtime)을 사용해 example.csv 파일의 행을 채점하여 예측값을 얻습니다.
java -Xmx5g -Dai.h2o.mojos.runtime.license.file=license.file -jar mojo2-runtime.jar pipeline.mojo example.csv

transformed features 에 대한 Shapley contributions 를 얻으려면 --show-contributions 플래그를 사용하여 실행합니다.

java -Xmx5g -Dai.h2o.mojos.runtime.license.file=license.file -jar mojo2-runtime.jar --show-contributions pipeline.mojo example.csv

original features 에 대한 Shapley contributions 를 얻으려면 --show-contributions-original 플래그를 사용하여 실행합니다.

java -Xmx5g -Dai.h2o.mojos.runtime.license.file=license.file -jar mojo2-runtime.jar --show-contributions-original pipeline.mojo example.csv

run-example.sh를 참조하십시오. 테스트 파일/MOJO가 클수록 점수를 위해 더 많은 메모리(Xmx)가 필요할 수 있습니다.

Notes:

현재 transformed features 에 대한 Shapley contributions 는 XGBoost(GBM, GLM, RF, DART), LightGBM, Zero-Inflated, Imbalanced, DecisionTree 모델(및 그 앙상블)에 대해 available 합니다. ExtraTrees 메타 학습기를 포함한 앙상블(ensemble_meta_learner=’extra_trees’) 모델의 경우, MLI Python 채점 패키지를 사용하는 것이 좋습니다.

현재 original features 에 대한 Shapley contributions 가 단일 모델(즉, 앙상블 레벨 1 또는 0)에 대해서만 available 합니다.

MOJO에서 original features 에 대한 Shapley value는 Naive Shapley (even split) 방법을 사용하여 변환된 기능에 대한 Shapley value로부터의 근사치입니다.

Shapley fast approximation 은 처음 50개 이하의 트리가 있는 하나의 모델(첫 번째 폴드)만 사용합니다. 관련 정보는 fast_approx_num_trees 및 fast_approx_do_one_fold_one_model config.toml settings 를 참조하십시오.

전제 조건¶

MOJO Scoring Pipeline을 실행하려면 다음 조건이 필요합니다.

Java 7 런타임(JDK 1.7) 이상. NOTE: Java의 버그로 인해 Java 11 이상을 사용할 것을 권장합니다. (https://bugs.openjdk.java.net/browse/JDK-8186464 참조.)
유효한 Driverless AI 라이선스. Driverless AI를 호스팅하는 시스템(일반적으로 license 폴더에 있음)에서 license.sig 파일을 다운로드할 수 있습니다. 다운로드한 mojo-pipeline 폴더에 라이선스 파일을 복사합니다.
mojo2-runtime.jar 파일. 이 파일은 Driverless AI UI의 상단 탐색 메뉴와 실험을 위해 다운로드한 mojo-pipeline.zip 파일에 있습니다.

라이선스 사양¶

Driverless AI에서 MOJO Scoring Pipeline을 실행하려면 라이선스를 지정해야 합니다. 다음 중 한 가지 방법으로 라이선스를 지정할 수 있습니다.

환경 변수를 통해
- DRIVERLESS_AI_LICENSE_FILE: Driverless AI 라이선스 파일의 경로, 또는
- DRIVERLESS_AI_LICENSE_KEY: Driverless AI 라이선스 키(Base64 인코드 스트링)
JVM의 시스템 속성 이용(-D 옵션):
- ai.h2o.mojos.runtime.license.file: Driverless AI 라이선스 파일의 경로, 또는
- ai.h2o.mojos.runtime.license.key: Driverless AI 라이선스 키(Base64 인코드 문자열)
애플리케이션 클래스 경로를 통해
- 라이선스는 /license.sig 라는 리소스에서 로드됩니다.
- 기본 리소스 이름은 JVM 시스템 속성 ai.h2o.mojos.runtime.license.filename 을 통해 변경할 수 있습니다.

예:

# Specify the license via a temporary environment variable
export DRIVERLESS_AI_LICENSE_FILE="path/to/license.sig"

MOJO Scoring Pipeline 파일¶

mojo-pipeline 폴더에는 다음 파일이 포함되어 있습니다.

run_example.sh: 샘플 테스트 세트를 채점하기 위한 bash 스크립트.
pipeline.mojo: MOJO 형식의 독립형 스코어링 파이프라인.
mojo2-runtime.jar: MOJO Java 런타임.
example.csv: 샘플 테스트 세트(합성, 올바른 형식).
DOT 파일: MOJO Scoring Pipeline의 시각적 표현을 제공하는 그래프로 렌더링할 수 있는 텍스트 파일(편집하여 렌더링된 그래프의 모양과 구조를 변경할 수 있음).
PNG 파일: MOJO Scoring Pipeline의 시각적 표현을 제공하는 이미지 파일.

빠른 시작¶

빠른 시작 예시를 실행하기 전에 MOJO Scoring Pipeline이 다운로드되어 압축이 해제되어 있어야 합니다.

완료된 Experiment 페이지에서, Download MOJO Scoring Pipeline 버튼을 클릭합니다.

팝업 메뉴가 나타나면 Download MOJO Scoring Pipeline 버튼을 다시 클릭하여 이 실험에 대한 scorer.zip 파일을 로컬 컴퓨터에 다운로드합니다. Java, Python 또는 R에 대해 제공된 설명서를 참조하십시오.

다음을 실행하여 환경 변수 TEST_SET_FILE, MOJO_PIPELINE_FILE, DRIVERLESS_AI_LICENSE_KEY 에 저장된 테스트 세트(example.csv), MOJO 파이프라인(pipeline.mojo) 및 라이선스(license.sig)의 파일 경로로 샘플 테스트 세트의 모든 행을 채점합니다.

bash run_example.sh

다음을 실행하여 MOJO 파이프라인(pipeline.mojo) 및 라이선스 파일(license.sig)로 특정 테스트 세트(example.csv)를 채점합니다.

bash run_example.sh pipeline.mojo example.csv license.sig

데이터 변환을 위해 Java 애플리케이션을 직접 실행하려면

java -Dai.h2o.mojos.runtime.license.file=license.sig -cp mojo2-runtime.jar ai.h2o.mojos.ExecuteMojo pipeline.mojo example.csv
Note: 아주 큰 모델의 경우, 데이터 변환을 위해 Java 애플리케이션을 실행할 때 메모리 제한을 늘려야 할 수 있습니다. 위 명령을 실행할 때 -Xmx25g 를 지정하면 됩니다.

MOJO Scoring 명령줄 옵션¶

Java 런타임 실행¶

다음은 명령줄에서 Java 런타임을 실행하는 일반적인 두 가지 예시입니다.

With additional libraries:

java <JVM options> [options...] -cp mojo2-runtime.jar:your-other.jar:many-more-libs.jar ai.h2o.mojos.ExecuteMojo path-to/pipeline.mojo path-to/input.csv path-to/output.csv

Without additional libraries:

java <JVM options> -jar mojo2-runtime.jar path-to/pipeline.mojo path-to/input.csv path-to/output.csv

따라서 예를 들어 sys.ai.h2o.mojos.parser.csv.separator 옵션을 다음과 함께 전달할 수 있습니다.

java -Dsys.ai.h2o.mojos.parser.csv.separator='|' -Dai.h2o.mojos.runtime.license.file=../license.sig -jar mojo2-runtime.jar pipeline.mojo input.csv output.csv

이와 유사하게, sys.ai.h2o.mojos.exposedInputs 옵션을 다음과 함께 전달할 수 있습니다.

java -Xmx5g -Dsys.ai.h2o.mojos.exposedInputs=ALL -Dai.h2o.mojos.runtime.license.file= -cp mojo2-runtime.jar ai.h2o.mojos.ExecuteMojo pipeline.mojo example.csv

Note: 입력 및 출력 CSV 인수를 모두 `-`로 대체하여 데이터를 stdin에서 stdout으로 스트리밍할 수 있습니다.

Java 가상 머신(JVM) 옵션¶

sys.ai.h2o.mojos.parser.csv.keepCarriageReturn (boolean) - 구문 분석 후 캐리지 리턴을 유지할지 여부를 지정합니다. 이 값의 기본값은 True입니다.
sys.ai.h2o.mojos.parser.csv.stripCrFromLastColumn (boolean) - OpenCSV 파서와 관련된 문제에 대한 해결 방법입니다. 기본값은 True입니다.
sys.ai.h2o.mojos.parser.csv.quotedHeaders (boolean) - 출력 CSV 파일에서 헤더 이름을 인용할지 여부를 지정합니다. 기본값은 False입니다.
sys.ai.h2o.mojos.parser.csv.separator (char) - CSV 필드 사이에 사용되는 구분 기호를 지정합니다. 탭으로 구분된 값에는 특수 값 `TAB`을 사용할 수 있습니다. 기본값은 `,`입니다.
sys.ai.h2o.mojos.parser.csv.escapeChar (char) - CSV 필드 구문 분석을 위한 이스케이프 문자를 지정합니다. 이 값을 지정하지 않으면 이스케이프를 시도하지 않습니다. 기본값은 빈 문자열입니다.
sys.ai.h2o.mojos.parser.csv.batch (int) - 일괄 처리를 위해 메모리로 가져온 입력 레코드 수를 지정합니다(사용된 메모리를 확인함). 기본값은 1000입니다.
sys.ai.h2o.mojos.pipelineFormats (string) - 여러 형식이 인식되는 경우, 이 옵션은 시도할 순서를 지정합니다. 기본값은 `pbuf,toml,klime,h2o3`입니다.
sys.ai.h2o.mojos.parser.csv.date.formats (string) - 날짜 형식을 지정합니다. 기본값은 빈 문자열입니다.
sys.ai.h2o.mojos.exposedInputs (string) - 출력에 필요한 쉼표로 구분된 입력 열 목록을 지정합니다. 특수 값 ‘`ALL`은 모든 입력을 사용합니다. 기본값은 null입니다.
sys.ai.h2o.mojos.useWeakHash (boolean) - WeakHashMap 사용 여부를 지정합니다. 기본적으로 False로 설정되어 있습니다. 이 설정을 활성화하면 MOJO 로드 시간이 향상될 수 있습니다.

JVM Options for Access Control

ai.h2o.mojos.runtime.license.key - 라이선스 키를 지정합니다.
ai.h2o.mojos.runtime.license.file - 라이선스 키의 위치를 지정합니다.
ai.h2o.mojos.runtime.license.filename - 기본 라이선스 파일 이름을 재정의합니다.
ai.h2o.mojos.runtime.signature.filename - 기본 서명 파일 이름을 재정의합니다.
ai.h2o.mojos.runtime.watermark.filename - 기본 워터마크 파일 이름을 재정의합니다.

Java에서 MOJO 실행¶

새 터미널 창을 열고 실험 폴더를 만들어 디렉터리를 새 폴더로 변경합니다.

mkdir experiment && cd experiment

새로운 파일 DocsExample.java 를 만들어 experiment 폴더에 기본 프로그램을 생성합니다(예: vim DocsExample.java 사용). 다음 콘텐츠를 포함시킵니다.

import ai.h2o.mojos.runtime.MojoPipeline;
import ai.h2o.mojos.runtime.api.MojoPipelineService;
import ai.h2o.mojos.runtime.frame.MojoFrame;
import ai.h2o.mojos.runtime.frame.MojoFrameBuilder;
import ai.h2o.mojos.runtime.frame.MojoRowBuilder;
import ai.h2o.mojos.runtime.lic.LicenseException;
import ai.h2o.mojos.runtime.utils.CsvWritingBatchHandler;
import com.opencsv.CSVWriter;
import java.io.BufferedWriter;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.Writer;

public class DocsExample {
    public static void main(String[] args) throws IOException, LicenseException {
        // Load model and csv
        final MojoPipeline model = MojoPipelineService.loadPipeline(new File("pipeline.mojo"));

        // Get and fill the input columns
        final MojoFrameBuilder frameBuilder = model.getInputFrameBuilder();
        final MojoRowBuilder rowBuilder = frameBuilder.getMojoRowBuilder();
        rowBuilder.setValue("AGE", "68");
        rowBuilder.setValue("RACE", "2");
        rowBuilder.setValue("DCAPS", "2");
        rowBuilder.setValue("VOL", "0");
        rowBuilder.setValue("GLEASON", "6");
        frameBuilder.addRow(rowBuilder);

        // Create a frame which can be transformed by MOJO pipeline
        final MojoFrame iframe = frameBuilder.toMojoFrame();

        // Transform input frame by MOJO pipeline
        final MojoFrame oframe = model.transform(iframe);
        // `MojoFrame.debug()` can be used to view the contents of a Frame
        // oframe.debug();

        // Output prediction as CSV
        final Writer writer = new BufferedWriter(new OutputStreamWriter(System.out));
        final CSVWriter csvWriter = new CSVWriter(writer);
        CsvWritingBatchHandler.csvWriteFrame(csvWriter, oframe, true);
    }
}

실험에 복사된 MOJO 런타임(mojo2-runtime.jar) 및 MOJO 파이프라인(pipeline.mojo) 파일로 소스 코드를 컴파일합니다.

javac -cp mojo2-runtime.jar -J-Xms2g -J-XX:MaxPermSize=128m DocsExample.java

실험에 복사한 라이선스(license.sig)로 MOJO 예시를 실행합니다.

# Linux and OS X users
java -Dai.h2o.mojos.runtime.license.file=license.sig -cp .:mojo2-runtime.jar Main

# Windows users
java -Dai.h2o.mojos.runtime.license.file=license.sig -cp .;mojo2-runtime.jar Main

다음 출력이 표시됩니다.

CAPSULE.True
0.5442205910902282

Spark/Sparkling Water로 MOJO Scoring Pipeline 사용¶

Note: Driverless AI 1.5 릴리스는 TOML 기반 MOJO2를 사용하는 마지막 릴리스입니다. 1.5 이상부터는 protobuf 기반 MOJO2가 포함됩니다.

MOJO Scoring Pipeline 아티팩트는 Spark에서 Sparkling Water API를 사용하여 동시에 예측을 배포하는 데 사용할 수 있습니다. 이 섹션에서는 Scala 및 Python API를 사용하여 Spark에서 MOJO Scoring Pipeline의 예측을 로드하고 실행하는 방법을 보여줍니다.

H2O Driverless AI를 업그레이드할 고객에게는 희소식이 있습니다! Sparkling Water가 이전 Driverless AI 버전에서 생산된 MOJO 버전과 역호환됩니다.

요구 사항¶

Sparkling Water JAR 파일이 포함된 Spark 클러스터가 Spark에 전달되어야 합니다.
PySparkling으로 실행하려면 PySparkling zip 파일이 필요합니다.

Spark를 사용하여 MOJO에 대한 예측만 실행하려는 경우 H2OContext를 만들 필요가 없습니다. 스코어링은 H2O 런타임과 독립적이기 때문입니다.

환경 준비¶

MOJO Scoring Pipeline을 사용하려면 Driverless AI 라이선스를 Spark에 전달해야 합니다. Spark 런처 스크립트의 `` –jars`` 인수를 사용하면 됩니다.

Note: 로컬 Spark 모드에서 --driver-class-path 를 사용하여 라이선스 파일의 경로를 지정하십시오.

PySparkling¶

먼저 PySparkling Python 패키지 및 Driverless AI 라이선스로 PySpark를 시작합니다.

./bin/pyspark --jars license.sig --py-files pysparkling.zip

또는 H2O 다운로드 페이지 에서 공식 Sparkling Water 배포를 다운로드할 수 있습니다. Sparkling Water 다운로드 페이지의 절차를 따르십시오. Sparkling Water 디렉터리에 들어가면 다음을 호출할 수 있습니다.

./bin/pysparkling --jars license.sig

이 때 예측을 시도할 수 있는 PySpark 대화형 터미널이 있어야 합니다. 스코어링 프로세스를 생산화(productionalize)하려면, 동일한 구성을 사용할 수 있습니다. 단, 작업을 클러스터에 제출할 때 ./bin/pyspark 대신 ./bin/spark-submit 를 사용해야 합니다.

# First, specify the dependencies
from pysparkling.ml import H2OMOJOPipelineModel, H2OMOJOSettings

# The 'namedMojoOutputColumns' option ensures that the output columns are named properly.
# If you want to use old behavior when all output columns were stored inside an array,
# set it to False. However we strongly encourage users to use True which is defined as a default value.
settings = H2OMOJOSettings(namedMojoOutputColumns = True)

# Load the pipeline. 'settings' is an optional argument. If it's not specified, the default values are used.
mojo = H2OMOJOPipelineModel.createFromMojo("file:///path/to/the/pipeline.mojo", settings)

# Load the data as Spark's Data Frame
dataFrame = spark.read.csv("file:///path/to/the/data.csv", header=True)

# Run the predictions. The predictions contain all the original columns plus the predictions
# added as new columns
predictions = mojo.transform(dataFrame)

# You can easily get the predictions for a desired column using the helper function as
predictions.select(mojo.selectPredictionUDF("AGE")).collect()

Sparkling Water¶

먼저 Sparkling Water Scala 어셈블리 및 Driverless AI 라이선스로 Spark를 시작합니다.

./bin/spark-shell --jars license.sig,sparkling-water-assembly.jar

또는 H2O 다운로드 페이지 에서 공식 Sparkling Water 배포를 다운로드할 수 있습니다. Sparkling Water 다운로드 페이지의 절차를 따르십시오. Sparkling Water 디렉터리에 들어가면 다음을 호출할 수 있습니다.

./bin/sparkling-shell --jars license.sig

이 때 예측을 수행할 수 있는 Sparkling Water 대화형 터미널이 있어야 합니다. 스코어링 프로세스를 생산화하려면, 동일한 구성을 사용할 수 있습니다. 단, 작업을 클러스터에 제출할 때 ./bin/spark-shell 대신 ./bin/spark-submit 를 사용해야 합니다.

// First, specify the dependencies
import ai.h2o.sparkling.ml.models.{H2OMOJOPipelineModel, H2OMOJOSettings}

// The 'namedMojoOutputColumns' option ensures that the output columns are named properly.
// If you want to use old behavior when all output columns were stored inside an array,
// set it to false. However we strongly encourage users to use true which is defined as a default value.
val settings = H2OMOJOSettings(namedMojoOutputColumns = true)

// Load the pipeline. 'settings' is an optional argument. If it's not specified, the default values are used.
val mojo = H2OMOJOPipelineModel.createFromMojo("file:///path/to/the/pipeline.mojo", settings)

// Load the data as Spark's Data Frame
val dataFrame = spark.read.option("header", "true").csv("file:///path/to/the/data.csv")

// Run the predictions. The predictions contain all the original columns plus the predictions
// added as new columns
val predictions = mojo.transform(dataFrame)

// You can easily get the predictions for desired column using the helper function as follows:
predictions.select(mojo.selectPredictionUDF("AGE")).show()