The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Kogito を使用してアプリケーションに予測機能を追加する

このガイドでは、QuarkusアプリケーションがKogitoを使用してビジネスオートメーションを追加し、予測機能を強化する方法について説明します。

Kogitoは、よく知られたオープンソース・プロジェクトであるDrools(予測のための)から生まれた、次世代のビジネス・オートメーション・ツールキットです。Kogitoは、ビジネス・オートメーションに新しいアプローチを提供することを目的としており、主なメッセージは、ビジネス・ナレッジ(プロセス、ルール、意思決定、予測)をドメイン固有の方法で公開することです。

前提条件

このガイドを完成させるには、以下が必要です:

  • 約15分

  • IDE

  • JDK 11+ がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.8.1+

  • 動作するコンテナランタイム(Docker, Podman)

  • 使用したい場合、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

アーキテクチャ

この例では、1つのRESTエンドポイントを提供する非常にシンプルなマイクロサービスを構築します:

  • /LogisticRegressionIrisData

このエンドポイントは、与えられたPMMLファイルに基づいて自動的に生成されます。生成されたコードを使用して、処理されるデータに基づいて特定の予測を行います。

PMMLファイル

The PMML file describes the prediction logic of our microservice. It should provide the actual model (Regression, Tree, Scorecard, Clustering, etc.) needed to make the prediction.

予測エンドポイント

これらは、クライアントが実行するサービスへのエントリーポイントとなります。

ソリューション

次のセクションで紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

Gitリポジトリをクローンする: git clone https://github.com/quarkusio/quarkus-quickstarts.git 、または archive をダウンロードする。

このソリューションは kogito-pmml-quickstart directory にあります。

Mavenプロジェクトの作成

まず、新しいプロジェクトを用意します。以下のコマンドで新しいプロジェクトを作成します:

CLI
quarkus create app org.acme:kogito-pmml-quickstart \
    --extension=kogito,resteasy-reactive-jackson \
    --no-code
cd kogito-pmml-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストール方法については、Quarkus CLIガイドをご参照ください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.11.1.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=kogito-pmml-quickstart \
    -Dextensions="kogito,resteasy-reactive-jackson" \
    -DnoCode
cd kogito-pmml-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

このコマンドはMavenプロジェクトを生成し、アプリケーションにビジネス・オートメーションの機能を追加するために必要な依存関係と構成をすべて備えた kogito エクステンションをインポートします。また、KogitoがRESTサービスを公開するのに必要な resteasy-jackson エクステンションをインポートします。

すでにQuarkusプロジェクトが設定されている場合は、プロジェクトのベースディレクトリーで以下のコマンドを実行することで、プロジェクトに kogito エクステンションを追加することができます:

CLI
quarkus extension add 'kogito'
Maven
./mvnw quarkus:add-extension -Dextensions="kogito"
Gradle
./gradlew addExtension --extensions="kogito"

これにより、 pom.xml に以下が追加されます:

pom.xml
<dependency>
    <groupId>org.kie.kogito</groupId>
    <artifactId>kogito-quarkus</artifactId>
</dependency>
build.gradle
implementation("org.kie.kogito:kogito-quarkus")

アプリケーションの作成

Predictions are evaluated based on a PMML model, whose standard and specifications may be read here. Let’s start by adding a simple PMML file: LogisticRegressionIrisData.pmml. It contains a Regression model named LogisticRegressionIrisData, and it uses a regression function to predict plant species from sepal and petal dimensions:

<PMML xmlns="http://www.dmg.org/PMML-4_2" version="4.2">
  <Header/>
  <DataDictionary numberOfFields="5">
    <DataField name="Sepal.Length" optype="continuous" dataType="double"/>
    <DataField name="Sepal.Width" optype="continuous" dataType="double"/>
    <DataField name="Petal.Length" optype="continuous" dataType="double"/>
    <DataField name="Petal.Width" optype="continuous" dataType="double"/>
    <DataField name="Species" optype="categorical" dataType="string">
      <Value value="setosa"/>
      <Value value="virginica"/>
      <Value value="versicolor"/>
    </DataField>
  </DataDictionary>
  <RegressionModel functionName="classification" modelName="LogisticRegressionIrisData" targetFieldName="Species">
    <MiningSchema>
      <MiningField name="Sepal.Length"/>
      <MiningField name="Sepal.Width"/>
      <MiningField name="Petal.Length"/>
      <MiningField name="Petal.Width"/>
      <MiningField name="Species" usageType="target"/>
    </MiningSchema>
    <Output>
      <OutputField name="Probability_setosa" optype="continuous" dataType="double" feature="probability" value="setosa"/>
      <OutputField name="Probability_versicolor" optype="continuous" dataType="double" feature="probability" value="versicolor"/>
      <OutputField name="Probability_virginica" optype="continuous" dataType="double" feature="probability" value="virginica"/>
    </Output>
    <RegressionTable targetCategory="setosa" intercept="0.11822288946815">
      <NumericPredictor name="Sepal.Length" exponent="1" coefficient="0.0660297693761902"/>
      <NumericPredictor name="Sepal.Width" exponent="1" coefficient="0.242847872054487"/>
      <NumericPredictor name="Petal.Length" exponent="1" coefficient="-0.224657116235727"/>
      <NumericPredictor name="Petal.Width" exponent="1" coefficient="-0.0574727291860025"/>
    </RegressionTable>
    <RegressionTable targetCategory="versicolor" intercept="1.57705897385745">
      <NumericPredictor name="Sepal.Length" exponent="1" coefficient="-0.0201536848255179"/>
      <NumericPredictor name="Sepal.Width" exponent="1" coefficient="-0.44561625761404"/>
      <NumericPredictor name="Petal.Length" exponent="1" coefficient="0.22066920522933"/>
      <NumericPredictor name="Petal.Width" exponent="1" coefficient="-0.494306595747785"/>
    </RegressionTable>
    <RegressionTable targetCategory="virginica" intercept="-0.695281863325603">
      <NumericPredictor name="Sepal.Length" exponent="1" coefficient="-0.0458760845506725"/>
      <NumericPredictor name="Sepal.Width" exponent="1" coefficient="0.202768385559553"/>
      <NumericPredictor name="Petal.Length" exponent="1" coefficient="0.00398791100639665"/>
      <NumericPredictor name="Petal.Width" exponent="1" coefficient="0.551779324933787"/>
    </RegressionTable>
  </RegressionModel>
</PMML>

プロジェクトのコンパイル時に、Kogitoはファイルを読み込んで、評価に必要なクラスと、いくつかのRESTエンドポイントを生成します。

すぐに始めるには、 quickstart からPMMLファイルをコピーしてください。

アプリケーションの実行と使用

Devモードでの動作

マイクロサービスをdevモードで実行するには:

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

JVMモードでの動作

「開発モード」で遊び終わったら、標準のJavaアプリケーションとして実行することができます。

まずコンパイルします:

CLI
quarkus build
Maven
./mvnw clean package
Gradle
./gradlew build

それから以下を実行してください:

java -jar target/quarkus-app/quarkus-run.jar

ネイティブモードでの実行

同じデモをネイティブコードにコンパイルすることができます。修正は必要ありません。

これは、生成されたバイナリにランタイム技術が含まれており、最小限のリソースオーバーヘッドで実行できるように最適化されているため、本番環境にJVMをインストールする必要がないことを意味します。

コンパイルには少し時間がかかるので、このステップはデフォルトでは無効になっています。以下のコマンドでネイティブ実行可能ファイルをビルドしてみましょう:

CLI
quarkus build --native
Maven
./mvnw package -Dnative
Gradle
./gradlew build -Dquarkus.package.type=native

コーヒーを飲み終わると、このバイナリは以下のように直接実行出来るようになります:

./target/kogito-pmml-quickstart-1.0.0-SNAPSHOT-runner

アプリケーションのテスト

アプリケーションをテストするには、JSONペイロードとして期待される入力を提供して、エンドポイントにリクエストを送るだけです。

curl -X POST http://localhost:8080/LogisticRegressionIrisData \
    -H 'content-type: application/json' \
    -H 'accept: application/json' \
    -d '{ "Sepal.Length": 6.9, "Sepal.Width": 3.1, "Petal.Length": 5.1, "Petal.Width": 2.3 }'

レスポンスの中に、予測値が表示されているはずですが、それは virginica のはずです:

{
  "Species": "virginica"
}

また、descriptive エンドポイントを呼び出すこともでき、その場合は OutputField の評価も提供されます:

curl -X POST http://localhost:8080/LogisticRegressionIrisData/descriptive \
    -H 'content-type: application/json' \
    -H 'accept: application/json' \
    -d '{ "Sepal.Length": 6.9, "Sepal.Width": 3.1, "Petal.Length": 5.1, "Petal.Width": 2.3 }'
{
    "correlationId": null,
    "segmentationId": null,
    "segmentId": null,
    "segmentIndex": 0,
    "resultCode": "OK",
    "resultObjectName": "Species",
    "resultVariables": {
        "Probability_setosa": 0.04871813160275851,
        "Probability_versicolor": 0.04509592640753013,
        "Probability_virginica": 0.9061859419897114,
        "Species": "virginica"
    }
}