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:

     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)

{
  "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)

{
  "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)

{
  "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 สร้างภาพบุคคลจริงโดยไม่ได้รับความยินยอม