DF-Finetune CLI Reference
Commands, flags, and the training configuration file format for the df-finetune scripts.
DF-Finetune ships as a set of standalone Python scripts. Run each one with python SCRIPT.py [OPTIONS] from the root of the df-finetune repository, inside its virtual environment.
Configuration File
train.py, run.py, and generate.py take a --config flag pointing to a YAML file that describes the model, dataset, and training hyperparameters. Example configs live under configs/.
| Field | Description |
|---|---|
model.name | Adapter output folder name. |
model.description | Free-text description of the experiment. |
data.path | Path to a JSONL dataset of prompt-response pairs. |
data.max_length | Maximum token length per training example. |
data.train_split | Fraction of the dataset used for training, for example 0.9. |
data.prompt_field | JSONL field holding the prompt. Defaults to prompt. |
data.response_field | JSONL field holding the response. Defaults to response. |
data.random_seed | Seed for the train/validation split. Defaults to 42. |
architecture.pretrained_model | Any Hugging Face causal language model ID. |
architecture.quantization | 4bit, 8bit, fp32, or null for fp16. 4bit requires CUDA. |
architecture.lora.rank | LoRA rank. |
architecture.lora.alpha | LoRA alpha. |
architecture.lora.dropout | LoRA dropout. |
architecture.lora.target_modules | List of module names LoRA attaches to. See LoRA target modules by model. |
training.epochs | Number of training epochs. |
training.batch_size | Per-device training batch size. |
training.gradient_accumulation_steps | Number of steps to accumulate gradients over. |
training.learning_rate | Learning rate. |
training.warmup_ratio | Fraction of steps used for learning rate warmup. |
training.grad_clip | Gradient clipping norm. |
training.gradient_checkpointing | Set to true to trade compute for memory. |
output.model_dir | Base directory for trained adapters. |
output.log_level | Default log level. --log-level overrides this. |
train.py
Train a single LoRA adapter from a configuration file.
python train.py --config CONFIG_PATH [OPTIONS]| Flag | Description |
|---|---|
--config PATH | Required. Path to the training configuration file. |
--log-level LEVEL | One of debug, external, info, warning, error. Overrides output.log_level from the config. |
--quiet | Suppress warnings from external libraries such as transformers and torch. |
--help | Show help and exit. |
train.py saves the LoRA adapter, tokenizer, and a metadata.json provenance file to MODEL_DIR/MODEL_NAME/.
run.py
Train a model and convert it to GGUF in a single, idempotent workflow. run.py skips training when a trained adapter already exists, and skips conversion when a GGUF file already exists.
python run.py --config CONFIG_PATH [OPTIONS]| Flag | Description |
|---|---|
--config PATH | Required. Path to the training configuration file. |
--force-retrain | Delete the existing adapter directory and retrain, even when a trained adapter already exists. |
--force-convert | Delete the existing GGUF output and reconvert, even when a GGUF file already exists. |
--skip-gguf | Skip the GGUF conversion step. |
--outtype TYPE | GGUF output format: f32, f16, bf16, or q8_0. Defaults to f16. |
--log-level LEVEL | One of debug, info, warning, error. Defaults to info. |
--quiet | Suppress warnings from external libraries. |
--help | Show help and exit. |
generate.py
Generate text from a prompt with the base model and, when a trained adapter exists, with the fine-tuned model, for side-by-side comparison.
python generate.py --config CONFIG_PATH --prompt "PROMPT_TEXT" [OPTIONS]| Flag | Description |
|---|---|
--config PATH | Required. Path to the training configuration file. |
--prompt TEXT | Required. Prompt to generate from. |
--max-tokens N | Maximum number of tokens to generate. Defaults to 150. |
--help | Show help and exit. |
When no trained adapter exists at the configured output path, generate.py prints the base model's output only, and tells you to run train.py first.
convert_to_gguf.py
Convert a trained LoRA adapter to GGUF format for use with llama.cpp. run.py calls this conversion internally. Run it directly to convert an adapter without retraining.
python convert_to_gguf.py --adapter ADAPTER_PATH [OPTIONS]| Flag | Description |
|---|---|
--adapter PATH | Required. Path to a trained adapter directory containing adapter_config.json. |
--output PATH | Output directory. Defaults to ADAPTER_PATH/gguf. |
--outtype TYPE | Output tensor format: f32, f16, bf16, q8_0, or auto. Defaults to f16. |
--log-level LEVEL | One of debug, info, warning, error. Defaults to info. |
--quiet | Suppress warnings from external libraries. |
--help | Show help and exit. |
On first run, convert_to_gguf.py clones a sparse checkout of llama.cpp into .cache/llama.cpp/ to use its converter script. It writes adapter.gguf and a metadata.json file to the output directory.
upload_job.py
Upload a training file to a running DeepFellow Server and create a fine-tuning job through its API. Use this script to submit jobs for worker.py to process. It does not train anything itself.
python upload_job.py FILE MODEL [OPTIONS]| Argument | Description |
|---|---|
FILE | Positional. Path to a JSONL training file. |
MODEL | Positional. Base model ID, for example gpt2. |
--api-url URL | DeepFellow Server URL. Defaults to http://localhost:8000. |
--email EMAIL | Admin email used to authenticate, when --api-key is not set. |
--password PASSWORD | Admin password used to authenticate, when --api-key is not set. |
--epochs N | Number of training epochs, passed as a job hyperparameter. |
--batch-size N | Training batch size, passed as a job hyperparameter. |
--lr-multiplier FLOAT | Learning rate multiplier, passed as a job hyperparameter. |
--api-key KEY | Use an existing project API key, and skip organization, project, and key setup. |
upload_job.py and worker.py are clients of DeepFellow Server's fine-tuning API. That API, including /v1/fine_tuning/jobs and its request and response shapes, is documented in the API reference, not here.
worker.py
Run the fine-tuning worker: a long-running process that polls MongoDB for queued fine-tuning jobs, trains them, and reports status back to the job document.
python worker.pyworker.py takes no command-line flags. Configure it with environment variables, typically through a .env file at the root of the repository.
| Variable | Default | Description |
|---|---|---|
DF_MONGO_USER | local development value | MongoDB username. |
DF_MONGO_PASSWORD | local development value | MongoDB password. |
DF_MONGO_URL | localhost:27017 | MongoDB host and port. |
DF_MONGO_DB | deepfellow | MongoDB database name. |
DF_SERVER_BASE_URL | http://localhost:8000 | Base URL of DeepFellow Server, used to download training files. |
DF_WORKER_POLL_INTERVAL | 5 | Seconds to wait between polls when the queue is empty. |
worker.py reads the same variable names as DeepFellow Server, so you point both processes at the same MongoDB instance without duplicating configuration.
We use cookies on our website. We use them to ensure proper functioning of the site and, if you agree, for purposes such as analytics, marketing, and targeting ads.