# EdgeAI untuk Pemula - Bengkel

> **Jalan Pembelajaran Praktikal untuk Membina Aplikasi Edge AI Sedia Pengeluaran**
>
> Kuasai pengendalian AI secara tempatan dengan Microsoft Foundry Local, dari penyelesaian chat pertama hingga orkestrasi multi-agent dalam 6 sesi progresif.

---

## 🎯 Pengenalan

Selamat datang ke **Bengkel EdgeAI untuk Pemula** - panduan praktikal anda untuk membina aplikasi pintar yang berjalan sepenuhnya pada perkakasan tempatan. Bengkel ini mengubah konsep teori Edge AI menjadi kemahiran dunia nyata melalui latihan yang semakin mencabar menggunakan Microsoft Foundry Local dan Small Language Models (SLMs).

### Kenapa Bengkel Ini?

**Revolusi Edge AI Telah Bermula**

Organisasi di seluruh dunia sedang beralih daripada AI bergantung kepada awan kepada pengkomputeran edge atas tiga sebab utama:

1. **Privasi & Pematuhan** - Memproses data sensitif secara tempatan tanpa penghantaran ke awan (HIPAA, GDPR, peraturan kewangan)
2. **Prestasi** - Menghapuskan latensi rangkaian (50-500ms tempatan vs 500-2000ms perjalanan awan)
3. **Kawalan Kos** - Menghapuskan kos API per-token dan skala tanpa perbelanjaan awan

**Tetapi Edge AI Berbeza**

Menjalankan AI secara tempatan memerlukan kemahiran baru:
- Pemilihan dan pengoptimuman model untuk kekangan sumber
- Pengurusan perkhidmatan tempatan dan pecutan perkakasan
- Kejuruteraan prompt untuk model yang lebih kecil
- Corak pengeluaran untuk peranti edge

**Bengkel Ini Menyampaikan Kemahiran Tersebut**

Dalam 6 sesi fokus (~3 jam keseluruhan), anda akan maju dari "Hello World" hingga melancarkan sistem multi-agent sedia pengeluaran - semuanya berjalan secara tempatan pada mesin anda.

---

## 📚 Objektif Pembelajaran

Dengan melengkapkan bengkel ini, anda akan dapat:

### Kompetensi Teras
1. **Melancarkan dan Mengurus Perkhidmatan AI Tempatan**
   - Pasang dan konfigurasi Microsoft Foundry Local
   - Pilih model yang sesuai untuk pelancaran edge
   - Urus kitaran hayat model (muat turun, muatkan, cache)
   - Pantau penggunaan sumber dan optimalkan prestasi

2. **Membina Aplikasi Berkuasa AI**
   - Laksanakan penyelesaian chat yang serasi dengan OpenAI secara tempatan
   - Reka bentuk prompt yang berkesan untuk Small Language Models
   - Tangani respons streaming untuk UX yang lebih baik
   - Integrasi model tempatan ke dalam aplikasi sedia ada

3. **Mencipta Sistem RAG (Retrieval Augmented Generation)**
   - Bina carian semantik dengan embeddings
   - Asaskan respons LLM dalam pengetahuan khusus domain
   - Nilai kualiti RAG dengan metrik standard industri
   - Skala dari prototaip ke pengeluaran

4. **Optimalkan Prestasi Model**
   - Benchmark pelbagai model untuk kes penggunaan anda
   - Ukur latensi, throughput, dan masa token pertama
   - Pilih model optimum berdasarkan kompromi kelajuan/kualiti
   - Bandingkan kompromi SLM vs LLM dalam senario sebenar

5. **Orkestrasi Sistem Multi-Agent**
   - Reka bentuk agen khusus untuk tugas yang berbeza
   - Laksanakan memori agen dan pengurusan konteks
   - Koordinasi agen dalam aliran kerja yang kompleks
   - Laluan permintaan secara pintar merentasi pelbagai model

6. **Melancarkan Penyelesaian Sedia Pengeluaran**
   - Laksanakan pengendalian ralat dan logik ulang
   - Pantau penggunaan token dan sumber sistem
   - Bina seni bina yang boleh diskala dengan corak model-sebagai-alat
   - Rancang laluan migrasi dari edge ke hibrid (edge + awan)

---

## 🎓 Hasil Pembelajaran

### Apa yang Akan Anda Bina

Menjelang akhir bengkel ini, anda akan menghasilkan:

| Sesi | Hasil | Kemahiran Ditunjukkan |
|------|-------|------------------------|
| **1** | Aplikasi chat dengan streaming | Persediaan perkhidmatan, penyelesaian asas, UX streaming |
| **2** | Sistem RAG dengan penilaian | Embeddings, carian semantik, metrik kualiti |
| **3** | Suite benchmark multi-model | Pengukuran prestasi, perbandingan model |
| **4** | Perbandingan SLM vs LLM | Analisis kompromi, strategi pengoptimuman |
| **5** | Orkestrator multi-agent | Reka bentuk agen, pengurusan memori, koordinasi |
| **6** | Sistem laluan pintar | Pengesanan niat, pemilihan model, skalabiliti |

### Matriks Kompetensi

| Tahap Kemahiran | Sesi 1-2 | Sesi 3-4 | Sesi 5-6 |
|-----------------|----------|----------|----------|
| **Pemula** | ✅ Persediaan & asas | ⚠️ Mencabar | ❌ Terlalu maju |
| **Pertengahan** | ✅ Ulasan pantas | ✅ Pembelajaran teras | ⚠️ Matlamat regangan |
| **Maju** | ✅ Mudah dilalui | ✅ Penapisan | ✅ Corak pengeluaran |

### Kemahiran Sedia Kerjaya

**Selepas bengkel ini, anda akan bersedia untuk:**

✅ **Membina Aplikasi Berorientasi Privasi**
- Aplikasi penjagaan kesihatan yang mengendalikan PHI/PII secara tempatan
- Perkhidmatan kewangan dengan keperluan pematuhan
- Sistem kerajaan dengan keperluan kedaulatan data

✅ **Optimalkan untuk Persekitaran Edge**
- Peranti IoT dengan sumber terhad
- Aplikasi mudah alih yang berorientasi offline
- Sistem masa nyata dengan latensi rendah

✅ **Reka Bentuk Seni Bina Pintar**
- Sistem multi-agent untuk aliran kerja kompleks
- Pelancaran hibrid edge-awan
- Infrastruktur AI yang dioptimumkan kos

✅ **Memimpin Inisiatif Edge AI**
- Menilai kebolehlaksanaan Edge AI untuk projek
- Pilih model dan rangka kerja yang sesuai
- Reka bentuk penyelesaian AI tempatan yang boleh diskala

---

## 🗺️ Struktur Bengkel

### Gambaran Keseluruhan Sesi (6 Sesi × 30 Minit = 3 Jam)

| Sesi | Topik | Fokus | Tempoh |
|------|-------|-------|--------|
| **1** | Bermula dengan Foundry Local | Pasang, sahkan, penyelesaian pertama | 30 min |
| **2** | Membina Penyelesaian AI dengan RAG | Kejuruteraan prompt, embeddings, penilaian | 30 min |
| **3** | Model Sumber Terbuka | Penemuan model, benchmarking, pemilihan | 30 min |
| **4** | Model Terkini | SLM vs LLM, pengoptimuman, rangka kerja | 30 min |
| **5** | Agen Berkuasa AI | Reka bentuk agen, orkestrasi, memori | 30 min |
| **6** | Model sebagai Alat | Laluan, rantai, strategi skalabiliti | 30 min |

---

## 🚀 Permulaan Pantas

### Prasyarat

**Keperluan Sistem:**
- **OS**: Windows 10/11, macOS 11+, atau Linux (Ubuntu 20.04+)
- **RAM**: Minimum 8GB, disyorkan 16GB+
- **Storan**: Ruang kosong 10GB+ untuk model
- **CPU**: Pemproses moden dengan sokongan AVX2
- **GPU** (pilihan): Serasi CUDA atau Qualcomm NPU untuk pecutan

**Keperluan Perisian:**
- **Python 3.8+** ([Muat Turun](https://www.python.org/downloads/))
- **Microsoft Foundry Local** ([Panduan Pemasangan](../../../Workshop))
- **Git** ([Muat Turun](https://git-scm.com/downloads))
- **Visual Studio Code** (disyorkan) ([Muat Turun](https://code.visualstudio.com/))

### Persediaan dalam 3 Langkah

#### 1. Pasang Foundry Local

**Windows:**
```powershell
winget install Microsoft.FoundryLocal
```

**macOS:**
```bash
brew tap microsoft/foundrylocal
brew install foundrylocal
```

**Sahkan Pemasangan:**
```bash
foundry --version
foundry service status
```

**Pastikan Azure AI Foundry Local berjalan dengan port tetap**

```bash
# Set FoundryLocal to use port 58123 (default)
foundry service set --port 58123 --show

# Or use a different port
foundry service set --port 58000 --show
```

**Sahkan ia berfungsi:**
```bash
# Check service status
foundry service status

# Test the endpoint
curl http://127.0.0.1:58123/v1/models
```
**Mencari Model Tersedia**
Untuk melihat model yang tersedia dalam instance Foundry Local anda, anda boleh membuat pertanyaan ke endpoint model:

```bash
# cmd/bash/powershell
foundry model list
```

Menggunakan Endpoint Web 

```bash
# Windows PowerShell
powershell -Command "Invoke-RestMethod -Uri 'http://127.0.0.1:58123/v1/models' -Method Get"

# Or using curl (if available)
curl http://127.0.0.1:58123/v1/models
```

#### 2. Clone Repository & Pasang Kebergantungan

```bash
# Clone repository
git clone https://github.com/microsoft/edgeai-for-beginners.git
cd edgeai-for-beginners/Workshop

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.\.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

#### 3. Jalankan Sampel Pertama Anda

```bash
# Start Foundry Local and load a model
foundry model run phi-4-mini

# Run the chat bootstrap sample
cd samples
python -m session01.chat_bootstrap "What is edge AI?"
```

**✅ Berjaya!** Anda sepatutnya melihat respons streaming tentang edge AI.

---

## 📦 Sumber Bengkel

### Sampel Python

Contoh praktikal progresif yang menunjukkan setiap konsep:

| Sesi | Sampel | Penerangan | Masa Jalankan |
|------|--------|------------|---------------|
| 1 | [`chat_bootstrap.py`](../../../Workshop/samples/session01/chat_bootstrap.py) | Chat asas & streaming | ~30s |
| 2 | [`rag_pipeline.py`](../../../Workshop/samples/session02/rag_pipeline.py) | RAG dengan embeddings | ~45s |
| 2 | [`rag_eval_ragas.py`](../../../Workshop/samples/session02/rag_eval_ragas.py) | Penilaian kualiti RAG | ~60s |
| 3 | [`benchmark_oss_models.py`](../../../Workshop/samples/session03/benchmark_oss_models.py) | Benchmarking multi-model | ~2-3m |
| 4 | [`model_compare.py`](../../../Workshop/samples/session04/model_compare.py) | Perbandingan SLM vs LLM | ~45s |
| 5 | [`agents_orchestrator.py`](../../../Workshop/samples/session05/agents_orchestrator.py) | Sistem multi-agent | ~60s |
| 6 | [`models_router.py`](../../../Workshop/samples/session06/models_router.py) | Laluan berdasarkan niat | ~45s |
| 6 | [`models_pipeline.py`](../../../Workshop/samples/session06/models_pipeline.py) | Pipeline multi-langkah | ~60s |

### Jupyter Notebooks

Eksplorasi interaktif dengan penjelasan dan visualisasi:

| Sesi | Notebook | Penerangan | Kesukaran |
|------|----------|------------|-----------|
| 1 | [`session01_chat_bootstrap.ipynb`](./notebooks/session01_chat_bootstrap.ipynb) | Asas chat & streaming | ⭐ Pemula |
| 2 | [`session02_rag_pipeline.ipynb`](./notebooks/session02_rag_pipeline.ipynb) | Bina sistem RAG | ⭐⭐ Pertengahan |
| 2 | [`session02_rag_eval_ragas.ipynb`](./notebooks/session02_rag_eval_ragas.ipynb) | Nilai kualiti RAG | ⭐⭐ Pertengahan |
| 3 | [`session03_benchmark_oss_models.ipynb`](./notebooks/session03_benchmark_oss_models.ipynb) | Benchmarking model | ⭐⭐ Pertengahan |
| 4 | [`session04_model_compare.ipynb`](./notebooks/session04_model_compare.ipynb) | Perbandingan model | ⭐⭐ Pertengahan |
| 5 | [`session05_agents_orchestrator.ipynb`](./notebooks/session05_agents_orchestrator.ipynb) | Orkestrasi agen | ⭐⭐⭐ Maju |
| 6 | [`session06_models_router.ipynb`](./notebooks/session06_models_router.ipynb) | Laluan niat | ⭐⭐⭐ Maju |
| 6 | [`session06_models_pipeline.ipynb`](./notebooks/session06_models_pipeline.ipynb) | Orkestrasi pipeline | ⭐⭐⭐ Maju |

### Dokumentasi

Panduan dan rujukan yang komprehensif:

| Dokumen | Penerangan | Gunakan Apabila |
|---------|------------|-----------------|
| [QUICK_START.md](./QUICK_START.md) | Panduan persediaan pantas | Bermula dari awal |
| [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) | Lembaran rujukan arahan & API | Perlukan jawapan pantas |
| [FOUNDRY_SDK_QUICKREF.md](./FOUNDRY_SDK_QUICKREF.md) | Corak SDK & contoh | Menulis kod |
| [ENV_CONFIGURATION.md](./ENV_CONFIGURATION.md) | Panduan pembolehubah persekitaran | Konfigurasi sampel |
| [notebooks/TROUBLESHOOTING.md](./notebooks/TROUBLESHOOTING.md) | Isu biasa & penyelesaian | Menyelesaikan masalah |

---

## 🎓 Cadangan Laluan Pembelajaran

### Untuk Pemula (3-4 jam)
1. ✅ Sesi 1: Bermula (fokus pada persediaan dan chat asas)
2. ✅ Sesi 2: Asas RAG (langkau penilaian pada awalnya)
3. ✅ Sesi 3: Benchmarking mudah (2 model sahaja)
4. ⏭️ Langkau Sesi 4-6 buat masa ini
5. 🔄 Kembali ke Sesi 4-6 selepas membina aplikasi pertama

### Untuk Pembangun Pertengahan (3 jam)
1. ⚡ Sesi 1: Pengesahan persediaan pantas
2. ✅ Sesi 2: Lengkapkan pipeline RAG dengan penilaian
3. ✅ Sesi 3: Suite benchmarking penuh
4. ✅ Sesi 4: Pengoptimuman model
5. ✅ Sesi 5-6: Fokus pada corak seni bina

### Untuk Pengamal Maju (2-3 jam)
1. ⚡ Sesi 1-3: Ulasan dan pengesahan pantas
2. ✅ Sesi 4: Pengoptimuman mendalam
3. ✅ Sesi 5: Seni bina multi-agent
4. ✅ Sesi 6: Corak pengeluaran dan skalabiliti
5. 🚀 Lanjutkan: Bina logik laluan tersuai dan pelancaran hibrid

---

## Pek Sesi Bengkel (Makmal Fokus 30‑Minit)

Jika anda mengikuti format bengkel 6 sesi yang dipadatkan, gunakan panduan khusus ini (setiap satu memetakan dan melengkapi dokumen modul yang lebih luas di atas):

| Sesi Bengkel | Panduan | Fokus Teras |
|--------------|---------|-------------|
| 1 | [Session01-GettingStartedFoundryLocal](./Session01-GettingStartedFoundryLocal.md) | Pasang, sahkan, jalankan phi & GPT-OSS-20B, pecutan |
| 2 | [Session02-BuildAISolutionsRAG](./Session02-BuildAISolutionsRAG.md) | Kejuruteraan prompt, corak RAG, CSV & dokumen asas, migrasi |
| 3 | [Session03-OpenSourceModels](./Session03-OpenSourceModels.md) | Integrasi Hugging Face, benchmarking, pemilihan model |
| 4 | [Session04-CuttingEdgeModels](./Session04-CuttingEdgeModels.md) | SLM vs LLM, WebGPU, Chainlit RAG, pecutan ONNX |
| 5 | [Session05-AIPoweredAgents](./Session05-AIPoweredAgents.md) | Peranan agen, memori, alat, orkestrasi |
| 6 | [Session06-ModelsAsTools](./Session06-ModelsAsTools.md) | Penghalaan, penggabungan, skala laluan ke Azure |

Setiap fail sesi termasuk: abstrak, objektif pembelajaran, aliran demo 30 minit, projek permulaan, senarai semak pengesahan, penyelesaian masalah, dan rujukan kepada Foundry Local Python SDK rasmi.

### Skrip Contoh

Pasang keperluan bengkel (Windows):

```powershell
cd Workshop
py -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
```

macOS / Linux:

```bash
cd Workshop
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Jika menjalankan perkhidmatan Foundry Local pada mesin atau VM (Windows) yang berbeza daripada macOS, eksport titik akhir:

```bash
export FOUNDRY_LOCAL_ENDPOINT=http://<windows-host>:5273/v1
```

| Sesi | Skrip | Penerangan |
|------|-------|------------|
| 1 | `samples/session01/chat_bootstrap.py` | Perkhidmatan permulaan & sembang streaming |
| 2 | `samples/session02/rag_pipeline.py` | RAG minimum (embedding dalam memori) |
|   | `samples/session02/rag_eval_ragas.py` | Penilaian RAG dengan metrik ragas |
| 3 | `samples/session03/benchmark_oss_models.py` | Penanda aras kependaman & throughput pelbagai model |
| 4 | `samples/session04/model_compare.py` | Perbandingan SLM vs LLM (kependaman & output sampel) |
| 5 | `samples/session05/agents_orchestrator.py` | Penyelidikan dua ejen → saluran editorial |
| 6 | `samples/session06/models_router.py` | Demo penghalaan berdasarkan niat |
|   | `samples/session06/models_pipeline.py` | Rantaian rancangan/laksana/perbaiki pelbagai langkah |

### Pembolehubah Persekitaran (Umum untuk Semua Sampel)

| Pembolehubah | Tujuan | Contoh |
|--------------|--------|--------|
| `FOUNDRY_LOCAL_ALIAS` | Alias model tunggal lalai untuk sampel asas | `phi-4-mini` |
| `SLM_ALIAS` / `LLM_ALIAS` | SLM eksplisit vs model lebih besar untuk perbandingan | `phi-4-mini` / `gpt-oss-20b` |
| `BENCH_MODELS` | Senarai alias untuk penanda aras | `qwen2.5-0.5b,mistral-7b` |
| `BENCH_ROUNDS` | Ulangan penanda aras setiap model | `3` |
| `BENCH_PROMPT` | Prompt yang digunakan dalam penanda aras | `Explain retrieval augmented generation briefly.` |
| `EMBED_MODEL` | Model embedding sentence-transformers | `sentence-transformers/all-MiniLM-L6-v2` |
| `RAG_QUESTION` | Menimpa pertanyaan ujian untuk saluran RAG | `Why use RAG with local inference?` |
| `AGENT_QUESTION` | Menimpa pertanyaan saluran ejen | `Explain why edge AI matters for compliance.` |
| `AGENT_MODEL_PRIMARY` | Alias model untuk ejen penyelidikan | `phi-4-mini` |
| `AGENT_MODEL_EDITOR` | Alias model untuk ejen editor (boleh berbeza) | `gpt-oss-20b` |
| `SHOW_USAGE` | Apabila `1`, mencetak penggunaan token setiap penyelesaian | `1` |
| `RETRY_ON_FAIL` | Apabila `1`, cuba semula sekali pada ralat sembang sementara | `1` |
| `RETRY_BACKOFF` | Saat untuk menunggu sebelum mencuba semula | `1.0` |

Jika pembolehubah tidak ditetapkan, skrip akan kembali kepada tetapan lalai yang munasabah. Untuk demo model tunggal, biasanya hanya perlu `FOUNDRY_LOCAL_ALIAS`.

### Modul Utiliti

Semua sampel kini berkongsi pembantu `samples/workshop_utils.py` yang menyediakan:

* Penciptaan cache `FoundryLocalManager` + klien OpenAI
* Pembantu `chat_once()` dengan pilihan cuba semula + cetakan penggunaan
* Laporan penggunaan token yang mudah (aktifkan melalui `SHOW_USAGE=1`)

Ini mengurangkan pengulangan dan menonjolkan amalan terbaik untuk orkestrasi model tempatan yang cekap.

## Penambahbaikan Pilihan (Merentas Sesi)

| Tema | Penambahbaikan | Sesi | Env / Togol |
|------|----------------|------|-------------|
| Ketentuan | Suhu tetap + set prompt stabil | 1–6 | Tetapkan `temperature=0`, `top_p=1` |
| Penglihatan Penggunaan Token | Pengajaran kos/kecekapan yang konsisten | 1–6 | `SHOW_USAGE=1` |
| Penstriman Token Pertama | Metrik kependaman yang dirasakan | 1,3,4,6 | `BENCH_STREAM=1` (penanda aras) |
| Ketahanan Cuba Semula | Menangani permulaan sejuk sementara | Semua | `RETRY_ON_FAIL=1` + `RETRY_BACKOFF` |
| Ejen Pelbagai Model | Pengkhususan peranan heterogen | 5 | `AGENT_MODEL_PRIMARY`, `AGENT_MODEL_EDITOR` |
| Penghalaan Adaptif | Niat + heuristik kos | 6 | Kembangkan penghala dengan logik eskalasi |
| Memori Vektor | Ingatan semantik jangka panjang | 2,5,6 | Integrasi indeks embedding FAISS/Chroma |
| Eksport Jejak | Audit & penilaian | 2,5,6 | Tambah baris JSON setiap langkah |
| Rubrik Kualiti | Penjejakan kualitatif | 3–6 | Prompt penilaian sekunder |
| Ujian Asap | Pengesahan pra-bengkel cepat | Semua | `python Workshop/tests/smoke.py` |

### Permulaan Cepat Deterministik

```powershell
set FOUNDRY_LOCAL_ALIAS=phi-4-mini
set SHOW_USAGE=1
python Workshop\tests\smoke.py
```

Jangka penggunaan token yang stabil merentasi input yang sama berulang.

### Penilaian RAG (Sesi 2)

Gunakan `rag_eval_ragas.py` untuk mengira relevansi jawapan, kesetiaan, dan ketepatan konteks pada dataset sintetik kecil:

```powershell
cd Workshop/samples
python -m session02.rag_eval_ragas
```

Kembangkan dengan membekalkan JSONL yang lebih besar bagi soalan, konteks, dan kebenaran asas, kemudian menukarnya kepada `Dataset` Hugging Face.

## Lampiran Ketepatan Perintah CLI

Bengkel ini sengaja menggunakan hanya perintah CLI Foundry Local yang didokumentasikan / stabil pada masa ini.

### Perintah Stabil yang Dirujuk

| Kategori | Perintah | Tujuan |
|----------|----------|--------|
| Teras | `foundry --version` | Tunjukkan versi yang dipasang |
| Perkhidmatan | `foundry service start` | Mulakan perkhidmatan tempatan (jika tidak automatik) |
| Perkhidmatan | `foundry service status` | Tunjukkan status perkhidmatan |
| Model | `foundry model list` | Senaraikan katalog / model yang tersedia |
| Model | `foundry model download <alias>` | Muat turun berat model ke cache |
| Model | `foundry model run <alias>` | Lancarkan (muat) model secara tempatan; gabungkan dengan `--prompt` untuk satu kali |
| Model | `foundry model unload <alias>` / `foundry model stop <alias>` | Nyahmuat model dari memori (jika disokong) |
| Cache | `foundry cache list` | Senaraikan model yang di-cache (dimuat turun) |

### Corak Prompt Satu Kali

Sebagai ganti subperintah `model chat` yang tidak lagi digunakan, gunakan:

```powershell
foundry model run <alias> --prompt "Your question here"
```

Ini melaksanakan satu kitaran prompt/respons kemudian keluar.

### Corak yang Dihapus / Dielakkan

| Tidak Digunakan / Tidak Didokumentasikan | Penggantian / Panduan |
|------------------------------------------|------------------------|
| `foundry model chat <model> "..."` | `foundry model run <model> --prompt "..."` |
| `foundry model list --running` | Gunakan `foundry model list` biasa + aktiviti terkini / log |
| `foundry model list --cached` | `foundry cache list` |
| `foundry model stats <model>` | Gunakan skrip penanda aras Python + alat OS (Task Manager / `nvidia-smi`) |
| `foundry model benchmark ...` | `samples/session03/benchmark_oss_models.py` |

### Penanda Aras & Telemetri

- Kependaman, p95, token/saat: `samples/session03/benchmark_oss_models.py`
- Kependaman token pertama (penstriman): tetapkan `BENCH_STREAM=1`
- Penggunaan sumber: pemantau OS (Task Manager, Activity Monitor, `nvidia-smi`).

Apabila perintah telemetri CLI baru stabil, ia boleh dimasukkan dengan pengeditan minimum pada markdown sesi.

### Penjaga Lint Automatik

Lint automatik menghalang pengenalan semula corak CLI yang tidak lagi digunakan dalam blok kod berpagar fail markdown:

Skrip: `Workshop/scripts/lint_markdown_cli.py`

Corak yang tidak lagi digunakan disekat dalam pagar kod.

Penggantian yang disyorkan:
| Tidak Digunakan | Penggantian |
|-----------------|-------------|
| `foundry model chat <a> "..."` | `foundry model run <a> --prompt "..."` |
| `model list --running` | `model list` |
| `model list --cached` | `cache list` |
| `model stats` | Skrip penanda aras + alat sistem |
| `model benchmark` | `samples/session03/benchmark_oss_models.py` |
| `model list --available` | `model list` |

Jalankan secara tempatan:
```powershell
python Workshop\scripts\lint_markdown_cli.py --verbose
```

GitHub Action: `.github/workflows/markdown-cli-lint.yml` dijalankan pada setiap push & PR.

Hook pra-komit pilihan:
```bash
echo "python Workshop/scripts/lint_markdown_cli.py" > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

## Jadual Migrasi CLI → SDK Cepat

| Tugas | Perintah CLI Satu Baris | Setara SDK (Python) | Nota |
|-------|--------------------------|---------------------|------|
| Jalankan model sekali (prompt) | `foundry model run phi-4-mini --prompt "Hello"` | `manager=FoundryLocalManager("phi-4-mini"); client=OpenAI(base_url=manager.endpoint, api_key=manager.api_key or "not-needed"); client.chat.completions.create(model=manager.get_model_info("phi-4-mini").id, messages=[{"role":"user","content":"Hello"}])` | SDK secara automatik memulakan perkhidmatan & cache |
| Muat turun (cache) model | `foundry model download qwen2.5-0.5b` | `FoundryLocalManager("qwen2.5-0.5b")  # triggers download/load` | Pengurus memilih varian terbaik jika alias memetakan kepada beberapa binaan |
| Senaraikan katalog | `foundry model list` | `# gunakan pengurus untuk setiap alias atau mengekalkan senarai yang diketahui` | CLI mengagregat; SDK kini per-alias inisialisasi |
| Senaraikan model yang di-cache | `foundry cache list` | `manager.list_cached_models()` | Selepas inisialisasi pengurus (mana-mana alias) |
| Dapatkan URL titik akhir | (implisit) | `manager.endpoint` | Digunakan untuk mencipta klien yang serasi dengan OpenAI |
| Panaskan model | `foundry model run <alias>` kemudian prompt pertama | `chat_once(alias, messages=[...])` (utiliti) | Utiliti menangani pemanasan kependaman sejuk awal |
| Ukur kependaman | `python -m session03.benchmark_oss_models` | `import benchmark_oss_models` (atau skrip pengeksport baru) | Lebih suka skrip untuk metrik yang konsisten |
| Hentikan / nyahmuat model | `foundry model unload <alias>` | (Tidak didedahkan – mulakan semula perkhidmatan / proses) | Biasanya tidak diperlukan untuk aliran bengkel |
| Dapatkan penggunaan token | (lihat output) | `resp.usage.total_tokens` | Disediakan jika backend mengembalikan objek penggunaan |

## Eksport Markdown Penanda Aras

Gunakan skrip `Workshop/scripts/export_benchmark_markdown.py` untuk menjalankan penanda aras baru (logik yang sama seperti `samples/session03/benchmark_oss_models.py`) dan mengeluarkan jadual Markdown mesra GitHub serta JSON mentah.

### Contoh

```powershell
python Workshop\scripts\export_benchmark_markdown.py --models "qwen2.5-0.5b,mistral-7b" --prompt "Explain retrieval augmented generation briefly." --rounds 3 --output benchmark_report.md
```

Fail yang dihasilkan:
| Fail | Kandungan |
|------|-----------|
| `benchmark_report.md` | Jadual Markdown + petunjuk tafsiran |
| `benchmark_report.json` | Susunan metrik mentah (untuk perbezaan / penjejakan trend) |

Tetapkan `BENCH_STREAM=1` dalam persekitaran untuk memasukkan kependaman token pertama jika disokong.

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Penafian**:  
Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil perhatian bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang berwibawa. Untuk maklumat penting, terjemahan manusia profesional adalah disyorkan. Kami tidak bertanggungjawab atas sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->