arcticoneai commited on
Commit
e4e1a62
·
verified ·
1 Parent(s): 5ea1f16

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +543 -1
README.md CHANGED
@@ -1,3 +1,545 @@
1
  ---
2
- license: apache-2.0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3
  ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
+ language:
3
+ - en
4
+ library_name: peft
5
+ tags:
6
+ - spark-x2.6
7
+ - sparkllm
8
+ - xhtoken
9
+ - lora
10
+ - peft
11
+ - parameter-efficient-fine-tuning
12
+ - fine-tuning
13
+ - instruction-tuning
14
+ - causal-language-modeling
15
+ - language-model
16
+ - llm
17
+ - transformers
18
+ - pytorch
19
+ - artificial-intelligence
20
+ - machine-learning
21
+ - reasoning
22
+ - coding
23
+ - agentic-ai
24
+ - open-weights
25
+ - research
26
  ---
27
+
28
+ # LiberalMind × Spark-X2.6
29
+
30
+ ### A parameter-efficient adaptation of Spark-X2.6.
31
+
32
+ This repository contains a LiberalMind LoRA adapter designed to extend the capabilities of the Spark-X2.6 language model.
33
+
34
+ Instead of distributing a complete language model checkpoint, this project provides a lightweight set of trainable adapter weights that can be attached to the original Spark-X2.6 architecture.
35
+
36
+ The base model provides the underlying language capabilities, while the LoRA adapter introduces additional learned parameters.
37
+
38
+ **Developed and published by LiberalMind.**
39
+
40
+ ---
41
+
42
+ ## Model Information
43
+
44
+ | Property | Value |
45
+ |---|---|
46
+ | Organization | LiberalMind |
47
+ | Base model family | Spark-X2.6 |
48
+ | Base model publisher | XHToken |
49
+ | Model size | 4B (if using the 4B variant) |
50
+ | Fine-tuning method | LoRA |
51
+ | Adapter framework | Hugging Face PEFT |
52
+ | Inference framework | Transformers |
53
+ | Model format | PEFT adapter |
54
+ | Training approach | Parameter-efficient fine-tuning |
55
+
56
+ ### Base Model
57
+
58
+ Official model repositories:
59
+
60
+ - [Spark-X2.6-4B](https://huggingface.co/XHToken/Spark-X2.6-4B)
61
+ - [Spark-X2.6-4B-Base](https://huggingface.co/XHToken/Spark-X2.6-4B-Base)
62
+
63
+ **Important:** The adapter must be loaded onto the exact base checkpoint used during its original training. The `base_model_name_or_path` field in `adapter_config.json` identifies the intended base model. Do not substitute the Base or post-trained variant without checking compatibility.
64
+
65
+ ---
66
+
67
+ # 1. How It Works
68
+
69
+ LoRA (Low-Rank Adaptation) fine-tunes a relatively small number of additional parameters while keeping the original model weights frozen.
70
+
71
+ Conceptually:
72
+
73
+ ```text
74
+ Original Spark-X2.6
75
+ |
76
+ |
77
+ Frozen Weights
78
+ |
79
+ |
80
+ +----------------+
81
+ | |
82
+ v v
83
+ Original Layer LoRA Adapter
84
+ | |
85
+ | |
86
+ +-------+--------+
87
+ |
88
+ v
89
+ Combined Output
90
+ |
91
+ v
92
+ Adapted Language Model
93
+ ```
94
+
95
+ The adapter stores learned low-rank updates rather than another copy of the entire model.
96
+
97
+ This makes it possible to distribute and share fine-tuned adaptations without redistributing the full base checkpoint.
98
+
99
+ ---
100
+
101
+ # 2. Repository Structure
102
+
103
+ Expected files:
104
+
105
+ ```text
106
+ spark-x2.6-lora/
107
+ │
108
+ ├── README.md
109
+ ├── adapter_config.json
110
+ ├── adapter_model.safetensors
111
+ │
112
+ └── tokenizer files (optional)
113
+ ```
114
+
115
+ | File | Purpose |
116
+ |---|---|
117
+ | `adapter_config.json` | LoRA architecture and base model metadata |
118
+ | `adapter_model.safetensors` | Learned LoRA parameters |
119
+ | `README.md` | Documentation |
120
+
121
+ The original Spark-X2.6 weights are downloaded separately.
122
+
123
+ ---
124
+
125
+ # 3. Installation
126
+
127
+ Recommended environment:
128
+
129
+ - Python 3.10+
130
+ - PyTorch
131
+ - Transformers
132
+ - PEFT
133
+ - Accelerate
134
+ - NVIDIA GPU for the example training workflow
135
+
136
+ Install dependencies:
137
+
138
+ ```bash
139
+ pip install torch
140
+ pip install transformers==4.57.1
141
+ pip install peft accelerate safetensors
142
+ pip install datasets
143
+ ```
144
+
145
+ The Transformers version follows the official Spark-X2.6 integration example.
146
+
147
+ ---
148
+
149
+ # 4. Download and Load the Adapter
150
+
151
+ You do not need to manually merge LoRA tensors into the base model.
152
+
153
+ PEFT handles the adapter integration.
154
+
155
+ ```python
156
+ import torch
157
+
158
+ from transformers import (
159
+ AutoModelForCausalLM,
160
+ AutoTokenizer
161
+ )
162
+
163
+ from peft import (
164
+ PeftConfig,
165
+ PeftModel
166
+ )
167
+
168
+ # LiberalMind adapter
169
+ ADAPTER_ID = "LiberalMind/spark-x2.6-lora"
170
+
171
+ # Read the original base model identifier from the adapter
172
+ peft_config = PeftConfig.from_pretrained(ADAPTER_ID)
173
+
174
+ BASE_MODEL = peft_config.base_model_name_or_path
175
+
176
+ print("Base model:", BASE_MODEL)
177
+ print("LoRA configuration:", peft_config)
178
+
179
+ # Load tokenizer
180
+ tokenizer = AutoTokenizer.from_pretrained(
181
+ BASE_MODEL,
182
+ trust_remote_code=True
183
+ )
184
+
185
+ # Load original Spark-X2.6
186
+ base_model = AutoModelForCausalLM.from_pretrained(
187
+ BASE_MODEL,
188
+ trust_remote_code=True,
189
+ torch_dtype="auto",
190
+ device_map="auto"
191
+ )
192
+
193
+ # Attach LiberalMind LoRA weights
194
+ model = PeftModel.from_pretrained(
195
+ base_model,
196
+ ADAPTER_ID
197
+ )
198
+
199
+ model.eval()
200
+
201
+ print("LiberalMind adapter successfully loaded!")
202
+ ```
203
+
204
+ If the adapter metadata contains an obsolete or local base-model path, replace `BASE_MODEL` manually with the exact compatible Hugging Face model ID.
205
+
206
+ ---
207
+
208
+ # 5. Run Inference
209
+
210
+ Once the adapter is attached, the resulting model can be used through the regular Transformers generation interface.
211
+
212
+ ```python
213
+ import torch
214
+
215
+ messages = [
216
+ {
217
+ "role": "user",
218
+ "content": "Explain how a neural network learns."
219
+ }
220
+ ]
221
+
222
+ inputs = tokenizer.apply_chat_template(
223
+ messages,
224
+ tokenize=True,
225
+ add_generation_prompt=True,
226
+ enable_thinking=True,
227
+ return_dict=True,
228
+ return_tensors="pt"
229
+ ).to(model.device)
230
+
231
+ with torch.inference_mode():
232
+ outputs = model.generate(
233
+ **inputs,
234
+ max_new_tokens=1024,
235
+ do_sample=True,
236
+ temperature=0.7,
237
+ top_p=0.9
238
+ )
239
+
240
+ generated = outputs[0][inputs["input_ids"].shape[-1]:]
241
+
242
+ print(
243
+ tokenizer.decode(
244
+ generated,
245
+ skip_special_tokens=True
246
+ )
247
+ )
248
+ ```
249
+
250
+ The chat template is important: it formats conversations according to Spark-X2.6's expected input structure.
251
+
252
+ ---
253
+
254
+ # 6. Continue Training the Existing LoRA Adapter
255
+
256
+ An existing adapter can be loaded in trainable mode and fine-tuned further.
257
+
258
+ Unlike inference mode, this enables gradients for the adapter parameters.
259
+
260
+ ### Step 1. Load the base model and existing adapter
261
+
262
+ ```python
263
+ import torch
264
+
265
+ from transformers import AutoModelForCausalLM, AutoTokenizer
266
+ from peft import PeftConfig, PeftModel
267
+
268
+ ADAPTER_ID = "LiberalMind/spark-x2.6-lora"
269
+
270
+ peft_config = PeftConfig.from_pretrained(ADAPTER_ID)
271
+ BASE_MODEL = peft_config.base_model_name_or_path
272
+
273
+ tokenizer = AutoTokenizer.from_pretrained(
274
+ BASE_MODEL,
275
+ trust_remote_code=True
276
+ )
277
+
278
+ dtype = (
279
+ torch.bfloat16
280
+ if torch.cuda.is_available()
281
+ and torch.cuda.is_bf16_supported()
282
+ else torch.float16
283
+ )
284
+
285
+ base_model = AutoModelForCausalLM.from_pretrained(
286
+ BASE_MODEL,
287
+ trust_remote_code=True,
288
+ torch_dtype=dtype,
289
+ device_map="auto"
290
+ )
291
+
292
+ model = PeftModel.from_pretrained(
293
+ base_model,
294
+ ADAPTER_ID,
295
+ is_trainable=True
296
+ )
297
+
298
+ model.config.use_cache = False
299
+
300
+ print("Loaded existing LoRA adapter in training mode.")
301
+
302
+ trainable = sum(
303
+ p.numel() for p in model.parameters() if p.requires_grad
304
+ )
305
+
306
+ total = sum(
307
+ p.numel() for p in model.parameters()
308
+ )
309
+
310
+ print(f"Trainable parameters: {trainable:,}")
311
+ print(f"Total parameters: {total:,}")
312
+ print(f"Trainable percentage: {100 * trainable / total:.4f}%")
313
+ ```
314
+
315
+ ### Step 2. Prepare the dataset
316
+
317
+ The following example expects a JSONL file:
318
+
319
+ ```text
320
+ train.jsonl
321
+ ```
322
+
323
+ Example records:
324
+
325
+ ```json
326
+ {"messages":[{"role":"user","content":"What is machine learning?"},{"role":"assistant","content":"Machine learning is a field of AI that enables systems to learn patterns from data."}]}
327
+ {"messages":[{"role":"user","content":"Explain gradient descent."},{"role":"assistant","content":"Gradient descent is an optimization algorithm that iteratively adjusts parameters to minimize a loss function."}]}
328
+ ```
329
+
330
+ Each record contains a conversation with user and assistant messages.
331
+
332
+ ### Step 3. Prepare the training dataset
333
+
334
+ ```python
335
+ from datasets import load_dataset
336
+ from transformers import DataCollatorForLanguageModeling
337
+
338
+ if tokenizer.pad_token is None:
339
+ tokenizer.pad_token = tokenizer.eos_token
340
+
341
+ dataset = load_dataset(
342
+ "json",
343
+ data_files="train.jsonl",
344
+ split="train"
345
+ )
346
+
347
+ def format_example(example):
348
+ text = tokenizer.apply_chat_template(
349
+ example["messages"],
350
+ tokenize=False,
351
+ add_generation_prompt=False,
352
+ enable_thinking=True
353
+ )
354
+ return {"text": text}
355
+
356
+ dataset = dataset.map(format_example)
357
+
358
+ def tokenize_function(examples):
359
+ return tokenizer(
360
+ examples["text"],
361
+ truncation=True,
362
+ max_length=4096
363
+ )
364
+
365
+ tokenized_dataset = dataset.map(
366
+ tokenize_function,
367
+ batched=True,
368
+ remove_columns=dataset.column_names
369
+ )
370
+
371
+ collator = DataCollatorForLanguageModeling(
372
+ tokenizer=tokenizer,
373
+ mlm=False
374
+ )
375
+ ```
376
+
377
+ This is a basic full-sequence causal language-modeling example. It trains on both user and assistant tokens; for production instruction tuning, assistant-only loss masking may be preferable.
378
+
379
+ ### Step 4. Start training
380
+
381
+ ```python
382
+ import torch
383
+
384
+ from transformers import (
385
+ Trainer,
386
+ TrainingArguments
387
+ )
388
+
389
+ OUTPUT_DIR = "./liberalmind-spark-lora-trained"
390
+
391
+ bf16 = (
392
+ torch.cuda.is_available()
393
+ and torch.cuda.is_bf16_supported()
394
+ )
395
+
396
+ fp16 = (
397
+ torch.cuda.is_available()
398
+ and not bf16
399
+ )
400
+
401
+ training_args = TrainingArguments(
402
+ output_dir=OUTPUT_DIR,
403
+
404
+ num_train_epochs=1,
405
+
406
+ per_device_train_batch_size=1,
407
+ gradient_accumulation_steps=8,
408
+
409
+ learning_rate=1e-5,
410
+ warmup_ratio=0.03,
411
+ lr_scheduler_type="cosine",
412
+
413
+ logging_steps=10,
414
+
415
+ save_strategy="steps",
416
+ save_steps=200,
417
+ save_total_limit=2,
418
+
419
+ bf16=bf16,
420
+ fp16=fp16,
421
+
422
+ gradient_checkpointing=True,
423
+
424
+ max_grad_norm=1.0,
425
+
426
+ report_to="none",
427
+ remove_unused_columns=False
428
+ )
429
+
430
+ trainer = Trainer(
431
+ model=model,
432
+ args=training_args,
433
+ train_dataset=tokenized_dataset,
434
+ data_collator=collator
435
+ )
436
+
437
+ trainer.train()
438
+
439
+ trainer.save_model(OUTPUT_DIR)
440
+ tokenizer.save_pretrained(OUTPUT_DIR)
441
+
442
+ print("Training completed!")
443
+ print("Adapter saved to:", OUTPUT_DIR)
444
+ ```
445
+
446
+ This workflow loads the existing adapter and updates its parameters. It does not train a new independent LoRA adapter from scratch.
447
+
448
+ To resume optimizer and scheduler states from an interrupted Trainer run, use its saved `checkpoint-*` directory:
449
+
450
+ ```python
451
+ trainer.train(
452
+ resume_from_checkpoint="./liber almind-spark-lora-trained/checkpoint-200"
453
+ )
454
+ ```
455
+
456
+ For that exact resume, the checkpoint must contain the Trainer state, not merely the final adapter weights.
457
+
458
+ ---
459
+
460
+ # 7. Export the Adapted Model
461
+
462
+ The adapter can optionally be merged into the base model.
463
+
464
+ ```python
465
+ merged_model = model.merge_and_unload()
466
+
467
+ merged_model.save_pretrained(
468
+ "./liber almind-spark-merged",
469
+ safe_serialization=True
470
+ )
471
+
472
+ tokenizer.save_pretrained(
473
+ "./liber almind-spark-merged"
474
+ )
475
+
476
+ print("Merged model exported.")
477
+ ```
478
+
479
+ The merged checkpoint contains the combined model weights rather than a separate LoRA adapter.
480
+
481
+ The resulting model is substantially larger than the adapter-only repository.
482
+
483
+ ---
484
+
485
+ # 8. Training and Reproducibility
486
+
487
+ For reproducibility, the following should be preserved:
488
+
489
+ - Original base-model identifier.
490
+ - `adapter_config.json`.
491
+ - LoRA adapter weights.
492
+ - Training dataset and preprocessing.
493
+ - Learning rate and batch configuration.
494
+ - Training framework versions.
495
+ - Training checkpoints, when exact optimizer-state recovery is required.
496
+
497
+ A LoRA checkpoint by itself does not contain the full base language model.
498
+
499
+ Anyone using this repository must have access to the corresponding original Spark-X2.6 checkpoint.
500
+
501
+ ---
502
+
503
+ # 9. Research Direction
504
+
505
+ LiberalMind explores lightweight model adaptation and efficient AI development.
506
+
507
+ This project represents an approach to extending existing language model capabilities without requiring a complete new pretraining run.
508
+
509
+ Potential future directions include:
510
+
511
+ - Further instruction tuning.
512
+ - Mathematical reasoning.
513
+ - Coding and software engineering.
514
+ - Tool-use and agent workflows.
515
+ - Model efficiency and deployment.
516
+ - Evaluation across different reasoning and problem-solving tasks.
517
+
518
+ No benchmark improvement is claimed without a corresponding evaluation.
519
+
520
+ ---
521
+
522
+ ## Credits
523
+
524
+ **Base architecture and pretrained weights:** XHToken / SparkLLM
525
+
526
+ **Adapter development:** LiberalMind
527
+
528
+ **Fine-tuning technology:** Hugging Face PEFT
529
+
530
+ **Inference framework:** Transformers
531
+
532
+ **License:** The base model is published under Apache 2.0. Verify the adapter's own licensing and attribution requirements before redistribution.
533
+
534
+ ---
535
+
536
+ **LiberalMind**
537
+
538
+ *Building intelligence beyond the screen.*
539
+
540
+ ### References
541
+
542
+ - [Spark-X2.6 Official Repository](https://github.com/XHToken/Spark-X2.6)
543
+ - [Spark-X2.6-4B on Hugging Face](https://huggingface.co/XHToken/Spark-X2.6-4B)
544
+ - [Hugging Face PEFT Documentation](https://huggingface.co/docs/peft)
545
+ - [Transformers PEFT Integration](https://huggingface.co/docs/transformers/peft)