USAGE_GUIDE.md

# 📖 Руководство по использованию

## 🎯 Цель

Этот Space автоматизирует процесс конвертации моделей из safetensors в Diffusers формат.

---

## 🚀 Быстрый старт

### Web UI

1. **Откройте Space**: https://huggingface.co/spaces/Gerchegg/Qwen-Model-Converter
2. **Заполните форму**:
   ```
   Source Repo: Gerchegg/QwenSolobandModel
   Source File: Qwen_Soloband_Model_V1-000140.safetensors
   Base Model: Qwen/Qwen-Image
   Target Repo: YourUsername/YourModel-Diffusers
   HF Token: hf_your_token_here
   ```
3. **Нажмите "Запустить конвертацию"**
4. **Дождитесь завершения** (~45-90 минут)

---

## 🔌 API Использование

### Python

```python
from gradio_client import Client

client = Client("Gerchegg/Qwen-Model-Converter")

# Запуск конвертации
result = client.predict(
    source_repo_id="Gerchegg/QwenSolobandModel",
    source_filename="Qwen_Soloband_Model_V1-000140.safetensors",
    base_model_id="Qwen/Qwen-Image",
    target_repo_id="YourUsername/YourModel-Diffusers",
    hf_token="hf_your_token_here",
    api_name="/convert"
)

status, logs = result

print(status)  # ✅ Готово! URL: https://...
print(logs)    # Подробные логи процесса
```

### JavaScript (Node.js)

```javascript
import { client } from "@gradio/client";

const app = await client("Gerchegg/Qwen-Model-Converter");

const result = await app.predict("/convert", {
    source_repo_id: "Gerchegg/QwenSolobandModel",
    source_filename: "Qwen_Soloband_Model_V1-000140.safetensors",
    base_model_id: "Qwen/Qwen-Image",
    target_repo_id: "YourUsername/YourModel-Diffusers",
    hf_token: "hf_your_token_here"
});

console.log(result.data);
```

### cURL

```bash
curl -X POST "https://gerchegg-qwen-model-converter.hf.space/api/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      "Gerchegg/QwenSolobandModel",
      "Qwen_Soloband_Model_V1-000140.safetensors",
      "Qwen/Qwen-Image",
      "YourUsername/YourModel-Diffusers",
      "hf_your_token_here"
    ]
  }'
```

---

## 📊 Примеры конвертации

### Пример 1: Стандартная Qwen модель

```python
source_repo_id = "Gerchegg/QwenSolobandModel"
source_filename = "Qwen_Soloband_Model_V1-000140.safetensors"
base_model_id = "Qwen/Qwen-Image"
target_repo_id = "Gerchegg/Qwen-Soloband-Diffusers"
```

**Время**: ~60 минут  
**Размер**: ~58GB (40GB transformer + 18GB компоненты)

---

### Пример 2: Кастомная модель

```python
source_repo_id = "YourUsername/CustomQwenModel"
source_filename = "custom_transformer.safetensors"
base_model_id = "Qwen/Qwen-Image"
target_repo_id = "YourUsername/CustomModel-Diffusers"
```

---

### Пример 3: Fine-tuned модель

```python
source_repo_id = "Community/FineTunedQwen"
source_filename = "checkpoint-1000.safetensors"
base_model_id = "Qwen/Qwen-Image"
target_repo_id = "YourUsername/FineTuned-Diffusers"
```

---

## ⏱️ Время выполнения

| Этап | Время | Зависит от |
|------|-------|------------|
| **Скачивание safetensors** | 5-15 мин | Размер файла, интернет |
| **Скачивание базовой модели** | 5-10 мин | Первый раз дольше, затем кэш |
| **Конвертация** | 1-3 мин | Размер модели |
| **Загрузка на HF** | 30-90 мин | Размер, скорость upload |
| **Итого** | **45-120 мин** | Для модели ~40GB |

---

## 💾 Требования к памяти

### Во время процесса:

| Компонент | Размер | Примечание |
|-----------|--------|------------|
| Safetensors (скачан) | ~40GB | Временный |
| Базовая модель | ~18GB | Кэшируется |
| Diffusers (выход) | ~58GB | Результат |
| **Peak usage** | **~70GB** | Temporary + Output |

**Примечание**: Space на HuggingFace имеет достаточно места для обработки больших моделей.

---

## 🔐 HuggingFace Token

### Требуемые права:

✅ **Read** - для скачивания source и base моделей  
✅ **Write** - для создания и загрузки в target репозиторий

### Создание токена:

1. Перейдите: https://huggingface.co/settings/tokens
2. Нажмите "New token"
3. Выберите тип: **Write**
4. Скопируйте токен (начинается с `hf_`)

---

## 📝 Подробные логи

Во время конвертации Space показывает подробные логи:

```
[12:00:01] 🚀 Начало процесса конвертации
[12:00:01]   Source: Gerchegg/QwenSolobandModel/Qwen_Soloband_Model_V1-000140.safetensors
[12:00:01]   Base: Qwen/Qwen-Image
[12:00:01]   Target: YourUsername/Model-Diffusers
[12:00:01] 
[12:00:01] ============================================================
[12:00:01] ШАГ 1: Скачивание safetensors модели
[12:00:01] ============================================================
[12:08:32] ✓ Safetensors скачан: 40.9 GB
[12:08:32] 
[12:08:32] ============================================================
[12:08:32] ШАГ 2: Скачивание базовой модели
[12:08:32] ============================================================
[12:15:45] ✓ Базовая модель скачана
[12:15:45] 
[12:15:45] ============================================================
[12:15:45] ШАГ 3: Конвертация в Diffusers формат
[12:15:45] ============================================================
[12:17:20] ✓ Модель конвертирована: 58.3 GB
[12:17:20]   Путь: workspace/output/Model-Diffusers
[12:17:20] 
[12:17:20] ============================================================
[12:17:20] ШАГ 4: Загрузка на HuggingFace Hub
[12:17:20] ============================================================
[12:17:20] ⏳ Это может занять 30-60 минут для больших моделей...
[12:17:20] 
[13:05:42] ✓ Модель загружена на HuggingFace!
[13:05:42]   URL: https://huggingface.co/YourUsername/Model-Diffusers
[13:05:42] 
[13:05:42] ============================================================
[13:05:42] ✅ ПРОЦЕСС ЗАВЕРШЕН УСПЕШНО!
[13:05:42] ============================================================
```

---

## 🐛 Troubleshooting

### Проблема: "Invalid HF Token"

**Решение**:
- Убедитесь что токен начинается с `hf_`
- Проверьте права токена (должен быть Write)
- Создайте новый токен если нужно

### Проблема: "File not found"

**Решение**:
- Проверьте правильность написания repo_id
- Проверьте правильность имени файла
- Убедитесь что токен имеет доступ к source репо

### Проблема: "Out of space"

**Решение**:
- Space на HF имеет достаточно места
- Если проблема - сообщите в discussions
- Попробуйте позже

### Проблема: "Upload failed"

**Решение**:
- HF API автоматически возобновляет загрузку
- Просто перезапустите конвертацию
- Загрузка продолжится с места остановки

---

## 📚 Дополнительные ресурсы

- [Diffusers Documentation](https://huggingface.co/docs/diffusers)
- [HuggingFace Hub Guide](https://huggingface.co/docs/hub)
- [Safetensors Format](https://huggingface.co/docs/safetensors)