📄 guides/cron-troubleshooting.md

sidebar_position: 12 title: "Cron Troubleshooting" description: "Diagnose and fix common Hermes cron issues - jobs not firing, delivery failures, skill loading errors, and performance problems"

Cron Troubleshooting

เมื่อ cron job ทำงานไม่เป็นไปตามที่คาดไว้ ให้ตรวจสอบตามรายการเหล่านี้ตามลำดับ ปัญหาส่วนใหญ่มักแบ่งออกเป็น 4 หมวดหมู่: timing, delivery, permissions, หรือ skill loading

Jobs Not Firing

Check 1: Verify the job exists and is active

hermes cron list

ให้มองหา job นั้นและยืนยันว่าสถานะเป็น [active] (ไม่ใช่ [paused] หรือ [completed]) หากแสดง [completed] อาจเป็นเพราะจำนวนครั้งที่ทำซ้ำหมดแล้ว - ให้แก้ไข job เพื่อรีเซ็ต

Check 2: Confirm the schedule is correct

หากรูปแบบตารางเวลาผิดพลาด ระบบจะตั้งค่าเป็นแบบครั้งเดียวโดยอัตโนมัติ (one-shot) หรือถูกปฏิเสธทั้งหมด ให้ทดสอบ expression ของคุณ:

หาก job ทำงานเพียงครั้งเดียวแล้วหายไปจากรายการ นั่นเป็นเพราะเป็นตารางเวลาแบบครั้งเดียว (เช่น 30m, 1d, หรือ ISO timestamp) - ซึ่งเป็นพฤติกรรมที่คาดหวัง

Check 3: Is the gateway running?

Cron jobs ถูกเรียกใช้โดย background ticker thread ของ gateway ซึ่งจะนับทุก 60 วินาที การเปิด CLI chat session ทั่วไปจะ ไม่ เรียกใช้ cron jobs โดยอัตโนมัติ

หากคุณคาดหวังว่า job จะทำงานโดยอัตโนมัติ คุณต้องมี gateway ที่กำลังทำงานอยู่ (hermes gateway หรือ hermes serve) สำหรับการดีบักแบบครั้งเดียว คุณสามารถเรียก tick ด้วยตนเองโดยใช้ hermes cron tick

Check 4: Check the system clock and timezone

Job ใช้ timezone ท้องถิ่น หากนาฬิกาของเครื่องคุณผิดพลาด หรืออยู่ใน timezone ที่แตกต่างจากที่คาดไว้ job จะทำงานในเวลาที่ไม่ถูกต้อง ให้ตรวจสอบ:

date
hermes cron list   # Compare next_run times with local time

Delivery Failures

Check 1: Verify the deliver target is correct

Delivery targets มีความอ่อนไหวต่อตัวพิมพ์ใหญ่-เล็ก (case-sensitive) และต้องมีการตั้งค่า platform ที่ถูกต้อง การตั้งค่า target ผิดพลาดจะทำให้ระบบลบ response นั้นไปโดยเงียบๆ

แพลตฟอร์มที่รองรับอื่น ๆ ได้แก่ mattermost, homeassistant, dingtalk, feishu, wecom, weixin, bluebubbles, qqbot, และ webhook คุณยังสามารถกำหนดเป้าหมายไปยัง chat เฉพาะด้วย syntax platform:chat_id (เช่น telegram:-1001234567890)

หากการส่งมอบล้มเหลว job ก็ยังคงทำงานอยู่ - เพียงแต่จะไม่ส่งไปที่ไหน ให้ตรวจสอบ hermes cron list สำหรับฟิลด์ last_error ที่อัปเดต (ถ้ามี)

Check 2: Check [SILENT] usage

หาก cron job ของคุณไม่มี output หรือ agent ตอบกลับด้วย [SILENT] การส่งมอบจะถูกระงับ นี่เป็นสิ่งที่ตั้งใจสำหรับ jobs ที่ใช้ในการตรวจสอบ (monitoring jobs) - แต่ให้แน่ใจว่า prompt ของคุณไม่ได้ปิดกั้นทุกอย่างโดยไม่ได้ตั้งใจ

Prompt ที่ระบุว่า "respond with [SILENT] if nothing changed" จะกลืนกิน response ที่ไม่ว่างเปล่าโดยเงียบๆ ด้วย ให้ตรวจสอบ logic แบบมีเงื่อนไขของคุณ

Check 3: Platform token permissions

Bot ของแต่ละ messaging platform ต้องการสิทธิ์เฉพาะในการรับข้อความ หากการส่งมอบล้มเหลวโดยเงียบๆ:

• Telegram: Bot ต้องเป็นแอดมินใน group/channel เป้าหมาย
• Discord: Bot ต้องมีสิทธิ์ในการส่งข้อความใน channel เป้าหมาย
• Slack: Bot ต้องถูกเพิ่มเข้าไปใน workspace และมี scope chat:write

Check 4: Response wrapping

โดยค่าเริ่มต้น cron responses จะถูกห่อด้วย header และ footer (cron.wrap_response: true ใน config.yaml) แพลตฟอร์มหรือ integration บางตัวอาจจัดการเรื่องนี้ได้ไม่ดี หากต้องการปิดใช้งาน:

cron:
  wrap_response: false

Skill Loading Failures

Check 1: Verify skills are installed

hermes skills list

Skills ต้องได้รับการติดตั้งก่อนจึงจะสามารถแนบกับ cron jobs ได้ หากขาด skill ให้ติดตั้งก่อนโดยใช้ hermes skills install <skill-name> หรือผ่าน /skills ใน CLI

Check 2: Check skill name vs. skill folder name

Skill names มีความอ่อนไหวต่อตัวพิมพ์ใหญ่-เล็ก และต้องตรงกับชื่อ folder ของ skill ที่ติดตั้งไว้ หาก job ของคุณระบุ ai-funding-daily-report แต่ folder skill คือ ai-funding-daily-report ให้ยืนยันชื่อที่แน่นอนจาก hermes skills list

Check 3: Skills that require interactive tools

Cron jobs ทำงานโดยที่ toolsets cronjob, messaging, และ clarify ถูกปิดใช้งาน สิ่งนี้ป้องกันการสร้าง cron แบบวนซ้ำ การส่งข้อความโดยตรง (การส่งมอบจัดการโดย scheduler) และ prompt แบบโต้ตอบ หาก skill พึ่งพา toolsets เหล่านี้ มันจะไม่ทำงานในบริบทของ cron

ให้ตรวจสอบเอกสารของ skill เพื่อยืนยันว่ามันทำงานในโหมด non-interactive (headless)

Check 4: Multi-skill ordering

เมื่อใช้หลาย skills พวกมันจะโหลดตามลำดับ หาก Skill A ต้องพึ่งพา context จาก Skill B ให้แน่ใจว่า B โหลดก่อน:

/cron add "0 9 * * *" "..." --skill context-skill --skill target-skill

ในตัวอย่างนี้ context-skill จะโหลดก่อน target-skill

Job Errors and Failures

Check 1: Review recent job output

หาก job ทำงานและล้มเหลว คุณอาจเห็น error context ใน:

1. Chat ที่ job ส่งมอบ (หากการส่งมอบสำเร็จ)
2. ~/.hermes/logs/agent.log สำหรับข้อความจาก scheduler (หรือ errors.log สำหรับคำเตือน)
3. metadata last_run ของ job ผ่าน hermes cron list

Check 2: Common error patterns

"No such file or directory" สำหรับ scripts Path ของ script ต้องเป็น absolute path (หรือ relative to the Hermes config directory) ให้ตรวจสอบ:

ls ~/.hermes/scripts/your-script.py   # Must exist
hermes cron edit <job_id> --script ~/.hermes/scripts/your-script.py

"Skill not found" เมื่อรัน job Skill ต้องได้รับการติดตั้งบนเครื่องที่รัน scheduler หากคุณย้ายระหว่างเครื่อง Skill จะไม่ซิงค์โดยอัตโนมัติ - ให้ติดตั้งใหม่ด้วย hermes skills install <skill-name>

Job ทำงานแต่ไม่ส่งมอบอะไรเลย น่าจะเป็นปัญหาที่ delivery target (ดู Delivery Failures ข้างต้น) หรือ response ที่ถูกระงับโดยเงียบๆ ([SILENT])

Job ค้างหรือหมดเวลา Scheduler ใช้ timeout ที่อิงตามความไม่เคลื่อนไหว (default 600s, กำหนดค่าได้ผ่าน env var HERMES_CRON_TIMEOUT, 0 สำหรับไม่จำกัด) Agent สามารถทำงานได้ตราบเท่าที่มันเรียกใช้ tools อยู่ - ตัวจับเวลาจะทำงานหลังจากไม่มีกิจกรรมเป็นเวลานาน Job ที่ทำงานนานควรใช้ scripts ในการจัดการการรวบรวมข้อมูล และส่งมอบเฉพาะผลลัพธ์เท่านั้น

Check 3: Lock contention

Scheduler ใช้ file-based locking เพื่อป้องกันการนับที่ทับซ้อนกัน หากมี gateway instance สองตัวทำงานอยู่ (หรือ CLI session ขัดแย้งกับ gateway) job อาจล่าช้าหรือถูกข้าม

Kill duplicate gateway processes:

ps aux | grep hermes
# Kill duplicate processes, keep only one

Check 4: Permissions on jobs.json

Jobs ถูกเก็บไว้ใน ~/.hermes/cron/jobs.json หากไฟล์นี้ไม่สามารถอ่าน/เขียนได้โดย user ของคุณ scheduler จะล้มเหลวโดยเงียบๆ:

ls -la ~/.hermes/cron/jobs.json
chmod 600 ~/.hermes/cron/jobs.json   # Your user should own it

Performance Issues

Slow job startup

cron job แต่ละตัวจะสร้าง AIAgent session ใหม่ ซึ่งอาจเกี่ยวข้องกับการตรวจสอบสิทธิ์ของ provider และการโหลด model สำหรับตารางเวลาที่ต้องการความรวดเร็ว ให้เพิ่ม buffer time (เช่น 0 8 * * * แทนที่จะเป็น 0 9 * * *)

Too many overlapping jobs

Scheduler จะรัน jobs ตามลำดับภายในแต่ละ tick หากมีหลาย job กำหนดเวลาให้ทำงานพร้อมกัน พวกมันจะทำงานทีละตัว ให้พิจารณาการจัดตารางเวลาให้ห่างกัน (เช่น 0 9 * * * และ 5 9 * * * แทนที่จะเป็นทั้งคู่ที่ 0 9 * * *) เพื่อหลีกเลี่ยงความล่าช้า

Large script output

Scripts ที่ dump output เป็นเมกะไบต์จะทำให้ agent ช้าลงและอาจถึงขีดจำกัดของ token ให้กรอง/สรุปที่ระดับ script - ส่งออกเฉพาะสิ่งที่ agent ต้องการใช้ในการให้เหตุผลเท่านั้น

Diagnostic Commands

hermes cron list                    # Show all jobs, states, next_run times
hermes cron run <job_id>            # Schedule for next tick (for testing)
hermes cron edit <job_id>           # Fix configuration issues
hermes logs                         # View recent Hermes logs
hermes skills list                  # Verify installed skills

Getting More Help

หากคุณได้ทำตามคู่มือนี้แล้วและปัญหายังคงอยู่:

1. รัน job ด้วย hermes cron run <job_id> (จะทำงานใน next gateway tick) และสังเกตข้อผิดพลาดใน chat output
2. ตรวจสอบ ~/.hermes/logs/agent.log สำหรับข้อความจาก scheduler และ ~/.hermes/logs/errors.log สำหรับคำเตือน
3. เปิด issue ที่ github.com/NousResearch/hermes-agent พร้อมข้อมูล:
   • The job ID and schedule
   • The delivery target
   • What you expected vs. what happened
   • Relevant error messages from the logs

สำหรับข้อมูลอ้างอิง cron ฉบับสมบูรณ์ ดูที่ Automate Anything with Cron และ Scheduled Tasks (Cron).

📄 guides/daily-briefing-bot.md

sidebar_position: 3 title: "Tutorial: Daily Briefing Bot" description: "Build an automated daily briefing bot that researches topics, summarizes findings, and delivers them to Telegram or Discord every morning"

บทช่วยสอน: สร้าง Daily Briefing Bot

ในบทช่วยสอนนี้ คุณจะได้สร้าง personal briefing bot ที่จะทำงานทุกเช้า ทำการค้นคว้าหัวข้อที่คุณสนใจ สรุปผลการค้นคว้า และส่งสรุปสั้นๆ ไปยัง Telegram หรือ Discord ของคุณโดยตรง

เมื่อทำเสร็จแล้ว คุณจะได้ workflow อัตโนมัติเต็มรูปแบบ ซึ่งรวมเอา web search, cron scheduling, delegation, และ messaging delivery เข้าด้วยกัน โดยที่ไม่ต้องเขียนโค้ดเลย

What We're Building

นี่คือขั้นตอนการทำงาน:

1. 8:00 AM - cron scheduler จะเรียกใช้ job ของคุณ
2. Hermes spins up agent session ใหม่พร้อม prompt ของคุณ
3. Web search ดึงข่าวสารล่าสุดเกี่ยวกับหัวข้อของคุณ
4. Summarization กลั่นกรองข้อมูลเหล่านั้นให้เป็นรูปแบบ briefing ที่สะอาดตา
5. Delivery ส่ง briefing ไปยัง Telegram หรือ Discord ของคุณ

ระบบทั้งหมดนี้ทำงานได้โดยไม่ต้องดูแล คุณแค่สามารถอ่าน briefing ของคุณพร้อมกับกาแฟยามเช้าเท่านั้น

Prerequisites

ก่อนเริ่มต้น โปรดตรวจสอบให้แน่ใจว่าคุณมี:

• Hermes Agent installed - ดูที่ Installation guide
• Gateway running - daemon gateway จะจัดการการรัน cron:

  hermes gateway install   # ติดตั้งเป็น user service
  sudo hermes gateway install --system   # Linux servers: boot-time system service
  # หรือ
  hermes gateway           # รันใน foreground

• Firecrawl API key - ตั้งค่า FIRECRAWL_API_KEY ใน environment ของคุณสำหรับการ web search
• Messaging configured (ไม่บังคับแต่แนะนำ) - ตั้งค่า Telegram หรือ Discord ด้วย home channel

:::tip ไม่มี Messaging? ไม่เป็นไร คุณยังคงทำตามบทช่วยสอนนี้ได้โดยใช้ deliver: "local" Briefings จะถูกบันทึกไว้ที่ ~/.hermes/cron/output/ และคุณสามารถอ่านได้ตลอดเวลา :::

Step 1: Test the Workflow Manually

ก่อนที่จะทำให้เป็นระบบอัตโนมัติใดๆ เรามาตรวจสอบให้แน่ใจก่อนว่า briefing ทำงานได้ เริ่มต้นเซสชันแชท:

hermes

จากนั้นป้อน prompt นี้:

Search for the latest news about AI agents and open source LLMs.
Summarize the top 3 stories in a concise briefing format with links.

Hermes จะทำการค้นหาบนเว็บ อ่านผลลัพธ์ และสร้างผลลัพธ์ที่คล้ายกับ:

☀️ Your AI Briefing — March 8, 2026

1. Qwen 3 Released with 235B Parameters
   Alibaba's latest open-weight model matches GPT-4.5 on several
   benchmarks while remaining fully open source.
   → https://qwenlm.github.io/blog/qwen3/

2. LangChain Launches Agent Protocol Standard
   A new open standard for agent-to-agent communication gains
   adoption from 15 major frameworks in its first week.
   → https://blog.langchain.dev/agent-protocol/

3. EU AI Act Enforcement Begins for General-Purpose Models
   The first compliance deadlines hit, with open source models
   receiving exemptions under the 10M parameter threshold.
   → https://artificialintelligenceact.eu/updates/

---
3 stories • Sources searched: 8 • Generated by Hermes Agent

ถ้าสิ่งนี้ใช้งานได้ คุณก็พร้อมที่จะทำให้มันเป็นระบบอัตโนมัติ

:::tip ลองปรับปรุงรูปแบบ ลองใช้ prompts ที่แตกต่างกันจนกว่าจะได้ผลลัพธ์ที่คุณชอบ เพิ่มคำสั่งเช่น "ใช้ emoji headers" หรือ "ให้แต่ละสรุปไม่เกิน 2 ประโยค" สิ่งที่คุณตัดสินใจใช้จะถูกใส่เข้าไปใน cron job :::

Step 2: Create the Cron Job

ตอนนี้เรามาตั้งเวลาให้มันทำงานโดยอัตโนมัติทุกเช้า คุณสามารถทำได้สองวิธี

ก่อนสร้าง cron jobs โปรดตรวจสอบให้แน่ใจว่า Hermes ได้ตั้งค่า default model และ provider ไว้ทั่วโลก หากคุณต้องการให้ job เฉพาะใช้ค่าที่แตกต่างกัน ให้กำหนด model/provider overrides ที่ชัดเจนเมื่อสร้างมัน

Option A: Natural Language (in chat)

เพียงแค่บอก Hermes ว่าคุณต้องการอะไร:

Every morning at 8am, search the web for the latest news about AI agents
and open source LLMs. Summarize the top 3 stories in a concise briefing
with links. Use a friendly, professional tone. Deliver to telegram.

Hermes จะสร้าง cron job ให้คุณโดยใช้เครื่องมือ cronjob แบบรวม

Option B: CLI Slash Command

ใช้คำสั่ง /cron เพื่อควบคุมได้มากขึ้น:

/cron add "0 8 * * *" "Search the web for the latest news about AI agents and open source LLMs. Find at least 5 recent articles from the past 24 hours. Summarize the top 3 most important stories in a concise daily briefing format. For each story include: a clear headline, a 2-sentence summary, and the source URL. Use a friendly, professional tone. Format with emoji bullet points and end with a total story count."

The Golden Rule: Self-Contained Prompts

:::warning แนวคิดที่สำคัญ Cron jobs ทำงานใน เซสชันที่สดใหม่โดยสมบูรณ์ - ไม่มีหน่วยความจำจากการสนทนาครั้งก่อนของคุณ ไม่มีบริบทว่าคุณ "ตั้งค่าอะไรไว้ก่อนหน้านี้" Prompt ของคุณต้องมี ทุกอย่าง ที่ agent ต้องการเพื่อทำงานนั้น :::

Bad prompt:

Do my usual morning briefing.

Good prompt:

Search the web for the latest news about AI agents and open source LLMs.
Find at least 5 recent articles from the past 24 hours. Summarize the
top 3 most important stories in a concise daily briefing format. For each
story include: a clear headline, a 2-sentence summary, and the source URL.
Use a friendly, professional tone. Format with emoji bullet points.

Good prompt จะระบุอย่างชัดเจนเกี่ยวกับ สิ่งที่ต้องค้นหา, จำนวนบทความ, รูปแบบ, และ โทนเสียง มันคือทุกสิ่งที่ agent ต้องการในครั้งเดียว

Step 3: Customize the Briefing

เมื่อ basic briefing ทำงานได้แล้ว คุณก็สามารถสร้างสรรค์ได้

Multi-Topic Briefings

ครอบคลุมหลายหัวข้อใน briefing เดียว:

/cron add "0 8 * * *" "Create a morning briefing covering three topics. For each topic, search the web for recent news from the past 24 hours and summarize the top 2 stories with links.

Topics:
1. AI and machine learning - focus on open source models and agent frameworks
2. Cryptocurrency - focus on Bitcoin, Ethereum, and regulatory news
3. Space exploration - focus on SpaceX, NASA, and commercial space

Format as a clean briefing with section headers and emoji. End with today's date and a motivational quote."

Using Delegation for Parallel Research

สำหรับ briefing ที่รวดเร็วยิ่งขึ้น ให้บอก Hermes ให้ delegate แต่ละหัวข้อไปยัง sub-agent:

/cron add "0 8 * * *" "Create a morning briefing by delegating research to sub-agents. Delegate three parallel tasks:

1. Delegate: Search for the top 2 AI/ML news stories from the past 24 hours with links
2. Delegate: Search for the top 2 cryptocurrency news stories from the past 24 hours with links
3. Delegate: Search for the top 2 space exploration news stories from the past 24 hours with links

Collect all results and combine them into a single clean briefing with section headers, emoji formatting, and source links. Add today's date as a header."

sub-agent แต่ละตัวจะค้นหาอย่างอิสระและแบบขนาน จากนั้น main agent จะรวบรวมทุกอย่างให้เป็น briefing ที่สมบูรณ์ ดู Delegation docs สำหรับรายละเอียดเพิ่มเติมว่าสิ่งนี้ทำงานอย่างไร

Weekday-Only Schedule

ไม่ต้องการ briefing ในวันหยุดสุดสัปดาห์ใช่ไหม? ใช้ cron expression ที่กำหนดเป้าหมายวันจันทร์-ศุกร์:

/cron add "0 8 * * 1-5" "Search for the latest AI and tech news..."

Twice-Daily Briefings

รับภาพรวมยามเช้าและการสรุปยามเย็น:

/cron add "0 8 * * *" "Morning briefing: search for AI news from the past 12 hours..."
/cron add "0 18 * * *" "Evening recap: search for AI news from the past 12 hours..."

Adding Personal Context with Memory

หากคุณเปิดใช้งาน memory คุณสามารถจัดเก็บ preferences ที่คงอยู่ข้ามเซสชันได้ แต่โปรดจำไว้ว่า - cron jobs ทำงานในเซสชันที่สดใหม่โดยไม่มีหน่วยความจำจากการสนทนา ในการเพิ่ม personal context ให้ฝังมันลงใน prompt โดยตรง:

/cron add "0 8 * * *" "You are creating a briefing for a senior ML engineer who cares about: PyTorch ecosystem, transformer architectures, open-weight models, and AI regulation in the EU. Skip stories about product launches or funding rounds unless they involve open source.

Search for the latest news on these topics. Summarize the top 3 stories with links. Be concise and technical - this reader doesn't need basic explanations."

:::tip ปรับแต่ง persona การรวมรายละเอียดว่า briefing นี้ สำหรับใคร ช่วยเพิ่มความเกี่ยวข้องได้อย่างมาก บอก agent เกี่ยวกับบทบาท ความสนใจ และสิ่งที่ควรข้าม :::

Step 4: Manage Your Jobs

List All Scheduled Jobs

ใน chat:

/cron list

หรือจาก terminal:

hermes cron list

คุณจะเห็นผลลัพธ์เช่น:

ID          | Name              | Schedule    | Next Run           | Deliver
------------|-------------------|-------------|--------------------|--------
a1b2c3d4    | Morning Briefing  | 0 8 * * *   | 2026-03-09 08:00   | telegram
e5f6g7h8    | Evening Recap     | 0 18 * * *  | 2026-03-08 18:00   | telegram

Remove a Job

ใน chat:

/cron remove a1b2c3d4

หรือถามแบบสนทนา:

Remove my morning briefing cron job.

Hermes จะใช้ cronjob(action="list") เพื่อค้นหาและ cronjob(action="remove") เพื่อลบมัน

Check Gateway Status

ตรวจสอบให้แน่ใจว่า scheduler กำลังทำงานอยู่:

hermes cron status

หาก gateway ไม่ได้ทำงาน job ของคุณจะไม่ถูกดำเนินการ ติดตั้งมันเป็น background service เพื่อความน่าเชื่อถือ:

hermes gateway install
# หรือบน Linux servers
sudo hermes gateway install --system

Going Further

คุณได้สร้าง daily briefing bot ที่ใช้งานได้แล้ว นี่คือทิศทางบางอย่างที่คุณสามารถสำรวจต่อไปได้:

• Scheduled Tasks (Cron) - ข้อมูลอ้างอิงฉบับเต็มสำหรับรูปแบบตารางเวลา, ข้อจำกัดการทำซ้ำ, และตัวเลือกการส่งมอบ
• Delegation - เจาะลึก workflow sub-agent แบบขนาน
• Messaging Platforms - ตั้งค่า Telegram, Discord, หรือปลายทางการส่งมอบอื่น ๆ
• Memory - บริบทที่คงอยู่ข้ามเซสชัน
• Tips & Best Practices - คำแนะนำเพิ่มเติมด้าน prompt engineering

:::tip คุณสามารถตั้งเวลาอะไรได้อีก? รูปแบบ briefing bot ใช้ได้กับทุกอย่าง: การติดตามคู่แข่ง, สรุป repo GitHub, พยากรณ์อากาศ, การติดตามพอร์ตโฟลิโอ, การตรวจสอบสถานะเซิร์ฟเวอร์, หรือแม้แต่เรื่องตลกประจำวัน หากคุณสามารถอธิบายมันใน prompt ได้ คุณก็สามารถตั้งเวลาให้มันได้ :::

📄 guides/delegation-patterns.md

sidebar_position: 13 title: "Delegation & Parallel Work" description: "เมื่อไหร่และอย่างไรในการใช้ subagent delegation - patterns สำหรับการวิจัยแบบขนาน, code review, และงานหลายไฟล์"

Delegation & Parallel Work

Hermes สามารถสร้าง child agents ที่แยกตัวออกมาเพื่อทำงานใน tasks เหล่านั้นแบบขนานได้ subagent แต่ละตัวจะได้รับ conversation, terminal session, และ toolset เป็นของตัวเอง มีเพียง final summary เท่านั้นที่ส่งกลับมา ส่วน intermediate tool calls จะไม่เข้าสู่ context window ของคุณ

สำหรับการอ้างอิงฟีเจอร์ทั้งหมด ดูที่ Subagent Delegation

When to Delegate

ตัวเลือกที่ดีสำหรับการมอบหมายงาน:

• subtasks ที่ต้องใช้การคิดวิเคราะห์สูง (เช่น debugging, code review, research synthesis)
• tasks ที่จะทำให้ context ของคุณเต็มไปด้วยข้อมูลระหว่างทาง
• workstreams ที่เป็นอิสระและทำงานขนานกัน (เช่น การวิจัย A และ B พร้อมกัน)
• tasks ที่ต้องการให้ agent เข้าถึงโดยไม่มีอคติ (fresh-context)

ควรใช้สิ่งอื่นแทน:

• การเรียกใช้ tool ครั้งเดียว -> ใช้ tool นั้นโดยตรงเลย
• งานหลายขั้นตอนแบบกลไกที่มี logic ระหว่างขั้นตอน -> execute_code
• tasks ที่ต้องมีการโต้ตอบกับผู้ใช้ -> subagents ไม่สามารถใช้ clarify ได้
• การแก้ไขไฟล์แบบรวดเร็ว -> ทำด้วยตัวเองโดยตรง

Pattern: Parallel Research

ทำการวิจัยสามหัวข้อพร้อมกันและรับ structured summaries กลับมา:

Research these three topics in parallel:
1. Current state of WebAssembly outside the browser
2. RISC-V server chip adoption in 2025
3. Practical quantum computing applications

Focus on recent developments and key players.

เบื้องหลัง Hermes ใช้:

delegate_task(tasks=[
    {
        "goal": "Research WebAssembly outside the browser in 2025",
        "context": "Focus on: runtimes (Wasmtime, Wasmer), cloud/edge use cases, WASI progress",
        "toolsets": ["web"]
    },
    {
        "goal": "Research RISC-V server chip adoption",
        "context": "Focus on: server chips shipping, cloud providers adopting, software ecosystem",
        "toolsets": ["web"]
    },
    {
        "goal": "Research practical quantum computing applications",
        "context": "Focus on: error correction breakthroughs, real-world use cases, key companies",
        "toolsets": ["web"]
    }
])

ทั้งสามส่วนจะทำงานพร้อมกัน subagent แต่ละตัวจะค้นหาข้อมูลบน web อย่างอิสระและส่งคืน summary จากนั้น parent agent จะสังเคราะห์ข้อมูลเหล่านั้นให้เป็นรายงานที่สอดคล้องกัน

Pattern: Code Review

มอบหมายการตรวจสอบความปลอดภัยให้กับ subagent fresh-context ที่เข้าถึงโค้ดโดยไม่มีความเข้าใจล่วงหน้า:

Review the authentication module at src/auth/ for security issues.
Check for SQL injection, JWT validation problems, password handling,
and session management. Fix anything you find and run the tests.

สิ่งสำคัญคือ field context — ต้องรวมทุกสิ่งที่ subagent ต้องการ:

delegate_task(
    goal="Review src/auth/ for security issues and fix any found",
    context="""Project at /home/user/webapp. Python 3.11, Flask, PyJWT, bcrypt.
    Auth files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py
    Test command: pytest tests/auth/ -v
    Focus on: SQL injection, JWT validation, password hashing, session management.
    Fix issues found and verify tests pass.""",
    toolsets=["terminal", "file"]
)

:::warning The Context Problem Subagents ไม่รู้ อะไรเลย เกี่ยวกับ conversation ของคุณ พวกมันเริ่มต้นใหม่ทั้งหมด หากคุณมอบหมายงานว่า "แก้ไข bug ที่เรากำลังคุยกันอยู่" subagent จะไม่รู้ว่าคุณหมายถึง bug อะไร โปรดระบุ file paths, error messages, project structure, และ constraints อย่างชัดเจนเสมอ :::

Pattern: Compare Alternatives

ประเมินแนวทางหลายอย่างสำหรับปัญหาเดียวกันแบบขนาน จากนั้นเลือกแนวทางที่ดีที่สุด:

I need to add full-text search to our Django app. Evaluate three approaches
in parallel:
1. PostgreSQL tsvector (built-in)
2. Elasticsearch via django-elasticsearch-dsl
3. Meilisearch via meilisearch-python

For each: setup complexity, query capabilities, resource requirements,
and maintenance overhead. Compare them and recommend one.

subagent แต่ละตัวจะวิจัยตัวเลือกหนึ่งอย่างอิสระ เนื่องจากพวกมันถูกแยกออกจากกัน จึงไม่มีการปนเปื้อนข้าม (cross-contamination) — การประเมินแต่ละครั้งจึงมีคุณค่าในตัวเอง parent agent จะได้รับ summary ทั้งสามและทำการเปรียบเทียบ

Pattern: Multi-File Refactoring

แบ่งงาน refactoring ขนาดใหญ่ไปยัง subagents แบบขนาน โดยแต่ละตัวรับผิดชอบส่วนที่แตกต่างกันของ codebase:

delegate_task(tasks=[
    {
        "goal": "Refactor all API endpoint handlers to use the new response format",
        "context": """Project at /home/user/api-server.
        Files: src/handlers/users.py, src/handlers/auth.py, src/handlers/billing.py
        Old format: return {"data": result, "status": "ok"}
        New format: return APIResponse(data=result, status=200).to_dict()
        Import: from src.responses import APIResponse
        Run tests after: pytest tests/handlers/ -v""",
        "toolsets": ["terminal", "file"]
    },
    {
        "goal": "Update all client SDK methods to handle the new response format",
        "context": """Project at /home/user/api-server.
        Files: sdk/python/client.py, sdk/python/models.py
        Old parsing: result = response.json()["data"]
        New parsing: result = response.json()["data"] (same key, but add status code checking)
        Also update sdk/python/tests/test_client.py""",
        "toolsets": ["terminal", "file"]
    },
    {
        "goal": "Update API documentation to reflect the new response format",
        "context": """Project at /home/user/api-server.
        Docs at: docs/api/. Format: Markdown with code examples.
        Update all response examples from old format to new format.
        Add a 'Response Format' section to docs/api/overview.md explaining the schema.""",
        "toolsets": ["terminal", "file"]
    }
])

:::tip subagent แต่ละตัวจะได้รับ terminal session เป็นของตัวเอง พวกมันสามารถทำงานใน project directory เดียวกันได้โดยไม่รบกวนกัน — ตราบใดที่พวกมันกำลังแก้ไขไฟล์ที่แตกต่างกัน หากมีโอกาสที่ subagents สองตัวจะแตะไฟล์เดียวกัน ให้จัดการไฟล์นั้นด้วยตัวเองหลังจากที่งานแบบขนานเสร็จสมบูรณ์ :::

Pattern: Gather Then Analyze

ใช้ execute_code สำหรับการรวบรวมข้อมูลแบบกลไก จากนั้นมอบหมายการวิเคราะห์ที่ต้องใช้การคิดวิเคราะห์สูง:

# Step 1: Mechanical gathering (execute_code is better here - no reasoning needed)
execute_code("""
from hermes_tools import web_search, web_extract

results = []
for query in ["AI funding Q1 2026", "AI startup acquisitions 2026", "AI IPOs 2026"]:
    r = web_search(query, limit=5)
    for item in r["data"]["web"]:
        results.append({"title": item["title"], "url": item["url"], "desc": item["description"]})

# Extract full content from top 5 most relevant
urls = [r["url"] for r in results[:5]]
content = web_extract(urls)

# Save for the analysis step
import json
with open("/tmp/ai-funding-data.json", "w") as f:
    json.dump({"search_results": results, "extracted": content["results"]}, f)
print(f"Collected {len(results)} results, extracted {len(content['results'])} pages")
""")

# Step 2: Reasoning-heavy analysis (delegation is better here)
delegate_task(
    goal="Analyze AI funding data and write a market report",
    context="""Raw data at /tmp/ai-funding-data.json contains search results and
    extracted web pages about AI funding, acquisitions, and IPOs in Q1 2026.
    Write a structured market report: key deals, trends, notable players,
    and outlook. Focus on deals over $100M.""",
    toolsets=["terminal", "file"]
)

นี่มักจะเป็น pattern ที่มีประสิทธิภาพที่สุด: execute_code จัดการการเรียกใช้ tool แบบลำดับ 10+ ได้อย่างประหยัด จากนั้น subagent จะทำงาน reasoning task ที่มีราคาสูงเพียงครั้งเดียวด้วย context ที่สะอาด

Toolset Selection

เลือก toolsets ตามสิ่งที่ subagent ต้องการ:

การจำกัด toolsets ช่วยให้ subagent มีสมาธิและป้องกัน side effects โดยไม่ได้ตั้งใจ (เช่น subagent วิจัยที่รัน shell commands)

Constraints

• Default 3 parallel tasks — โดยค่าเริ่มต้นจะใช้ subagents พร้อมกัน 3 ตัว (สามารถกำหนดค่าได้ผ่าน delegation.max_concurrent_children ใน config.yaml - ไม่มีขีดจำกัดสูงสุดที่แน่นอน มีเพียงขีดจำกัดต่ำสุดที่ 1)
• Nested delegation is opt-in — leaf subagents (ค่าเริ่มต้น) ไม่สามารถเรียกใช้ delegate_task, clarify, memory, send_message, หรือ execute_code ได้ subagents ประเภท Orchestrator (role="orchestrator") ยังคงสามารถใช้ delegate_task สำหรับการมอบหมายงานเพิ่มเติมได้ แต่เฉพาะเมื่อ delegation.max_spawn_depth ถูกเพิ่มขึ้นจากค่าเริ่มต้น 1 (รองรับ 1-3); อีกสี่ตัวยังคงถูกบล็อก ปิดการใช้งานทั่วโลกผ่าน delegation.orchestrator_enabled: false
• Separate terminals — subagent แต่ละตัวจะได้รับ terminal session เป็นของตัวเองพร้อม working directory และ state ที่แยกจากกัน
• No conversation history — subagents จะเห็นเฉพาะ goal และ context ที่ parent agent ส่งมาเมื่อเรียกใช้ delegate_task
• Default 50 iterations — ตั้งค่า max_iterations ให้ต่ำลงสำหรับ tasks ง่ายๆ เพื่อประหยัดค่าใช้จ่าย

Tips

ระบุ goals ให้ชัดเจน "Fix the bug" นั้นคลุมเครือเกินไป "Fix the TypeError in api/handlers.py line 47 where process_request() receives None from parse_body()" ให้ข้อมูลเพียงพอแก่ subagent ในการทำงาน

รวม file paths Subagents ไม่รู้ project structure ของคุณเสมอไป โปรดรวม absolute paths ไปยังไฟล์ที่เกี่ยวข้อง, project root, และ test command เสมอ

ใช้ delegation เพื่อแยก context บางครั้งคุณต้องการมุมมองที่สดใหม่ การมอบหมายงานจะบังคับให้คุณระบุปัญหาอย่างชัดเจน และ subagent จะเข้าถึงปัญหานั้นโดยไม่มีสมมติฐานที่สะสมมาจากการสนทนาของคุณ

ตรวจสอบ results summary ของ subagent ก็คือ summary เท่านั้น หาก subagent บอกว่า "fixed the bug and tests pass" ให้ตรวจสอบด้วยการรัน tests ด้วยตัวเอง หรืออ่าน diff

สำหรับการอ้างอิง delegation ฉบับสมบูรณ์ — พารามิเตอร์ทั้งหมด, ACP integration, และการกำหนดค่าขั้นสูง — ดูที่ Subagent Delegation.

📄 guides/github-pr-review-agent.md

sidebar_position: 10 title: "Tutorial: GitHub PR Review Agent" description: "Build an automated AI code reviewer that monitors your repos, reviews pull requests, and delivers feedback - hands-free"

Tutorial: Build a GitHub PR Review Agent

ปัญหาที่พบ: ทีมของคุณเปิด PRs เร็วกว่าที่คุณจะตรวจทานได้ PRs จึงค้างเป็นวันๆ รอคนมาดู นักพัฒนาจูเนียร์รวมโค้ดที่มีบั๊กเพราะไม่มีใครมีเวลาตรวจสอบ คุณต้องใช้เวลาช่วงเช้าไปกับการตามดู diff แทนที่จะใช้เวลาไปกับการพัฒนา

วิธีแก้ปัญหา: AI agent ที่คอยเฝ้าดู repos ของคุณตลอด 24 ชั่วโมง ตรวจสอบ PR ใหม่ทุกรายการเพื่อหาบั๊ก ปัญหาด้านความปลอดภัย และคุณภาพโค้ด พร้อมส่งสรุปให้คุณ - ทำให้คุณใช้เวลาไปกับ PRs ที่จำเป็นต้องใช้การตัดสินใจจากมนุษย์จริงๆ เท่านั้น

สิ่งที่คุณจะได้สร้าง:

┌───────────────────────────────────────────────────────────────────┐
│                                                                  │
│   Cron Timer  ──▶  Hermes Agent  ──▶  GitHub API  ──▶  Review     │
│   (every 2h)       + gh CLI           (PR diffs)       delivery   │
│                    + skill                             (Telegram, │
│                    + memory                            Discord,   │
│                                                        local)     │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

คู่มือนี้ใช้ cron jobs เพื่อตรวจสอบ PRs ตามตารางเวลา - ไม่จำเป็นต้องมี server หรือ public endpoint ทำงานได้แม้หลัง NAT และ firewalls

:::tip ต้องการการรีวิวแบบเรียลไทม์แทนหรือไม่? หากคุณมี public endpoint ให้ใช้งาน ลองดู Automated GitHub PR Comments with Webhooks - GitHub จะส่ง events ไปให้ Hermes ทันทีเมื่อมีการเปิดหรืออัปเดต PR :::

Prerequisites

• Hermes Agent installed - ดูที่ Installation guide
• Gateway สำหรับ cron jobs ที่ทำงานอยู่:

  hermes gateway install   # ติดตั้งเป็น service
  # หรือ
  hermes gateway           # รันใน foreground

• GitHub CLI (gh) ติดตั้งและ authenticated แล้ว:

  # ติดตั้ง
  brew install gh        # macOS
  sudo apt install gh    # Ubuntu/Debian
  
  # Authenticate
  gh auth login

• ตั้งค่า Messaging (ทางเลือก) - Telegram หรือ Discord

:::tip ไม่มี messaging? ไม่เป็นไร ใช้ deliver: "local" เพื่อบันทึกรีวิวไปยัง ~/.hermes/cron/output/. เหมาะสำหรับการทดสอบก่อนที่จะเชื่อมต่อระบบแจ้งเตือน :::

Step 1: Verify the Setup

ตรวจสอบให้แน่ใจว่า Hermes สามารถเข้าถึง GitHub ได้ เริ่มแชท:

hermes

ทดสอบด้วยคำสั่งง่ายๆ:

Run: gh pr list --repo NousResearch/hermes-agent --state open --limit 3

คุณควรเห็นรายการ PRs ที่เปิดอยู่ ถ้าทำได้ แสดงว่าคุณพร้อมแล้ว

Step 2: Try a Manual Review

ในแชทเดิม ให้ขอให้ Hermes รีวิว PR จริง:

Review this pull request. Read the diff, check for bugs, security issues,
and code quality. Be specific about line numbers and quote problematic code.

Run: gh pr diff 3888 --repo NousResearch/hermes-agent

Hermes จะ:

1. Execute gh pr diff เพื่อดึงการเปลี่ยนแปลงโค้ด
2. อ่าน diff ทั้งหมด
3. สร้างรีวิวที่มีโครงสร้างพร้อมการค้นพบที่เฉพาะเจาะจง

หากคุณพอใจกับคุณภาพ ก็ถึงเวลาทำให้เป็นระบบอัตโนมัติ

Step 3: Create a Review Skill

Skill จะมอบแนวทางการรีวิวที่สม่ำเสมอให้ Hermes ซึ่งจะคงอยู่แม้ในระหว่างเซสชันและรอบ cron job หากไม่มี skill คุณภาพการรีวิวก็จะแตกต่างกันไป

mkdir -p ~/.hermes/skills/code-review

สร้างไฟล์ ~/.hermes/skills/code-review/SKILL.md:

---
name: code-review
description: Review pull requests for bugs, security issues, and code quality
---

# Code Review Guidelines

เมื่อรีวิว pull request:

## What to Check
1. **Bugs** - Logic errors, off-by-one, null/undefined handling
2. **Security** - Injection, auth bypass, secrets in code, SSRF
3. **Performance** - N+1 queries, unbounded loops, memory leaks
4. **Style** - Naming conventions, dead code, missing error handling
5. **Tests** - Are changes tested? Do tests cover edge cases?

## Output Format
For each finding:
- **File:Line** - exact location
- **Severity** - Critical / Warning / Suggestion
- **What's wrong** - one sentence
- **Fix** - how to fix it

## Rules
- Be specific. Quote the problematic code.
- Don't flag style nitpicks unless they affect readability.
- If the PR looks good, say so. Don't invent problems.
- End with: APPROVE / REQUEST_CHANGES / COMMENT

ตรวจสอบว่าโหลดสำเร็จ - เริ่ม hermes และคุณควรเห็น code-review ในรายการ skills เมื่อเริ่มทำงาน

Step 4: Teach It Your Conventions

นี่คือสิ่งที่ทำให้ reviewer มีประโยชน์จริงๆ เริ่มเซสชันและสอนมาตรฐานของทีมคุณให้ Hermes:

Remember: In our backend repo, we use Python with FastAPI.
All endpoints must have type annotations and Pydantic models.
We don't allow raw SQL - only SQLAlchemy ORM.
Test files go in tests/ and must use pytest fixtures.

Remember: In our frontend repo, we use TypeScript with React.
No `any` types allowed. All components must have props interfaces.
We use React Query for data fetching, never useEffect for API calls.

ความทรงจำเหล่านี้จะคงอยู่ตลอดไป - reviewer จะบังคับใช้ convention ของคุณโดยไม่ต้องบอกทุกครั้ง

Step 5: Create the Automated Cron Job

ตอนนี้ให้เชื่อมทุกอย่างเข้าด้วยกัน สร้าง cron job ที่ทำงานทุก 2 ชั่วโมง:

hermes cron create "0 */2 * * *" \
  "Check for new open PRs and review them.

Repos to monitor:
- myorg/backend-api
- myorg/frontend-app

Steps:
1. Run: gh pr list --repo REPO --state open --limit 5 --json number,title,author,createdAt
2. For each PR created or updated in the last 4 hours:
   - Run: gh pr diff NUMBER --repo REPO
   - Review the diff using the code-review guidelines
3. Format output as:

## PR Reviews - today

### [repo] #[number]: [title]
**Author:** [name] | **Verdict:** APPROVE/REQUEST_CHANGES/COMMENT
[findings]

If no new PRs found, say: No new PRs to review." \
  --name "pr-review" \
  --deliver telegram \
  --skill code-review

ตรวจสอบว่ามีการตั้งเวลาแล้ว:

hermes cron list

ตารางเวลาที่มีประโยชน์อื่นๆ

Step 6: Run It On Demand

ไม่อยากรอตามตารางเวลา? ให้เรียกใช้ด้วยตนเอง:

hermes cron run pr-review

หรือจากภายในเซสชันแชท:

/cron run pr-review

Going Further

Post Reviews Directly to GitHub

แทนที่จะส่งไปยัง Telegram ให้ agent แสดงความคิดเห็นบน PR นั้นโดยตรง:

เพิ่มสิ่งนี้ใน prompt cron ของคุณ:

After reviewing, post your review:
- For issues: gh pr review NUMBER --repo REPO --comment --body "YOUR_REVIEW"
- For critical issues: gh pr review NUMBER --repo REPO --request-changes --body "YOUR_REVIEW"
- For clean PRs: gh pr review NUMBER --repo REPO --approve --body "Looks good"

:::caution ตรวจสอบให้แน่ใจว่า gh มี token ที่มี scope repo การรีวิวจะถูกโพสต์ในชื่อผู้ใช้ที่ gh authenticated อยู่ :::

Weekly PR Dashboard

สร้างภาพรวม PRs ทั้งหมดสำหรับวันจันทร์:

hermes cron create "0 9 * * 1" \
  "Generate a weekly PR dashboard:
- myorg/backend-api
- myorg/frontend-app
- myorg/infra

For each repo show:
1. Open PR count and oldest PR age
2. PRs merged this week
3. Stale PRs (older than 5 days)
4. PRs with no reviewer assigned

Format as a clean summary." \
  --name "weekly-dashboard" \
  --deliver telegram

Multi-Repo Monitoring

ขยายขนาดโดยการเพิ่ม repos เข้าไปใน prompt agent จะประมวลผลทีละรายการ - ไม่ต้องตั้งค่าเพิ่มเติม

Troubleshooting

"gh: command not found"

gateway ทำงานในสภาพแวดล้อมที่จำกัด ตรวจสอบให้แน่ใจว่า gh อยู่ใน system PATH และรีสตาร์ท gateway

Reviews are too generic

1. เพิ่ม skill code-review (Step 3)
2. สอน convention ของคุณให้ Hermes ผ่าน memory (Step 4)
3. ยิ่งมี context เกี่ยวกับ stack ของคุณมากเท่าไหร่ รีวิวก็จะยิ่งดีขึ้นเท่านั้น

Cron job doesn't run

hermes gateway status    # gateway กำลังทำงานอยู่หรือไม่?
hermes cron list         # job ถูกเปิดใช้งานแล้วหรือไม่?

Rate limits

GitHub อนุญาตให้มีการร้องขอ API 5,000 ครั้ง/ชั่วโมง สำหรับผู้ใช้ที่ authenticated การรีวิว PR แต่ละครั้งใช้ประมาณ 3-5 requests (list + diff + comments ที่อาจมี) แม้การรีวิว 100 PRs/วัน ก็ยังอยู่ในขีดจำกัดที่กำหนด

What's Next?

• Webhook-Based PR Reviews - รับรีวิวทันทีเมื่อมีการเปิด PR (ต้องใช้ public endpoint)
• Daily Briefing Bot - ผสมผสาน PR reviews เข้ากับสรุปข่าวประจำเช้าของคุณ
• Build a Plugin - ห่อหุ้ม logic การรีวิวให้เป็น plugin ที่แชร์ได้
• Profiles - รัน reviewer profile เฉพาะพร้อม memory และ config ของตัวเอง
• Fallback Providers - รับรองว่ารีวิวจะทำงานแม้ว่า provider ตัวใดตัวหนึ่งจะล่ม

📄 guides/local-llm-on-mac.md

sidebar_position: 2 title: "Run Local LLMs on Mac" description: "Set up a local OpenAI-compatible LLM server on macOS with llama.cpp or MLX, including model selection, memory optimization, and real benchmarks on Apple Silicon"

การรัน LLM แบบ Local บน Mac

คู่มือนี้จะแนะนำคุณถึงวิธีการตั้งค่า local LLM server บน macOS ที่ใช้ API ที่เข้ากันได้กับ OpenAI คุณจะได้รับความเป็นส่วนตัวเต็มรูปแบบ ไม่มีค่าใช้จ่าย API และประสิทธิภาพที่น่าประหลาดใจบน Apple Silicon

เราจะกล่าวถึง backend สองตัว:

ทั้งสองตัวจะเปิดเผย endpoint /v1/chat/completions ที่เข้ากันได้กับ OpenAI โดย Hermes สามารถทำงานกับตัวใดตัวหนึ่งได้ เพียงแค่ชี้ไปที่ http://localhost:8080 หรือ http://localhost:8000

:::info Apple Silicon only คู่มือนี้ออกแบบมาสำหรับ Mac ที่ใช้ Apple Silicon (M1 และรุ่นที่ใหม่กว่า) Mac ที่ใช้ Intel จะสามารถทำงานกับ llama.cpp ได้ แต่จะไม่มี GPU acceleration - คาดว่าจะได้ประสิทธิภาพที่ช้าลงอย่างมาก :::

การเลือกโมเดล (Choosing a model)

สำหรับการเริ่มต้น เราแนะนำ Qwen3.5-9B - เป็น model ด้าน reasoning ที่แข็งแกร่งและสามารถทำงานได้สบายๆ ใน unified memory ขนาด 8GB ขึ้นไปด้วยการทำ quantization

หลักการจำหน่วยความจำ (Memory rule of thumb): ขนาดโมเดล + KV cache โมเดล 9B Q4 มีขนาดประมาณ ~5 GB ส่วน KV cache ที่ 128K context ด้วย Q4 quantization จะเพิ่มประมาณ ~4-5 GB ด้วย default (f16) KV cache จะพุ่งสูงถึง ~16 GB ตัว flag ของ quantized KV cache ใน llama.cpp คือเคล็ดลับสำคัญสำหรับระบบที่มีหน่วยความจำจำกัด

สำหรับโมเดลที่ใหญ่กว่า (27B, 35B) คุณจะต้องใช้ unified memory 32 GB ขึ้นไป โมเดล 9B จึงเป็นจุดที่ลงตัวสำหรับเครื่องที่มีหน่วยความจำ 8-16 GB

Option A: llama.cpp

llama.cpp เป็น runtime LLM local ที่พกพาสะดวกที่สุด บน macOS มันใช้ Metal สำหรับ GPU acceleration ได้ทันที

ติดตั้ง (Install)

brew install llama.cpp

คำสั่งนี้จะให้คำสั่ง llama-server ทั่วทั้งระบบ

ดาวน์โหลดโมเดล (Download the model)

คุณต้องการโมเดลในรูปแบบ GGUF แหล่งที่ง่ายที่สุดคือ Hugging Face ผ่าน huggingface-cli:

brew install huggingface-cli

จากนั้นดาวน์โหลด:

huggingface-cli download unsloth/Qwen3.5-9B-GGUF Qwen3.5-9B-Q4_K_M.gguf --local-dir ~/models

:::tip Gated models โมเดลบางตัวบน Hugging Face ต้องการการยืนยันตัวตน ให้รัน huggingface-cli login ก่อน หากคุณได้รับ error 401 หรือ 404 :::

เริ่มต้น server

llama-server -m ~/models/Qwen3.5-9B-Q4_K_M.gguf \
  -ngl 99 \
  -c 131072 \
  -np 1 \
  -fa on \
  --cache-type-k q4_0 \
  --cache-type-v q4_0 \
  --host 0.0.0.0

นี่คือความหมายของแต่ละ flag:

server พร้อมใช้งานเมื่อคุณเห็น:

main: server is listening on http://0.0.0.0:8080
srv  update_slots: all slots are idle

การเพิ่มประสิทธิภาพหน่วยความจำสำหรับระบบที่จำกัด (Memory optimization for constrained systems)

flag --cache-type-k q4_0 --cache-type-v q4_0 เป็นการเพิ่มประสิทธิภาพที่สำคัญที่สุดสำหรับระบบที่มีหน่วยความจำจำกัด นี่คือผลกระทบที่ 128K context:

บน Mac 8 GB ให้ใช้ q4_0 KV cache และลด context เป็น -c 32768 (32K) บน 16 GB คุณสามารถทำ 128K context ได้อย่างสบายๆ บน 32 GB+ คุณสามารถรันโมเดลที่ใหญ่ขึ้นหรือหลาย parallel slots

หากคุณยังคงประสบปัญหาหน่วยความจำไม่พอ ให้ลดขนาด context ก่อน (-c) จากนั้นลองใช้ quantization ที่เล็กลง (Q3_K_M แทน Q4_K_M)

ทดสอบ (Test it)

curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3.5-9B-Q4_K_M.gguf",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 50
  }' | jq .choices[0].message.content

รับชื่อโมเดล (Get the model name)

หากคุณลืมชื่อโมเดล ให้ query ที่ endpoint models:

curl -s http://localhost:8080/v1/models | jq '.data[].id'

Option B: MLX via omlx

omlx เป็นแอปที่ออกแบบมาสำหรับ macOS โดยเฉพาะ ซึ่งจัดการและให้บริการโมเดล MLX MLX คือ framework machine learning ของ Apple เอง ซึ่งได้รับการปรับให้เหมาะสมสำหรับสถาปัตยกรรม unified memory ของ Apple Silicon

ติดตั้ง (Install)

ดาวน์โหลดและติดตั้งจาก omlx.ai มันให้ GUI สำหรับการจัดการโมเดลและ server ในตัว

ดาวน์โหลดโมเดล (Download the model)

ใช้แอป omlx เพื่อเรียกดูและดาวน์โหลดโมเดล ค้นหา Qwen3.5-9B-mlx-lm-mxfp4 และดาวน์โหลด โมเดลจะถูกจัดเก็บในเครื่อง (โดยปกติใน ~/.omlx/models/)

เริ่มต้น server

omlx จะให้บริการโมเดลที่ http://127.0.0.1:8000 โดยค่าเริ่มต้น เริ่มการให้บริการจาก UI ของแอป หรือใช้ CLI หากมี

ทดสอบ (Test it)

curl -s http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3.5-9B-mlx-lm-mxfp4",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 50
  }' | jq .choices[0].message.content

รายการโมเดลที่พร้อมใช้งาน (List available models)

omlx สามารถให้บริการหลายโมเดลพร้อมกัน:

curl -s http://127.0.0.1:8000/v1/models | jq '.data[].id'

Benchmarks: llama.cpp vs MLX

ทั้งสอง backend ถูกทดสอบบนเครื่องเดียวกัน (Apple M5 Max, 128 GB unified memory) โดยใช้โมเดลเดียวกัน (Qwen3.5-9B) ที่ระดับ quantization ที่เทียบเคียงกัน (Q4_K_M สำหรับ GGUF, mxfp4 สำหรับ MLX) มีการทดสอบ 5 prompts ที่หลากหลาย โดยทำซ้ำ 3 รอบ เพื่อหลีกเลี่ยงการแย่งทรัพยากร

ผลลัพธ์ (Results)

ความหมายของสิ่งนี้ (What this means)

• llama.cpp โดดเด่นในการประมวลผล prompt - pipeline flash attention + quantized KV cache ทำให้ได้ token แรกในเวลาประมาณ ~66ms หากคุณกำลังสร้างแอปพลิเคชันแบบ interactive ที่ความรู้สึกตอบสนองมีความสำคัญ (เช่น chatbots, autocomplete) นี่คือข้อได้เปรียบที่มีความหมาย

• MLX สร้าง token ได้เร็วกว่า ~37% เมื่อเริ่มทำงานแล้ว สำหรับงานแบบ batch workloads, long-form generation, หรืองานใดๆ ที่เวลาการทำงานรวมสำคัญกว่า latency เริ่มต้น MLX จะเสร็จเร็วกว่า

• ทั้งสอง backend มีความสม่ำเสมออย่างยิ่ง - ความแปรปรวนในการรันนั้นน้อยมาก คุณสามารถเชื่อถือตัวเลขเหล่านี้ได้

ควรเลือกตัวไหน? (Which one should you pick?)

เชื่อมต่อกับ Hermes (Connect to Hermes)

เมื่อ local server ของคุณทำงานอยู่:

hermes model

เลือก Custom endpoint และทำตามคำแนะนำ มันจะขอ base URL และ model name - ให้ใช้ค่าจาก backend ที่คุณตั้งค่าไว้ข้างต้น

Timeouts

Hermes จะตรวจจับ local endpoints (localhost, LAN IPs) โดยอัตโนมัติ และผ่อนคลาย timeout สำหรับ streaming ไม่จำเป็นต้องตั้งค่าสำหรับส่วนใหญ่ของการตั้งค่า

หากคุณยังคงพบข้อผิดพลาด timeout (เช่น context ขนาดใหญ่มากบน hardware ที่ช้า) คุณสามารถ override streaming read timeout ได้:

# ในไฟล์ .env - เพิ่มจากค่า default 120s เป็น 30 นาที
HERMES_STREAM_READ_TIMEOUT=1800

stream read timeout เป็นตัวที่น่าจะทำให้เกิดปัญหามากที่สุด - มันคือ deadline ระดับ socket สำหรับการรับข้อมูล chunk ถัดไป ในระหว่าง prefill บน context ขนาดใหญ่ โมเดล local อาจไม่มี output เป็นเวลาหลายนาทีขณะที่กำลังประมวลผล prompt การ auto-detection จัดการสิ่งนี้อย่างโปร่งใส