Merge pull request #10 from BethanyJep/main

adding documentation and additional optimizations for the code

Author: nitya

docs/Core-Labs/4-Customize-Model/01.md

@@ -1,9 +1,252 @@
-# 4.1 Engineer Context
+# 4.1 Customize The Tone & Style With SFT
 
 !!! quote "BY THE END OF THIS LAB YOU SHOULD HAVE"
 
-    - [X] Completed Task 1
-    - [X] Completed Task 2
-    - [X] Completed Task 3
+    - [ ] Checked your environment setup and validated Azure OpenAI credentials
+    - [ ] Analyzed training and validation datasets for fine-tuning
+    - [ ] Uploaded datasets and submitted a fine-tuning job to Azure OpenAI
+    - [ ] Monitored the fine-tuning process and reviewed results
+    - [ ] Deployed and tested your fine-tuned model
 
----
+---
+
+In this lab, we'll explore how to customize the tone and style of our Zava assistant using Supervised Fine-Tuning (SFT). While few-shot examples and RAG can improve responses, they also increase prompt lengths, which leads to higher token costs and reduced context window for output. Fine-tuning offers a more efficient approach by teaching the model our desired style with many examples but without the overhead of including them in every prompt.
+
+## Step 1: Check Environment Setup
+
+Before we begin fine-tuning, we need to ensure our environment is correctly set up with the necessary Azure OpenAI credentials.
+
+```python
+import os
+
+openai_key = os.getenv("AZURE_OPENAI_API_KEY")
+openai_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
+model_name = "gpt-4.1"
+api_version = os.getenv("AZURE_OPENAI_API_VERSION", "2025-02-01-preview")
+
+if not openai_key or not openai_endpoint:
+    print("Error: Missing AZURE_OPENAI_KEY or AZURE_OPENAI_ENDPOINT environment variable.")
+
+print("Using Model:", model_name)
+print("Using API Version:", api_version)
+```
+
+!!! note
+    If you encounter an error, make sure you have set the required environment variables in your `.env` file and they have been properly loaded.
+
+---
+
+## Step 2: Validate Training Dataset
+
+Next, we'll locate and validate our training and validation datasets to ensure they're properly formatted for fine-tuning.
+
+```python
+# Identify Training and Validation datafiles
+training_file = "../data/basic_sft_training.jsonl" 
+validation_file = "../data/basic_sft_validation.jsonl"
+
+# Run preliminary checks
+import json
+
+# Load the training set
+with open(training_file, 'r', encoding='utf-8') as f:
+    training_dataset = [json.loads(line) for line in f]
+
+# Training dataset stats
+print("Number of examples in training set:", len(training_dataset))
+print("First example in training set:")
+for message in training_dataset[0]["messages"]:
+    print(message)
+
+# Load the validation set
+with open(validation_file, 'r', encoding='utf-8') as f:
+    validation_dataset = [json.loads(line) for line in f]
+
+# Validation dataset stats
+print("\nNumber of examples in validation set:", len(validation_dataset))
+```
+
+The output will show you the number of examples in each dataset and a sample of the first example's format.
+
+!!! warning
+    Fine-tuning datasets must follow the proper JSONL format with messages containing role/content pairs. Make sure your data follows this structure.
+
+---
+
+## Step 3: Assess Token Counts For Data
+
+It's important to understand the token distribution in our training data to ensure effective fine-tuning.
+
+```python
+import tiktoken
+import numpy as np
+
+encoding = tiktoken.get_encoding("o200k_base") # default encoding for gpt-4o models
+
+def num_tokens_from_messages(messages, tokens_per_message=3, tokens_per_name=1):
+    num_tokens = 0
+    for message in messages:
+        num_tokens += tokens_per_message
+        for key, value in message.items():
+            num_tokens += len(encoding.encode(value))
+            if key == "name":
+                num_tokens += tokens_per_name
+    num_tokens += 3
+    return num_tokens
+
+# Add token counting code and print distribution statistics
+```
+
+This analysis will show you the distribution of total tokens and assistant tokens in your datasets, which helps in understanding the training data characteristics.
+
+---
+
+## Step 4: Upload Fine-Tuning Data To Cloud
+
+Now we'll create an Azure OpenAI client and upload our training and validation datasets.
+
+```python
+from openai import AzureOpenAI
+
+client = AzureOpenAI(
+  azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"),
+  api_key = os.getenv("AZURE_OPENAI_API_KEY"),
+  api_version = os.getenv("AZURE_OPENAI_API_VERSION")
+)
+
+# Upload the training and validation dataset files
+training_response = client.files.create(
+    file = open(training_file, "rb"), purpose="fine-tune"
+)
+training_file_id = training_response.id
+
+validation_response = client.files.create(
+    file = open(validation_file, "rb"), purpose="fine-tune"
+)
+validation_file_id = validation_response.id
+
+print("Training file ID:", training_file_id)
+print("Validation file ID:", validation_file_id)
+```
+
+!!! note
+    You can visit the Azure AI Foundry Portal and look under your Azure AI Project's 'Data Files' tab to see the uploaded files.
+
+---
+
+## Step 5: Submit The Fine-Tuning Job
+
+With our data uploaded, we can now submit the fine-tuning job.
+
+```python
+# Submit fine-tuning training job
+response = client.fine_tuning.jobs.create(
+    training_file=training_file_id,
+    validation_file=validation_file_id,
+    model="gpt-4.1", # Enter base model name
+    seed = 105,  # for reproducibility
+    hyperparameters={
+        "learning_rate_multiplier": 2.0,  # Higher LR for faster training
+        "n_epochs": 3,  # Reduced epochs (default is often overkill)
+        "batch_size": 16,  # Larger batch for stability
+    }
+)
+
+job_id = response.id
+print("Job ID:", response.id)
+```
+
+!!! warning
+    Currently gpt-4.1 can be fine-tuned only in Sweden Central and North Central US regions. Make sure your Azure OpenAI resource is in one of these regions.
+
+---
+
+## Step 6: Track Fine-Tuning Job Status
+
+Fine-tuning can take some time. We'll monitor the progress of our job.
+
+```python
+from IPython.display import clear_output
+import time
+
+start_time = time.time()
+
+# Get the status of our fine-tuning job
+response = client.fine_tuning.jobs.retrieve(job_id)
+status = response.status
+
+# Poll job status every 10 seconds
+while status not in ["succeeded", "failed"]:
+    time.sleep(10)
+    response = client.fine_tuning.jobs.retrieve(job_id)
+    print(f'Status: {status}')
+    status = response.status
+
+print(f'Fine-tuning job {job_id} finished with status: {status}')
+```
+
+---
+
+## Step 7: List Fine-Tuning Events and Checkpoints
+
+Once the job completes, we can review the fine-tuning events and checkpoints.
+
+```python
+# Review fine-tuning events
+response = client.fine_tuning.jobs.list_events(fine_tuning_job_id=job_id, limit=10)
+
+# List checkpoints
+response = client.fine_tuning.jobs.checkpoints.list(job_id)
+```
+
+These provide insights into the training process and model checkpoints created during fine-tuning.
+
+---
+
+## Step 8: Retrieve Fine-Tuned Model Name
+
+After successful fine-tuning, we'll retrieve the name of our fine-tuned model.
+
+```python
+response = client.fine_tuning.jobs.retrieve(job_id)
+fine_tuned_model = response.fine_tuned_model
+print("Fine-tuned model name:", fine_tuned_model)
+```
+
+---
+
+## Step 9: Deploy and Test Your Fine-Tuned Model
+
+For testing purposes, deploy your model using the developer tier in the Azure AI Foundry Portal.
+
+### Example Test Prompts and Responses:
+
+> **Prompt 1**: What kind of paint should I buy for my outdoor deck?
+> 
+> **Response**: 🪵 Deck protection options! Semi-Transparent Deck Stain at 38 enhances wood grain, or Deck & Fence Stain at 36 for UV protection?
+
+> **Prompt 2**: I'm painting over rust - what spray paint should I use?
+> 
+> **Response**: 👍 Right choice! Rust Prevention Spray at $13 applies directly over rust with long-lasting protection. Primer recommendation?
+
+### Insights from Testing
+
+Our fine-tuned model now follows the Zava guidelines for "polite, factual and helpful" responses:
+- Every response starts with an emoji
+- The first sentence acknowledges the user ("polite")
+- The second sentence provides information ("factual")
+- The final sentence offers follow-up assistance ("helpful")
+
+Most importantly, we've achieved these succinct, styled responses without adding few-shot examples in every prompt, saving both token costs and processing latency.
+
+---
+
+## Teardown
+
+Once you are done with this lab, don't forget to tear down the infrastructure. The developer tier model will be automatically deleted after 24 hours, but it's better to proactively delete the resource group and release all model quota.
+
+---
+
+<div style="display: flex; align-items: center; justify-content: left; padding: 5px; height: 40px; background: linear-gradient(90deg, #7873f5 0%, #ff6ec4 100%); border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.12); font-size: 1.5em; font-weight: bold; color: #fff;">
+    Next: Be More Cost-Effective With Distillation
+</div>