README_TH.md

# 🎭 Character Studio — คู่มือภาษาไทย

Space รวมโมเดลสร้างตัวละครหลายตัวไว้ใน UI เดียว ทำงานบน **ZeroGPU**
เลือกโมเดลจากรายการ → พิมพ์ prompt → (ถ้าต้องการ) ใส่รูปต้นแบบ → กด Generate

---

## 1) วิธีนำขึ้น Hugging Face

1. สร้าง Space ใหม่: https://huggingface.co/new-space
   - **SDK = Gradio**
   - **Hardware = ZeroGPU** (Nvidia, dynamic)
2. อัปโหลดไฟล์ทั้งหมดในโฟลเดอร์นี้ (`app.py`, `pipeline_manager.py`, `models.json`,
   `requirements.txt`, `README.md`) ขึ้นไปที่ root ของ Space
   - ผ่านเว็บ (ลากวาง) หรือผ่าน git:
     ```bash
     git clone https://huggingface.co/spaces/<user>/<space-name>
     # คัดลอกไฟล์ในโฟลเดอร์นี้เข้าไป แล้ว
     git add . && git commit -m "init character studio" && git push
     ```
3. ไปที่ **Settings → Variables and secrets** ใส่ค่า (เท่าที่จำเป็น):
   - `HF_TOKEN` — เฉพาะโมเดล gated เช่น FLUX.1-dev
   - `CIVITAI_TOKEN` — เฉพาะเมื่อโหลดจากลิงก์ Civitai

---

## 2) เพิ่ม / ลบ / ปิดโมเดล (แก้ `models.json` อย่างเดียว)

แก้ไฟล์ `models.json` แล้วกดปุ่ม **🔄 Reload models** ใน UI (หรือ restart Space)

### โครงสร้างแต่ละโมเดล

| field | ความหมาย |
|---|---|
| `id` | รหัสไม่ซ้ำ (อังกฤษ-ขีดกลาง) |
| `label` | ชื่อที่โชว์ใน UI |
| `base` | `"sd15"` / `"sdxl"` / `"flux"` — **สำคัญมาก** กำหนดว่าโหมดไหนใช้ได้ |
| `type` | `"checkpoint"` (โมเดลเต็ม) หรือ `"lora"` |
| `repo_id` | repo บน HF (สำหรับ checkpoint) หรือ **base checkpoint** (สำหรับ lora) |
| `single_file_url` | ลิงก์ `.safetensors` โดยตรง เช่น Civitai (ใช้แทน repo_id ได้) |
| `lora_repo_id` / `lora_weight_name` | สำหรับ LoRA ที่อยู่บน HF |
| `lora_url` | สำหรับ LoRA จาก Civitai (ลิงก์ download) |
| `lora_scale` | น้ำหนัก LoRA เช่น 0.8 |
| `trigger` | คำ trigger ที่จะเติมหน้า prompt อัตโนมัติ |
| `recommended_prompt` | prompt ตัวอย่าง (โชว์เป็น placeholder) |
| `negative_prompt` | negative เริ่มต้น |
| `default_steps` / `default_guidance` | ค่าเริ่มต้นเวลาเลือกโมเดลนี้ |
| `enabled` | `true`/`false` ปิดชั่วคราวได้โดยไม่ต้องลบ |

### ตัวอย่าง — checkpoint จาก Civitai (SD1.5)
```json
{
  "id": "asian-realistic-v6",
  "label": "AsianRealistic SDLife V6 (SD1.5)",
  "base": "sd15",
  "type": "checkpoint",
  "repo_id": null,
  "single_file_url": "https://civitai.com/api/download/models/130072",
  "default_steps": 28,
  "default_guidance": 6.5,
  "enabled": true
}
```
> ต้องใส่ `CIVITAI_TOKEN` ใน Secrets ด้วย

### ตัวอย่าง — LoRA จาก Civitai (วางบน base SD1.5)
```json
{
  "id": "asian-girls-face",
  "label": "Asian Girls Face (LoRA)",
  "base": "sd15",
  "type": "lora",
  "repo_id": "stable-diffusion-v1-5/stable-diffusion-v1-5",
  "lora_url": "https://civitai.com/api/download/models/67980",
  "lora_scale": 0.8,
  "enabled": true
}
```

### ตัวอย่าง — โมเดลบน HF (SDXL)
```json
{
  "id": "my-sdxl",
  "label": "My SDXL model",
  "base": "sdxl",
  "type": "checkpoint",
  "repo_id": "author/my-sdxl-repo",
  "default_steps": 30,
  "default_guidance": 6.0,
  "enabled": true
}
```

**ลบโมเดล** = ลบ block นั้นออกจาก array `models` หรือตั้ง `"enabled": false`

---

## 3) โหมดรูปต้นแบบ (Input mode)

| โหมด | ทำอะไร | ใช้กับ base |
|---|---|---|
| Text → Image | สร้างจาก prompt อย่างเดียว | ทุก base |
| Image → Image | แปลงรูปเดิม (ปรับ denoise) | ทุก base |
| IP-Adapter | ดึงสไตล์/องค์ประกอบจากรูป | sd15, sdxl |
| Face identity | ล็อกใบหน้าจากรูปต้นแบบ (FaceID) | sd15, sdxl |

> FLUX รองรับเฉพาะ txt2img / img2img (IP-Adapter/FaceID ของ FLUX ยังไม่รวมในเวอร์ชันนี้)

---

## 4) ข้อควรรู้เรื่อง ZeroGPU
- โมเดลใหญ่จะถูกเก็บทีละตัว สลับโมเดล = โหลดใหม่ (ครั้งแรกช้าหน่อย)
- หนึ่งครั้ง generate จำกัดเวลา GPU ~120 วินาที (ปรับใน `@spaces.GPU(duration=...)`)
- โมเดล Civitai/checkpoint เต็มก้อนใหญ่ ดาวน์โหลดครั้งแรกใช้เวลา — ใจเย็น

---

## 5) การใช้งานอย่างรับผิดชอบ
เครื่องมือนี้สำหรับงานสร้างสรรค์ตัวละครต้นฉบับ/งานที่ได้รับอนุญาต
**อย่าใช้โหมด Face identity สร้างภาพบุคคลจริงโดยไม่ได้รับความยินยอม**