From d7b0b4cd7a1622fcb098bb93c7c1b7e78cc3a1ca Mon Sep 17 00:00:00 2001 From: Jeff MAURY Date: Thu, 25 Jan 2024 14:29:20 +0100 Subject: [PATCH 1/6] docs: add packaging guide Fixes #123 Signed-off-by: Jeff MAURY --- PACKAGING-GUIDE.md | 101 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++ 2 files changed, 105 insertions(+) create mode 100644 PACKAGING-GUIDE.md diff --git a/PACKAGING-GUIDE.md b/PACKAGING-GUIDE.md new file mode 100644 index 000000000..05676af59 --- /dev/null +++ b/PACKAGING-GUIDE.md @@ -0,0 +1,101 @@ +# Packaging guide + +## Catalog + +AI Studio uses an internal catalog that is embedded into AI Studio. This catalog is loaded +by AI Studio and displayed when you access the catalog page. + +The format of the catalog is JSON. It is possible for users to have a custom version of +the catalog. In order to do so, copy the file located at https://github.com/projectatomic/ai-studio/blob/main/packages/backend/src/ai.json +to $HOME/podman-desktop/ai-studio/catalog.json and AI Studio will use it instead of the embedded one. +Any change done to this file will also be automatically be loaded by AI Studio. + +### Format of the catalog file + +The catalog file has three main elements: categories, models and recipes. Each of these elements is +represented in the JSON file as an array. + +#### Categories + +This is the top level construct of the catalog UI. Recipes are grouped into categories. A category +represents the kind of AI application. Although the list of categories provided by default by +AI Studio represents the AI landscape, it is possible to add new categories. + +A category has three main attributes: an id (which should be unique among categories), a description +and a name. The category id attribute will then be used to attach a recipe to one or several categories. + +#### Models + +The catalog also list the models that may be associated to recipes. A model is also a first class +citizen in AI Studio as they will be listed in the Models page and can be tested through the playground. + +A model has the following attributes: +- ```id```: a unique identifier for the model +- ```name```: the model name +- ```description```: a detailed description about the model +- ```hw```: the hardware where the model is compatible. Possible values are CPU and GPU +- ```registry```: the model registry where the model is stored +- ```popularity```: an integer field giving the rating of the model. Can be thought as the number of stars +- ```license```: the license under which the model is available +- ```url```: the URL used to download the model + +#### Recipes + +A recipe is a sample AI application that is packaged as one or several containers. It is build by +AI Studio when the user chooses to download it on his workstation and run it. It is provided as +source code and AI Studio will make sure the container images are built prior to laucnhing the containers. + +A recipe has the following attributes: +- ```id```: a unique identifier to the recipe +- ```name```: the recipe name +- ```description```: a detailed description about the recipe +- ```repository```: the URL where the recipe code can be retrieved +- ```categories```: an array of category id to be associated by this recipe +- ```config```: an optional path of the configuration file within the repository. If not provided, the file is assumed to be located at the root the repository and called ai-studio.yaml +- ```readme```: a markdown description of the recipe +- ```models```: an array of model id to be associated with this recipe + +#### Recipe configuration file + +The configuration file is called ```ai-studio.yaml``` and follows the following syntax. + +The root element is called ```application```. This element contains an attribute called ```containers``` +whose syntax is an array of objects containing the following attribute: +- ```name```: the name of the container +- ```contextdir```: the context directory used to build the container. +- ```containerfile```: the containerfile used to build the image +- ```model-service```: a boolean flag used to indicate if the container is running the model or not +- ```arch```: an optional array of architecture for which this image is compatible with. The values follows the +[GOARCH specification](https://go.dev/src/go/build/syslist.go) +- ```gpu-env```: an optional array of GPU environment for which this image is compatible with. The only accepted value here is cuda. + +The container that is running the service (having the ```model-service``` flag equal to ```true```) can use at runtime +the model managed by AI Studio through an environment variable ```MODEL_PATH``` whose value is the full path name of the +model file + +Below is given an example of such a configuration file: +```yaml +application: + containers: + - name: chatbot-inference-app + contextdir: ai_applications + containerfile: builds/Containerfile + - name: chatbot-model-service + contextdir: model_services + containerfile: base/Containerfile + model-service: true + arch: + - arm64 + - amd64 + - name: chatbot-model-servicecuda + contextdir: model_services + containerfile: cuda/Containerfile + model-service: true + gpu-env: + - cuda + arch: + - amd64 +``` + + + diff --git a/README.md b/README.md index ae50624ee..3973ab4c6 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,10 @@ Each recipe can belong to one or several categories. Each model can be used by o The format of the catalog is not stable nor versioned yet, you can see the current catalog's format [in the sources of the extension](https://github.com/projectatomic/studio-extension/blob/main/packages/backend/src/ai.json). +## Packaging sample applications + +Sample applications may be added to the catalog. See [packaging guide](PACKAGING-GUIDE.md) for detailed information. + ## Feedback You can provide your feedback on the extension with [this form](https://forms.gle/tctQ4RtZSiMyQr3R8) or create [an issue on this repository](https://github.com/projectatomic/studio-extension/issues). From b9e08cba63aff45c335087c1f0c98e6c20e21cf4 Mon Sep 17 00:00:00 2001 From: Jeff MAURY Date: Tue, 30 Jan 2024 15:46:01 +0100 Subject: [PATCH 2/6] fix: typo Co-authored-by: Luca Stocchi <49404737+lstocchi@users.noreply.github.com> --- PACKAGING-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PACKAGING-GUIDE.md b/PACKAGING-GUIDE.md index 05676af59..737bd8cbd 100644 --- a/PACKAGING-GUIDE.md +++ b/PACKAGING-GUIDE.md @@ -8,7 +8,7 @@ by AI Studio and displayed when you access the catalog page. The format of the catalog is JSON. It is possible for users to have a custom version of the catalog. In order to do so, copy the file located at https://github.com/projectatomic/ai-studio/blob/main/packages/backend/src/ai.json to $HOME/podman-desktop/ai-studio/catalog.json and AI Studio will use it instead of the embedded one. -Any change done to this file will also be automatically be loaded by AI Studio. +Any change done to this file will also be automatically loaded by AI Studio. ### Format of the catalog file From 097deb83a2f74c41351b3cdaec57f4a622a8829f Mon Sep 17 00:00:00 2001 From: Jeff MAURY Date: Tue, 30 Jan 2024 15:47:12 +0100 Subject: [PATCH 3/6] fix: wording Co-authored-by: Luca Stocchi <49404737+lstocchi@users.noreply.github.com> --- PACKAGING-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PACKAGING-GUIDE.md b/PACKAGING-GUIDE.md index 737bd8cbd..f3c6b6dac 100644 --- a/PACKAGING-GUIDE.md +++ b/PACKAGING-GUIDE.md @@ -2,7 +2,7 @@ ## Catalog -AI Studio uses an internal catalog that is embedded into AI Studio. This catalog is loaded +AI Studio uses an internal catalog embedded within the application. This catalog is loaded by AI Studio and displayed when you access the catalog page. The format of the catalog is JSON. It is possible for users to have a custom version of From 43a1f2f989dd1c9d87e6665543e87707dbb21943 Mon Sep 17 00:00:00 2001 From: Jeff MAURY Date: Tue, 30 Jan 2024 15:47:40 +0100 Subject: [PATCH 4/6] fix: typo Co-authored-by: Luca Stocchi <49404737+lstocchi@users.noreply.github.com> --- PACKAGING-GUIDE.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/PACKAGING-GUIDE.md b/PACKAGING-GUIDE.md index f3c6b6dac..9aadfaa68 100644 --- a/PACKAGING-GUIDE.md +++ b/PACKAGING-GUIDE.md @@ -41,8 +41,7 @@ A model has the following attributes: #### Recipes -A recipe is a sample AI application that is packaged as one or several containers. It is build by -AI Studio when the user chooses to download it on his workstation and run it. It is provided as +A recipe is a sample AI application that is packaged as one or several containers. It is built by AI Studio when the user chooses to download and run it on their workstation. It is provided as source code and AI Studio will make sure the container images are built prior to laucnhing the containers. A recipe has the following attributes: From a5f8be7552c8ec582db7d77fbac205b5217230f4 Mon Sep 17 00:00:00 2001 From: Jeff MAURY Date: Tue, 30 Jan 2024 15:47:56 +0100 Subject: [PATCH 5/6] fix: typo Co-authored-by: Luca Stocchi <49404737+lstocchi@users.noreply.github.com> --- PACKAGING-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PACKAGING-GUIDE.md b/PACKAGING-GUIDE.md index 9aadfaa68..be3bcb519 100644 --- a/PACKAGING-GUIDE.md +++ b/PACKAGING-GUIDE.md @@ -42,7 +42,7 @@ A model has the following attributes: #### Recipes A recipe is a sample AI application that is packaged as one or several containers. It is built by AI Studio when the user chooses to download and run it on their workstation. It is provided as -source code and AI Studio will make sure the container images are built prior to laucnhing the containers. +source code and AI Studio will make sure the container images are built prior to launching the containers. A recipe has the following attributes: - ```id```: a unique identifier to the recipe From bf8c3274ebc5c8d35bf8be5b65894c893b1639e7 Mon Sep 17 00:00:00 2001 From: Jeff MAURY Date: Tue, 30 Jan 2024 18:49:30 +0100 Subject: [PATCH 6/6] fix: apply suggestions from @feloy code review Co-authored-by: Philippe Martin --- PACKAGING-GUIDE.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/PACKAGING-GUIDE.md b/PACKAGING-GUIDE.md index be3bcb519..077c84c9d 100644 --- a/PACKAGING-GUIDE.md +++ b/PACKAGING-GUIDE.md @@ -26,7 +26,7 @@ and a name. The category id attribute will then be used to attach a recipe to on #### Models -The catalog also list the models that may be associated to recipes. A model is also a first class +The catalog also lists the models that may be associated to recipes. A model is also a first class citizen in AI Studio as they will be listed in the Models page and can be tested through the playground. A model has the following attributes: @@ -59,18 +59,18 @@ A recipe has the following attributes: The configuration file is called ```ai-studio.yaml``` and follows the following syntax. The root element is called ```application```. This element contains an attribute called ```containers``` -whose syntax is an array of objects containing the following attribute: +whose syntax is an array of objects containing the following attributes: - ```name```: the name of the container - ```contextdir```: the context directory used to build the container. - ```containerfile```: the containerfile used to build the image - ```model-service```: a boolean flag used to indicate if the container is running the model or not -- ```arch```: an optional array of architecture for which this image is compatible with. The values follows the +- ```arch```: an optional array of architecture for which this image is compatible with. The values follow the [GOARCH specification](https://go.dev/src/go/build/syslist.go) - ```gpu-env```: an optional array of GPU environment for which this image is compatible with. The only accepted value here is cuda. The container that is running the service (having the ```model-service``` flag equal to ```true```) can use at runtime the model managed by AI Studio through an environment variable ```MODEL_PATH``` whose value is the full path name of the -model file +model file. Below is given an example of such a configuration file: ```yaml