From d7b0b4cd7a1622fcb098bb93c7c1b7e78cc3a1ca Mon Sep 17 00:00:00 2001 From: Jeff MAURY Date: Thu, 25 Jan 2024 14:29:20 +0100 Subject: [PATCH] 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).