Merge pull request #321 from stochasticai/issue-135-simplify-notebook-examples

Simplify notebook examples with task-based workflows

Author: glennko

README.md

@@ -210,14 +210,11 @@ Playground().launch() ## launches localhost UI
 
 ## 📚 Tutorials
 - [Preparing your dataset](examples/datasets/preparing_your_dataset.py)
-- [Cerebras-GPT fine-tuning with LoRA and INT8](examples/models/cerebras/cerebras_lora_int8.ipynb)   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1eKq3oF7dnK8KuIfsTE70Gvvniwr1O9D0?usp=sharing)
-- [Cerebras-GPT fine-tuning with LoRA](examples/models/cerebras/cerebras_lora.ipynb)   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1VjqQhstm5pT4EjPjx4Je7b3W2X1V3vDo?usp=sharing)
-- [LLaMA fine-tuning with LoRA and INT8](examples/models/llama/llama_lora_int8.py)   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1SQUXq1AMZPSLD4mk3A3swUIc6Y2dclme?usp=sharing)
-- [LLaMA fine-tuning with LoRA](examples/models/llama/llama_lora.py)
-- [LLaMA fine-tuning](examples/models/llama/llama.py)
-- [GPT-J fine-tuning with LoRA and INT8](examples/models/gptj/gptj_lora_int8.py)   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1hB_8s1V9K4IzifmlmN2AovGEJzTB1c7e?usp=sharing)
-- [GPT-J fine-tuning with LoRA](examples/models/gptj/gptj_lora.py)
-- [GPT-2 fine-tuning with LoRA](examples/models/gpt2/gpt2_lora.py)   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://drive.google.com/file/d/1Sh-ocNpKn9pS7jv6oBb_Q8DitFyj1avL/view?usp=sharing)
+- [Task notebook: fine-tune with LoRA](examples/notebooks/finetune_lora.ipynb)
+- [Task notebook: fine-tune with LoRA + INT8](examples/notebooks/finetune_lora_int8.ipynb)
+- [Task notebook: evaluate model perplexity](examples/notebooks/evaluate_perplexity.ipynb)
+- [Qwen3 LoRA runnable script](examples/models/qwen3/qwen3_lora_finetune.py)
+- [Model key and variant reference](https://xturing.stochastic.ai/overview/supported_models)
 
 <br>
 

docs/docs/overview/intro.md

@@ -49,20 +49,17 @@ So, if you're ready to add a personal touch to AI, welcome to xTuring. It's a jo
 
 To get started with xTuring, check out the [Quickstart](/overview/quickstart) guide or try some of the examples below.
 
-## Model examples
-
-| Model | Examples |
-| --- | --- |
-| Bloom | [Bloom fine-tuning on Alpaca dataset with/without LoRA and with/without INT8](https://github.com/stochasticai/xturing/tree/main/examples/models/bloom) |
-| Cerebras-GPT | [Cerebras-GPT fine-tuning on Alpaca dataset with/without LoRA and with/without INT8](https://github.com/stochasticai/xturing/tree/main/examples/models/cerebras) |
-| Falcon | [Falcon 7B fine-tuning on Alpaca dataset with/without LoRA and with/without INT8](https://github.com/stochasticai/xturing/tree/main/examples/models/falcon) |
-| Galactica | [Galactica fine-tuning on Alpaca dataset with/without LoRA and with/without INT8](https://github.com/stochasticai/xturing/tree/main/examples/models/galactica) |
-| Generic Wrapper | [Any large language model fine-tuning on Alpaca dataset with/without LoRA and with/without INT8](https://github.com/stochasticai/xturing/tree/main/examples/models/generic) |
-| GPT-J | [GPT-J 6B LoRA fine-tuning with/without INT8 ](https://github.com/stochasticai/xturing/tree/main/examples/models/gptj) |
-| GPT-2 | [GPT-2 fine-tuning on Alpaca dataset with/without LoRA and with/without INT8](https://github.com/stochasticai/xturing/tree/main/examples/models/gpt2) |
-| LLaMA | [LLaMA 7B fine-tuning on Alpaca dataset with/without LoRA and with/without INT8](https://github.com/stochasticai/xturing/tree/main/examples/models/llama) |
-| LLaMA 2 | [LLaMA 2 7B fine-tuning on Alpaca dataset with/without LoRA and with/without INT8](https://github.com/stochasticai/xturing/tree/main/examples/models/llama2) |
-| OPT | [OPT fine-tuning on Alpaca dataset with/without LoRA and with/without INT8](https://github.com/stochasticai/xturing/tree/main/examples/models/opt) |
+## Example notebooks
+
+Examples are organized by task, not by model family. Start with one of these:
+
+| Task | Notebook |
+| --- | --- |
+| Fine-tune with LoRA | [examples/notebooks/finetune_lora.ipynb](https://github.com/stochasticai/xturing/blob/main/examples/notebooks/finetune_lora.ipynb) |
+| Fine-tune with LoRA + INT8 | [examples/notebooks/finetune_lora_int8.ipynb](https://github.com/stochasticai/xturing/blob/main/examples/notebooks/finetune_lora_int8.ipynb) |
+| Evaluate perplexity | [examples/notebooks/evaluate_perplexity.ipynb](https://github.com/stochasticai/xturing/blob/main/examples/notebooks/evaluate_perplexity.ipynb) |
+
+For model options and naming variants, see [Supported models and variants](/overview/supported_models).
 
 xTuring is licensed under [Apache 2.0](https://github.com/stochasticai/xturing/blob/main/LICENSE)
 

docs/docs/overview/quickstart/finetune_guide.md

@@ -42,7 +42,11 @@ Start by loading the instruction dataset and initializing the model of your choi
 
 <Test instruction={'Instruction'}/>
 
-A list of all the supported models can be found [here](/overview/supported_models).
+A list of all model keys and variant templates can be found [here](/overview/supported_models).
+
+If you prefer notebooks, start from the task-based examples:
+- `examples/notebooks/finetune_lora.ipynb`
+- `examples/notebooks/finetune_lora_int8.ipynb`
 
 
 

docs/docs/overview/supported_models.md

@@ -1,39 +1,48 @@
 ---
 sidebar_position: 4
-title: 🦾 Supported models
-description: Models Supported by xTuring
+title: 🦾 Supported models and variants
+description: Choose model keys and variant templates for task-based notebooks
 ---
 
-<!-- # Models supported by xTuring -->
-## Base versions
-|   Model | Model Key | LoRA | INT8 | LoRA + INT8 | LoRA + INT4 |
-| ------ | --- | :---: | :---: | :---: | :---: |
-| BLOOM 1.1B| bloom |  ✅ | ✅ | ✅ | ✅ |
-| Cerebras 1.3B| cerebras | ✅  | ✅ | ✅ | ✅ |
-| DistilGPT-2 | distilgpt2 | ✅  | ✅ | ✅ | ✅ |
-| Falcon 7B | falcon | ✅  | ✅ | ✅ | ✅ |
-| Galactica 6.7B| galactica | ✅  | ✅ | ✅ | ✅ |
-| GPT-J  6B | gptj | ✅ | ✅ | ✅ | ✅ |
-| GPT-2  | gpt2 | ✅  | ✅ | ✅ | ✅ |
-| LLaMA  7B | llama | ✅ | ✅ | ✅ | ✅ |
-| LLaMA2  | llama2 | ✅ | ✅ | ✅ | ✅ |
-| MiniMaxM2 | minimax_m2 | ✅ | ✅ | ✅ | ✅ |
-| Qwen3 0.6B | qwen3_0_6b | ✅ | ✅ | ✅ | ✅ |
-| OPT 1.3B  | opt | ✅ | ✅ |  ✅ | ✅ |
-
-### Memory-efficient versions
-> The above mentioned are the base variants of the LLMs. Below are the templates to get their `LoRA`, `INT8`, `INT8 + LoRA` and `INT4 + LoRA` versions.
-
-| Version | Template |
-| -- | -- |
-| LoRA |  <model_key>_lora|
-| INT8 |  <model_key>_int8|
-| INT8 + LoRA |  <model_key>_lora_int8|
-
-### INT4 Precision model versions
-> In order to load any model's __`INT4+LoRA`__ version, you will need to make use of `GenericLoraKbitModel` class from `xturing.models`. Below is how to use it:
+Use one task notebook from `examples/notebooks/`, then choose a model key from this page.
+
+## Naming templates
+
+| Variant | Key template |
+| --- | --- |
+| Base | `<model_key>` |
+| LoRA | `<model_key>_lora` |
+| INT8 | `<model_key>_int8` |
+| LoRA + INT8 | `<model_key>_lora_int8` |
+| LoRA + K-bit (INT4 flow) | `<model_key>_lora_kbit` |
+
+## Model keys
+
+| Model | Base key | Available variants |
+| --- | --- | --- |
+| BLOOM 1.1B | `bloom` | `base`, `lora`, `int8`, `lora_int8` |
+| Cerebras 1.3B | `cerebras` | `base`, `lora`, `int8`, `lora_int8` |
+| DistilGPT-2 | `distilgpt2` | `base`, `lora` |
+| Falcon 7B | `falcon` | `base`, `lora`, `int8`, `lora_int8`, `lora_kbit` |
+| Galactica 6.7B | `galactica` | `base`, `lora`, `int8`, `lora_int8` |
+| Generic wrapper | `generic` | `base`, `lora`, `int8`, `lora_int8`, `lora_kbit` |
+| GPT-J 6B | `gptj` | `base`, `lora`, `int8`, `lora_int8` |
+| GPT-2 | `gpt2` | `base`, `lora`, `int8`, `lora_int8` |
+| GPT-OSS 20B | `gpt_oss_20b` | `base`, `lora`, `int8`, `lora_int8`, `lora_kbit` |
+| GPT-OSS 120B | `gpt_oss_120b` | `base`, `lora`, `int8`, `lora_int8`, `lora_kbit` |
+| LLaMA | `llama` | `base`, `lora`, `int8`, `lora_int8`, `lora_kbit` |
+| LLaMA 2 | `llama2` | `base`, `lora`, `int8`, `lora_int8`, `lora_kbit` |
+| Mamba | `mamba` | `base` |
+| MiniMaxM2 | `minimax_m2` | `base`, `lora`, `int8`, `lora_int8`, `lora_kbit` |
+| OPT 1.3B | `opt` | `base`, `lora`, `int8`, `lora_int8` |
+| Qwen3 0.6B | `qwen3_0_6b` | `base`, `lora`, `int8`, `lora_int8`, `lora_kbit` |
+| Stable Diffusion | `stable_diffusion` | `base` |
+
+## INT4-style workflow
+
+For models that expose `*_lora_kbit`, you can still use the generic K-bit API directly:
+
 ```python
 from xturing.models import GenericLoraKbitModel
-model = GenericLoraKbitModel('/path/to/model')
+model = GenericLoraKbitModel("/path/to/model")
 ```
-The `/path/to/model` can be replaced with you local directory or any HuggingFace library model like `facebook/opt-1.3b`.

examples/README.md

@@ -1,58 +1,53 @@
-# Navigating through examples
-Here, is a brief about how to navigate through examples quick and efficiently, and get your hands dirty with `xTuring`.
+# Navigating examples
+
+This folder is organized by task first, so you can pick a workflow quickly and then
+switch model keys as needed.
 
 ## Directory structure
-```
+
+```text
 examples/
-    | datasets
+    | datasets/
     | features/
-        | dataset_generation/
-        | evaluation/
-        | generic/
-        | int4_finetuning/
     | models/
+    | notebooks/
     | playground_ui/
 ```
 
-### datsets/
-This directory consists of multiple ways to generate your custom dataset from a given set of examples.
+## Start here: task-based notebooks
 
-### features/
-This directory consists of files with exapmles highlighting speific major features of the library, which can be replicated to any LLM you want.
-For example, in `dataset_generation/`, you will find an example on how to generate your custom dataset from a .jsonl file. In `evaluation/`, you will find a specific exapmle on how to evaluate your finetuned model, which can then be extended to any LLM and any dataset.
+Use the notebooks in `examples/notebooks/` as the primary entry point:
 
-### models/
-This directory consists of examples specific to each model mentioned.
+| Notebook | Purpose |
+| --- | --- |
+| `notebooks/finetune_lora.ipynb` | Fine-tune with LoRA |
+| `notebooks/finetune_lora_int8.ipynb` | Fine-tune with LoRA + INT8 |
+| `notebooks/evaluate_perplexity.ipynb` | Evaluate with perplexity |
 
-### playground_ui/
-This directory consists of an example which demonstrates how you can play around with your LLM through a web interface.
+## Model variants
 
-## Models
-Below is a list of all the supported models via `BaseModel` class of `xTuring` and their corresponding keys to load them.
+Instead of maintaining one notebook per model, use one task notebook and choose a model key.
 
-|  Model |  Key |
-| -- | -- |
-|Bloom | bloom|
-|Cerebras | cerebras|
-|DistilGPT-2 | distilgpt2|
-|Falcon-7B | falcon|
-|Galactica | galactica|
-|GPT-J | gptj|
-|GPT-2 | gpt2|
-|LlaMA | llama|
-|LlaMA2 | llama2|
-|OPT-1.3B | opt|
+| Version | Template |
+| --- | --- |
+| Base | `<model_key>` |
+| LoRA | `<model_key>_lora` |
+| INT8 | `<model_key>_int8` |
+| LoRA + INT8 | `<model_key>_lora_int8` |
 
-The above mentioned are the base variants of the LLMs. Below are the templates to get their `LoRA`, `INT8`, `INT8 + LoRA` and `INT4 + LoRA` versions.
+For the full model-key list, see `https://xturing.stochastic.ai/overview/supported_models` in the docs.
 
-| Version | Template |
-| -- | -- |
-| LoRA|  <model_key>_lora|
-| INT8|  <model_key>_int8|
-| INT8 + LoRA|  <model_key>_lora_int8|
+For INT4 + LoRA:
 
-** In order to load any model's __`INT4+LoRA`__ version, you will need to make use of `GenericLoraKbitModel` class from `xturing.models`. Below is how to use it:
 ```python
-model = GenericLoraKbitModel('<model_path>')
+from xturing.models import GenericLoraKbitModel
+model = GenericLoraKbitModel("<model_path>")
 ```
-The `model_path` can be replaced with you local directory or any HuggingFace library model like `facebook/opt-1.3b`.
+
+`<model_path>` can be a local directory or a Hugging Face model path.
+
+## Legacy model folders
+
+Legacy model-specific notebooks are archived in `examples/legacy/model_notebooks/`.
+The `examples/models/` folders remain for scripts and dataset references.
+New examples should prefer task-based notebooks and keep model differences in docs.

examples/legacy/model_notebooks/README.md

@@ -0,0 +1,6 @@
+# Archived model-specific notebooks
+
+These notebooks are archived from `examples/models/` as part of issue `#135`.
+
+Use task-based notebooks in `examples/notebooks/` for active workflows.
+Keep this folder only for historical reference and migration support.