INSTRUKCJE.md

# Ollama Universal — HF Spaces Template

Uniwersalny szablon do deployowania dowolnego modelu Ollama na Hugging Face Spaces.
Wystarczy wgrać 3 pliki i ustawić 2 zmienne — kod nie wymaga zmian.

---

## Pliki repozytorium

```
Dockerfile       — buduje obraz (nie edytuj)
entrypoint.sh    — startuje Ollama i proxy (nie edytuj)
proxy.py         — API proxy z oznaczonymi miejscami do edycji
INSTRUKCJE.md    — ten plik
```

---

## Szybki start

### 1. Utwórz Space na HuggingFace
- huggingface.co → Spaces → Create new Space
- SDK: **Docker**
- Hardware: **CPU Basic** (free, 16 GB RAM)
- Visibility: Public lub Private

### 2. Wgraj pliki
Przez UI (przeciągnij i upuść) lub git:
```bash
git clone https://huggingface.co/spaces/<username>/<space-name>
cd <space-name>
# skopiuj Dockerfile, entrypoint.sh, proxy.py
git add . && git commit -m "init" && git push
```

### 3. Ustaw zmienne środowiskowe
Settings → Variables and Secrets → New variable:

| Nazwa | Przykład | Opis |
|-------|---------|------|
| `MODEL` | `deepseek-r1:14b` | Model do załadowania |
| `API_KEY` | `moj-tajny-klucz` | Klucz autoryzacji Bearer |

### 4. Poczekaj
- Build: ~2 min
- Cold start: zależy od rozmiaru modelu (np. 9 GB = ~3-5 min pobierania)

---

## Zmiana modelu

Zmień tylko Variable `MODEL` w Settings — Space restartuje się automatycznie.

### Modele z Ollama registry
```
deepseek-r1:14b          9.0 GB   reasoning
deepseek-r1:7b           4.7 GB   reasoning
qwen3:8b                 5.2 GB   reasoning
qwen3:4b                 2.6 GB   reasoning
qwen2.5:7b               4.7 GB
llama3.2:3b              2.0 GB
gemma3:9b                5.8 GB
mistral:7b               4.1 GB
phi4-mini:latest         4.2 GB
```

### Modele z HuggingFace (hf.co/...)
```
hf.co/unsloth/GLM-4.7-Flash-GGUF:UD-TQ1_0        8.33 GB
hf.co/bartowski/Qwen2.5-7B-Instruct-GGUF:Q4_K_M  4.7  GB
hf.co/bartowski/gemma-3-9b-it-GGUF:Q4_K_M        5.8  GB
```

---

## Co edytować w proxy.py

Szukaj komentarzy `!TU MUSISZ EDYTOWAC!`:

```python
API_KEY = os.environ.get("API_KEY", "connectkey")
#                                    ^^^^^^^^^^^ zmień domyślny klucz

MODEL = os.environ.get("MODEL", "deepseek-r1:14b")
#                                ^^^^^^^^^^^^^^^^ zmień domyślny model

temperature = body.get("temperature", 0.6)
#                                     ^^^ zmień domyślną temperaturę

top_p = body.get("top_p", 0.95)
#                          ^^^^ zmień domyślne top_p
```

Wartości z ENV (HF Variables) zawsze mają priorytet nad domyślnymi w kodzie.

---

## Użycie API

Base URL: `https://<username>-<space-name>.hf.space`

### curl
```bash
curl https://<space>.hf.space/v1/chat/completions \
  -H "Authorization: Bearer moj-tajny-klucz" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Cześć!"}]
  }'
```

### Python (openai SDK)
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://<space>.hf.space/v1",
    api_key="moj-tajny-klucz",
)

stream = client.chat.completions.create(
    model="deepseek-r1:14b",
    messages=[{"role": "user", "content": "Cześć!"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if hasattr(delta, "reasoning_content") and delta.reasoning_content:
        print(delta.reasoning_content, end="", flush=True)
    if delta.content:
        print(delta.content, end="", flush=True)
```

---

## Endpointy

| Endpoint | Metoda | Opis |
|----------|--------|------|
| `/v1/chat/completions` | POST | Chat — zawsze streaming |
| `/v1/models` | GET | Lista załadowanych modeli |
| `/health` | GET | Status Ollamy i modelu |

---

## Limity CPU Basic (free)

| Parametr | Wartość |
|----------|---------|
| RAM | 16 GB |
| vCPU | 2 |
| Disk | 50 GB (reset przy restarcie) |
| Sleep po bezczynności | 48h |
| Max rozmiar modelu | ~13 GB GGUF |