{"id":13628566,"url":"https://github.com/knjcode/mxnet-finetuner","last_synced_at":"2026-01-18T15:08:21.231Z","repository":{"id":78141056,"uuid":"99867630","full_name":"knjcode/mxnet-finetuner","owner":"knjcode","description":"An all-in-one Deep Learning toolkit for image classification to fine-tuning pretrained models using MXNet.","archived":false,"fork":false,"pushed_at":"2018-11-02T23:22:31.000Z","size":536,"stargazers_count":103,"open_issues_count":3,"forks_count":9,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-08T19:42:00.923Z","etag":null,"topics":["deep-learning","deep-neural-networks","fine-tuning-cnns","machine-learning","mxnet"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knjcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-08-10T01:29:33.000Z","updated_at":"2024-01-04T16:16:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"fe678ae0-9cc0-4710-8251-fd6db697946e","html_url":"https://github.com/knjcode/mxnet-finetuner","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knjcode%2Fmxnet-finetuner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knjcode%2Fmxnet-finetuner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knjcode%2Fmxnet-finetuner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knjcode%2Fmxnet-finetuner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knjcode","download_url":"https://codeload.github.com/knjcode/mxnet-finetuner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249315953,"owners_count":21249866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","deep-neural-networks","fine-tuning-cnns","machine-learning","mxnet"],"created_at":"2024-08-01T22:00:54.095Z","updated_at":"2026-01-18T15:08:21.204Z","avatar_url":"https://github.com/knjcode.png","language":"Jupyter Notebook","readme":"# mxnet-finetuner\n\nAn all-in-one Deep Learning toolkit for image classification to fine-tuning pretrained models using MXNet.\n\n\n## Prerequisites\n\n- docker\n- docker-compose\n- jq\n- wget or curl\n\nWhen using NVIDIA GPUs\n\n- nvidia-docker (Both version 1.0 and 2.0 are acceptable)\n\nIf you are using nvidia-docker version 1.0 and have never been running the `nvidia-docker` command after installing it, run the following command at least once to create the volume for GPU container.\n\n```\n$ nvidia-docker run --rm nvidia/cuda nvidia-smi\n```\n\n## Setup\n\n```\n$ git clone https://github.com/knjcode/mxnet-finetuner\n$ cd mxnet-finetuner\n$ bash setup.sh\n```\n\n`setup.sh` will automatically generate` docker-compose.yml` and `config.yml` which are necessary for executing this tool according to your environment such as existence of the GPU. Please see [common settings](#common-settings) on how to run with GPU image on NVIDIA GPUs.\n\nWhen updating the GPU driver of the host machine, re-running `setup.sh`. Please see [After updating the GPU driver of the host machine](docs/setup.md#after-updating-the-gpu-driver-of-the-host-machine) for details.\n\n## Example usage\n\n\n### 1. Arrange images into their respective directories\n\nA training data directory (`images/train`), validation data directory (`images/valid`), and test data directory (`images/test`) should containing one subdirectory per image class.\n\nFor example, arrange training, validation, and test data as follows.\n\n```\nimages/\n    train/\n        airplanes/\n            airplane001.jpg\n            airplane002.jpg\n            ...\n        watch/\n            watch001.jpg\n            watch002.jpg\n            ...\n    valid/\n        airplanes/\n            airplane101.jpg\n            airplane102.jpg\n            ...\n        watch/\n            watch101.jpg\n            watch102.jpg\n            ...\n    test/\n        airplanes/\n            airplane201.jpg\n            airplane202.jpg\n            ...\n        watch/\n            watch201.jpg\n            watch202.jpg\n            ...\n```\n\n\n### 2. Edit config.yml\n\nEdit `config.yml` as you like.\n\nFor example\n```\ncommon:\n  num_threads: 4\n  gpus: 0\n\ndata:\n  quality: 100\n  shuffle: 1\n  center_crop: 0\n\nfinetune:\n  models:\n    - imagenet1k-resnet-50\n  optimizers:\n    - sgd\n  num_epochs: 30\n  lr: 0.0001\n  lr_factor: 0.1\n  lr_step_epochs: 10,20\n  mom: 0.9\n  wd: 0.00001\n  batch_size: 10\n```\n\nPlease see [common settings](#common-settings) on how to run with GPU image on NVIDIA GPUs.\n\n### 3. Do Fine-tuning\n\n```\n$ docker-compose run finetuner\n```\n\nmxnet-finetuner will automatically execute the followings according to `config.yml`.\n\n- Create RecordIO data from images\n- Download pretrained models\n- Replace the last fully-connected layer with a new one that outputs the desired number of classes\n- Data augumentaion\n- Do Fine-tuning\n- Make training accuracy/loss graph\n- Make confusion matrix\n- Upload training accuracy/loss graph and confusion matrix to Slack\n\nTraining accuracy/loss graph and/or confusion matrix are save at `logs/` directory.  \nTrained models are save at `model/` directory.\n\nTrained models are saved with the following file name for each epoch.\n```\nmodel/201705292200-imagenet1k-nin-sgd-0000.params\n```\n\nIf you want to upload results to Slack, set `SLACK_API_TOKEN` environment variable and edit `config.yml` as below.\n```\nfinetune:\n  train_accuracy_graph_slack_upload: 1\n  train_loss_graph_slack_upload: 1\ntest:\n  confusion_matrix_slack_upload: 1\n```\n\n\n### 4. Predict with trained models\n\nSelect the trained model and epoch you want to use for testing and edit `config.yml`\n\nIf you want to use `model/201705292200-imagenet1k-nin-sgd-0001.params`, edit `config.yml` as blow.\n\n```\ntest:\n  model: 201705292200-imagenet1k-nin-sgd-0001\n```\n\nWhen you want to use the latest highest validation accuracy trained model, edit `config.yml` as below.\n\n```\ntest:\n  use_latest: 1\n```\n\nIf set this option, `model` is ignored.\n\nWhen you are done, you can predict with the following command\n\n```\n$ docker-compose run finetuner test\n```\n\nPredict result and classification report and/or confusion matrix are save at `logs/` directory.\n\n\n## Available pretrained models\n\n|model                          |pretrained model name            |\n|:------------------------------|:--------------------------------|\n|CaffeNet                       |imagenet1k-caffenet              |\n|SqueezeNet                     |imagenet1k-squeezenet            |\n|NIN                            |imagenet1k-nin                   |\n|VGG16                          |imagenet1k-vgg16                 |\n|Inception-BN                   |imagenet1k-inception-bn          |\n|ResNet-50                      |imagenet1k-resnet-50             |\n|ResNet-152                     |imagenet1k-resnet-152            |\n|Inception-v3                   |imagenet1k-inception-v3          |\n|DenseNet-169                   |imagenet1k-densenet-169          |\n|SE-ResNeXt-50                  |imagenet1k-se-resnext-50         |\n\nTo use these pretrained models, specify the following pretrained model name in `config.yml`.\n\nFor details, please check [Available pretrained models](docs/pretrained_models.md)\n\n\n## Available optimizers\n\n- SGD\n- NAG\n- RMSProp\n- Adam\n- AdaGrad\n- AdaDelta\n- Adamax\n- Nadam\n- DCASGD\n- SGLD\n- Signum\n- FTML\n- Ftrl\n\nTo use these optimizers, specify the optimizer name in lowercase in `config.yml`.\n\n\n## Benchmark (Speed and Memory Footprint)\n\nSingle TITAN X (Maxwell) with batch size 40\n\n|Model       |speed (images/sec)|memory (MiB)|\n|:-----------|:-----------------|:-----------|\n|CaffeNet    |1077.63           |716         |\n|ResNet-50   |111.04            |5483        |\n|Inception-V3|82.34             |6383        |\n|ResNet-152  |48.28             |11330       |\n\nFor details, please check [Benchmark](docs/benchmark.md)\n\n\n## Utilities\n\n### util/counter.sh\n\nCount the number of files in each subdirectory.\n\n```\n$ util/counter.sh testdir\ntestdir contains 4 directories\nLeopards    197\nMotorbikes  198\nairplanes   199\nwatch       200\n```\n\n### util/move_images.sh\n\nMove the specified number of jpeg images from the target directory to the output directory while maintaining the directory structure.\n\n```\n$ util/move_images.sh 20 testdir newdir\nprocessing Leopards\nprocessing Motorbikes\nprocessing airplanes\nprocessing watch\n$ util/counter.sh newdir\nnewdir contains 4 directories\nLeopards    20\nMotorbikes  20\nairplanes   20\nwatch       20\n```\n\n### Prepare sample images for fine-tuning\n\nDownload [Caltech 101] dataset, and split part of it into the `example_images` directory.\n\n```\n$ util/caltech101_prepare.sh\n```\n\n- `example_images/train` is train set of 60 images for each classes\n- `example_images/valid` is validation set of 20 images for each classes\n- `example_imags/test` is test set of 20 images for each classes\n\n```\n$ util/counter.sh example_images/train\nexample_images/train contains 10 directories\nFaces       60\nLeopards    60\nMotorbikes  60\nairplanes   60\nbonsai      60\ncar_side    60\nchandelier  60\nhawksbill   60\nketch       60\nwatch       60\n```\n\nWith this data you can immediately try fine-tuning.\n\n```\n$ util/caltech101_prepare.sh\n$ rm -rf images\n$ mv exmaple_images images\n$ docker-compose run finetuner\n```\n\n\n\n## Misc\n\n### How to freeze layers during fine-tuning\n\nIf you set the number of target layer to `finetune.num_active_layers` in `config.yml` as below, only layers whose number is not greater than the number of the specified layer will be train.\n\n```\nfinetune:\n  models:\n    - imagenet1k-nin\n  optimizers:\n    - sgd\n  num_active_layers: 6\n```\n\nThe default for `finetune.num_active_layers` is `0`, in which case all layers are trained.\n\nIf you set `1` to `finetune.num_active_layers`, only the last fully-connected layers are trained.\n\nYou can check the layer numbers of various pretrained models with `num_layers` command.\n\n```\n$ docker-compose run finetuner num_layers \u003cpretrained model name\u003e\n```\n\nFor details, please check [How to freeze layers during fine-tuning](docs/freeze_layers.md)\n\n\n### Training from scratch\n\nEdit `config.yml` as below.\n\n```\nfinetune:\n  models:\n    - scratch-alexnet\n```\n\nYou can also run fine-tuning and training from scratch together.\n\n```\nfinetune:\n  models:\n    - imagenet1k-inception-v3\n    - scratch-inception-v3\n```\n\nFor details, please check [Available models training from scratch](docs/train_from_scratch.md)\n\n\n## Averaging ensemble test with trained models\n\nYou can do averaging ensemble test using multiple trained models.\n\nIf you want to use the following the three trained models,\n\n- `model/20180130074818-imagenet1k-nin-nadam-0003.params`\n- `model/20180130075252-imagenet1k-squeezenet-nadam-0003.params`\n- `model/20180131105109-imagenet1k-caffenet-nadam-0003.params`\n\nedit `config.yml` as blow.\n\n```\nensemble:\n  models:\n    - 20180130074818-imagenet1k-nin-nadam-0003\n    - 20180130075252-imagenet1k-squeezenet-nadam-0003\n    - 20180131105109-imagenet1k-caffenet-nadam-0003\n```\n\n\nWhen you are done, you can do averaging ensemble test with the following command.\n\n```\n$ docker-compose run finetuner ensemble test\n```\n\nIf you want to use validation dataset, do as follows.\n\n```\n$ docker-compose run finetuner ensemble valid\n```\n\nAveraging ensemble test result and classification report and/or confusion matrix are save at `logs/` directory.\n\n\n## Export your trained model\n\nYou can export your trained model in a format that can be used with [Model Server for Apache MXNet] as follows.\n\n```\n$ docker-compose run finetuner export\n```\n\nThe exported file (extension is .model) is saved at `model/` directory.\n\nPlease check [export settings](#export-settings) for export settings.\n\n\n## Serve your exported model\n\nYou can serve your exported model as API server.\n\nWith the following command, launch the API server with the last exported model using pre-configured Docker image of [Model Server for Apache MXNet].\n\n```\n$ docker-compose up -d mms\n```\n\nThe API server is started at port 8080 of your local host.\n\nThen you will `curl` a `POST` to the MMS predict endpoint with the test image. (For exmple, use `airlane.jpg`).\n\n```\n$ curl -X POST http://127.0.0.1:8080/model/predict -F \"data=@airplane.jpg\"\n```\n\nThe predict endpoint will return a prediction response in JSON. It will look something like the following result:\n\n```\n{\n  \"prediction\": [\n    [\n      {\n        \"class\": \"airplane\",\n        \"probability\": 0.9950716495513916\n      },\n      {\n        \"class\": \"watch\",\n        \"probability\": 0.004928381647914648\n      }\n    ]\n  ]\n}\n```\n\n\n## Try image classification with jupyter notebook\n\n```\n$ docker-compose run --service-ports finetuner jupyter\n```\n*Please note that the `--service-port` option is required*\n\nReplace the IP address of the displayed URL with the IP address of the host machine and access it from the browser.\n\nOpen the `classify_example/classify_example.ipynb` and try out the image classification sample using the VGG-16 pretrained model pretrained with ImageNet.\n\n\n\n## config.yml options\n\n### common settings\n\n```\ncommon:\n  num_threads: 4\n  gpus: 0  # list of gpus to run, e.g. 0 or 0,2,5.\n```\n\nIf a machine has one or more GPU cards installed, then each card is labeled by a number starting from 0.\nTo use GPU for training or inference, specify GPU number in common.gpus.\n\nIf you do not use the GPU or you can not use it, please comment out common.gpus.\n\nIn the environment where GPU can not be used, `common.gpus` in `config.yml` generated by `setup.sh` is automatically commented out.\n\n### data settings\n\ntrain, validation and test RecordIO data generation settings.\n\nmxnet-finetuner resize and pack the image files into a recordIO file for increased performance.\n\nBy setting the `resize_short`, you can resize shorter edge of images to that size.\n\nIf `resize_short` is not specified, it is automatically determined according to the model you are using.\n\n```\ndata:\n  quality: 100\n  shuffle: 1\n  center_crop: 0\n  # test_center_crop: 1\n  # resize_short: 256\n```\n\n## finetune settings\n\n```\nfinetune:\n  models:  # specify models to use\n    - imagenet1k-nin\n    # - imagenet1k-inception-v3\n    # - imagenet1k-vgg16\n    # - imagenet1k-resnet-50\n    # - imagenet11k-resnet-152\n    # - imagenet1k-resnext-101\n    # - imagenet1k-se-resnext-50\n    # etc\n  optimizers:  # specify optimizers to use\n    - sgd\n    # optimizers: sgd, nag, rmsprop, adam, adagrad, adadelta, adamax, nadam, dcasgd, signum, etc.\n  # num_active_layers: 1  # train last n-layers without last fully-connected layer\n  num_epochs: 10  # max num of epochs\n  # load_epoch: 0  # specify when using user fine-tuned model\n  lr: 0.0001  # initial learning rate\n  lr_factor: 0.1  # the ratio to reduce lr on each step\n  lr_step_epochs: 10  # the epochs to reduce the lr, e.g. 30,60\n  mom: 0.9  # momentum for sgd\n  wd: 0.00001  # weight decay for sgd\n  batch_size: 10  # the batch size\n  disp_batches: 10  # show progress for every n batches\n  # top_k: 0  # report the top-k accuracy. 0 means no report.\n  # data_aug_level: 3  # preset data augumentation level\n  # random_crop: 0  # if or not randomly crop the image\n  # random_mirror: 0  # if or not randomly flip horizontally\n  # max_random_h: 0  # max change of hue, whose range is [0, 180]\n  # max_random_s: 0  # max change of saturation, whose range is [0, 255]\n  # max_random_l: 0  # max change of intensity, whose range is [0, 255]\n  # max_random_aspect_ratio: 0  # max change of aspect ratio, whose range is [0, 1]\n  # max_random_rotate_angle: 0  # max angle to rotate, whose range is [0, 360]\n  # max_random_shear_ratio: 0  # max ratio to shear, whose range is [0, 1]\n  # max_random_scale: 1  # max ratio to scale\n  # min_random_scale: 1  # min ratio to scale, should \u003e= img_size/input_shape. otherwise use --pad-size\n  # rgb_mean: '123.68,116.779,103.939'  # a tuple of size 3 for the mean rgb\n  # monitor: 0  # log network parameters every N iters if larger than 0\n  # pad_size: 0  # padding the input image\n  auto_test: 1  # if or not test with validation data after fine-tuneing is completed\n  train_accuracy_graph_output: 1\n  # train_accuracy_graph_fontsize: 12\n  # train_accuracy_graph_figsize: 8,6\n  # train_accuracy_graph_slack_upload: 1\n  # train_accuracy_graph_slack_channels:\n  #   - general\n  train_loss_graph_output: 1\n  # train_loss_graph_fontsize: 12\n  # train_loss_graph_figsize: 8,6\n  # train_loss_graph_slack_upload: 1\n  # train_loss_graph_slack_channels:\n  #   - general\n```\n\n#### data_aug_level\n\nBy setting the `data_aug_level` parameter, you can set the data augumentation settings collectively.\n\n|Level  |settings                          |\n|:------|:---------------------------------|\n|Level 1|random_crop: 1\u003cbr\u003erandom_mirror: 1|\n|Level 2|max_random_h: 36\u003cbr\u003emax_random_s: 50\u003cbr\u003emax_random_l: 50\u003cbr\u003e+ Level 1|\n|Level 3|max_random_aspect_ratio: 0.25\u003cbr\u003emax_random_rotate_angle: 10\u003cbr\u003emax_random_shear_ratio: 0.1\u003cbr\u003e+ Level 2|\n\nIf `data_aug_level` is set, parameters related to data augumentation will be overwritten.\n\n\n### test settings\n\n```\ntest:\n  use_latest: 1  # Use last trained model. If set this option, model is ignored\n  model: 201705292200-imagenet1k-nin-sgd-0001\n  # model_epoch_up_to: 10  # test from epoch of model to model_epoch_up_to respectively\n  test_batch_size: 10\n  # top_k: 10\n  # rgb_mean: '123.68,116.779,103.939'  # a tuple of size 3 for the mean rgb\n  classification_report_output: 1\n  # classification_report_digits: 3\n  confusion_matrix_output: 1\n  # confusion_matrix_fontsize: 12\n  # confusion_matrix_figsize: 16,12\n  # confusion_matrix_slack_upload: 1\n  # confusion_matrix_slack_channels:\n  #   - general\n```\n\n\n### ensemble settings\n\n```\n# ensemble settings\nensemble:\n  models:\n    - 20180130074818-imagenet1k-nin-nadam-0003\n    - 20180130075252-imagenet1k-squeezenet-nadam-0003\n    - 20180131105109-imagenet1k-caffenet-nadam-0003\n  # weights: 1,1,1\n  ensemble_batch_size: 10\n  # top_k: 10\n  # rgb_mean: '123.68,116.779,103.939'  # a tuple of size 3 for the mean rgb\n  classification_report_output: 1\n  # classification_report_digits: 3\n  confusion_matrix_output: 1\n  # confusion_matrix_fontsize: 12\n  # confusion_matrix_figsize: 16,12\n  # confusion_matrix_slack_upload: 1\n  # confusion_matrix_slack_channels:\n  #   - general\n```\n\n\n### export settings\n\n```\n# export settings\nexport:\n  use_latest: 1 # Use last trained model. If set this option, model is ignored\n  model: 201705292200-imagenet1k-nin-sgd-0001\n  # top_k: 10  # report the top-k accuracy\n  # rgb_mean: '123.68,116.779,103.939'  # a tuple of size 3 for the mean rgb\n  # center_crop: 1  # if or not center crop at image preprocessing\n  # model_name: model\n```\n\n\n# Acknowledgement\n\n- [MXNet]\n- [Mo - Mustache Templates in Bash]\n- [A MXNet implementation of DenseNet with BC structure]\n- [SENet.mxnet]\n- [Model Server for Apache MXNet]\n\n# Licnese\n\n[Apache-2.0] license.\n\n\n[Apache-2.0]: https://github.com/dmlc/mxnet/blob/master/LICENSE\n[MXNet]: https://github.com/apache/incubator-mxnet\n[Mo - Mustache Templates in Bash]: https://github.com/tests-always-included/mo\n[A MXNet implementation of DenseNet with BC structure]: https://github.com/bruinxiong/densenet.mxnet\n[Caltech 101]: http://www.vision.caltech.edu/Image_Datasets/Caltech101/\n[SENet.mxnet]: https://github.com/bruinxiong/SENet.mxnet\n[Model Server for Apache MXNet]: https://github.com/awslabs/mxnet-model-server\n","funding_links":[],"categories":["\u003ca name=\"Tools\"\u003e\u003c/a\u003e13. Tools","Jupyter Notebook","\u003ca name=\"Tools\"\u003e\u003c/a\u003e9. Tools"],"sub_categories":["13.5 Productivity"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknjcode%2Fmxnet-finetuner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknjcode%2Fmxnet-finetuner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknjcode%2Fmxnet-finetuner/lists"}