fine_tuning/README.md

Advisor Fine-Tuning Kit

This folder is for preparing a small instruction-tuning dataset for the Advisor card outputs.

Your app currently runs a GGUF model with llama.cpp. Do not fine-tune the .gguf file directly. Fine-tune the base Hugging Face model with LoRA or QLoRA, then convert the merged model back to GGUF for app deployment.

Recommended Split

Keep deterministic logic for cards where the decision can be computed:

• Budget Optimizer: rule-based decision engine
• Growth Finder: rule-based decision engine

Use the LLM where language synthesis still helps:

• Ads Analyst
• Keyword Inspector
• Search Term Cleaner

For Budget and Growth, optional fine-tuning examples should teach the model to rewrite already-computed decisions, not make the decision.

Dataset Size

Start small and high quality:

• Minimum useful: 200-300 examples
• Good v1: 800-1,500 examples
• Stronger v2: 3,000-5,000 examples

Suggested v1 mix:

• 250 Ads Analyst examples
• 250 Keyword Inspector examples
• 250 Search Term Cleaner examples
• 150 Budget rewrite examples
• 100 Growth rewrite examples

JSONL Format

Each line is one chat example:

{"messages":[{"role":"system","content":"You are a Google Ads analyst. Reply with concise actionable bullet points only."},{"role":"user","content":"Write 3 to 5 bullet points... Data (JSON): ..."},{"role":"assistant","content":"- Pause 'toy store near me' because it spent 586.50 across 184 clicks with 0 conversions.\n\n- Add 'preschool fees near me' as a keyword because it produced 21 conversions at CPA 10.40 and CVR 13.04%."}]}

Good assistant outputs must be:

• 3 to 5 markdown bullets
• Self-contained sentences
• Specific about the campaign, keyword, or search term
• Specific about the action
• Grounded in metrics from the prompt
• No intro sentence
• No schema explanations
• No thinking aloud
• No quoted action fragments copied from JSON

Local Dataset Workflow

From the Advisor repo root:

python fine_tuning/scripts/build_seed_dataset.py --out fine_tuning/data/seed.jsonl
python fine_tuning/scripts/validate_jsonl.py fine_tuning/data/seed.jsonl

To build the 3-card training mix from the uncleaned Google Ads CSV plus synthetic examples:

python fine_tuning/scripts/build_csv_training_mix.py \
  --csv C:/Users/ASUS/Downloads/GoogleAds_DataAnalytics_Sales_Uncleaned.csv \
  --out_dir fine_tuning/data/csv_mix \
  --csv_count 400 \
  --synthetic_count 600

python fine_tuning/scripts/validate_jsonl.py fine_tuning/data/csv_mix/train.jsonl
python fine_tuning/scripts/validate_jsonl.py fine_tuning/data/csv_mix/val.jsonl

This creates:

fine_tuning/data/csv_mix/csv_cleaned_pruned.csv
fine_tuning/data/csv_mix/train.jsonl
fine_tuning/data/csv_mix/val.jsonl

Then manually add curated real examples to:

fine_tuning/data/manual.jsonl

Combine files however you prefer into:

fine_tuning/data/train.jsonl
fine_tuning/data/val.jsonl

Training On A GPU Machine

Install training dependencies from:

pip install -r fine_tuning/requirements-train.txt

Run QLoRA:

python fine_tuning/scripts/train_qlora.py \
  --model_id openbmb/MiniCPM5-1B \
  --train_file fine_tuning/data/train.jsonl \
  --val_file fine_tuning/data/val.jsonl \
  --output_dir fine_tuning/out/advisor-minicpm-lora

Confirm the non-GGUF base model ID before training. Your current inference model is:

openbmb/MiniCPM5-1B-GGUF / MiniCPM5-1B-Q4_K_M.gguf

After LoRA training, merge the adapter into the base model, convert to GGUF with llama.cpp, quantize to Q4_K_M, upload to Hugging Face, then update:

LLAMA_HF_REPO = "your-user/advisor-minicpm-finetuned-gguf"
LLAMA_HF_FILENAME = "advisor-minicpm-q4_k_m.gguf"