diff --git a/source/basics.rst b/source/basics.rst index 3894adf..29b045c 100644 --- a/source/basics.rst +++ b/source/basics.rst @@ -1,18 +1,373 @@ ============================================================ -[|:construction:| WIP |:construction:|] Basics +Basics ============================================================ -Basics page. - -Create your first project +Creating a project ---------------------------------- -Type in the following command to create your first project +To create a new project, run : .. code-block:: shell emf-cli init awesome-ia-app -**Congratulations on creating your first project!** |:clap:| +Installing an existing project +-------------------------------------- + +The ``emf-cli install`` command sets up the development environment for an existing EMF project based on its configuration. It prepares the project for use : installing the configured models, configuring the SDK and setting up any necessary development tools. + +.. code-block:: html + + Installs an existing EMF project. Basically combining a slightly different init and the tidy commands. + + Usage: + emf-cli install [flags] + + Flags: + -c, --cuda Use torch with cuda + -h, --help help for install + + Global Flags: + --config-path string config file path (default ".") + +Understanding its content +-------------------------------------- + +Let's enter you project's folder and analyze it : + +.. code-block:: shell + + awesome-ia-app + ├── .venv/ + ├── dist/ + ├── models/ + ├── sdk/ + ├── config.yaml + ├── main.py + +* ``.venv/`` encapsulates all Python dependencies required by the project, ensuring a clean and isolated environment for development. +* ``dist/`` contains the distribution files of your project, which includes the executable or packaged files ready for deployment. +* ``models/`` contains the downloaded `models `_ to be used in the project. +* ``sdk/`` contains essential tools and resources tailored for the project's development needs. For more details, refer to the :doc:`Development ` page. +* ``config.yaml`` centralizes application settings, enabling user customization for behavior and AI model selection. For more details, refer to the :doc:`Configuration Reference ` page. +* ``main.py`` is where the magic happens : it serves as the heart of your application and showcases the full capabilities of the EMF toolkit. + +Working with models +---------------------------------- + +When working with `models `_, you will be using the ``emf-cli model`` command : + +.. code-block:: html + + Palette that contains model based commands + + Usage: + emf-cli model [flags] + emf-cli model [command] + + Available Commands: + add Add model by name to your project + remove Remove one or more models + update Update one or more models + + Flags: + -h, --help help for model + + Global Flags: + --config-path string config file path (default ".") + + Use "emf-cli model [command] --help" for more information about a command. + +Adding a model +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. WARNING:: + + Please note that we currently support the following model types: + - single file models + - `diffusers `_ models + - `transformers `_ models + + Please ensure that the models you intend to use adhere to these specifications. Using unsupported models may lead to unexpected behavior or errors in the application. + +| The ``emf-cli model add`` command allows users to add a model to their project by specifying the model name and optional configuration flags. +| For more information on available models, visit the `Hugging Face Models page `_. + +.. code-block:: html + + Add model by name to your project + + Usage: + emf-cli model add [model name] [flags] + + Flags: + -h, --help help for add + -c, --model-class string Python class within the module + -m, --model-module string Python module used for download + -o, --model-options strings List of model options + -p, --path string Downloaded Model directory path + -s, --skip string Skip the model or tokenizer download + -t, --tokenizer-class string Tokenizer class (only for transformers) + -T, --tokenizer-options stringArray List of tokenizer options (only for transformers) + -y, --yes Automatic yes to prompts + + Global Flags: + --config-path string config file path (default ".") + + Use "emf-cli model [command] --help" for more information about a command. + +Remove a model +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``emf-cli model remove`` command allows users to remove one or more models from their project. Users specify the name of the model(s) they wish to remove as command arguments. Upon execution, it removes the specified models from both the project's configuration file and the device. + +.. code-block:: html + + Remove one or more models + + Usage: + emf-cli model remove [...] [flags] + + Flags: + -a, --all Remove all models + -h, --help help for remove + + Global Flags: + --config-path string config file path (default ".") + +Update a model +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``emf-cli model update`` command allows users to update one or more models from their project. Users specify the name of the model(s) they wish to update as command arguments. This command will only update models sourced from `Hugging Face `_ and if a newer version is available (determined through the `Hugging Face API `_). + +.. code-block:: html + + Update one or more models + + Usage: + emf-cli model update [...] [flags] + + Flags: + -h, --help help for update + + Global Flags: + --config-path string config file path (default ".") + +Working with tokenizers +---------------------------------- + +.. WARNING:: + + **Tokenizer Requirements** + + `Tokenizers `_ are only available for models sourced from `Hugging Face's Transformers `_ library. Please ensure that you are using a compatible model type when requesting tokenizers. Using incompatible models may result in unexpected behavior or errors in your application. + +When working with `tokenizers `_, you will be using the ``emf-cli tokenizer`` command : + +.. code-block:: html + + Palette that contains tokenizer based commands + + Usage: + emf-cli tokenizer [flags] + emf-cli tokenizer [command] + + Available Commands: + add Add one or more tokenizers + remove Remove one or more tokenizers + update Update one or more tokenizers + + Flags: + -h, --help help for tokenizer + + Global Flags: + --config-path string config file path (default ".") + + Use "emf-cli tokenizer [command] --help" for more information about a command. + +Adding a tokenizer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + A recommended tokenizer should already be downloaded by default upon adding a model with the ``emf-cli model add`` command. Users can verify the configured models in the configuration file. If the downloaded tokenizer does not meet the user's preferences, they are welcome to add one of their choice. + +.. code-block:: html + + Add one or more tokenizer + + Usage: + emf-cli tokenizer add [...] [flags] + + Flags: + -h, --help help for add + + Global Flags: + --config-path string config file path (default ".") + +Remove a tokenizer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``emf-cli tokenizer remove`` command allows users to remove one or more `tokenizers `_ from their project. Users specify the name of the model associated with the tokenizer and the tokenizer name(s) they wish to remove as command arguments. + +.. code-block:: html + + Remove one or more tokenizer + + Usage: + emf-cli tokenizer remove [...] [flags] + + Flags: + -h, --help help for remove + + Global Flags: + --config-path string config file path (default ".") + +Update a tokenizer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning:: + + It currently cannot be determined if a tokenizer can be updated. Therefore, we created this command to allow you to redownload a tokenizer if you have learned that a new version is available. + +The ``emf-cli tokenizer update`` command allows users to update one or more `tokenizers `_ from their project. Users specify the name of the model associated with the tokenizer and the tokenizer name(s) they wish to update as command arguments. + +.. code-block:: html + + Update one or more tokenizer + + Usage: + emf-cli tokenizer update [...] [flags] + + Flags: + -h, --help help for update + + Global Flags: + --config-path string config file path (default ".") + +Manipulating options +---------------------------------- + +When specifying options with ``--model-options`` or ``--tokenizer-options``, things might be a bit tricky so let's go through the different formats and examples to ensure clarity and accuracy. + +Default +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When working with default values, you just have to use the following format : + +.. code-block:: html + + --model-options key=module.value + --model-options key=True + --model-options key=123456789 + +Multiple options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You could simply specify the flag as many times as needed : + +.. code-block:: html + + --model-options key1=value1 --model-options key2=value2 --model-options key3=value3 + +Or you could put them side by side and encapsulate them into double quotes : + +.. code-block:: html + + --model-options "key1=value1 key2=value2 key3=value3" + +Strings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In shell scripting or command-line interfaces, quoting strings is crucial to prevent interpretation or expansion by the shell. Without quoting, certain characters or sequences might be treated specially, leading to unintended behavior : + +.. code-block:: html + + --model-options "key='value'" + --model-options key="'value'" + +Now here is how it looks like when combining with multiple options : + +.. code-block:: html + + --model-options "key1='value1' key2='value2' key3='value3'" + --model-options key="'value'" + +Project synchronization (tidy) +---------------------------------- + +.. warning:: + + Please be aware that it is currently not possible to retrieve the version or the options used while handling downloaded but not configured models. + +The ``emf-cli tidy`` command synchronizes the project's configuration file with the downloaded models. It ensures consistency between the configured models in the project's configuration file and the actual downloaded models on the device. + +Upon execution, the command performs the following tasks: + +- Removes any configured models that are not downloaded, ensuring that the configuration file accurately reflects the current state of downloaded models. +- Offers options to either download or remove any downloaded models that are not configured in the configuration file, providing users with the flexibility to manage downloaded models as needed. + +This command aids in maintaining an organized and up-to-date model repository, facilitating efficient management of models within the project. + +.. code-block:: html + + Synchronizes the configuration file with the downloaded models + + Usage: + emf-cli tidy [flags] + + Flags: + -h, --help help for tidy + + Global Flags: + --config-path string config file path (default ".") + +Building a project +---------------------------------- + +The ``emf-cli build`` command facilitates the process of building the project. It compiles the project's source code and dependencies into an executable format suitable for deployment or distribution. + +Upon execution, the command offers various options to customize the build process: + - ``-c, --compress``: Compresses the output file(s) into a tarball file for easy distribution. + - ``-m, --include-models``: Includes models in the build compressed file, allowing for bundled distribution of models with the project. + - ``-n, --name string``: Allows users to specify a custom name for the executable. + - ``-f, --one-file``: Builds the project in one file, consolidating all dependencies and resources into a single executable file. + - ``-o, --out-dir string``: Specifies the destination directory where the project will be built. + +.. code-block:: html + + Build the project. + + Usage: + emf-cli build [flags] + + Flags: + -c, --compress Compress the output file(s) into a tarball file + -h, --help help for build + -m, --include-models Include models in the build compressed file + -n, --name string Custom name for the executable + -f, --one-file Build the project in one file + -o, --out-dir string Destination directory where the project will be built + + Global Flags: + --config-path string config file path (default ".") + +Cleaning a project +---------------------------------- + +The ``emf-cli clean`` command allows users to clean project files. The cleaning operation removes build files and, optionally, all downloaded models associated with the project. + +.. code-block:: html + + Clean project files (e.g. build) + + Usage: + emf-cli clean [flags] + + Flags: + -a, --all clean all project + -h, --help help for clean + -y, --yes bypass delete all confirmation -You've successfully taken your first step with the EMF toolkit. Now, it's time to dive deeper and unlock the full potential of this powerful tool. \ No newline at end of file + Global Flags: + --config-path string config file path (default ".") \ No newline at end of file diff --git a/source/conf.py b/source/conf.py index 526e55a..e61bd62 100644 --- a/source/conf.py +++ b/source/conf.py @@ -7,8 +7,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'Easy Model Fusion' -copyright = '2024, tbd' -author = 'tbd' +copyright = '2024, Easy Model Fusion' +author = 'Easy Model Fusion' release = 'tbd' # -- General configuration --------------------------------------------------- diff --git a/source/config-yaml.rst b/source/config-yaml.rst new file mode 100644 index 0000000..fd9c0aa --- /dev/null +++ b/source/config-yaml.rst @@ -0,0 +1,92 @@ +======================= +Configuration Reference +======================= + +The ``config.yaml`` file serves as a centralized configuration hub for the application, allowing users to specify various parameters and settings tailored to their requirements. It facilitates customization of the application's behavior, including the selection and configuration of AI models. Users can modify the configuration file to adapt the application to different environments and use cases, enhancing flexibility and versatility. + + +Application Information +----------------------------------- + +- **name**: The name of the application. +- **version**: The version of the application. +- **description**: A brief description of the application. + +SDK Configuration +----------------------------------- + +- **sdk-tag**: The version of the SDK to download. + +Model Configuration +----------------------------------- + +.. NOTE:: + + When manipulating configured models, please refer to the :doc:`Basics ` page for detailed instructions and best practices. + +The ``models`` section allows users to specify AI models to be used in the application. Each model configuration includes the following parameters: + +- **name**: The name of the model. +- **path**: The path of the directory that will contain the model. +- **module**: The Python module used for downloading the model. +- **class**: The Python class within the module. +- **options**: A map of additional options for configuring the model. +- **tokenizers**: List of tokenizer configurations. + + - **path**: The path of the directory that will contain the tokenizer. + - **class**: The Python class used for downloading the tokenizer. + - **options**: A map of additional options for configuring the tokenizer. +- **pipelinetag**: The pipeline tag used by the model identifies the specific task or functionality supported by the model (e.g., text-to-image, text-generation). +- **source**: The source of the model (e.g., hugging_face). +- **addtobinaryfile**: Indicates if the model should be added to the executable. +- **isdownloaded**: Indicates if the model has been downloaded. +- **version**: The version of the model. + +Example +----------------------------------- + +.. code-block:: yaml + + # Application information + name: "awesome-ia-app" + version: "1.0.0" + description: "Description for your awesome IA application." + + # SDK Configuration + sdk-tag: "vX.Y.Z" + + # Model Configuration + models: + + # Diffusers model + - name: stabilityai/sdxl-turbo + path: models/stabilityai/sdxl-turbo + module: diffusers + class: StableDiffusionXLPipeline + options: + torch_dtype: torch.float16 + tokenizers: [] + pipelinetag: text-to-image + source: hugging_face + addtobinaryfile: false + isdownloaded: false + version: "2023-12-07T18:04:49.000Z" + + # Transformers model + - name: microsoft/phi-2 + path: models/microsoft/phi-2/model + module: transformers + class: PhiModel + options: + torch_dtype: '"auto"' + tokenizers: + - path: models\microsoft\phi-2\AutoTokenizer + class: AutoTokenizer + options: + do_lower_case: "True" + max_len: "128" + pipelinetag: text-generation + source: hugging_face + addtobinaryfile: true + isdownloaded: true + version: "2024-02-06T12:36:24.000Z" diff --git a/source/contributing.rst b/source/contributing.rst index ef95f59..4b7e69c 100644 --- a/source/contributing.rst +++ b/source/contributing.rst @@ -1,5 +1,5 @@ ======================================================= -[|:construction:| WIP |:construction:|] Contributing +Contributing ======================================================= -Contributing documentation page. \ No newline at end of file +|:construction:| WIP |:construction:| \ No newline at end of file diff --git a/source/development.rst b/source/development.rst new file mode 100644 index 0000000..5699b5a --- /dev/null +++ b/source/development.rst @@ -0,0 +1,12 @@ +=================================================== +Development +=================================================== + +|:construction:| WIP |:construction:| + +Upgrading +---------------------------------- + +.. code-block:: sh + + emf-cli upgrade \ No newline at end of file diff --git a/source/emf-cli.rst b/source/emf-cli.rst deleted file mode 100644 index 848098b..0000000 --- a/source/emf-cli.rst +++ /dev/null @@ -1,105 +0,0 @@ -============================================================================== -[|:construction:| WIP |:construction:|] EMF Command Line Interface -============================================================================== - -EMF Command Line Interface page. - - -Titre de niveau 2 ------------------ - -Titre de niveau 3 -~~~~~~~~~~~~~~~~~ - -Un autre titre de niveau 2 --------------------------- - - - -Voici du texte en *italique*, en **gras**, et voici du ``code inline``. - - -Pour faire un lien inline c'est simple : -lien vers le `liens de la doc `_ - - - - -Liste à puce : - -* Ceci est une liste -* un autre élément - - * Une sous-liste - * notez bien le saut de ligne avec la liste principale, - ça ne marchera pas si vous l'oubliez ! - -* un dernier élément - - - - -Liste ordonnée : - -1. Un -2. Deux -3. Trois - - - - -Voici comment faire un bloc de code simple :: - - Ceci est un bloc de code. Il est créé grâce aux doubles deux-points. - - - - - -On peut aussi définir un bloc de code avec une syntaxe -plus explicite, grâce à laquelle on peut indiquer à Sphinx dans quel -langage il est rédigé, ce qui lui permettra d'activer la coloration -syntaxique : - -.. code-block:: python - - #!/usr/bin/env python - - print("Ceci est un bloc de code Python\n") - - - - -.. NOTE:: - - Ceci est une note. - -.. WARNING:: - - Ceci est un avertissement ! - -.. IMPORTANT:: - - Ceci est important ! - - -+-----------+-----------+-----------+ -| Heading 1 | Heading 2 | Heading 3 | -+===========+===========+===========+ -| Hello | World | | -+-----------+-----------+-----------+ -| foo | | -+-----------+ bar | -| baz | | -+-----------+-----------------------+ - - - -.. csv-table:: Title! - :header: "Produit", "Quantité", "Description" - :widths: 15, 10, 30 - - "Albatross", 2.99, "On a stick!" - "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be - crunchy, now would it?" - "Gannet Ripple", 1.99, "On a stick!" \ No newline at end of file diff --git a/source/examples.rst b/source/examples.rst index ff8f552..27cdb7f 100644 --- a/source/examples.rst +++ b/source/examples.rst @@ -1,5 +1,5 @@ =================================================== -[|:construction:| WIP |:construction:|] Examples +Examples =================================================== -Examples page. \ No newline at end of file +|:construction:| WIP |:construction:| \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index 0ae273e..36e0656 100644 --- a/source/index.rst +++ b/source/index.rst @@ -18,7 +18,7 @@ environments and deploy applications across various platforms with ease |:chart_ overview.rst installation.rst basics.rst + config-yaml.rst + development.rst examples.rst - emf-cli.rst - sdk.rst contributing.rst diff --git a/source/installation.rst b/source/installation.rst index c49c272..1b00020 100644 --- a/source/installation.rst +++ b/source/installation.rst @@ -30,7 +30,7 @@ Install using Go Install it directly using the following command """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.. |:construction:| This might not work since the repository is still private |:construction:| +|:construction:| This might not work since the repository is still private |:construction:| .. code-block:: shell diff --git a/source/overview.rst b/source/overview.rst index ebdac82..14c967b 100644 --- a/source/overview.rst +++ b/source/overview.rst @@ -1,5 +1,5 @@ ====================================================== -[|:construction:| WIP |:construction:|] Overview +Overview ====================================================== -Overview page. \ No newline at end of file +|:construction:| WIP |:construction:| \ No newline at end of file diff --git a/source/sdk.rst b/source/sdk.rst deleted file mode 100644 index 9457ec2..0000000 --- a/source/sdk.rst +++ /dev/null @@ -1,12 +0,0 @@ -=========================================== -[|:construction:| WIP |:construction:|] SDK -=========================================== - -SDK documentation page. - -Upgrading ----------------------------------- - -.. code-block:: sh - - emf-cli upgrade \ No newline at end of file