From a3e549615627c7893f1b7189719644a02d0f0319 Mon Sep 17 00:00:00 2001 From: Frank Lee Date: Wed, 11 Jan 2023 10:46:32 +0800 Subject: [PATCH] [example] improved the clarity yof the example readme (#2427) * [example] improved the clarity yof the example readme * polish workflow * polish workflow * polish workflow * polish workflow * polish workflow * polish workflow --- .github/workflows/auto_example_check.yml | 5 ++- examples/README.md | 48 +++++++++++++++--------- 2 files changed, 33 insertions(+), 20 deletions(-) diff --git a/.github/workflows/auto_example_check.yml b/.github/workflows/auto_example_check.yml index d9063bad9..f88b6858e 100644 --- a/.github/workflows/auto_example_check.yml +++ b/.github/workflows/auto_example_check.yml @@ -39,7 +39,7 @@ jobs: res=`python .github/workflows/scripts/example_checks/detect_changed_example.py --fileNameList $changedFileName` echo "All changed examples are $res" - if [ "$x" = "[]" ]; then + if [ "$res" = "[]" ]; then echo "anyChanged=false" >> $GITHUB_OUTPUT echo "matrix=null" >> $GITHUB_OUTPUT else @@ -54,7 +54,8 @@ jobs: if: | github.event.pull_request.draft == false && github.base_ref == 'main' && - github.event.pull_request.base.repo.full_name == 'hpcaitech/ColossalAI' && github.event_name == 'pull_request' + github.event.pull_request.base.repo.full_name == 'hpcaitech/ColossalAI' && github.event_name == 'pull_request' && + needs.detect-changed-example.outputs.anyChanged == 'true' name: Test the changed example needs: detect-changed-example runs-on: [self-hosted, gpu] diff --git a/examples/README.md b/examples/README.md index 53ab0896d..78facea54 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,28 +1,40 @@ -## Examples folder document +# Colossal-AI Examples ## Table of Contents - -## Example folder description +- [Colossal-AI Examples](#colossal-ai-examples) + - [Table of Contents](#table-of-contents) + - [Overview](#overview) + - [Folder Structure](#folder-structure) + - [Integrate Your Example With Testing](#integrate-your-example-with-testing) -This folder provides several examples using colossalai. The images folder includes model like diffusion, dreambooth and vit. The language folder includes gpt, opt, palm and roberta. The tutorial folder is for concept illustration, such as auto-parallel, hybrid-parallel and so on. +## Overview +This folder provides several examples accelerated by Colossal-AI. The `tutorial` folder is for everyone to quickly try out the different features in Colossal-AI. Other folders such as `images` and `language` include a wide range of deep learning tasks and applications. -## Integrate Your Example With System Testing +## Folder Structure -For example code contributor, to meet the expectation and test your code automatically using github workflow function, here are several steps: +```text +└─ examples + └─ images + └─ vit + └─ test_ci.sh + └─ train.py + └─ README.md + └─ ... + └─ ... +``` +## Integrate Your Example With Testing -- (must) Have a test_ci.sh file in the folder like shown below in 'File Structure Chart' -- The dataset should be located in the company's machine and can be announced using environment variable and thus no need for a separate terminal command. -- The model parameters should be small to allow fast testing. -- File Structure Chart +Regular checks are important to ensure that all examples run without apparent bugs and stay compatible with the latest API. +Colossal-AI runs workflows to check for examples on a on-pull-request and weekly basis. +When a new example is added or changed, the workflow will run the example to test whether it can run. +Moreover, Colossal-AI will run testing for examples every week. - └─examples - └─images - └─vit - └─requirements.txt - └─test_ci.sh +Therefore, it is essential for the example contributors to know how to integrate your example with the testing workflow. Simply, you can follow the steps below. + +1. Create a script called `test_ci.sh` in your example folder +2. Configure your testing parameters such as number steps, batch size in `test_ci.sh`, e.t.c. Keep these parameters small such that each example only takes several minutes. +3. Export your dataset path with the prefix `/data` and make sure you have a copy of the dataset in the `/data/scratch/examples-data` directory on the CI machine. Community contributors can contact us via slack to request for downloading the dataset on the CI machine. +4. Implement the logic such as dependency setup and example execution