docs/08-deploy-hf-space.md

08 — Deploy Hugging Face Space

Panduan deploy wajib untuk submission hackathon. Fokus: build sukses dan inferensi tidak timeout.

Ringkasan risiko

Masalah	Penyebab	Solusi
Build timeout	pip install llama-cpp-python compile dari source	Prebuilt wheel via URL
Start timeout	Download GGUF saat runtime	preload_from_hub
OOM	n_ctx besar + 7B	N_CTX=2048, Q4 only
Lambat	CPU only	Terima latency / ZeroGPU / video dari lokal

Langkah 1 — Buat Space

1. Org: build-small-hackathon
2. Nama: oneiros
3. SDK: Gradio
4. Visibility: public

Langkah 2 — README YAML header

Di README.md Space (frontmatter):

---
title: Oneiros
emoji: ✦
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: "4.40.0"
app_file: app.py
pinned: true
short_description: Map your dreams with a small model — no ChatGPT API.
preload_from_hub:
  - repo_id: Qwen/Qwen2.5-7B-Instruct-GGUF
    filename: qwen2.5-7b-instruct-q4_k_m.gguf
startup_duration_timeout: 45m
---

Sesuaikan field dengan docs HF Spaces terbaru.

Langkah 3 — requirements.txt (Space)

Jangan:

llama-cpp-python>=0.2.90

Gunakan wheel (contoh CPU Python 3.10):

gradio>=4.40.0
huggingface-hub>=0.23.0
jsonschema>=4.0.0
llama-cpp-python @ https://huggingface.co/Luigi/llama-cpp-python-wheels-hf-spaces-free-cpu/resolve/main/llama_cpp_python-0.3.22-cp310-cp310-linux_x86_64.whl

Verifikasi versi Python Space di Settings → sesuaikan wheel.

Alternatif: Docker SDK

Jika wheel gagal:

1. Ubah Space SDK ke Docker
2. Dockerfile: install wheel + copy app
3. Kontrol penuh atas glibc / OpenBLAS

Referensi: Luigi wheels repo.

Langkah 4 — MODEL_PATH & shard GGUF

Repo Qwen memakai 2 shard (bukan satu file):

• qwen2.5-7b-instruct-q4_k_m-00001-of-00002.gguf
• qwen2.5-7b-instruct-q4_k_m-00002-of-00002.gguf

model/loader.py memuat shard 00001 jika 00002 ada di folder yang sama (llama.cpp multi-part).

Setelah deploy, cek log startup:

[oneiros] diagnosis: {..., 'shard_pair_ok': True, 'model_path': '/data/.../00001-of-00002.gguf'}

Atau jalankan lokal: python scripts/verify_day1.py

Variables Space (disarankan):

Key	Nilai
N_GPU_LAYERS	0
N_CTX	4096 atau 2048
ONEIROS_SKIP_WARMUP	1 sampai preload selesai

Set MODEL_PATH manual hanya jika auto-detect gagal (arahkan ke file 00001).

Langkah 5 — Konfigurasi inferensi Space

# Otomatis via SPACE_ID di loader.py
N_GPU_LAYERS=0
N_CTX=4096   # atau 2048 jika OOM

Warm-up di app.py:

from model.loader import get_model
get_model()  # saat module load

Langkah 6 — ZeroGPU (opsional)

Jika CPU >45 detik:

1. Hardware: ZeroGPU (perlu PRO/Team sesuai kebijakan HF)
2. Decorate fungsi inferensi:

import spaces

@spaces.GPU
def infer_dream(...):
    ...

3. Model tetap load ke cuda per docs ZeroGPU.

Docs: https://huggingface.co/docs/hub/spaces-zerogpu

Langkah 7 — Checklist sebelum push

• Wheel URL valid (build log hijau)
• preload_from_hub mengunduh GGUF
• get_model() tidak crash di startup
• UI disclaimer privasi tampil
• Satu mimpi contoh selesai <60s
• Tidak ada secret / token di repo

Debugging

Log	Arti
Building... lama	Kemungkinan compile llama.cpp
Exit code 137	OOM — turunkan n_ctx atau model
Model not found	MODEL_PATH salah
libcuda.so missing	Wheel CUDA di hardware CPU — ganti wheel CPU

Forum: https://discuss.huggingface.co/t/using-llama-cpp-on-spaces/172216

Strategi demo untuk judge

1. Pre-warm Space sebelum share link (submit 1 mimpi dummy).
2. Video rekam dari lokal agar respons cepat.
3. README jelaskan Space untuk try-live, lokal untuk privasi.

Dokumen terkait

• 03 Positioning
• 07 Setup lokal
• 13 Timeline — Day 1 gate