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

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)

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

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 модель

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: Кастомная модель

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 модель

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
• HuggingFace Hub Guide
• Safetensors Format