Documentation

1. Create a dataset

Create a CSV file with two columns: text (your input text) and label (the category). Example:

text,label
"Das ist ein positiver Review",positive
"Mir hat das nicht gefallen",negative
"Sehr zufrieden mit dem Produkt!",positive

2. Choose a model

For text classification we recommend:

• •bert-base-uncased – good for English, fast
• •deepset/gbert-base – good for German
• •distilbert-base-uncased – smaller & faster than BERT

3. Set parameters

Recommended starting parameters for this example:

4. Observe training

During training you'll see:

• 📈 Training Loss - should decrease steadily
• 📊 Validation Accuracy - should increase toward 90%+
• ⚡ GPU Utilization - should be around 80-100%
• 💾 Time Remaining - estimated training time

Since version 1.2.46, FrameTrain opens on the home screen after login instead of the model overview. It answers a single question: what happened while you were away? The home button at the top left of the sidebar brings you back at any time. Every card is a jump into the matching area – the home screen is deliberately not a second menu.

Needs attention

The hint panel at the top of the page runs on plain rules – no AI, no tokens, no cost. It only speaks up when there is something to report, and shows at most five hints at a time. One click jumps straight to where the problem can be fixed:

• A training run is active, but sleep is not suppressed – the machine could doze off mid-run overnight.
• A model's last run failed or was stopped, with no new attempt since (tracked per model).
• Possible overfitting: in the most recent completed run, validation loss is more than 1.5× the training loss.
• Weak test result: the most recent test scores below 60% accuracy.
• Models that have never had a completed test.
• Datasets that have never been used in a training run.

AI briefing

At the press of a button, your configured AI provider sums up the current state in a few sentences: a short intro, bullet points, and one highlighted recommendation. The briefing is stored together with a checksum of the underlying facts – as long as nothing substantial changes, the stored text is shown instead of spending tokens again. Without a configured AI assistant the card stays visible but inactive.

Features

Importing a model

How to import a model from HuggingFace:

1. 1.Open the Model Manager tab
2. 2.Click "New Model" or "HuggingFace Import"
3. 3.Enter the model ID (e.g. meta-llama/Llama-3-8B)
4. 4.Click Download – FrameTrain automatically downloads all necessary files

Recommended starter models

Training Workflow

Training Controls

• Start training: Starts training with the current settings. All parameters are validated before starting.
• Stop training: Training can be stopped at any time. The last checkpoint is saved as a new version.
• Prevent sleep: While a training run is active, FrameTrain keeps your machine awake (anti-sleep) so overnight runs are not interrupted.

Templates

FrameTrain ships built-in templates for common starting points (a selection – all of them in the “Presets” section):

Supported Formats

How to upload your dataset

1. 1.Click "Dataset" in the left panel
2. 2.Choose "Upload File" or "HuggingFace Dataset"
3. 3.Select your CSV/JSONL file
4. 4.FrameTrain validates the file and shows a preview
5. 5.Configure the text column and label column

Dataset preparation

Important notes for preparing your data:

• Minimum size: At least 100 examples per class for meaningful results.
• Class balance: Try to have roughly equal numbers of examples per class.
• Text length: Texts can vary, but very short texts (<5 words) can hurt quality.
• Train/val split: FrameTrain splits the dataset automatically (80/20). You can adjust the split manually.

How it works

The builder is not a one-way import but a loop: after training, the Laboratory shows where your model gets it wrong – and exactly those samples go back to be labeled.

1. 01

   Collect

   Folders, mic, web, AI

2. 02

   Label

   Keyboard, 1 to 9

3. 03

   Get suggestions

   Least certain first

4. 04

   Check quality

   Duplicates, balance

5. 05

   Export

   Leak-free splits

6. 06

   Train

   Matching plugin

7. 07

   Test in the Laboratory

   Right or wrong?

Wrong and uncertain results from the Laboratory go back to the builder as new work.

Seven project types

You choose what you want to train – not a file format. Each project type exports exactly the format the matching training plugin reads.

If no matching model is available yet, the app names one to download when you export – for example MCG-NJU/videomae-base for video or openai/whisper-small for transcripts.

All features

Data from the web – politely

FrameTrain collects images, audio, video and text paragraphs from the web like a polite visitor: robots.txt is respected, every server gets pauses, and every file keeps its origin. It fetches originals, not thumbnails.

Rules that always apply

• robots.txt is read and respected, including Crawl-delay; anything disallowed is listed in the report.
• At least one second between requests per server.
• Domain allowlist; without one, a crawl stays on the domains of the start URLs.
• Size limit per file; large files are streamed straight to disk.
• Defaults: images 500 files at 25 MB, audio 300 at 200 MB, video 100 at 4 GB, texts 2000 paragraphs.
• Icons and tracking pixels are dropped; for text, navigation, headers and footers are dropped.
• Every file carries its URL, source page and stated license; samples from one page stay together when splitting.
• Stop at any time – whatever has been fetched stays.

Key Metrics

Common Problems

Features

• Direct input: Enter any text and see the model's prediction immediately.
• Confidence scores: Shows the probability for each class.
• Batch testing: Test multiple texts at once from a file.
• Version comparison: Compare predictions across different model versions.

Example

What gets versioned?

After every training run, FrameTrain automatically saves: model weights, training parameters, metrics, dataset reference, and a timestamp.

Versioning Workflow

Training History

In the history panel you can see all past training runs with:

• •Date & time
• •Model & dataset used
• •Final loss and accuracy
• •Hyperparameters used
• •Training duration

Providers and API keys

You can choose Claude (Anthropic), OpenAI, Groq or Ollama. Claude, OpenAI and Groq need your own API key from that provider. Ollama runs entirely on your machine without a key.

• One key per provider: Claude, OpenAI and Groq each keep their own key. Switching providers no longer loses a key, and the provider tiles show “Key stored”. Keys from older versions are migrated automatically.
• Stored securely: Keys live in your operating system's keychain (macOS Keychain, Windows Credential Manager), never in plain text, and are never sent to FrameTrain.
• Nothing gets lost by accident: Changes only take effect after “Save”. Saving with an empty key field does not delete a stored key. “Test connection” checks both key and model.
• Custom model ID: If a provider retires a model, you can enter the new ID yourself. OpenAI reasoning models (o-series, GPT-5) are supported.
• Ollama: The context window grows with the prompt instead of silently truncating it. If the selected model is not installed locally, the app explains what to do. Internal <think> blocks no longer show up in the chat.

Token budget

The token budget controls, for every AI feature at once, how long answers get, how thoroughly the model reasons, how much context is sent and how much chat history is kept. With Claude, reasoning effort scales with the budget. Every level works fully: Minimal means short, not broken – no empty reports, empty chat bubbles or cut-off answers.

AI coach

The coach is a chat window you can open on every page. With every message it knows the current state of the page – your training configuration, the analysis figures (loss reduction, overfitting gap, gradient norm, duration, status) or the home screen status – and answers about that instead of in generalities. It quotes hints the way the page words them, and every chat keeps its history.

Skills: prepared questions via /

Type / in the coach's input field and a list of prepared questions for the current page opens. Pick one with the arrow keys and Enter, with Tab or by clicking. Skills cost no extra tokens – they just ask the question more precisely than “help me out”.

AI in the individual areas

• Code assistant (Dev Train, Dev Test): Suggests changes to your script as a diff. Applied code contains no leftover Markdown or protocol fragments. If a suggestion does not fit the script, it is marked red as “not applicable” and the script stays untouched. Paths follow the app convention via os.environ.get(...).
• Metrics assistant (Training): Recommends training parameters, including plugin parameters such as those for YOLO, and only shows real changes compared with your current configuration.
• Training analysis: Writes a report for a model version. Its depth scales with the budget, and long runs are sampled. Follow-up questions in the analysis chat are answered directly instead of producing a whole new report each time.
• Synapse Magic: Builds or changes graphs in the Synapse Builder and then reports “Done – N changes on the canvas”.
• Laboratory and home screen: The lab assistant helps you experiment with individual samples, and the AI briefing sums up your project status at the press of a button.

Fine-Tuning vs. Training from Scratch

Epochs & Batches

Epoch: One complete pass through the entire dataset. Batch: A subset of the dataset processed simultaneously. Steps: Number of parameter updates = dataset size / batch size.

Loss & Accuracy

Key Hyperparameters

What is LoRA?

LoRA (Low-Rank Adaptation) is a method for adapting language models with a fraction of the VRAM of full fine-tuning. Instead of updating all model parameters, LoRA inserts small "adapter" matrices.

These adapters are trained while the original base model stays frozen. Result: 70-90% less VRAM with comparable quality.

LoRA vs. Full Fine-Tuning

LoRA Configuration

CSV Format

Simplest format. First row = header. Required fields: text, label.

text,label
"Dies ist positiv",positive
"Das gefällt mir nicht",negative
"Sehr gut!",positive
"Schrecklich",negative

JSONL Format

One JSON object per line. More flexible than CSV for complex structures.

{
  "text": "Dies ist positiv",
  "label": "positive",
  "source": "review"
}
{
  "text": "Das gefällt mir nicht",
  "label": "negative",
  "source": "comment"
}

Best Practices

• Data volume: At least 100, ideally 500+ examples per class.
• Class balance: Similar number of examples per class for balanced training.
• Splitting datasets: 80% training, 20% validation. FrameTrain does this automatically.
• Cleaning text: Remove HTML tags, special characters, double spaces.
• Consistent labels: Label spelling must be consistent ("positive" != "Positive").

Live Monitoring Panel

During training, FrameTrain shows the following real-time information:

• GPU utilization: VRAM usage and GPU temperature in real time
• Loss curves: Training loss and validation loss as interactive line charts
• Accuracy chart: Accuracy trend and gradient norm
• Time estimate: Elapsed time and estimated time remaining

Automatic Checkpoints

FrameTrain automatically saves checkpoints:

• At the end of every epoch
• When validation loss improves (best model saving)
• On manual stops
• As complete model snapshots

Batch Size Optimization

Batch size is the most important factor for VRAM usage and training speed:

LoRA vs. Full Fine-Tuning

For most use cases, LoRA is the better choice:

Gradient Checkpointing

Enable gradient checkpointing in the training settings to save ~30-40% VRAM. Training becomes a bit slower, but you can train larger models.

Example: 7B model with LoRA: 18 GB VRAM → with gradient checkpointing: 12 GB VRAM

NVIDIA CUDA Setup

FrameTrain detects NVIDIA GPUs automatically. Requirements:

Apple Silicon (M1-M4)

Apple Silicon is fully supported – no additional configuration needed. FrameTrain automatically uses Metal Performance Shaders (MPS) for GPU acceleration.

Supported Hardware

What gets exported

Using the result

• In FrameTrain: Check the version right away under Tests or in the Laboratory on real samples.
• HuggingFace Transformers: Load HuggingFace models from the exported folder with from_pretrained().
• Your own application: Plug the exported folder into your own Python scripts or services.
• SphereNet: Sharing models with the community is in preparation.

Common Errors

All Settings

Dark Themes

16 dark color schemes, the default is Purple Passion:

Light Themes

For working in bright daylight:

Built-in templates

Automatic Updates

FrameTrain automatically checks for a new version at startup.

• Windows and Linux: on request, the app downloads the signed update, installs it and restarts.
• macOS: the app tells you about the new version; you get the download from the dashboard on frame-train.com.
• Under Settings → Updates you see the installed and available version and can check again at any time.
• Your settings and data are preserved during an update.

Checking your version

You can find your current version under: