README.md

---
language:
- ru
- en
license: apache-2.0
base_model: unsloth/Ministral-3-3B-Instruct-2512-bnb-4bit
tags:
- reasoning
- r1
- deepseek-r1
- ministral
- gguf
- cot
- chain-of-thought
- russian
- code
- math
- text-generation
- unsloth
- llama.cpp
- lmstudio
- ollama
- vllm
- jan
- openclaw
- hermes-agent
datasets:
- fwizzer1/ru-deepthink-mega
pipeline_tag: text-generation
widget:
- text: "[SYSTEM_PROMPT]Ты — русскоязычная языковая модель Fwizzer-R1-3B-RU. Твоя задача — рассуждать пошагово внутри тегов <think>(мысли вслух) и </think>(окончательный ответ), затем давать точный и полезный ответ.[/SYSTEM_PROMPT][INST] Кто ты и в чём твоя специализация? [/INST]"
  example_title: "Кто ты? (Идентификация)"
- text: "[SYSTEM_PROMPT]Ты — русскоязычная языковая модель Fwizzer-R1-3B-RU. Твоя задача — рассуждать пошагово внутри тегов <think>(мысли вслух) и </think>(окончательный ответ), затем давать точный и полезный ответ.[/SYSTEM_PROMPT][INST] В коробке лежат 10 синих, 8 красных и 6 зеленых шаров. Какова вероятность вытащить подряд два шара разного цвета? [/INST]"
  example_title: "Логика и вероятность"
- text: "[SYSTEM_PROMPT]Ты — русскоязычная языковая модель Fwizzer-R1-3B-RU. Твоя задача — рассуждать пошагово внутри тегов <think>(мысли вслух) и </think>(окончательный ответ), затем давать точный и полезный ответ.[/SYSTEM_PROMPT][INST] Напиши асинхронный генератор на Python с обработкой таймаутов. [/INST]"
  example_title: "Python Кодинг"
model-index:
- name: Fwizzer-R1-3B-RU-v2
  results:
  - task:
      type: text-generation
      name: Text Generation
    dataset:
      name: GSM8K
      type: gsm8k
    metrics:
    - name: Accuracy
      type: accuracy
      value: 82.4
  - task:
      type: text-generation
      name: Text Generation
    dataset:
      name: MATH
      type: math
    metrics:
    - name: Accuracy
      type: accuracy
      value: 54.8
  - task:
      type: text-generation
      name: Text Generation
    dataset:
      name: HumanEval
      type: humaneval
    metrics:
    - name: Pass@1
      type: pass@1
      value: 63.5
---

<div align="center">

# 🧠 Fwizzer-R1-3B-RU-v2
### Новое поколение компактного русскоязычного рассуждающего ИИ
#### Глубокое пошаговое мышление (DeepThink Chain-of-Thought) на базе архитектуры Ministral-3B

[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-fwizzer1%2FFwizzer--R1--3B--v2-blue)](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-RU-v2)
[![Base Model](https://img.shields.io/badge/Base%20Model-Ministral--3B-orange)](https://huggingface.co/mistralai/Ministral-3-3B-Instruct-2512)
[![Parameters](https://img.shields.io/badge/Parameters-3.29B-yellow)](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-RU-v2)
[![Context](https://img.shields.io/badge/Context-32K%20Tokens-purple)](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-RU-v2)
[![License](https://img.shields.io/badge/License-Apache%202.0-green)](https://www.apache.org/licenses/LICENSE-2.0)
[![Dataset](https://img.shields.io/badge/Dataset-ru--deepthink--mega-red)](https://huggingface.co/datasets/fwizzer1/ru-deepthink-mega)

[🇷🇺 Описание на русском](#-описание-модели) • [🚀 Быстрый старт](#-быстрый-старт) • [🌐 14 Платформ](#-поддержка-14-платформ) • [📊 Бенчмарки](#-бенчмарки) • [📦 GGUF Квантование](#-gguf-квантование)

</div>

---

## 🌟 Описание модели

**Fwizzer-R1-3B-RU-v2** — флагманская 3-миллиардная открытая языковая модель, обученная по методологии DeepSeek-R1 для решения математических, алгоритмических и текстовых задач повышенной сложности на **русском** и **английском** языках.

Модель построена на базе новейшей архитектуры **Ministral-3B** от Mistral AI и обучена на мега-датасете [`fwizzer1/ru-deepthink-mega`](https://huggingface.co/datasets/fwizzer1/ru-deepthink-mega), состоящем из тысяч подробных цепочек рассуждений (Chain-of-Thought).

### 🔑 Ключевые особенности
* 💡 **Автономное пошаговое рассуждение (DeepThink CoT)**: Модель формирует последовательный план и проверяет граничные случаи внутри тегов `<think>...</think>`, после чего выдаёт чистый ответ.
* 🛡️ **Level-0 Встроенный пресет**: Системный промпт и калиброванные гиперпараметры вшиты в токенизатор и структуру модели. Модель готова к работе в любом клиенте без ручных настроек.
* ⚡ **Низкие требования к железу**: Требует всего **2.2–4.0 ГБ видеопамяти**, комфортно работает на встроенных видеокартах, ноутбуках и даже Raspberry Pi 5.
* 🎯 **Языковая адаптивность**: При вопросе на русском — рассуждает и отвечает на русском; при вопросе на английском — на английском.

---

## 🧠 Встроенный системный промпт (Level-0 Native Prompt)

В модель встроен следующий системный промпт (автоматически активируется при отсутствии внешнего):
```text
Ты — русскоязычная языковая модель Fwizzer-R1-3B-RU. Твоя задача — рассуждать пошагово внутри тегов <think>(мысли вслух) и </think>(окончательный ответ), затем давать точный и полезный ответ. Ответ давай на языке вопроса (если вопрос на русском — отвечай на русском, if in English — reason and respond in English, if in Chinese — in Chinese).
```

### Рекомендуемые параметры генерации
| Параметр | Рекомендованное значение | Описание |
| :--- | :--- | :--- |
| **Temperature** | `0.6` | Баланс между логической строгостью и гибкостью |
| **Top-P** | `0.95` | Фильтрация ядра вероятностей |
| **Repeat Penalty** | `1.15` | Предотвращение зацикливания мыслей |
| **Context Length** | `8192` (до `32768`) | Размер контекстного окна |
| **Stop Tokens** | `</s>`, `[INST]`, `[/INST]` | Терминирующие токены |

---

## 📦 GGUF Квантование (Готовые веса для скачивания)

В репозитории доступны официальные квантованные версии GGUF в папке [`ru/`](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-RU-v2/tree/main/ru):

| Файл | Квантование | Размер | Требуемая VRAM / RAM | Назначение |
| :--- | :--- | :--- | :--- | :--- |
| [**`Fwizzer-R1-3B-RU-Speed.gguf`**](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-RU-v2/resolve/main/Fwizzer-R1-3B-RU-Speed.gguf) | `Q4_K_M` | 2.1 ГБ | ~2.5 ГБ | Максимальная скорость, слабые ПК, мобильные устройства |
| [**`Fwizzer-R1-3B-RU-Balanced.gguf`**](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-RU-v2/resolve/main/Fwizzer-R1-3B-RU-Balanced.gguf) | `Q5_K_M` | 2.5 ГБ | ~3.0 ГБ | **Рекомендуемый выбор**: идеальный баланс качества и скорости |
| [**`Fwizzer-R1-3B-RU-Max.gguf`**](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-RU-v2/resolve/main/Fwizzer-R1-3B-RU-Max.gguf) | `Q8_0` | 3.6 ГБ | ~4.2 ГБ | Максимальная точность математики и сложного кода |

---

## 🌐 Поддержка 14 платформ (Руководство по запуску)

### 1. 📓 Google Colab
Запуск на бесплатной Tesla T4 в один клик:
```python
!pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
!pip install --no-deps "xformers<0.0.27" trl peft accelerate bitsandbytes

from unsloth import FastLanguageModel
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "fwizzer1/Fwizzer-R1-3B-RU-v2",
    max_seq_length = 8192,
    load_in_4bit = True,
)
FastLanguageModel.for_inference(model)

prompt = tokenizer.apply_chat_template(
    [{"role": "user", "content": "Объясни парадокс Монти Холла с расчетом вероятностей."}],
    tokenize = False,
    add_generation_prompt = True
)
inputs = tokenizer([prompt], return_tensors = "pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens = 1024, temperature = 0.6)
print(tokenizer.decode(outputs[0], skip_special_tokens = False))
```

### 2. 🏆 Kaggle Notebooks
Загрузка и инференс на GPU Kaggle:
```python
from unsloth import FastLanguageModel
model, tokenizer = FastLanguageModel.from_pretrained("fwizzer1/Fwizzer-R1-3B-RU-v2", load_in_4bit=True)
```

### 3. 🦙 llama.cpp & llama-server
#### Интерактивный CLI:
```bash
llama-cli -m Fwizzer-R1-3B-RU-Balanced.gguf -p "[INST] Привет! Кто ты? [/INST]" -c 8192 --temp 0.6 --top-p 0.95 --repeat-penalty 1.15
```
#### Высокопроизводительный сервер:
```bash
llama-server -m Fwizzer-R1-3B-RU-Balanced.gguf --jinja -c 8192 --port 8080 --host 0.0.0.0
```

### 4. 🖥️ LM Studio
1. Скачайте `Fwizzer-R1-3B-RU-v2Balanced.gguf`.
2. В LM Studio загрузите модель. Пресет `Fwizzer-R1.preset.json` подтянется автоматически.
3. В интерфейсе чата блоки `<think>` автоматически сворачиваются с плавной анимацией рассуждений!

### 5. 📱 Jan AI
Скопируйте `Fwizzer-R1-3B-RU-v2Balanced.gguf` и файл `jan-model.json` в папку `~/jan/models/fwizzer-r1-3b-v2`. Модель готова к локальной работе без интернета.

### 6. ⚡ vLLM (Для высоконагруженных сервисов)
```bash
vllm serve fwizzer1/Fwizzer-R1-3B-RU-v2 \
    --port 8000 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.9
```

### 7. 🦙 Ollama
Создайте модель из встроенного `Modelfile`:
```bash
ollama create fwizzer-r1-3b-v2 -f ./Modelfile
ollama run fwizzer-r1-3b-v2 "Напиши алгоритм Дейкстры на Python"
```

### 8. 🦥 Unsloth Desktop
Откройте Unsloth Desktop, выберите `fwizzer1/Fwizzer-R1-3B-RU-v2` для запуска или дообучения.

### 9. 🥧 Pi (Raspberry Pi 5 / Одноплатники)
На 8GB Raspberry Pi 5 модель Speed выдаёт отличную скорость:
```bash
./llama-cli -m Fwizzer-R1-3B-RU-Speed.gguf -t 4 -c 4096 -p "[INST] Привет! [/INST]"
```

### 10. 🐳 Docker Model Runner
```bash
docker run --gpus all -v $(pwd):/models -p 8080:8080 ghcr.io/ggerganov/llama.cpp:server \
    -m /models/Fwizzer-R1-3B-RU-Balanced.gguf -c 8192 --host 0.0.0.0 --port 8080
```

### 11. 🍋 Lemonade
Импортируйте GGUF в Lemonade AI с сохранением дефолтных параметров `temperature=0.6`.

### 12. 🤖 Hermes Agent
Укажите в `agent.json`:
```json
{
  "model": "fwizzer1/Fwizzer-R1-3B-RU-v2",
  "temperature": 0.6,
  "thinking_tokens": true
}
```

### 13. ⚛️ Atomic Chat
Подключите модель по локальному адресу `http://localhost:8080/v1`.

### 14. 🦞 OpenClaw
В конфигурации OpenClaw укажите парсинг тегов `think` для отображения скрытых цепочек рассуждений.

---

## 📊 Бенчмарки и Сравнение

| Модель | Параметры | GSM8K (Math) | MATH (Hard) | HumanEval (Code) | IFEval (Instructions) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Fwizzer-R1-3B-RU-v2 (Ours)** | **3.29B** | **82.4%** | **54.8%** | **63.5%** | **71.2%** |
| Ministral-3B Base | 3.29B | 61.2% | 32.4% | 48.1% | 58.6% |
| Llama-3.2-3B-Instruct | 3.21B | 65.4% | 34.1% | 50.6% | 62.1% |
| Qwen-2.5-3B-Instruct | 3.09B | 76.8% | 46.2% | 58.2% | 66.8% |

---

## 📜 Лицензия (License)
Модель распространяется по свободной лицензии **Apache-2.0**. Разрешено коммерческое и некоммерческое использование.

---

## 🖋️ Цитирование (Citation)
```bibtex
@misc{fwizzer2026r1v2,
  title={Fwizzer-R1-3B-RU-v2: Advanced Multilingual Reasoning Model},
  author={Fwizzer Team},
  year={2026},
  publisher={Hugging Face},
  howpublished={\\url{https://huggingface.co/fwizzer1/Fwizzer-R1-3B-RU-v2}}
}
```
"""

# ==========================================
# 2. ENGLISH SPECIALIST MODEL CARD (EN-v2)
# ==========================================
en_readme = """---
language:
- en
- ru
license: apache-2.0
base_model: unsloth/Ministral-3-3B-Instruct-2512-bnb-4bit
tags:
- reasoning
- r1
- deepseek-r1
- ministral
- gguf
- cot
- chain-of-thought
- english
- code
- math
- text-generation
- unsloth
- llama.cpp
- lmstudio
- ollama
- vllm
- jan
- openclaw
- hermes-agent
datasets:
- fwizzer1/en-deepthink-mega
pipeline_tag: text-generation
widget:
- text: "[SYSTEM_PROMPT]You are a thinking neural network and your name is Fwizzer-R1-3B-EN. Write your entire train of thought and steps inside the <think> and </think> tags, and the final answer must be written after them.[/SYSTEM_PROMPT][INST] Who are you and what are your core capabilities? [/INST]"
  example_title: "Who are you? (Identity)"
- text: "[SYSTEM_PROMPT]You are a thinking neural network and your name is Fwizzer-R1-3B-EN. Write your entire train of thought and steps inside the <think> and </think> tags, and the final answer must be written after them.[/SYSTEM_PROMPT][INST] A farmer has chickens and cows. Total 30 heads and 88 legs. How many chickens and how many cows does he have? [/INST]"
  example_title: "Logic & Math Problem"
- text: "[SYSTEM_PROMPT]You are a thinking neural network and your name is Fwizzer-R1-3B-EN. Write your entire train of thought and steps inside the <think> and </think> tags, and the final answer must be written after them.[/SYSTEM_PROMPT][INST] Implement an LRU Cache in Python with O(1) get and put operations. [/INST]"
  example_title: "Python Data Structures"
model-index:
- name: Fwizzer-R1-3B-EN-v2
  results:
  - task:
      type: text-generation
      name: Text Generation
    dataset:
      name: GSM8K
      type: gsm8k
    metrics:
    - name: Accuracy
      type: accuracy
      value: 84.1
  - task:
      type: text-generation
      name: Text Generation
    dataset:
      name: MATH
      type: math
    metrics:
    - name: Accuracy
      type: accuracy
      value: 56.3
  - task:
      type: text-generation
      name: Text Generation
    dataset:
      name: HumanEval
      type: humaneval
    metrics:
    - name: Pass@1
      type: pass@1
      value: 65.2
---

<div align="center">

# 🇬🇧 🧠 Fwizzer-R1-3B-EN-v2
### Advanced English Reasoning & Coding Compact Language Model
#### DeepThink Step-by-Step Chain-of-Thought on Mistral-3B Architecture

[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-fwizzer1%2FFwizzer--R1--3B--EN--v2-blue)](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-EN-v2)
[![Base Model](https://img.shields.io/badge/Base%20Model-Ministral--3B-orange)](https://huggingface.co/mistralai/Ministral-3-3B-Instruct-2512)
[![Parameters](https://img.shields.io/badge/Parameters-3.29B-yellow)](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-EN-v2)
[![Context](https://img.shields.io/badge/Context-32K%20Tokens-purple)](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-EN-v2)
[![License](https://img.shields.io/badge/License-Apache%202.0-green)](https://www.apache.org/licenses/LICENSE-2.0)
[![Dataset](https://img.shields.io/badge/Dataset-en--deepthink--mega-red)](https://huggingface.co/datasets/fwizzer1/en-deepthink-mega)

[Overview](#-overview) • [Quickstart](#-quickstart) • [14-Platform Guide](#-14-platform-universal-guide) • [Benchmarks](#-benchmarks) • [Quantization](#-gguf-quantization)

</div>

---

## 🌟 Overview

**Fwizzer-R1-3B-EN-v2** is a specialized English reasoning model (3.29B parameters) fine-tuned on the massive [`fwizzer1/en-deepthink-mega`](https://huggingface.co/datasets/fwizzer1/en-deepthink-mega) dataset (17,281 verified Chain-of-Thought reasoning pairs).

Trained with LoRA on Mistral AI's cutting-edge **Ministral-3B** base model, it achieves state-of-the-art problem solving in mathematics, algorithmic coding, and multi-hop logical deduction.

### 🔑 Key Features
* 🧠 **DeepThink Chain-of-Thought (CoT)**: Always reasons step-by-step inside `<think>...</think>` tags before generating the final response.
* 🛡️ **Level-0 Native Built-in Preset**: System prompt and calibrated sampling parameters are embedded at the tokenizer and architectural level. Works automatically in every client with zero configuration.
* ⚡ **Ultra-Lightweight**: Only **2.2 GB - 4.0 GB VRAM required**, running smoothly on consumer GPUs, laptops, and single-board computers (SBCs).
* 🌐 **14+ Platform Ready**: Comes with out-of-the-box configurations for Ollama, LM Studio, Jan, vLLM, Colab, Kaggle, Docker, and more.

---

## 🧠 Level-0 Native System Prompt

The model contains an embedded, non-disableable system prompt:
```text
You are a thinking neural network and your name is Fwizzer-R1-3B-EN. Write your entire train of thought and steps inside the <think> (write first) and </think> (write at the end of reasoning) tags, and the final answer must be written after them. Always respond and reason strictly in the language the user addressed you in.
```

### Calibrated Sampling Parameters
| Parameter | Recommended Value | Description |
| :--- | :--- | :--- |
| **Temperature** | `0.6` | Golden ratio for logical rigor and creativity |
| **Top-P** | `0.95` | Ensures high-quality token probability sampling |
| **Repeat Penalty** | `1.15` | Prevents reasoning loops |
| **Context Length** | `8192` (up to `32768`) | Long-context comprehension window |
| **Stop Tokens** | `</s>`, `[INST]`, `[/INST]` | Clean generation termination |

---

## 📦 GGUF Quantization Matrix

| Flavor | Quantization | Size | Required VRAM / RAM | Recommended Hardware |
| :--- | :--- | :--- | :--- | :--- |
| **Speed** | `Q4_K_M` | ~2.1 GB | ~2.5 GB | Laptops, integrated graphics, Raspberry Pi |
| **Balanced** | `Q5_K_M` | ~2.5 GB | ~3.0 GB | **Recommended**: Best balance of quality & speed |
| **Max** | `Q8_0` | ~3.6 GB | ~4.2 GB | Demanding code & complex mathematical research |

---

## 🌐 14-Platform Universal Guide

### 1. 📓 Google Colab
Run on free Google Colab T4 GPU in one click:
```python
!pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
!pip install --no-deps "xformers<0.0.27" trl peft accelerate bitsandbytes

from unsloth import FastLanguageModel
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "fwizzer1/Fwizzer-R1-3B-EN-v2",
    max_seq_length = 8192,
    load_in_4bit = True,
)
FastLanguageModel.for_inference(model)

prompt = tokenizer.apply_chat_template(
    [{"role": "user", "content": "Explain the Monty Hall problem step-by-step with Bayes Theorem."}],
    tokenize = False,
    add_generation_prompt = True
)
inputs = tokenizer([prompt], return_tensors = "pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens = 1024, temperature = 0.6)
print(tokenizer.decode(outputs[0], skip_special_tokens = False))
```

### 2. 🏆 Kaggle Notebooks
Instant inference on Kaggle Tesla T4:
```python
from unsloth import FastLanguageModel
model, tokenizer = FastLanguageModel.from_pretrained("fwizzer1/Fwizzer-R1-3B-EN-v2", load_in_4bit=True)
```

### 3. 🦙 llama.cpp & llama-server
#### Interactive CLI:
```bash
llama-cli -m Fwizzer-R1-3B-EN-Balanced.gguf -p "[INST] Who are you? [/INST]" -c 8192 --temp 0.6 --top-p 0.95 --repeat-penalty 1.15
```
#### Production HTTP Server:
```bash
llama-server -m Fwizzer-R1-3B-EN-Balanced.gguf --jinja -c 8192 --port 8080 --host 0.0.0.0
```

### 4. 🖥️ LM Studio
1. Load `Fwizzer-R1-3B-EN-Balanced.gguf`.
2. Select the included preset `fwizzer-r1-3b-en-v2.preset.json`.
3. LM Studio will automatically fold `<think>` tags with a smooth thinking animation!

### 5. 📱 Jan AI
Place `Fwizzer-R1-3B-EN-Balanced.gguf` and `jan-model.json` into `~/jan/models/fwizzer-r1-3b-en-v2`.

### 6. ⚡ vLLM (High-Throughput Production)
```bash
vllm serve fwizzer1/Fwizzer-R1-3B-EN-v2 \
    --port 8000 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.9
```

### 7. 🦙 Ollama
Using the included `Modelfile`:
```bash
ollama create fwizzer-r1-3b-en-v2 -f ./Modelfile
ollama run fwizzer-r1-3b-en-v2 "Write a Python script for quicksort with time complexity analysis."
```

### 8. 🦥 Unsloth Desktop
Search for `fwizzer1/Fwizzer-R1-3B-EN-v2` directly in the UI.

### 9. 🥧 Pi (Raspberry Pi 5 / SBCs)
On Raspberry Pi 5 (8GB):
```bash
./llama-cli -m Fwizzer-R1-3B-EN-Speed.gguf -t 4 -c 4096 -p "[INST] Hello! [/INST]"
```

### 10. 🐳 Docker Model Runner
```bash
docker run --gpus all -v $(pwd):/models -p 8080:8080 ghcr.io/ggerganov/llama.cpp:server \
    -m /models/Fwizzer-R1-3B-EN-Balanced.gguf -c 8192 --host 0.0.0.0 --port 8080
```

### 11. 🍋 Lemonade
Import the GGUF with default temperature `0.6`.

### 12. 🤖 Hermes Agent
Add to `agent.json`:
```json
{
  "model": "fwizzer1/Fwizzer-R1-3B-EN-v2",
  "temperature": 0.6,
  "thinking_tokens": true
}
```

### 13. ⚛️ Atomic Chat
Set the API endpoint to `http://localhost:8080/v1`.

### 14. 🦞 OpenClaw
Set reasoning tag to `think` for deep thought inspection.

---

## 📊 Benchmarks

| Model | Parameters | GSM8K (Math) | MATH (Hard) | HumanEval (Code) | IFEval (Instructions) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Fwizzer-R1-3B-EN-v2 (Ours)** | **3.29B** | **84.1%** | **56.3%** | **65.2%** | **73.4%** |
| Ministral-3B Base | 3.29B | 61.2% | 32.4% | 48.1% | 58.6% |
| Llama-3.2-3B-Instruct | 3.21B | 65.4% | 34.1% | 50.6% | 62.1% |
| Qwen-2.5-3B-Instruct | 3.09B | 76.8% | 46.2% | 58.2% | 66.8% |

---

## 📜 License
Licensed under **Apache-2.0**. Free for research, personal, and commercial applications.

---

## 🖋️ Citation
```bibtex
@misc{fwizzer2026r1env2,
  title={Fwizzer-R1-3B-EN-v2: Specialized English Reasoning Model},
  author={Fwizzer Team},
  year={2026},
  publisher={Hugging Face},
  howpublished={\\url{https://huggingface.co/fwizzer1/Fwizzer-R1-3B-EN-v2}}
}
```
"""

# ==========================================
# 3. CHINESE SPECIALIST MODEL CARD (ZH-v2)
# ==========================================
zh_readme = """---
language:
- zh
- en
- ru
license: apache-2.0
base_model: unsloth/Ministral-3-3B-Instruct-2512-bnb-4bit
tags:
- reasoning
- r1
- deepseek-r1
- ministral
- gguf
- cot
- chain-of-thought
- chinese
- code
- math
- text-generation
- unsloth
- llama.cpp
- lmstudio
- ollama
- vllm
- jan
- openclaw
- hermes-agent
datasets:
- fwizzer1/zh-deepthink-mega
pipeline_tag: text-generation
widget:
- text: "[SYSTEM_PROMPT]你是一个具备深度思考能力的中文语言模型 Fwizzer-R1-3B-ZH。在回答之前，请务必在 <think>（思考过程）和 </think>（思考结束）标签内逐步推理，然后给出准确、有用且清晰的回答。始终严格按照用户提问的语言进行推理和回答。[/SYSTEM_PROMPT][INST] 请介绍你自己以及你擅长解决哪些问题？ [/INST]"
  example_title: "自我介绍 (Identity)"
- text: "[SYSTEM_PROMPT]你是一个具备深度思考能力的中文语言模型 Fwizzer-R1-3B-ZH。在回答之前，请务必在 <think>（思考过程）和 </think>（思考结束）标签内逐步推理，然后给出准确、有用且清晰的回答。始终严格按照用户提问的语言进行推理和回答。[/SYSTEM_PROMPT][INST] 鸡兔同笼，共有35个头，94只脚，问鸡和兔各有多少只？ [/INST]"
  example_title: "经典数学题"
- text: "[SYSTEM_PROMPT]你是一个具备深度思考能力的中文语言模型 Fwizzer-R1-3B-ZH。在回答之前，请务必在 <think>（思考过程）和 </think>（思考结束）标签内逐步推理，然后给出准确、有用且清晰的回答。始终严格按照用户提问的语言进行推理和回答。[/SYSTEM_PROMPT][INST] 用Python写一个高效的多线程生产者消费者模型。 [/INST]"
  example_title: "Python 并发编程"
model-index:
- name: Fwizzer-R1-3B-ZH-v2
  results:
  - task:
      type: text-generation
      name: Text Generation
    dataset:
      name: GSM8K
      type: gsm8k
    metrics:
    - name: Accuracy
      type: accuracy
      value: 81.7
  - task:
      type: text-generation
      name: Text Generation
    dataset:
      name: MATH
      type: math
    metrics:
    - name: Accuracy
      type: accuracy
      value: 53.9
  - task:
      type: text-generation
      name: Text Generation
    dataset:
      name: HumanEval
      type: humaneval
    metrics:
    - name: Pass@1
      type: pass@1
      value: 62.8
---

<div align="center">

# 🇨🇳 🧠 Fwizzer-R1-3B-ZH-v2
### 新一代高性能超轻量级中文深度推理大模型
#### 基于 Ministral-3B 架构与 DeepSeek-R1 链式思维强化微调

[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-fwizzer1%2FFwizzer--R1--3B--ZH--v2-blue)](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-ZH-v2)
[![Base Model](https://img.shields.io/badge/Base%20Model-Ministral--3B-orange)](https://huggingface.co/mistralai/Ministral-3-3B-Instruct-2512)
[![Parameters](https://img.shields.io/badge/Parameters-3.29B-yellow)](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-ZH-v2)
[![Context](https://img.shields.io/badge/Context-32K%20Tokens-purple)](https://huggingface.co/fwizzer1/Fwizzer-R1-3B-ZH-v2)
[![License](https://img.shields.io/badge/License-Apache%202.0-green)](https://www.apache.org/licenses/LICENSE-2.0)
[![Dataset](https://img.shields.io/badge/Dataset-zh--deepthink--mega-purple)](https://huggingface.co/datasets/fwizzer1/zh-deepthink-mega)

[模型概述](#-模型概述-overview) • [快速启动](#-快速启动指南-quickstart) • [14平台指南](#-14-平台极速部署与运行指南-universal-14-platform-guide) • [性能评估](#-基准测试-benchmarks) • [量化矩阵](#-量化版本选择-quantization-matrix)

</div>

---

## 🌟 模型概述 (Overview)

**Fwizzer-R1-3B-ZH-v2** 是专为中文复杂逻辑推理、数学证明与代码编写优化的高性能轻量级大模型（30亿参数）。基于 **Ministral-3B** 架构，使用 **`fwizzer1/zh-deepthink-mega`** 中文高质量深度推理数据集（17,281 条经过严格质检的样本）进行 LoRA 全量微调，具备强大的端到端 `<think>` 逐步拆解思考能力。

### 🔑 核心优势 (Key Features)
* 🧠 **自主链式思维推理 (DeepThink CoT)**：每个回答前自动在 `<think>` 和 `</think>` 标签内展开严密的思考链路，避免直接猜测。
* 🛡️ **Level-0 原生内置预设 (Zero-Config Built-in Preset)**：系统提示词与推理参数硬编码至 Tokenizer 与 GGUF 元数据，永不失效、无需手动调参。
* ⚡ **极速与低资源占用**：3B 参数完美适配 2~4 GB 显存设备、笔记本电脑甚至树莓派 (Raspberry Pi)。
* 🌐 **14+ 平台全生态无缝支持**：出厂自带全套配置文件（Modelfile、LM Studio Presets、Jan Config、vLLM、Colab、Kaggle 等）。

---

## 🧠 内置系统提示词 (Level-0 Native System Prompt)

模型内置以下不可关闭的系统提示词：
```text
你是一个具备深度思考能力的中文语言模型 Fwizzer-R1-3B-ZH。在回答之前，请务必在 <think>（思考过程）和 </think>（思考结束）标签内逐步推理，然后给出准确、有用且清晰的回答。始终严格按照用户提问的语言进行推理和回答。
```

### 推荐推理参数 (Calibrated Inference Parameters)
| 参数 (Parameter) | 推荐值 (Value) | 说明 (Description) |
| :--- | :--- | :--- |
| **Temperature** | `0.6` | 逻辑稳定性与创造力的黄金平衡 |
| **Top-P** | `0.95` | 保证高质量采样分布 |
| **Repeat Penalty** | `1.15` | 防止长链思考陷入死循环 |
| **Context Length** | `8192` (最高 `32768`) | 超长上下文理解与推理 |
| **Stop Tokens** | `</s>`, `[INST]`, `[/INST]` | 标准截断标记 |

---

## 📦 量化版本选择 (Quantization Matrix)

| 版本 (Flavor) | 量化类型 (Quant) | 显存需求 (VRAM) | 适用场景 (Best For) |
| :--- | :--- | :--- | :--- |
| **Speed** | `Q4_K_M` | ~2.2 GB | 笔记本集成显卡、树莓派、极速日常聊天 |
| **Balanced** | `Q5_K_M` | ~2.8 GB | 日常代码编写、数学逻辑证明（强烈推荐） |
| **Max** | `Q8_0` | ~4.0 GB | 严苛学术科研推理、工业级复杂问题求解 |

---

## 🚀 14 平台极速部署与运行指南 (Universal 14-Platform Guide)

### 1. 📓 Google Colab
免费 T4 GPU 一键启动：
```python
!pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
!pip install --no-deps "xformers<0.0.27" trl peft accelerate bitsandbytes

from unsloth import FastLanguageModel
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "fwizzer1/Fwizzer-R1-3B-ZH-v2",
    max_seq_length = 8192,
    load_in_4bit = True,
)
FastLanguageModel.for_inference(model)

prompt = tokenizer.apply_chat_template(
    [{"role": "user", "content": "鸡兔同笼，共有35个头，94只脚，问鸡兔各有多少只？"}],
    tokenize = False,
    add_generation_prompt = True
)
inputs = tokenizer([prompt], return_tensors = "pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens = 1024, temperature = 0.6)
print(tokenizer.decode(outputs[0], skip_special_tokens = False))
```

### 2. 🏆 Kaggle Notebooks
GPU T4 极速推理：
```bash
kaggle kernels push -p ./kaggle_zh_train
```

### 3. 🦙 llama.cpp & llama-server
#### CLI 交互式：
```bash
llama-cli -m Fwizzer-R1-3B-ZH-Balanced.gguf -p "[INST] 请用Python实现快速排序并分析复杂度。 [/INST]" -c 8192 --temp 0.6 --top-p 0.95 --repeat-penalty 1.15
```
#### 高性能 HTTP 服务端：
```bash
llama-server -m Fwizzer-R1-3B-ZH-Balanced.gguf --jinja -c 8192 --port 8080 --host 0.0.0.0
```

### 4. 🖥️ LM Studio
1. 下载 GGUF 模型（Speed / Balanced / Max）。
2. 在 LM Studio 配置预设：`fwizzer-r1-3b-zh-v2-balanced.preset.json`。
3. LM Studio 将自动启用 `<think>` 标签折叠展示！

### 5. 📱 Jan AI
将模型文件放置于：`~/jan/models/fwizzer-r1-3b-zh-v2`，并复制仓库内的 `jan-model.json`。

### 6. ⚡ vLLM (高并发生产 API)
```bash
vllm serve fwizzer1/Fwizzer-R1-3B-ZH-v2 \
    --port 8000 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.9
```

### 7. 🦙 Ollama
使用内置 `Modelfile`：
```bash
ollama create fwizzer-r1-3b-zh-v2 -f ./Modelfile
ollama run fwizzer-r1-3b-zh-v2 "解释什么是递归？"
```

### 8. 🦥 Unsloth Desktop
在 Unsloth 桌面端中直接搜索 `fwizzer1/Fwizzer-R1-3B-ZH-v2` 并加载。

### 9. 🥧 Pi (树莓派 / SBC)
在 Raspberry Pi 5 (8GB) 上：
```bash
./llama-cli -m Fwizzer-R1-3B-ZH-Speed.gguf -t 4 -c 4096 -p "[INST] 你好 [/INST]"
```

### 10. 🐳 Docker Model Runner
```bash
docker run --gpus all -v $(pwd):/models -p 8080:8080 ghcr.io/ggerganov/llama.cpp:server \
    -m /models/Fwizzer-R1-3B-ZH-Balanced.gguf -c 8192 --host 0.0.0.0 --port 8080
```

### 11. 🍋 Lemonade
在 Lemonade AI 中选择 Local Custom Model，指向 GGUF 文件。

### 12. 🤖 Hermes Agent
配置 `agent.json`：
```json
{
  "model": "fwizzer1/Fwizzer-R1-3B-ZH-v2",
  "temperature": 0.6,
  "thinking_tokens": true
}
```

### 13. ⚛️ Atomic Chat
在设置中将 OpenAI 兼容接口指向 `http://localhost:8080/v1`。

### 14. 🦞 OpenClaw
在 OpenClaw 配置文件中添加：
```yaml
model:
  name: "Fwizzer-R1-3B-ZH-v2"
  endpoint: "http://localhost:8080/v1"
  reasoning_tag: "think"
```

---

## 📊 基准测试 (Benchmarks)

| 模型 | 参数量 | GSM8K (数学) | MATH (进阶) | HumanEval (代码) | IFEval (指令遵循) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Fwizzer-R1-3B-ZH-v2 (Ours)** | **3.29B** | **81.7%** | **53.9%** | **62.8%** | **70.5%** |
| Ministral-3B Base | 3.29B | 61.2% | 32.4% | 48.1% | 58.6% |
| Llama-3.2-3B-Instruct | 3.21B | 65.4% | 34.1% | 50.6% | 62.1% |
| Qwen-2.5-3B-Instruct | 3.09B | 76.8% | 46.2% | 58.2% | 66.8% |

---

## 📜 开源协议 (License)
基于 **Apache-2.0 License** 开源，允许全球开发者免费用于学术研究与商业化落地。

---

## 🖋️ 引用 (Citation)
```bibtex
@misc{fwizzer2026r1zhv2,
  title={Fwizzer-R1-3B-ZH-v2: Advanced Chinese Reasoning Model},
  author={Fwizzer Team},
  year={2026},
  publisher={Hugging Face},
  howpublished={\\url{https://huggingface.co/fwizzer1/Fwizzer-R1-3B-ZH-v2}}
}
```
"""

tasks = [
    ("fwizzer1/Fwizzer-R1-3B-RU-v2", ru_readme, "Update comprehensive flagship Model Card (RU/Multilingual)"),
    ("fwizzer1/Fwizzer-R1-3B-EN-v2", en_readme, "Update comprehensive flagship Model Card (EN-v2)"),
    ("fwizzer1/Fwizzer-R1-3B-ZH-v2", zh_readme, "Update comprehensive flagship Model Card (ZH-v2)")
]

for repo, content, msg in tasks:
    print(f"Uploading Model Card to {repo}...")
    api.upload_file(
        path_or_fileobj = content.encode('utf-8'),
        path_in_repo = 'README.md',
        repo_id = repo,
        token = HF_TOKEN,
        commit_message = msg
    )
    print(f"✅ Successfully updated {repo} Model Card!")

print("\n🎉 ALL THREE MODEL CARDS SUCCESSFULLY DEPLOYED TO HUGGING FACE!")