# คู่มือ AI ของ wxch (สถานะ 21 ต.ค. 2026)

คู่มือนี้อธิบายส่วน AI ของระบบ: มีอะไร ใช้อย่างไร ดูแลอย่างไร อะไรทดสอบแล้ว อะไรยังไม่ได้ทดสอบ และข้อเสนอแนะ
ภาษาไทยเป็นหลัก ชื่อคำสั่งและไฟล์เป็นภาษาอังกฤษตามจริง

## 1. โค้ดอยู่ที่ไหน

- **อ่านและคัดลอกได้ที่ [gitai.wxch.org](https://gitai.wxch.org)** เป็นสำเนาสาธารณะอ่านอย่างเดียว เปิดดูไฟล์ในเบราว์เซอร์ที่ `/src/`
  หรือคัดลอกลงเครื่องด้วย `git clone https://gitai.wxch.org/gitai.git`
- สำเนานี้เป็น **snapshot ที่คัดกรองแล้ว** ไม่ใช่ repo ที่ใช้ทำงานทุกวัน: ไม่มีบันทึกภายใน คำสั่งภายใน และไม่มีประวัติเก่า
  repo ที่ใช้ทำงานจริงเป็นของผู้ดูแลและไม่เปิดสาธารณะ
- สำเนาที่ gitai ถูกอัปเดตด้วยสคริปต์ภายในของผู้ดูแล (ไม่เปิดสาธารณะ เพราะผูกกับเซิร์ฟเวอร์ของผู้ดูแล) ซึ่งตรวจหาความลับและไอพีภายในก่อนอัปโหลดทุกครั้ง
  และตรวจซ้ำจากภายนอกหลังอัปโหลด
- ยังไม่มี license: อ่านได้แต่ยังไม่มีสิทธิ์คัดลอก รัน หรือแจกจ่าย ดู [GOVERNANCE.md](../GOVERNANCE.md) (ร่างเจตนารมณ์ ไม่ใช่ข้อความกฎหมาย)

## 2. ภาพรวมระบบ

| ส่วน | ที่อยู่ | ใช้ทำอะไร |
|---|---|---|
| หน้า Control | `control.wxch.org` | เทอร์มินัลบนเครื่อง สถานะเครื่อง โมเดล โมดูล AI API key |
| แชต | `chat.wxch.org` | คุยกับโมเดลที่เครื่อง GPU เปิดไว้ |
| Studio | `studio.wxch.org` | สร้างภาพ วิดีโอ แก้ภาพ/วิดีโอ ถอดเสียง |
| API (แบบ OpenAI) | `api.wxch.org` | ให้โปรแกรมอื่นเรียกโมเดลผ่าน API key |
| ComfyUI (ผู้ดูแล) | `comfy.wxch.org` | หน้า ComfyUI ของ engine ภาพ/วิดีโอ |
| เครื่อง GPU | `pgx` (NVIDIA GB10, หน่วยความจำรวม ~121 GB) | agent + runtime ทำงานจริง เครื่องเชื่อมออกมาเอง ไม่ต้องเปิดพอร์ต |

โมเดลแชตรันผ่าน **Ollama**, **LM Studio** หรือ **vLLM** (แยกกัน เลือกตามรุ่น) ส่วนภาพ/วิดีโอ/เสียงรันผ่าน **ComfyUI** และ **Whisper**
โดยตรงบนเครื่อง (ไม่ใช้ Docker เป็นค่าเริ่มต้น)

## 3. โมเดลที่ใช้ได้ และสถานะที่ตรวจแล้ว

รายการเต็มอยู่ใน `catalog/catalog.json` (ขนาดและ license อ่านจาก registry ไม่ได้เดา)

| รุ่น | ผ่าน | ขนาดไฟล์ | สถานะ |
|---|---|---|---|
| Nemotron 3 Super 120B-A12B (NVFP4) | vLLM | 80.4 GB | **ใช้ได้จริงในแชต** |
| Nemotron 3.5 Super VL 120B-A12B (NVFP4) | vLLM | 76.7 GB | **ใช้ได้จริงในแชต** (ต้องเปิด `--trust-remote-code` เฉพาะรุ่นนี้ ดูหัวข้อ 6) |
| Qwen3-Coder-Next | Ollama | 51.7 GB | ติดตั้งแล้ว |
| Nemotron 3.5 Lightning 30B-A3B (NVFP4) | vLLM | 21.6 GB | อยู่ในแคตตาล็อก **ยังไม่ได้ลอง** |
| Nemotron 3.5 Bolt 74B-A9B (2-bit) | LM Studio | 23.8 GB | อยู่ในแคตตาล็อก **ยังไม่ได้ลอง** (2-bit อาจเสียคุณภาพ ควรเทียบกับรุ่นโค้ดอื่น) |
| FLUX.1-schnell fp8 (สร้างภาพ) | ComfyUI | 17.2 GB | **ใช้ได้** ทดสอบ 21 ต.ค. |
| Wan 2.2 5B (วิดีโอ) | ComfyUI | ดู `catalog/modules.json` | ใช้ได้ แต่ช้า (ดูหัวข้อ 7) |

หน่วยความจำของ pgx ใช้ร่วมกันทั้งหมด (CPU/GPU/ระบบ): **รุ่น 120B กินมาก** (ตอนโหลด Super VL เครื่องใช้หน่วยความจำไป 101 GB รวมระบบ เหลือว่างราว 20 GB) จึงรันพร้อมงานภาพ (~24 GB) ไม่ได้
ถ้าจะสร้างภาพ/วิดีโอ ให้กด **Unload** รุ่น 120B ที่หน้า Models ก่อน ส่วน Lightning และ Bolt เล็กพอจะรันคู่กับงานภาพได้ (ตามการประมาณ ยังไม่ได้วัด)

## 4. ใช้งานประจำวัน

- **คุยกับโมเดล:** เปิด `chat.wxch.org` เลือกโมเดล (ครั้งแรกโหลดหลายนาที) รุ่นที่ไม่มีเครื่องออนไลน์จะแสดงสถานะบอก
- **สร้างภาพ:** `studio.wxch.org` เลือก "Generate images" ใส่ prompt เลือกขนาด (512×512 เร็วสุด) กด Start ผลเก็บ 7 วัน
- **เรียกจากโปรแกรม:** หน้า Control แท็บ API สร้าง key แล้วใช้ Base URL ที่หน้าแสดง ใช้กับโปรแกรมที่รองรับ OpenAI API ได้
- **ดูสถานะเครื่อง:** แท็บ "Machine status" แสดง CPU/GPU/หน่วยความจำ/ดิสก์/อุณหภูมิ และเครื่องที่หลุดจะบอกว่า "ออฟไลน์ตั้งแต่เมื่อไร"
- **ปล่อยหน่วยความจำ:** แท็บ Models กด Unload ที่รุ่นที่โหลดอยู่

## 5. ติดตั้งและอัปเดต

เครื่อง GPU ใหม่ (คำสั่งจากหน้า Control ปุ่ม ⎘ ที่การ์ดเครื่อง รันบนตัวเครื่อง จะขอรหัส sudo หนึ่งครั้ง):

```
curl -fsSL https://control.wxch.org/get | WXCH_TOKEN=<token ของเครื่อง> sh
```

| ต้องการ | คำสั่งหรือวิธี |
|---|---|
| ติดตั้งโมดูลภาพ/วิดีโอ/เสียง | หน้า Control แท็บ "AI modules" ติ๊กแล้วกด Install selected (ไม่ติดตั้งมาให้ เห็นขนาดรวมก่อน) |
| อัปเดต agent + runner บนเครื่อง | `curl -fsSL https://control.wxch.org/get \| WXCH_ONLY=agent,vllm sh` ห้ามรันระหว่างมีงานดาวน์โหลด/สร้างภาพ เพราะ agent รีสตาร์ต |
| เปิดสิทธิ์ `--trust-remote-code` ให้โมเดลหนึ่งรุ่น | `curl -fsSL https://control.wxch.org/get \| WXCH_ONLY=vllm WXCH_TRUST_REMOTE_CODE=org/ชื่อรุ่น sh` |
| เพิ่มดิสก์ external | `... \| sh -s -- add-disk` (ดู [INSTALL.md](INSTALL.md)) |

รันตัวติดตั้งจากเทอร์มินัลในหน้าเว็บได้ ถ้า agent รีสตาร์ตกลางทางจนเทอร์มินัลหลุด หน้าเว็บจะรอเครื่องกลับมาแล้วเปิดแท็บ
"log ตัวติดตั้ง" ให้เอง ตามไปจนขึ้น `DONE` หรือ `FINISHED WITH ERRORS` (log เต็มอยู่ที่ `/var/log/wxch-setup.log` บนเครื่อง)

## 6. ความปลอดภัยของโมเดลและ runner

- agent ขอสวิตช์ vLLM ที่ runner ไม่อนุญาตไม่ได้ (รายการอนุญาตอยู่ใน `cmd/wxch-runner/main.go`)
- `--trust-remote-code` (รันโค้ด Python ที่แถมมากับโมเดล) **ปิดเป็นค่าเริ่มต้น** เปิดได้เฉพาะรุ่นที่ root ใส่ชื่อไว้ใน `trust_remote_code`
  ของ `/etc/wxch/runner.json` เท่านั้น ตัวติดตั้งเก็บรายการนี้ไว้ข้ามการติดตั้งซ้ำ ก่อนเปิดให้รุ่นใหม่ควรอ่านโค้ดใน repo ของโมเดลก่อน
- ไฟล์โมเดลของโมดูล AI ตรวจ sha256 หลังดาวน์โหลด ไฟล์ที่ขนาดถูกแต่เสียหายจะถูกลบแล้วโหลดใหม่
- เจ้าของเครื่องมาก่อน: ระบบหยุดรับงานและปล่อยโมเดลเมื่อเจ้าของใช้เครื่อง และชะลอ/หยุดงานของเราเมื่อ CPU เกิน 90 °C หรือ GPU เกิน 80 °C (ปรับได้ที่แท็บ Machine status)

## 7. เวลาที่วัดได้จริง (pgx, 21 ต.ค. 2026)

| งาน | เวลา | หมายเหตุ |
|---|---|---|
| ภาพ 512×512 ครั้งแรก | 2 นาที 2 วินาที | รวมเริ่ม engine และโหลดโมเดล |
| ภาพ 1024×1024 (engine อุ่น) | 1 นาที 56 วินาที | สร้างเสร็จที่ ~1 นาที 22 วินาที ส่งผลกลับอีก ~35 วินาที (ช้าผิดปกติ ยังไม่ได้ตรวจ) |
| วิดีโอ (9 ต.ค.) | 2 นาที 13 วินาที เมื่อใช้ `--disable-dynamic-vram` เทียบกับราว 9 นาทีเมื่อไม่ใช้ | ตอนนี้สวิตช์นี้ตั้งด้วยมือที่ `engine-args.txt` ยังไม่เป็นค่าเริ่มต้น |
| วิดีโอ (17 ต.ค.) | 3 นาที 56 วินาที และ 6 นาที 8 วินาที | งานจริงของผู้ใช้ |

ตัวเลขหน่วยความจำและเวลาใน `catalog/modules.json` ยังเป็นค่าประมาณ (`measured: false`) ยกเว้นที่ระบุข้างบน

## 8. แก้ปัญหา

| อาการ | สาเหตุที่เจอมา | วิธีดู/แก้ |
|---|---|---|
| ภาพเป็นสัญญาณรบกวนสีๆ | ไฟล์โมเดล Flux เสียหาย (ขนาดถูก sha256 ผิด) | `sha256sum` ไฟล์ใน `/mnt/models/modules/comfyui/ComfyUI/models/checkpoints/` ต้องได้ `ead42627…93bf72` ถ้าไม่ตรง ถอนติดตั้ง "Generate images" แล้วติดตั้งใหม่ |
| แชตขึ้น "vLLM exited while loading …" | ขึ้นกับรุ่น | ข้อความมี log ของ vLLM ต่อท้ายแล้ว (เดิมว่างเพราะอ่านเฉพาะ stdout) รุ่น VL เคยขาด `--trust-remote-code` |
| งานภาพไม่เริ่ม / ไม่มีงานในรายการ | หน่วยความจำเหลือไม่พอ (โมเดล 120B ค้าง) | หน้า Models กด Unload แล้วลองใหม่ |
| ผลลัพธ์ส่งกลับแล้ว 502 | proxy ระหว่างทาง | agent 0.14.1 ขึ้นไปลองส่งซ้ำเองสูงสุด 4 ครั้ง |
| เครื่องหายจากหน้า Control | เครื่องดับ/เครือข่ายหลุด/agent ไม่ทำงาน | หน้า Machine status บอกเวลาที่หลุด บนเครื่อง: `systemctl status wxch-agent`, `ping -c 3 1.1.1.1`, `uptime` |
| ดูว่าเกิดอะไรกับ ComfyUI | | `tail -n 50 /mnt/models/modules/comfyui/engine.log` |

## 9. ข้อเสนอแนะ (เรียงตามความคุ้ม)

1. **แจ้งเตือนเมื่อเครื่องหลุด** ตอนนี้หน้า Control บอกว่า "ออฟไลน์ตั้งแต่เมื่อไร" แต่ไม่มีใครถูกแจ้ง เครื่อง pgx เคยหายไปหลายวันโดยไม่มีใครรู้
   ควรส่งข้อความ (อีเมล/แอปแชต) เมื่อเครื่องหลุดเกิน 10 นาที ใช้โค้ดที่บันทึกเวลาเชื่อมต่ออยู่แล้ว เป็นงานเล็ก
2. **ตั้ง `--disable-dynamic-vram` เป็นค่าเริ่มต้นสำหรับเครื่องหน่วยความจำรวม** (GB10): ภาพถูกต้อง วิดีโอเร็วขึ้นราว 4 เท่า เครื่องอื่นไม่เปลี่ยน และยังปรับกลับได้
3. **บอกผู้ใช้เมื่องานรอหน่วยความจำ** งานภาพที่ไม่ผ่านการตรวจหน่วยความจำไม่ปรากฏในรายการและไม่มีข้อความ ควรขึ้นสถานะ "รอหน่วยความจำ (โมเดล X กินอยู่)" พร้อมปุ่มปล่อยโมเดล
4. **ตรวจเวลาส่งผลกลับ ~35 วินาที** ของไฟล์ภาพ 0.9 MB เพื่อรู้ว่าคอขวดอยู่ที่ขั้นไหน
5. **ปล่อยโมเดลใหญ่อัตโนมัติเมื่อมีงานภาพ/วิดีโอรอ** (ถามก่อนทุกครั้ง หรือกำหนดเวลาไม่ใช้งาน) แทนที่จะให้คนกดเอง
6. **ลอง Lightning 30B และ Bolt 74B** เทียบกับรุ่นที่มีอยู่ เพราะเล็กพอรันคู่กับงานภาพได้ แล้วบันทึกผลวัดจริงลงแคตตาล็อก
7. **ตรวจแสงวาบเป็นจุดๆ ในวิดีโอ** (ผู้ใช้พบเมื่อทดสอบ ยังไม่ได้หาสาเหตุ)
8. **หน้าแชต:** ปุ่มดาวน์โหลดโค้ด/คำตอบ เล่นวิดีโอ/เสียง แนบไฟล์ข้อความ แล้วค่อยแนบรูปกับรุ่นที่ดูภาพได้ ดู [CHAT-GAPS.md](CHAT-GAPS.md)
9. **อัปเกรดภาพ vLLM** (ตอนนี้ 0.29.0) เมื่อต้องการรุ่นที่ต้อง 0.31.0 ขึ้นไป ต้องตรวจก่อนว่าภาพไหนรองรับ GB10 (arm64 + CUDA 13) และไม่ทำให้รุ่นที่ใช้อยู่เสีย
10. **วัดค่าจริงแทนค่าประมาณ** ของหน่วยความจำและเวลาในโมดูล แล้วตั้ง `measured: true`
11. **เทสต์อัตโนมัติ:** เทสต์ Talk ตัวหนึ่ง (`TestTalkReceiverEndToEndWithFakeCLI`) ล้มสุ่ม ทำให้ deploy สะดุดได้ ควรแก้ และรันเทสต์ตัวติดตั้งใน Docker (`tests/installer/run.sh`) ทุกครั้งที่แก้ตัวติดตั้ง
12. **สำรองข้อมูลที่ไม่อยู่ใน git:** ไฟล์ตั้งค่าและกุญแจของเซิร์ฟเวอร์ (`config.json`, `keys.json`, ไฟล์ Caddy), `/etc/wxch/runner.json` และ `/etc/wxch/node.json` บนเครื่อง GPU และไฟล์โมเดล (ดาวน์โหลดใหม่ได้ แต่ใช้เวลาและแบนด์วิดท์มาก)
13. **เลือก license** ให้สอดคล้องกับเจตนา "แบ่งปัน ไม่ยึดเป็นของตน" (ข้อความกฎหมายควรให้ผู้เชี่ยวชาญช่วยร่าง) ก่อนเชิญคนอื่นมาติดตั้งหรือร่วมพัฒนา

## 10. เอกสารที่เกี่ยวข้อง

[INSTALL.md](INSTALL.md) (ติดตั้งและระดับการรองรับ), [API.md](API.md) / [API-TH.md](API-TH.md) (API), [DNS.md](DNS.md) (ชื่อโดเมน),
[NATIVE-ENGINES-TH.md](NATIVE-ENGINES-TH.md) (engine ที่รันตรงบนเครื่อง), [DESIGN-TH.md](DESIGN-TH.md) (การออกแบบ), [CHAT-GAPS.md](CHAT-GAPS.md) (สิ่งที่หน้าแชตยังขาด)