update docs

Signed-off-by: scepter914 <scepter914@gmail.com>

Author: scepter914

README.md

@@ -58,7 +58,7 @@ cargo install ml-cellar
 ```
 
 <details>
-<summary> How to build on local device</summary>
+<summary> How to build on local device (If you need) </summary>
 
 If you build on local device, run below command.
 
@@ -77,6 +77,7 @@ Let's open the cellar for AI models
 - Start `ml-cellar`
 
 ```sh
+mkdir {your_ml_registry}
 cd {your_ml_registry}
 ml-cellar init
 ```
@@ -105,24 +106,42 @@ use_custom_transfer_agent = false
 
 If you need to handle many large files in your model registry, consider using a [Custom Transfer Agent](docs/docs_custom_transfer_agent.md) to replace the storage backend with AWS S3 or a similar service.
 
-### 4. Start project
+### 4. Construct a rack to start ML cellar
 
-A project in `ml-cellar` is like creating shelves in a wine cellar.
-If ML models are like wine, then project boxes are the shelves where you store the wine.
+A rack in `ml-cellar` is like creating racks in a wine cellar.
+If ML models are like wine, then racks are the shelves where you store the wine.
 Just as wine is labeled with its vintage year, we attach versions to AI models.
 
-- Decide directory pattern for
+The rack consists the directory like belows:
 
-Choose a directory pattern for `ml-cellar` from [the document](docs/docs_directory_pattern.md).
-Just as every winery has its optimal shelf arrangement, consider the directory structure that fits your team structure and what you're developing.
+```yaml
+- model_registry_repository/
+  - vit-l/
+    - 0.1/
+      - config.yaml
+      - checkpoint.pth
+      - result.json
+      - log.log
+    - 0.2/
+      - ...
+    - 1.0/
+      - ...
+    - 1.1/
+      - ...
+  - vit-m/
+    - ...
+```
+
+In this directory, we call the ML model like `vit-l 1.1` for "Large size of Vision Transformer, version 1.1".
+It is like vintage wine called by "Dom Pérignon Vintage 2010".
 
-- Start project
+- Make rack
 
 ```sh
-ml-cellar project {project_path}
+ml-cellar rack {path}
 ```
 
-- If you run `ml-cellar project my_algorithm`, then you can see as below
+- If you run `ml-cellar rack my_algorithm`, then you can see as below
 
 ```yaml
 - {your_ml_registry}/
@@ -133,40 +152,40 @@ ml-cellar project {project_path}
 ```
 
 - Edit project.toml
+  - Add required files to save ML registry
+  - If you allow to save any kind of file, you set `"*"` for optional files.
 
 ```toml
-[files]
-required_files = [
-  "config.yml",
-  "log.log",
-  "result.json",
-  "*.pth",
-]
-optional_files = [
-  "*.png",
-  "*.mp4",
-  "*.onnx",
-]
-
-[document]
-template_file = "template.md"
-#result_file = "result.json"
+[artifact]
+required_files = ["config.yaml", "logs/*"]
+optional_files = ["*"]
 ```
 
-- Edit template.md
-  - If you want to setup template.md and result.json for MLOps, then please see [the document](docs/docs_template.md).
+### 5. (Option) Set up projects for MLOps
+
+- Start fine-tuning for projects from base model
+
+If you use fixed dataset and focus on algorithm development like Kaggle competition or research usage, the simple ML cellar is fine to share various experimental results using single rack.
 
-### 5. Commit ML model
+However, if you are engineer and you have many projects you want to fine-tuning for, I recommend to use "project-based model registry".
+Please see [the document for project-based model registry](docs/project_based_model_registry.md)
 
-Let's actually stock AI models on the shelves
+- Setup template.md and result.json for MLOps
+
+If you want to setup template.md and result.json for MLOps, then please see [the document for template.md](docs/docs_template.md).
+
+### 6. Commit ML model
+
+Let's actually stock AI models on the racks
 
 - Make branch and switch the branch
 
 ```sh
 git sw -c feat/my_algorithm/0.1
 ```
 
-- Make version directory and put files you want to commit.
+- Make version directory and put files you want to commit for `{your_ml_registry}/{my_algorithm}/0.1/*`.
+
 
 ```yaml
 - {your_ml_registry}/
@@ -186,11 +205,15 @@ git sw -c feat/my_algorithm/0.1
 ```sh
 ml-cellar check {path}
 
-# Example
+```
+
+- In this example, please run this command
+
+```sh
 ml-cellar check {your_ml_registry}/{my_algorithm}/0.1/
 ```
 
-- Commit the files.
+- When check is fine, commit the files.
 
 ```sh
 ml-cellar commit {path} "{commit message}"
@@ -237,3 +260,8 @@ ml-cellar get {path to a directory}
 ```sh
 ml-cellar get {path to a file}
 ```
+
+## Reference
+
+- https://github.com/regen100/lfs-dal
+  - https://www.regentechlog.com/2024/01/07/lfs-dal/ (Japanese blog)

docs/docs_template.md

@@ -10,8 +10,8 @@ When you run `ml-cellar check {path}`, `ml-cellar` adds the summary of results i
 
 ```toml
 [document]
-result = "result.json"
 template = "template.md"
+result = "result.json"
 ```
 
 - `template.md`