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):

```yaml
---
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](https://huggingface.co/docs/hub/spaces-config-reference) terbaru.

## Langkah 3 — requirements.txt (Space)

**Jangan:**

```text
llama-cpp-python>=0.2.90
```

**Gunakan wheel (contoh CPU Python 3.10):**

```text
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](https://huggingface.co/Luigi/llama-cpp-python-wheels-hf-spaces-free-cpu).

## 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:

```text
[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

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

Warm-up di `app.py`:

```python
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:

```python
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](03-positioning-dan-privasi.md)
- [07 Setup lokal](07-setup-lokal.md)
- [13 Timeline](13-timeline-hackathon.md) — Day 1 gate