CLI で Web API を作成

はじめに

このドキュメントでは、ABEJA Platformを利用して、サンプルモデルをWebAPIとして起動する方法について説明します。

ABEJA Platform CLIを設定

ABEJA Platfrom CLI を利用することで、作成したモデルを ABEJA Platform へアップロードしたり、設定を変更したり、削除することが可能です。

インストール

ABEJA Platform CLIをインストールします。動作環境についてはこちらを参照してください。

$ curl -s https://packagecloud.io/install/repositories/abeja/platform-public/script.python.sh | bash
$ pip install abejacli

設定

ABEJA Platform CLIの設定を行います。ABEJA Platform の認証情報を設定してください。

$ abeja config init
User ID              : {USER_ID}
Personal Access Token: {PERSONAL_ACCESS_TOKEN}
Organization ID      : {ORGANIZATION_ID}
[INFO]: ABEJA credentials setup completed!

参照: ABEJA Platform CLI

サンプルのモデルを作成

サンプルモデルのダウンロード

こちらよりサンプルモデルのソースコードをダウンロードします。

ダウンロードしたソースコードには、簡単な計算を行う関数の実装が含まれています。

ソースコードを main.pyとして空のディレクトリに配置し、配置したディレクトリ上でコマンドを実行していきます。

$ ls
main.py
$ cat main.py
def handler(iter, context):
   for line in iter:
       if 'total_without_tax' not in line:
           raise context.exceptions.InvalidInput('total_without_tax not in the request')
       total_without_tax = line['total_without_tax']
       total_without_tax = int(total_without_tax)
       total = total_without_tax * 1.08
       yield {'total': total}

サンプルモデルのハンドラー関数をローカル実行

クラウド上にWebAPIの作成を開始する前に、ローカルでサンプルモデルのソースコードが動作することを確認します。

モデルハンドラー関数のテスト入力用に以下のようなJSONファイルを用意します。

$ cat request.json
{
  "total_without_tax": 100
}

run-localコマンドを実行し、サンプルモデルのハンドラー関数を呼び出します。

ハンドラー関数は main.pyに handlerという名前の関数として定義されているため、--handlerにはmain:handlerと指定します。

最終出力には入力であるrequest.jsonにハンドラー関数を適用した結果が表示されます。

$ abeja model run-local --image abeja/all-cpu:18.10 --handler main:handler --input request.json
[info] preparing image : abeja/all-cpu:18.10
...
[info] building image
...
[info] setting up local server
...
[info] waiting server running
...
[info] sending request to model
...
[info] finish requesting to model
{'total': 108.0}

モデルの作成

create-modelコマンドでモデルを作成します。

--name及び--descriptionには識別可能な任意の文字列を指定します。

$ abeja model create-model --name getting-started --description "this is a getting-started example model"
{
    "created_at": "2018-05-01T02:07:16.459526Z",
    "description": "this is a getting-started example model",
    "model_id": "1111111111111",
    "modified_at": "2018-05-01T02:07:16.459641Z",
    "name": "getting-started",
    "versions": []
}

モデルバージョンの作成

create-versionコマンドでモデルバージョンを作成します。

--model_idにはcreate-modelコマンドで作成したモデル識別子を指定します。

$ abeja model create-version --model_id {MODEL_ID} --version 0.0.1 \
                             --image abeja-inc/all-cpu:18.10 --handler main:handler
{
    "version": "0.0.1",
    "version_id": "ver-1111111111111111"
}

デプロイメントの作成

create-deploymentコマンドでデプロイメントを作成します。

--model_idにはcreate-modelコマンドで作成したモデル識別子を指定します。

$ abeja model create-deployment --name getting-started --model_id {MODEL_ID}
{
    "created_at": "2018-05-02T04:46:04.469269Z",
    "daemons": [],
    "default_environment": {},
    "deployment_id": "2222222222222",
    "model_id": "1111111111111",
    "modified_at": "2018-05-02T04:46:04.469381Z",
    "name": "getting-started",
    "runs": [],
    "services": [],
    "triggers": []
}

サービスの作成

create-serviceコマンドでサービスを作成し、対象モデルバージョンを WebAPIとして起動します。

--deploymentにはcreate-deploymentコマンドで作成したデプロイメント識別子、 --version_idにはcreate-versionコマンドで作成したバージョン識別子を指定します。

$ abeja model create-service --deployment_id {DEPLOYMENT_ID} --version_id {VERSION_ID}
{
    "created_at": "2018-05-02T05:38:19.312332Z",
    "deployment_id": "2222222222222",
    "instance_number": 1,
    "instance_type": "cpu-0.25",
    "metrics_url": "https://p.datadoghq.com/sb/aaaaaaaaa-6951475d7c4b91c840dbe30a07652620",
    "model_version": "0.0.1",
    "model_version_id": "ver-1111111111111111",
    "modified_at": "2018-05-02T05:38:21.301214Z",
    "service_id": "ser-1111111111111111",
    "status": "IN_PROGRESS",
    "user_env_vars": {}
}

作成されたサービスの起動状態の確認

サービスが利用可能な状態になっているか確認します。

describe-services コマンドを使用し、サービスのステータスを確認します。ステータスが READY になっていることを確認し、疎通確認を行います。

$ abeja model describe-services --deployment_id {DEPLOYMENT_ID}
{
    "entries": [
        {
            "created_at": "2018-05-02T05:38:19.312332Z",
            "deployment_id": "2222222222222",
            "instance_number": 1,
            "instance_type": "cpu-0.25",
            "metrics_url": "https://p.datadoghq.com/sb/c61020b12-6951475d7c4b91c840dbe30a07652620",
            "model_version": "0.0.1",
            "model_version_id": "ver-1111111111111111",
            "modified_at": "2018-05-02T05:38:21.301214Z",
            "service_id": "ser-1111111111111111",
            "status": "READY",
            "user_env_vars": {}
        }
    ]
}

作成されたサービスの動作を確認

create-service コマンドで作成されたWebAPIを呼び出し、 main.py の処理結果のレスポンスを確認します。

簡易チェックツールを利用する場合

JSONを入力として扱う WebAPIの動作チェックを行う場合、 check-endpoint-jsonコマンドを使用します。

$ abeja model check-endpoint-json --deployment_id {DEPLOYMENT_ID} --service_id {SERVICE_ID} \
                                  --key total_without_tax --value 100
{
    "total": 108.0
}

curlを利用する場合

curl で動作を確認する場合、以下のリクエストを行います。

$ curl  --user user-{ABEJA-PLATFORM-USER}:{PERSONAL-ACCESS-TOKEN} \
        -H 'Content-Type:application/json' \
        -XPOST -d '{"total_without_tax": 100}' \
        https://{ORGANIZATION_NAME}.api.abeja.io/deployments/{DEPLOYMENT_ID}/services/{SERVICE_ID}

サービスのエイリアス名の指定（エンドポイントの作成）

create-endpointコマンドを実行すると、指定したサービスにエイリアス（エンドポイント）を与えアクセスすることが可能になります。 その際に、endpointという管理単位が作成され describe-endpointsで確認することができます。

起動したサービスへの利用時は、 https://{ORGANIZATION_NAME}.api.abeja.io/deployments/{DEPLOYMENT_ID}/services/{SERVICE_ID}へのリクエストが必要ですが、 エイリアスを与えることで https://{ORGANIZATION_NAME}.api.abeja.io/deployments/{DEPLOYMENT_ID}/{エイリアス} としてアクセスすることが可能になります。

１つのサービスに複数のエイリアス（エンドポイント）を与えた場合も、いずれのエンドポイントへのリクエストもcreate-serviceで起動した同一のサービスが実態としてリクエストを受け付けます。

$ abeja model create-endpoint --deployment_id {DEPLOYMENT_ID} --service_id {SERVICE_ID} \
                              --custom_alias default
{
    "custom_alias": "default",
    "endpoint_id": "pnt-1111111111111111",
    "service_id": "ser-1111111111111111"
}

作成されたエンドポイントの動作を確認

create-endpoint コマンドで作成されたエンドポイントを呼び出し、 main.py の処理結果のレスポンスを確認します。

簡易チェックツールを利用する場合

JSONを入力として扱う WebAPIの動作チェックを行う場合、 check-endpoint-jsonコマンドを使用します。

$ abeja model check-endpoint-json --deployment_id {DEPLOYMENT_ID} \
                                  --key total_without_tax --value 100
{
    "total": 108.0
}

curlを利用する場合

curl で動作を確認する場合、以下のリクエストを行います。

$ curl  --user user-{ABEJA-PLATFORM-USER}:{PERSONAL-ACCESS-TOKEN} \
        -H 'Content-Type:application/json' \
        -XPOST -d '{"total_without_tax": 100}' \
        https://{ORGANIZATION_NAME}.api.abeja.io/deployments/{DEPLOYMENT_ID}