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)