Upload README.md with huggingface_hub

README.md

@@ -18,49 +18,41 @@ library_name: transformers
 👋 Join us on <a href="https://discord.gg/3cGQn9b3YM" target="_blank">Discord</a> and <a href="https://github.com/OpenBMB/MiniCPM/blob/main/assets/wechat.jpg" target="_blank">WeChat</a>
 </p>
 
-## Introduction
+## Overview
 
-BitCPM4-CANN-8B-unquantized is the **unquantized QAT training checkpoint** of the BitCPM4-CANN-8B model. This model stores the raw quantization-aware training (QAT) parameters **before** fake-quantizer fusion—the ternary fake quantizers are defined in `modeling.py` and applied during forward propagation.
+BitCPM4-CANN-1B-unquantized is the **unquantized QAT (Quantization-Aware Training) checkpoint** of BitCPM4-CANN-1B, designed for **continued pre-training and fine-tuning**. It preserves full-precision latent weights with ternary fake quantizers (weights → {-1, 0, 1} with group-wise scaling, trained via STE) defined in `modeling.py`, enabling the model to keep learning under quantization constraints. For technical details, see our [Technical Report](https://github.com/OpenBMB/MiniCPM/blob/main/docs/BitCPM_CANN.pdf).
 
-> ⚠️ **This model is NOT intended for direct inference.** It is designed as the starting point for fine-tuning BitCPM4-CANN. If you need a model for inference, please use the pseudo-quantized version: [openbmb/BitCPM4-CANN-8B](https://huggingface.co/openbmb/BitCPM4-CANN-8B).
+> ⚠️ **This model is NOT for direct inference.** For inference, use the pseudo-quantized version: [openbmb/BitCPM4-CANN-1B](https://huggingface.co/openbmb/BitCPM4-CANN-1B).
 
-### Key Characteristics
+## Continued Pre-training & Fine-tuning
 
-- 🎯 **Purpose**: Fine-tuning only. The model weights are un-fused QAT parameters with fake quantizers embedded in the `modeling.py` forward logic.
-- 🔬 **Ternary Fake Quantizer**: The forward pass in `modeling.py` contains ternary quantization logic (mapping weights to {-1, 0, 1} with group-wise scaling), which ensures the model continues learning under ternary constraints during fine-tuning.
-- 🔄 **Post-Training Conversion**: After fine-tuning, the model can be converted to pseudo-quantized format using the provided `qat-convert.py` script.
+The **only requirement** is that the forward pass must go through the bundled `modeling.py` (which contains the ternary fake quantizer). Load with `trust_remote_code=True` and do NOT replace or bypass the model's forward logic.
 
-## BitCPM4-CANN Model Family
+### Option 1: DeepSpeed (Recommended)
 
-| Model | HuggingFace (Inference) | HuggingFace (Fine-tuning) |
-|-------|-------------------------|---------------------------|
-| BitCPM4-CANN-0.5B | [openbmb/BitCPM4-CANN-0.5B](https://huggingface.co/openbmb/BitCPM4-CANN-0.5B) | [openbmb/BitCPM4-CANN-0.5B-unquantized](https://huggingface.co/openbmb/BitCPM4-CANN-0.5B-unquantized) |
-| BitCPM4-CANN-1B | [openbmb/BitCPM4-CANN-1B](https://huggingface.co/openbmb/BitCPM4-CANN-1B) | [openbmb/BitCPM4-CANN-1B-unquantized](https://huggingface.co/openbmb/BitCPM4-CANN-1B-unquantized) |
-| BitCPM4-CANN-3B | [openbmb/BitCPM4-CANN-3B](https://huggingface.co/openbmb/BitCPM4-CANN-3B) | [openbmb/BitCPM4-CANN-3B-unquantized](https://huggingface.co/openbmb/BitCPM4-CANN-3B-unquantized) |
-| BitCPM4-CANN-8B | [openbmb/BitCPM4-CANN-8B](https://huggingface.co/openbmb/BitCPM4-CANN-8B) | [openbmb/BitCPM4-CANN-8B-unquantized](https://huggingface.co/openbmb/BitCPM4-CANN-8B-unquantized) |
+We provide ready-to-use training scripts in the [example](https://huggingface.co/openbmb/BitCPM4-CANN-1B-unquantized/tree/main/example) directory (using the 1B model as an example):
 
-## Usage
+- **Continued pre-training**: `example/run.sh` + `example/train.py`
+- **SFT (Supervised Fine-tuning)**: `example/run_sft.sh` + `example/train_sft.py`
 
-### Fine-tuning
+Quick start:
 
-This model is designed for fine-tuning with frameworks that support custom modeling code. The critical requirement is that **the forward pass must go through the `modeling.py` file bundled with this model**, which contains the ternary fake quantizer logic. This ensures the model parameters remain compatible with ternary quantization constraints throughout fine-tuning.
-
-#### Supported Fine-tuning Frameworks
+```bash
+# Continued pre-training
+cd example && bash run.sh
 
-- **DeepSpeed** (recommended): See [example](https://huggingface.co/openbmb/BitCPM4-CANN-8B-unquantized/tree/main/example)
-- **LLaMA Factory**: Supports custom model loading with `trust_remote_code=True`
-- **Other Frameworks**: Any framework that supports HuggingFace-compatible model loading with custom modeling code
+# Supervised fine-tuning
+cd example && bash run_sft.sh
+```
 
-#### Important: Ensure Fake Quantizer is Active
+### Option 2: HuggingFace-compatible Frameworks
 
-When fine-tuning, you **must** ensure:
-1. Load the model with `trust_remote_code=True` so that the custom `modeling.py` (containing the ternary quantizer) is used.
-2. The forward pass during training goes through the ternary quantizer defined in `modeling.py`—do NOT replace or bypass the model's forward logic.
+Any framework that supports HuggingFace model loading with custom code can be used, such as **LLaMA Factory**, **HuggingFace Trainer**, etc. The key is to ensure `trust_remote_code=True`:
 
 ```python
 from transformers import AutoModelForCausalLM, AutoTokenizer
 
-path = 'openbmb/BitCPM4-CANN-8B-unquantized'
+path = 'openbmb/BitCPM4-CANN-1B-unquantized'
 tokenizer = AutoTokenizer.from_pretrained(path, trust_remote_code=True)
 model = AutoModelForCausalLM.from_pretrained(
     path,
@@ -68,13 +60,13 @@ model = AutoModelForCausalLM.from_pretrained(
     trust_remote_code=True
 )
 
-# Proceed with your fine-tuning pipeline (DeepSpeed, LLaMA Factory, etc.)
-# The ternary fake quantizer in modeling.py will be applied automatically during forward pass.
+# Use with your preferred framework (LLaMA Factory, HF Trainer, etc.)
+# The ternary fake quantizer in modeling.py is applied automatically during forward pass.
 ```
 
-### Post-Fine-tuning Conversion
+## Post-Training Conversion
 
-After fine-tuning is complete, use the `qat-convert.py` script to fuse the fake quantizer and produce the pseudo-quantized model weights that can be used for inference:
+After training, use `qat-convert.py` to fuse the fake quantizer and produce inference-ready pseudo-quantized weights:
 
 ```bash
 python qat-convert.py \
@@ -84,31 +76,34 @@ python qat-convert.py \
     --group_size -1
 ```
 
-The converted model can then be loaded for inference in the same way as [openbmb/BitCPM4-CANN-0.5B](https://huggingface.co/openbmb/BitCPM4-CANN-0.5B)—no special quantization libraries required.
+The converted model can be loaded for inference in the same way as [openbmb/BitCPM4-CANN-1B](https://huggingface.co/openbmb/BitCPM4-CANN-1B)—no special quantization libraries required.
 
-## Workflow Summary
+## Workflow
 
 ```
 ┌─────────────────────────────────┐
-│  BitCPM4-CANN-8B-unquantized  │   ← This model (QAT parameters + fake quantizer in modeling.py)
+│  BitCPM4-CANN-1B-unquantized  │   ← This model (QAT checkpoint + fake quantizer in modeling.py)
 └───────────────┬─────────────────┘
                 │
-                ▼  Fine-tune (DeepSpeed / LLaMA Factory / ...)
+                ▼  Train (DeepSpeed / LLaMA Factory / HF Trainer / ...)
 ┌─────────────────────────────────┐
-│   Fine-tuned pytorch.bin         │   ← Still contains un-fused QAT parameters
+│   Fine-tuned checkpoint          │   ← Still contains un-fused QAT parameters
 └───────────────┬─────────────────┘
                 │
                 ▼  python qat-convert.py --quant_type ternary --group_size -1
 ┌─────────────────────────────────┐
-│  Pseudo-quantized pytorch.bin    │   ← Ready for inference (same format as BitCPM4-CANN-0.5B)
+│  Pseudo-quantized model          │   ← Ready for inference (same format as BitCPM4-CANN-1B)
 └─────────────────────────────────┘
 ```
 
-## Technical Background
-
-BitCPM4-CANN uses a ternary quantizer that maps each weight group to {-1, 0, 1} scaled by a group-wise factor, trained with Straight-Through Estimator (STE) for gradient flow. The unquantized checkpoint preserves the full-precision latent weights alongside the quantizer parameters, allowing the model to continue learning under quantization constraints during fine-tuning.
+## BitCPM4-CANN Model Family
 
-For full technical details, please refer to our [Technical Report](https://github.com/OpenBMB/MiniCPM/blob/main/docs/BitCPM_CANN.pdf).
+| Model | HuggingFace (Inference) | HuggingFace (Fine-tuning) |
+|-------|-------------------------|---------------------------|
+| BitCPM4-CANN-0.5B | [openbmb/BitCPM4-CANN-0.5B](https://huggingface.co/openbmb/BitCPM4-CANN-0.5B) | [openbmb/BitCPM4-CANN-0.5B-unquantized](https://huggingface.co/openbmb/BitCPM4-CANN-0.5B-unquantized) |
+| BitCPM4-CANN-1B | [openbmb/BitCPM4-CANN-1B](https://huggingface.co/openbmb/BitCPM4-CANN-1B) | [openbmb/BitCPM4-CANN-1B-unquantized](https://huggingface.co/openbmb/BitCPM4-CANN-1B-unquantized) |
+| BitCPM4-CANN-3B | [openbmb/BitCPM4-CANN-3B](https://huggingface.co/openbmb/BitCPM4-CANN-3B) | [openbmb/BitCPM4-CANN-3B-unquantized](https://huggingface.co/openbmb/BitCPM4-CANN-3B-unquantized) |
+| BitCPM4-CANN-8B | [openbmb/BitCPM4-CANN-8B](https://huggingface.co/openbmb/BitCPM4-CANN-8B) | [openbmb/BitCPM4-CANN-8B-unquantized](https://huggingface.co/openbmb/BitCPM4-CANN-8B-unquantized) |
 
 ## Statement
 - As a language model, BitCPM4-CANN generates content by learning from a vast amount of text.