qwen3-8b-core-tauken

Qwen3-VL-8B для литологического описания керна месторождения Жосабай

<div align="center">

Специализированная Vision-Language модель для геологического описания буровых кернов

</div>

📋 Оглавление

• Описание
• Ключевые особенности модели
• Метрики обучения
• Использование
• Детали обучения
• Датасет
• Ограничения

---

🎯 Описание

Это файн-тюненная версия Qwen/Qwen3-VL-8B-Instruct, специализированная для генерации детальных литологических описаний керна буровых скважин месторождения Жосабай (Казахстан) на русском языке.

Что умеет модель

Модель анализирует фотографии керна и генерирует профессиональные геологические описания, включающие:

• 🪨 Литотип и цвет (андезитовые порфириты, диориты, туфы и т.д.)
• 🔬 Текстура и структура (порфировая, массивная, флюидальная)
• 💎 Минеральный состав (плагиоклаз, роговая обманка, биотит, и т.д.)
• 🌿 Вторичные изменения (пропилитизация, серицитизация, хлоритизация)
• 💥 Трещиноватость (плотность, углы к оси керна)
• ⛏️ Рудная минерализация (пирит, халькопирит, молибденит)
• 📏 Геометрия прожилков (мощность, углы, состав)

Обучающий датасет

• 1664 фотографии керна из 28 скважин
• Экспертные описания от геологов месторождения
• Типы фото: wet (мокрый), dry (сухой), cut (распиленный)

---

🔑 Ключевые особенности модели

1. Специфичность для Qwen3-VL (НЕ Qwen2-VL!)

⚠️ ВАЖНО: Эта модель использует архитектуру Qwen3-VL, которая отличается от Qwen2-VL!

# ✅ ПРАВИЛЬНО:
from transformers import Qwen3VLForConditionalGeneration
model = Qwen3VLForConditionalGeneration.from_pretrained(...)

# ❌ НЕПРАВИЛЬНО (будет ошибка загрузки):
from transformers import Qwen2VLForConditionalGeneration  # НЕТ!

2. Flash Attention 2

Модель обучалась с Flash Attention 2 на 4x RTX 5090.

Для инференса рекомендуется:

model = Qwen3VLForConditionalGeneration.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",  # Рекомендуется для скорости
    device_map="auto"
)

Альтернатива (если Flash Attention недоступен):

attn_implementation="eager"  # Fallback на PyTorch SDPA

Требования для Flash Attention 2:

• pip install flash-attn (требует компиляции из исходников)
• CUDA-совместимый GPU
• PyTorch >= 2.0

3. Grouped Query Attention (GQA)

Qwen3-VL-8B использует GQA:

• 32 query heads
• 8 key/value heads
• Соотношение 4:1 для эффективности памяти

При использовании SDPA fallback автоматически применяется repeat_interleave для key/value heads.

4. RTX 5090 Compatibility

Модель обучена на PyTorch 2.11.0.dev20260117 с CUDA 13.0 для поддержки RTX 5090 (compute capability sm_120).

5. DeepSpeed ZeRO-3 с CPU Offloading

Из-за ограничений памяти использовался ZeRO-3 с полной выгрузкой на CPU:

• Параметры модели: CPU RAM
• Optimizer states (Adam): CPU RAM
• Только активации: GPU VRAM (~2.4GB на GPU)

Это означает: модель весит ~17GB и требует достаточно RAM при загрузке.

6. Обучаемые компоненты

Vision Encoder (27 блоков)        → ❌ ЗАМОРОЖЕН
Vision-Language Merger             → ✅ ОБУЧЕН
LLM (36 слоев Qwen3-8B)           → ✅ ОБУЧЕН

Т.е. не обучали распознавание изображений, а только генерацию текста на основе визуальных признаков.

7. BFloat16 Precision

Модель обучена в bfloat16 (не fp16!), что критично для стабильности обучения больших моделей.

# Обязательно загружать в том же dtype:
torch_dtype=torch.bfloat16

---

📊 Метрики обучения

Финальные результаты

Динамика по эпохам

Эпоха 1 (шаги 0-52):    Loss: 1.4244 → 0.1067   (↓ 92.5%)
Эпоха 2 (шаги 52-104):  Loss: 0.1067 → 0.0437   (↓ 59.0%)
Эпоха 3 (шаги 104-156): Loss: 0.0437 → 0.0272   (↓ 37.8%)

График loss по шагам

 1.5 ┤●
     │
 1.2 ┤
     │  ●
 0.9 ┤
     │    ●●
 0.6 ┤       ●●
     │          ●●●
 0.3 ┤              ●●●●
     │                   ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
 0.0 ┤________________________________________________________________
     0         50        100       150
                      Training Steps

---

🚀 Использование

Установка

pip install transformers torch pillow accelerate

Требуемая версия transformers:

pip install transformers>=4.57.0  # Для поддержки Qwen3-VL

Базовый пример

import torch
from PIL import Image
from transformers import Qwen3VLForConditionalGeneration, AutoProcessor

# Загрузка модели
model_id = "RISEF/qwen3-8b-core-tauken"
model = Qwen3VLForConditionalGeneration.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    attn_implementation="eager",  # ОБЯЗАТЕЛЬНО!
    device_map="auto"
)
processor = AutoProcessor.from_pretrained(model_id)

# Загрузка изображения
image = Image.open("path/to/core_sample.jpg")

# Формирование промпта (формат OpenAI Messages API)
messages = [{
    "role": "user",
    "content": [
        {"type": "image"},
        {"type": "text", "text": "Опиши литологию керна на данном снимке. Скважина: ZHS_025, интервал: 100.0-105.5м."}
    ]
}]

# Генерация описания
text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = processor(text=[text], images=[image], padding=True, return_tensors="pt").to(model.device)

with torch.no_grad():
    output = model.generate(**inputs, max_new_tokens=512, do_sample=False)

result = processor.batch_decode(output, skip_special_tokens=True)[0]

# Извлечение ответа модели (удаление промпта)
if "assistant" in result:
    result = result.split("assistant")[-1].strip()

print(result)

Пример вывода

Вход:

• Изображение: фото керна ZHS_001_25, интервал 58.5-66.3м
• Промпт: "Опиши литологию керна на данном снимке. Скважина: ZHS_001_25, интервал: 58.5-66.3м."

Выход:

Андезитовые порфириты зеленовато-серого цвета с порфировой структурой.

Основная масса: мелкозернистая, серовато-зеленая, с признаками флюидальности.

Порфировые выделения:
- Плагиоклаз: 25-30%, размером 2-5 мм, таблитчатой формы
- Роговая обманка: 10-15%, размером 1-3 мм, призматической формы

Вторичные изменения:
- Пропилитизация умеренная, проявлена хлоритизацией и эпидотизацией
- Серицитизация слабая по плагиоклазу

Трещиноватость:
- Плотность: 3-4 трещины на 1 погонный метр
- Углы к оси керна: 30-45°

Прожилки:
- Кварц-карбонатного состава
- Мощность: 1-3 мм
- Углы к оси керна: 60-70°

Рудная минерализация:
- Пирит: рассеянная вкрапленность, 1-2%
- Халькопирит: единичные зерна, <1%

---

🛠️ Детали обучения

Инфраструктура

Hardware:

• GPU: 3x NVIDIA RTX 5090 (32GB VRAM каждая)
• CPU RAM: ~160GB использовалось (DeepSpeed offloading)
• Использованные GPU: 1, 2, 3 (GPU 0 занята другой задачей)

Software Stack:

• PyTorch 2.11.0.dev20260117+cu130 (nightly)
• transformers 4.57.0.dev0
• DeepSpeed 0.17.1
• CUDA 13.0 (для RTX 5090 support)

Конфигурация обучения

{
  # Модель
  "model_name_or_path": "Qwen/Qwen3-VL-8B-Instruct",
  "attn_implementation": "eager",  # SDPA fallback

  # Training
  "num_train_epochs": 3,
  "learning_rate": 1e-5,
  "per_device_train_batch_size": 1,
  "gradient_accumulation_steps": 8,
  "max_grad_norm": 1.0,

  # Optimizer
  "optim": "adamw_torch",
  "weight_decay": 0.01,
  "warmup_ratio": 0.03,
  "lr_scheduler_type": "cosine",

  # Precision
  "bf16": true,
  "gradient_checkpointing": true,

  # Модель компоненты
  "tune_mm_vision": false,  # Vision encoder заморожен
  "tune_mm_mlp": true,      # Merger обучаем
  "tune_mm_llm": true,      # LLM обучаем

  # DeepSpeed
  "deepspeed": "zero3_offload.json",  # ZeRO-3 + CPU offloading

  # Data
  "max_pixels": 50176,
  "min_pixels": 784,
  "model_max_length": 4096,

  # Checkpointing
  "save_strategy": "steps",
  "save_steps": 200,
  "save_total_limit": 2
}

DeepSpeed ZeRO-3 Offload Config

{
  "zero_optimization": {
    "stage": 3,
    "offload_optimizer": {
      "device": "cpu",
      "pin_memory": true
    },
    "offload_param": {
      "device": "cpu",
      "pin_memory": true
    },
    "overlap_comm": true,
    "contiguous_gradients": true,
    "gather_16bit_weights_on_model_save": true
  }
}

Почему именно эта конфигурация?

1. Batch size = 1: Из-за размера изображений (до 50176 pixels) и модели 8B
2. Gradient accumulation = 8: Для эффективного batch size 24
3. ZeRO-3 + CPU offload: 8B модель + full fine-tuning не влезала в 3x32GB VRAM
4. Eager attention: Flash-attn несовместим с PyTorch 2.11 nightly
5. 3 эпохи: Оптимальный баланс обучение/переобучение (loss стабилизировался)

---

📚 Датасет

Формат данных

{
  "image": "/absolute/path/to/image.JPG",
  "conversations": [
    {
      "from": "human",
      "value": "<image>\\nОпиши литологию керна на данном снимке. Скважина: ZHS_001, интервал: 58.5-66.3м."
    },
    {
      "from": "gpt",
      "value": "Андезитовые порфириты зеленовато-серого цвета..."
    }
  ]
}

Статистика датасета

Структура промптов

Все промпты следуют единому формату:

Опиши литологию керна на данном снимке. Скважина: {well}, интервал: {from}-{to}м.

Ground Truth

ВАЖНО: Модель обучена на экспертных геологических описаниях, а не на описаниях от других AI моделей (например, Claude).

---

⚠️ Ограничения и предостережения

1. Специфичность для месторождения

• Модель обучена только на керне месторождения Жосабай
• Терминология и стиль описаний специфичны для этого месторождения
• Для других месторождений потребуется дообучение

2. Галлюцинации

Модель может:

• Добавлять детали, не видимые на фотографии
• Переоценивать содержание минералов
• Описывать рудную минерализацию там, где её нет

Рекомендация: Всегда проверяйте описания у геолога перед использованием в отчетах.

3. Качество фотографий

Модель ожидает фотографии, похожие на обучающий датасет:

• Разрешение: достаточное для видения структуры
• Освещение: равномерное
• Фон: контрастный (обычно белый или синий)
• Ориентация: горизонтальная раскладка керна

4. Языковые ограничения

• Модель работает только на русском языке
• Промпты на английском языке дадут некорректные результаты

5. Технические ограничения

• Требуется GPU с минимум 16GB VRAM (лучше 24GB+)
• bfloat16 precision обязательна
• attn_implementation="eager" обязателен

6. Не использовать для критических решений

Эта модель - инструмент помощи геологу, не замена эксперта. Не следует использовать для:

• Принятия решений о разработке месторождения
• Официальных геологических отчетов без проверки
• Оценки запасов руды

---

📖 Цитирование

Если вы используете эту модель в исследованиях или проектах, пожалуйста, укажите:

@misc{qwen3-8b-core-tauken-2026,
  title={Qwen3-VL-8B для литологического описания керна месторождения Жосабай},
  author={RISEF},
  year={2026},
  month={January},
  publisher={HuggingFace},
  url={https://huggingface.co/RISEF/qwen3-8b-core-tauken},
  note={Fine-tuned from Qwen/Qwen3-VL-8B-Instruct on 1664 geological core samples}
}

---

📜 Лицензия

Apache License 2.0

Базовая модель Qwen3-VL-8B-Instruct также под Apache 2.0.

---

🙏 Благодарности

• Alibaba Cloud Qwen Team за базовую модель Qwen3-VL
• Эксперты-геологи месторождения Жосабай за детальные литологические описания
• RISEF Team за сбор датасета и обучение модели

---

📞 Контакты

• Организация: RISEF
• HuggingFace: RISEF/qwen3-8b-core-tauken
• Issues: Используйте Community tab на HuggingFace

---

<div align="center">

Сделано с ❤️ для геологов месторождения Жосабай

</div>