Awesome

kiosk-client

kiosk-client is tool for interacting with the DeepCell Kiosk in order to create and monitor deep learning image processing jobs. It uses the asynchronous HTTP client treq and the Kiosk-Frontend API to create and monitor many jobs at once. Once all jobs are completed, costs are estimated by using the cluster's Grafana API. An output file is then generated with statistics on each job's performance and resulting output files.

This repository is part of the DeepCell Kiosk. More information about the Kiosk project is available through Read the Docs and our FAQ page.

Installation

Install with `pip`

pip install kiosk_client

Install from source

# clone the repository
git clone https://github.com/vanvalenlab/kiosk-client.git

# install the package
pip install kiosk-client

Usage

The only thing necessary to use the CLI is the image file to process, the type of job, and the IP address or FQDN of the DeepCell Kiosk.

python -m kiosk_client path/to/image.png \
  --job-type segmentation \
  --host 123.456.789.012

It is also possible to override the default model and post-processing function for a given job type.

python -m kiosk_client path/to/image.png \
  --job-type segmentation \
  --host 123.456.789.012 \
  --model ModelName:0 \
  --post deep_watershed

Benchmark Mode

The CLI can also be used to benchmark the cluster with high volume jobs. It is a prerequisite that the the FILE exist in the STORAGE_BUCKET inside UPLOAD_PREFIX (e.g. /uploads/image.png). There are also a number of other benchmarking options including --upload-results and --calculate_cost. A new job is created every START_DELAY seconds up to COUNT jobs. The upload time can be simulated by changing the start delay.

# from within the kiosk-client repository
python -m kiosk_client path/to/image.png \
  --job-type segmentation \
  --host 123.456.789.012 \
  --model ModelName:0 \
  --post deep_watershed \
  --start-delay 0.5 \
  --count 1000 \
  --calculate_cost \
  --upload-results

It is easiest to run a benchmarking job from within the DeepCell Kiosk.

Configuration

Each job can be configured using environmental variables in a .env file. Most of these environment variables can be overridden with command line options. Use python benchmarking --help for detailed list of options.

Name	Description	Default Value
`JOB_TYPE`	REQUIRED: Name of job workflow.	`"segmentation"`
`API_HOST`	REQUIRED: Hostname and port for the kiosk-frontend API server.	`""`
`STORAGE_BUCKET`	Cloud storage bucket address (e.g. `"gs://bucket-name"`). Required if using `benchmark` mode and `upload-results`.	`""`
`MODEL`	Name and version of the model hosted by TensorFlow Serving (e.g. `"modelname:0"`). Overrides default model for the given `JOB_TYPE`	`"modelname:0"`
`SCALE`	Rescale data by this float value for model compatibility.	`1`
`LABEL`	Integer value of label type.	`""`
`PREPROCESS`	Name of the preprocessing function to use (e.g. `"normalize"`).	`""`
`POSTPROCESS`	Name of the postprocessing function to use (e.g. `"watershed"`).	`""`
`UPLOAD_PREFIX`	Prefix of upload directory in the cloud storage bucket.	`"/uploads"`
`UPDATE_INTERVAL`	Number of seconds a job should wait between sending status update requests to the server.	`10`
`START_DELAY`	Number of seconds between submitting each new job. This can be configured to simulate upload latency.	`0.05`
`MANAGER_REFRESH_RATE`	Number of seconds between completed job updates.	`10`
`EXPIRE_TIME`	Completed jobs are expired after this many seconds.	`3600`
`CONCURRENT_REQUESTS_PER_HOST`	Limit number of simultaneous requests to the server.	`64`
`NUM_CYCLES`	Number of times to run the job.	`1`
`NUM_GPUS`	Number of GPUs used during the run. Used for logging.	`0`
`LOG_ENABLED`	Toggle for enabling/disabling logging.	`True`
`LOG_LEVEL`	Level of output for logging statements.	`"DEBUG"`
`LOG_FILE`	Filename of the log file.	`"benchmark.log"`
`GRAFANA_HOST`	Hostname of the Grafana server.	`"prometheus-operator-grafana"`
`GRAFANA_USER`	Username for the Grafana server.	`"admin"`
`GRAFANA_PASSWORD`	Password for the Grafana server.	`"prom-operator"`

Google Cloud Authentication

When uploading to Google Cloud, you will need to authenticate using the GOOGLE_APPLICATION_CREDENTIALS set to your service account JSON file.

Contribute

We welcome contributions to the kiosk-console and its associated projects. If you are interested, please refer to our Developer Documentation, Code of Conduct and Contributing Guidelines.

License

This software is license under a modified Apache-2.0 license. See LICENSE for full details.

Copyright

Copyright © 2018-2020 The Van Valen Lab at the California Institute of Technology (Caltech), with support from the Paul Allen Family Foundation, Google, & National Institutes of Health (NIH) under Grant U24CA224309-01. All rights reserved.