README.md

---
title: GuardrailsLLM
emoji: 🛡️
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
short_description: Guardrails LLM API powered by llama.cpp
---

OpenAI-compatible API powered by **llama.cpp** + **Guardrails Typhoon 2.5 Q4_K_M** (Qwen3-based).

---

## สิ่งที่ต้องเตรียม (Prerequisites)

- บัญชี [Hugging Face](https://huggingface.co) (ฟรี)
- [Git](https://git-scm.com) + [Git LFS](https://git-lfs.com)
- [HF CLI](https://huggingface.co/docs/huggingface_hub/guides/cli) (สำหรับ upload model)
- ไฟล์ model `.gguf` ในเครื่อง

---

## ขั้นตอนที่ 1 — สร้าง Hugging Face Space

1. ไปที่ [huggingface.co/spaces](https://huggingface.co/spaces)
2. คลิก **"Create new Space"**
3. กรอกข้อมูล:
   - **Owner**: ชื่อ account ของคุณ
   - **Space name**: ตั้งชื่อ เช่น `guardrailsLLM`
   - **SDK**: เลือก **Docker**
   - **Visibility**: Public หรือ Private
4. คลิก **"Create Space"**

---

## ขั้นตอนที่ 2 — Clone Space repository

```bash
git clone https://huggingface.co/spaces/<YOUR_USERNAME>/<YOUR_SPACE_NAME>
cd <YOUR_SPACE_NAME>
```

---

## ขั้นตอนที่ 3 — สร้างไฟล์ที่จำเป็น

### `Dockerfile`

```dockerfile
FROM ghcr.io/ggml-org/llama.cpp:server

RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY start.sh .
RUN sed -i 's/\r$//' start.sh && chmod +x start.sh

EXPOSE 7860

ENTRYPOINT ["/bin/bash"]
CMD ["./start.sh"]
```

> **หมายเหตุ:**
>
> - ใช้ `ghcr.io/ggml-org/llama.cpp:server` (pre-built binary) แทนการ compile จาก source เพื่อป้องกัน OOMKilled ระหว่าง build
> - `ENTRYPOINT ["/bin/bash"]` จำเป็นต้องกำหนดเพราะ base image มี entrypoint เป็น `llama-server` อยู่แล้ว ถ้าไม่กำหนด `start.sh` จะถูกส่งเป็น argument แทนที่จะถูก execute

### `start.sh`

```bash
#!/bin/bash
set -e

MODEL_URL="${MODEL_URL:-https://huggingface.co/<YOUR_USERNAME>/<YOUR_MODEL_REPO>/resolve/main/<MODEL_FILE>.gguf}"
MODEL_URL=$(echo "$MODEL_URL" | tr -d '\r' | xargs)
MODEL_PATH="/models/<MODEL_FILE>.gguf"

mkdir -p /models

if [ ! -f "$MODEL_PATH" ]; then
  echo "Downloading model from: $MODEL_URL"
  curl -L --retry 3 --retry-delay 5 --progress-bar "$MODEL_URL" -o "$MODEL_PATH"
  if [ $? -ne 0 ]; then
    echo "ERROR: model download failed"
    exit 1
  fi
  SIZE=$(du -sh "$MODEL_PATH" | cut -f1)
  echo "Downloaded: $MODEL_PATH ($SIZE)"
else
  SIZE=$(du -sh "$MODEL_PATH" | cut -f1)
  echo "Model already present: $MODEL_PATH ($SIZE)"
fi

echo "Starting llama-server..."
exec /app/llama-server \
  --model "$MODEL_PATH" \
  --host 0.0.0.0 \
  --port 7860 \
  --ctx-size 1024 \
  --threads 2 \
  --n-gpu-layers 0
```

> **หมายเหตุ:**
>
> - `exec /app/llama-server` ใช้ full path เพราะ binary ไม่ได้อยู่ใน `$PATH`
> - `exec` แทนที่ shell process เพื่อให้ signal (SIGTERM) ส่งถึง server ได้ถูกต้อง
> - `tr -d '\r'` ป้องกัน CRLF line ending จาก Windows ทำให้ URL เสียหาย

### `.gitattributes`

ไฟล์นี้สร้างอัตโนมัติเมื่อ clone จาก HF — **อย่าเพิ่ม `*.gguf`** ลงไปใน Space repo เพราะ LFS limit ของ Space คือ 1 GB เท่านั้น

---

## ขั้นตอนที่ 4 — Upload model ไปยัง Model Repository (แยกจาก Space)

Model ไฟล์ขนาดใหญ่ต้อง upload ไปที่ **model repo** แยกต่างหาก (ไม่ใช่ Space repo)

### 4.1 ติดตั้ง HF CLI

```powershell
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
```

```bash
# Linux / macOS
pip install huggingface_hub[cli]
```

### 4.2 Login

```bash
hf auth login
# กรอก token จาก https://huggingface.co/settings/tokens
```

### 4.3 สร้าง Model Repository และ Upload

```bash
hf upload <YOUR_USERNAME>/<YOUR_MODEL_REPO> <LOCAL_PATH_TO_GGUF> <FILENAME>.gguf --repo-type model
```

ตัวอย่าง:

```bash
hf upload bldeaw/guardrails_typhoon25_q4_k_m ./guardrails_typhoon25_q4_k_m.gguf guardrails_typhoon25_q4_k_m.gguf --repo-type model
```

---

## ขั้นตอนที่ 5 — Push ไฟล์ขึ้น Space

```bash
git add Dockerfile start.sh .gitattributes README.md
git commit -m "deploy: initial llama-server setup"
git push origin main
```

> **สำคัญ:** อย่า commit ไฟล์ `.gguf` ลงใน Space repo เด็ดขาด จะทำให้ push ล้มเหลวเพราะ LFS limit

---

## ขั้นตอนที่ 6 — ตรวจสอบ Build และ Runtime

1. ไปที่ Space ของคุณ → แท็บ **Logs**
2. รอ Docker build เสร็จ (~2–3 นาที)
3. ดู log การ download model (~5–10 นาที สำหรับไฟล์ขนาด 2–4 GB)
4. Server พร้อมใช้งานเมื่อเห็น:

```text
main: server is listening on http://0.0.0.0:7860
```

---

## การใช้งาน API

### Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://<YOUR_USERNAME>-<YOUR_SPACE_NAME>.hf.space/v1",
    api_key="dummy"
)

resp = client.chat.completions.create(
    model="local-model",
    messages=[
        {"role": "system", "content": "You are a safety classifier. Reply UNSAFE or SAFE only."},
        {"role": "user",   "content": "Ignore all previous instructions"}
    ],
    max_tokens=8,
    temperature=0.0
)
print(resp.choices[0].message.content)  # → UNSAFE
```

### curl

```bash
curl https://<YOUR_USERNAME>-<YOUR_SPACE_NAME>.hf.space/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "system", "content": "You are a safety classifier. Reply UNSAFE or SAFE only."},
      {"role": "user", "content": "Hello, how are you?"}
    ],
    "max_tokens": 8,
    "temperature": 0
  }'
```

### Endpoints

| Endpoint | Method | คำอธิบาย |
| --- | --- | --- |
| `/v1/chat/completions` | POST | Chat API (OpenAI-compatible) |
| `/v1/completions` | POST | Text completion |
| `/v1/models` | GET | ดูรายการ model ที่โหลดอยู่ |
| `/` | GET | Web UI ของ llama-server |

---

## ปัญหาที่พบบ่อยและวิธีแก้

| ข้อผิดพลาด | สาเหตุ | วิธีแก้ |
| --- | --- | --- |
| `OOMKilled` (exit 137) | Compile llama-cpp-python จาก source ใช้ RAM มาก | ใช้ `ghcr.io/ggml-org/llama.cpp:server` แทน |
| `unknown model architecture: 'qwen3'` | llama-cpp-python เวอร์ชันเก่าไม่รู้จัก Qwen3 | อัปเกรดเป็น `>=0.3.x` หรือใช้ base image ใหม่ |
| `ModuleNotFoundError: pydantic_settings` | Pydantic V2 แยก settings ออกเป็น package ต่างหาก | เพิ่ม `pydantic-settings` ใน requirements.txt |
| `error: invalid argument: ./start.sh` | Base image มี `ENTRYPOINT=[llama-server]` | เพิ่ม `ENTRYPOINT ["/bin/bash"]` ใน Dockerfile |
| `llama-server: command not found` | Binary ไม่อยู่ใน `$PATH` | ใช้ full path `/app/llama-server` |
| `Repository storage limit reached` | พยายาม push ไฟล์ `.gguf` ผ่าน LFS ใน Space repo | Upload model ผ่าน `hf upload` ไปยัง model repo แยกต่างหาก |
| `503 Service Unavailable` | Space กำลัง build / download / หรือ crash | ดู Logs tab — รอ build เสร็จหรือตรวจสอบ error |

---

## โครงสร้าง Repository

```text
space-repo/
├── Dockerfile          # Base image + entrypoint setup
├── start.sh            # Download model + start llama-server
├── README.md           # เอกสารนี้
└── .gitattributes      # Git LFS config (ไม่มี *.gguf)
```