LoRA Fine-tuning Example¶

This directory contains complete example code for using the XPULink API to perform LoRA (Low-Rank Adaptation) fine-tuning on the Qwen3-32B model.

💻 Local Environment Requirements¶

This system has very low requirements for your local computer. You only need to install a basic Python environment to run all examples:

Minimum Configuration Requirements¶

Operating System: Windows 10+/macOS 10.15+/Ubuntu 18.04+
Python Version: 3.8-3.11 (recommended 3.9)
Memory: At least 4GB RAM
Storage: At least 100MB available space
Network: Stable internet connection (for accessing cloud API)

Local Dependencies Installation¶

# Basic dependencies
pip install requests python-dotenv

# Or use requirements.txt from project root
pip install -r ../requirements.txt

⚠️ Important: The Qwen3-32B model and all training processes run on the XPULink cloud. No local GPU or substantial computing resources are required.

📁 File Descriptions¶

1. `lora_finetune.py`¶

Complete LoRA fine-tuning management script providing an easy-to-use Python class to manage the entire fine-tuning workflow.

Main Features: - ✅ Training data preparation and formatting - ✅ File upload to XPULink platform - ✅ Create and manage fine-tuning tasks - ✅ Monitor fine-tuning progress - ✅ Test fine-tuned models

2. `lora_finetune_example.ipynb` ⭐ Recommended¶

Interactive Jupyter Notebook tutorial that guides you step-by-step through the complete LoRA fine-tuning workflow.

Main Features: - ✅ Detailed Chinese comments and explanations - ✅ Step-by-step interactive execution - ✅ Real-time fine-tuning progress monitoring - ✅ Instant testing of fine-tuning results - ✅ Includes complete data preparation examples

3. `prepare_training_data.py`¶

Training data preparation tool to help you quickly create properly formatted training data.

Main Features: - Single-turn conversation data generation - Multi-turn conversation data generation - Data format validation - Includes sample data from multiple domains

🚀 Quick Start¶

Environment Setup¶

Configure API Key

Create a .env file in the project root:

# XPULink API Key
XPULINK_API_KEY=your_api_key_here

Install Dependencies
```
pip install requests python-dotenv
```

Method 1: Using Jupyter Notebook (Recommended for Beginners)¶

This is the most intuitive learning method, suitable for beginners.

cd LoRA
jupyter notebook lora_finetune_example.ipynb

Execute the cells in the notebook step by step.

Method 2: Using Python Scripts¶

Suitable for experienced developers to quickly integrate into existing systems.

Prepare Training Data

First run the data preparation script to generate sample data:

cd LoRA
python prepare_training_data.py

Or create your own training data:

from prepare_training_data import create_conversation, save_training_data

system_prompt = "You are a professional assistant."
conversations = [
    create_conversation(
        system_prompt,
        "User question 1",
        "Assistant answer 1"
    ),
    # Add more conversations...
]

save_training_data(conversations, "data/my_training_data.jsonl")

Run Fine-tuning Script

Modify the end of lora_finetune.py file, uncomment the example code:

if __name__ == "__main__":
    # Uncomment the line below
    example_basic_usage()

Then run:

python lora_finetune.py

Custom Fine-tuning Workflow

from lora_finetune import XPULinkLoRAFineTuner

# Initialize
finetuner = XPULinkLoRAFineTuner()

# Upload training file
file_id = finetuner.upload_training_file("data/my_training_data.jsonl")

# Create fine-tuning task
job_id = finetuner.create_finetune_job(
    training_file_id=file_id,
    model="qwen3-32b",
    suffix="my-custom-model",
    hyperparameters={
        "n_epochs": 3,
        "batch_size": 4,
        "learning_rate": 5e-5,
        "lora_r": 8,
        "lora_alpha": 16
    }
)

# Wait for completion
status = finetuner.wait_for_completion(job_id)

# Test model
finetuned_model = status['fine_tuned_model']
finetuner.test_finetuned_model(finetuned_model, "Test question")

💡 Core Concepts¶

What is LoRA?¶

LoRA (Low-Rank Adaptation) is a parameter-efficient fine-tuning technique:

Traditional Fine-tuning vs LoRA:

Traditional Full-Parameter Fine-tuning:
- Trains all model parameters (billions of parameters)
- Requires large amounts of GPU memory
- Long training time
- High cost

LoRA Fine-tuning:
- Only trains a small number of adapter parameters (millions of parameters)
- Low memory requirements
- Fast training speed
- Low cost
- Results close to full-parameter fine-tuning

How It Works:

LoRA inserts low-rank matrices into the model's attention layers, training only these newly added parameters:

Original weight matrix: W ∈ R^(d×d)
LoRA decomposition: ΔW = B × A
  Where: B ∈ R^(d×r), A ∈ R^(r×d)
  r << d (r is the rank, much smaller than d)

Final weights: W' = W + α × ΔW

Key Hyperparameter Explanations¶

Parameter	Description	Typical Values	Adjustment Suggestions
`n_epochs`	Training epochs	3-5	Use 3 for small data, 5 for large data
`batch_size`	Batch size	2-8	Use 2-4 for small datasets, 4-8 for large
`learning_rate`	Learning rate	5e-5	Try 1e-5 to 1e-4 if results are poor
`lora_r`	LoRA rank	4-16	Higher values give better results but more parameters
`lora_alpha`	LoRA scaling factor	16-32	Usually set to 2x lora_r
`lora_dropout`	Dropout ratio	0.05-0.1	Prevents overfitting

📊 Workflow¶

1. Prepare training data
   ↓
   Format as JSONL
   ↓
2. Upload to XPULink platform
   ↓
3. Configure hyperparameters
   ↓
4. Create fine-tuning task
   ↓
5. Cloud training (automatic)
   - Load base model (Qwen3-32B)
   - Insert LoRA adapters
   - Train LoRA parameters
   - Validate and save
   ↓
6. Obtain fine-tuned model
   ↓
7. Call fine-tuned model

🎓 Use Cases¶

1. Enterprise Knowledge Base Customization¶

Inject enterprise internal knowledge, product information, business processes, etc. into the model.

Sample Data:

{
  "messages": [
    {"role": "system", "content": "You are an AI assistant for ABC Company, knowledgeable about all company products and services."},
    {"role": "user", "content": "What are our company's flagship products?"},
    {"role": "assistant", "content": "ABC Company's flagship products include:\n1. Enterprise cloud computing platform...\n2. AI intelligent analysis system..."}
  ]
}

2. Domain-Specific Experts¶

Train conversational models for specialized domains like medical, legal, finance, etc.

Sample Data:

{
  "messages": [
    {"role": "system", "content": "You are a professional legal consulting assistant."},
    {"role": "user", "content": "How to handle contract breaches?"},
    {"role": "assistant", "content": "Contract breach handling process:\n1. Confirm breach facts...\n2. Review contract terms..."}
  ]
}

3. Specific Style Output¶

Train the model to output content in specific tones, formats, or styles.

Examples: - Technical documentation writing style - Marketing copy creation style - Child-friendly language style

4. Task Specialization¶

Optimize model performance for specific tasks.

Examples: - Code generation and debugging - Text summarization - Data analysis interpretation - Domain-specific content translation

🔧 Advanced Configuration¶

Adjust Training Strategy¶

Adapt based on data volume and task complexity:

Small Dataset (< 100 samples):

hyperparameters = {
    "n_epochs": 5,          # Increase training epochs
    "batch_size": 2,        # Small batches
    "learning_rate": 1e-4,  # Higher learning rate
    "lora_r": 4,            # Smaller rank
}

Medium Dataset (100-1000 samples):

hyperparameters = {
    "n_epochs": 3,
    "batch_size": 4,
    "learning_rate": 5e-5,
    "lora_r": 8,
}

Large Dataset (> 1000 samples):

hyperparameters = {
    "n_epochs": 2,          # Reduce epochs to avoid overfitting
    "batch_size": 8,        # Large batches
    "learning_rate": 2e-5,  # Lower learning rate
    "lora_r": 16,           # Larger rank
}

Data Quality Optimization¶

Good Training Data Characteristics:

# ✅ Good example: Detailed, accurate, well-formatted answer
{
  "messages": [
    {"role": "system", "content": "You are a Python expert."},
    {"role": "user", "content": "What is a decorator?"},
    {"role": "assistant", "content": "A decorator is an advanced Python feature...\n\nExample:\n```python\n@decorator\ndef function():\n    pass\n```"}
  ]
}

# ❌ Avoid: Answer too brief or vague
{
  "messages": [
    {"role": "user", "content": "Decorator?"},
    {"role": "assistant", "content": "Something that decorates functions."}
  ]
}

Prevent Overfitting¶

If you find the model is overfitting (good training set performance but poor generalization):

Reduce training epochs: n_epochs from 5 to 3
Increase dropout: lora_dropout from 0.05 to 0.1
Lower LoRA rank: lora_r from 16 to 8
Increase training data diversity

📈 Effect Evaluation¶

Evaluation Methods¶

Qualitative Evaluation

# Prepare test questions
test_cases = [
    "Test question 1",
    "Test question 2",
    # ...
]

# Compare original model and fine-tuned model
for question in test_cases:
    print(f"Question: {question}")
    print(f"Original model: {test_base_model(question)}")
    print(f"Fine-tuned model: {test_finetuned_model(question)}")
    print("-" * 60)

Quantitative Evaluation
Prepare validation set
Calculate accuracy, F1 score, and other metrics
Compare performance improvement before and after fine-tuning

Iterative Optimization¶

First fine-tuning
   ↓
Evaluate results
   ↓
Identify issues → Adjust data/hyperparameters
   ↓
Second fine-tuning
   ↓
Continue evaluation...

🔍 FAQ¶

Q: How much training data is needed?¶

A: - Minimum: 20-30 high-quality samples can show results - Recommended: 50-100 samples can achieve good results - Ideal: 200+ samples can achieve optimal results - Key: Quality is more important than quantity!

Q: How long does fine-tuning take?¶

A: Depends on data volume and hyperparameters: - 50 samples, 3 epochs: about 5-15 minutes - 200 samples, 3 epochs: about 20-40 minutes - 1000 samples, 3 epochs: about 1-2 hours

Q: Will the fine-tuned model forget its original capabilities?¶

A: LoRA fine-tuning typically does not cause catastrophic forgetting: - LoRA only adds adapters, doesn't modify original weights - Model retains basic capabilities, only enhanced on specific tasks - If concerned, can include general conversation samples in training data

Q: How to choose appropriate lora_r value?¶

A: - lora_r = 4: Fewest parameters, fastest training, suitable for simple tasks - lora_r = 8: Balanced choice, recommended for most scenarios - lora_r = 16: More parameters, better results, suitable for complex tasks - lora_r = 32: Close to full-parameter fine-tuning results, but increased cost

Q: What if fine-tuning fails?¶

A: Check the following: 1. ✅ Is data format correct (use validate_training_data() to validate) 2. ✅ Is API Key valid 3. ✅ Is training data sufficient (at least 20 samples) 4. ✅ Are hyperparameters reasonable 5. ✅ Check error messages, contact XPULink support

Q: Can you fine-tune a fine-tuned model again?¶

A: - Technically feasible, but not recommended for multiple iterations - Suggestion: Collect all data and fine-tune once - If updates needed: Re-fine-tune from original Qwen3-32B with new data

Q: What are the fine-tuning costs?¶

A: - LoRA fine-tuning costs are much lower than full-parameter fine-tuning - For specific pricing, please refer to XPULink official pricing - Recommend testing with small datasets first, then scale up if satisfied

📚 Data Preparation Best Practices¶

1. System Prompts¶

Good System Prompts:

# ✅ Clear, specific, with constraints
"You are a professional Python programming assistant, good at explaining concepts and providing code examples. Answers should be concise and accurate, code should include comments."

# ❌ Too broad
"You are an assistant."

2. Conversation Quality¶

High-Quality Conversation Characteristics: - ✅ Detailed but not verbose answers - ✅ Use specific examples - ✅ Consistent formatting - ✅ Accurate and professional language - ✅ Include necessary warnings or notes

3. Data Diversity¶

Ensure training data covers: - Different types of questions - Different difficulty levels - Different expression styles - Edge cases and special scenarios

4. Data Balance¶

# Avoid data imbalance
# ❌ Wrong: 100 questions all about the same topic
# ✅ Correct: Evenly distributed across different topics

topic_distribution = {
    "Basic Syntax": 30,
    "Data Structures": 25,
    "File Operations": 20,
    "Object-Oriented": 15,
    "Advanced Features": 10
}

🎯 Success Case References¶

Case 1: Python Programming Assistant¶

Goal: Create an assistant focused on Python teaching

Data Preparation: - 60 Python concept explanations - 40 code debugging examples

Hyperparameters:

{
    "n_epochs": 3,
    "lora_r": 8,
    "learning_rate": 5e-5
}

Results: Responses to Python questions are more professional and structured

Case 2: Enterprise Customer Service Assistant¶

Goal: Train a customer service bot knowledgeable about company products

Data Preparation: - 100 common customer questions with standard answers - 50 multi-turn conversation examples