API Server — Hermes as a Service

API Server — Hermes ในรูปแบบบริการ

ลองนึกภาพดู: คุณสร้าง AI agent ที่ยอดเยี่ยมด้วย Hermes แล้ว มันสามารถรันคำสั่งเทอร์มินัล ค้นหาเว็บ จัดการไฟล์ และจดจำสิ่งต่างๆ ได้ แต่ปัญหาคือมันอาศัยอยู่ในเทอร์มินัลของคุณ แล้วถ้าคุณสามารถเชื่อมมันเข้ากับอินเทอร์เฟซแชทที่สวยงามอย่าง Open WebUI หรือ LobeChat ได้ล่ะ? นั่นคือสิ่งที่ API Server ทำได้พอดี

ลองนึกถึงมันเป็นตัวแปลภาษาสากล API Server เปิดเผย Hermes เป็น HTTP endpoint ที่เข้ากันได้กับ OpenAI ซึ่งหมายความว่า frontend ใดๆ ที่พูด “ภาษา OpenAI” — และมีอยู่เป็นร้อยๆ ตัว — สามารถเชื่อมต่อกับ Hermes และใช้มันเป็น backend ที่ทรงพลังได้ agent ของคุณยังคงมีเครื่องมือครบชุด และ frontend ก็แค่กลายเป็นหน้าตาที่สวยงามให้กับมัน

จุดเด่นที่สุด? เมื่อคุณสตรีมการตอบกลับ ตัวแสดงความคืบหน้าของเครื่องมือจะปรากฏขึ้นแบบอินไลน์ ดังนั้นผู้ใช้ของคุณจะได้ เห็น agent รันคำสั่งหรือค้นหาเว็บจริงๆ ไม่ใช่แค่นั่งมองเคอร์เซอร์กระพริบ

Backend เดียว พลังเต็มรูปแบบ

ก่อนที่เราจะลงรายละเอียด ขอแนะนำเคล็ดลับสั้นๆ ก่อน Hermes จำเป็นต้องมี provider และ tool backends ที่กำหนดค่าไว้เพื่อให้มีประโยชน์ การสมัครสมาชิก Nous Portal จัดการทั้งสองอย่างให้ — คุณจะได้เข้าถึงโมเดลมากกว่า 300+ ตัว พร้อมด้วยเครื่องมือเว็บ รูปภาพ TTS และเบราว์เซอร์ผ่าน Tool Gateway

รัน hermes setup --portal แค่ครั้งเดียว แล้วคุณก็พร้อมที่จะมอบ backend ที่มาพร้อมเครื่องมือครบชุดให้กับ frontend ใดๆ ก็ได้ นี่เป็นวิธีที่ง่ายที่สุดในการเริ่มต้น

เริ่มต้นอย่างรวดเร็ว: สามขั้นตอน

1. เปิดใช้งาน API Server

เปิดไฟล์ ~/.hermes/.env ของคุณแล้วเพิ่มบรรทัดเหล่านี้:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Optional: only if a browser must call Hermes directly
# API_SERVER_CORS_ORIGINS=http://localhost:3000

API_SERVER_KEY คือรหัสผ่านของคุณ เปลี่ยนเป็นสิ่งที่ปลอดภัยได้เลย!

2. เริ่ม Gateway

รันคำสั่งนี้:

hermes gateway

คุณจะเห็นข้อความประมาณ:

[API Server] API server listening on http://127.0.0.1:8642

แค่นี้เอง agent ของคุณก็กลายเป็นบริการแล้ว

3. เชื่อมต่อ Frontend

ชี้ client ที่เข้ากันได้กับ OpenAI ไปที่ http://localhost:8642/v1 มาทดสอบด้วย curl กัน:

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

หรือเชื่อมต่อ Open WebUI, LobeChat หรือ frontend อื่นๆ ก็ได้ ลองดู คู่มือการเชื่อมต่อ Open WebUI สำหรับคำแนะนำทีละขั้นตอน

Endpoints: สองวิธีในการสื่อสาร

API Server มี endpoint หลักสองแบบ

POST /v1/chat/completions

นี่คือรูปแบบมาตรฐานของ OpenAI Chat Completions มันเป็นแบบ stateless — คุณส่งประวัติการสนทนาทั้งหมดในแต่ละคำขอผ่านอาร์เรย์ messages

ตัวอย่างคำขอแบบง่าย:

{
  "model": "hermes-agent",
  "messages": [
    {"role": "system", "content": "You are a Python expert."},
    {"role": "user", "content": "Write a fibonacci function"}
  ],
  "stream": false
}

และการตอบกลับ:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "hermes-agent",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Here's a fibonacci function..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}

รองรับรูปภาพแบบอินไลน์ คุณสามารถส่งรูปภาพเป็นส่วนหนึ่งของเนื้อหาข้อความได้:

{
  "model": "hermes-agent",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
      ]
    }
  ]
}

ทั้ง URL ระยะไกลและ URL แบบ data:image/... ใช้งานได้ โปรดทราบว่าไฟล์ที่อัปโหลดและ data URLs ที่ไม่ใช่รูปภาพจะส่งคืนข้อผิดพลาด 400 unsupported_content_type

การสตรีมคือจุดที่ความมหัศจรรย์เกิดขึ้น ตั้งค่า "stream": true แล้วคุณจะได้รับ Server-Sent Events (SSE) พร้อมการตอบกลับแบบทีละโทเค็น สำหรับ Chat Completions คุณจะเห็นอีเวนต์มาตรฐาน chat.completion.chunk พร้อมกับอีเวนต์พิเศษ hermes.tool.progress ซึ่งช่วยให้ frontend แสดงกิจกรรมของเครื่องมือได้โดยไม่รบกวนข้อความตอบกลับสุดท้ายของ assistant

POST /v1/responses

นี่คือรูปแบบใหม่ของ OpenAI Responses API ข้อแตกต่างที่สำคัญ? มันรองรับ สถานะการสนทนาฝั่งเซิร์ฟเวอร์ ผ่าน previous_response_id เซิร์ฟเวอร์จะจัดเก็บประวัติการสนทนาทั้งหมด รวมถึงการเรียกใช้เครื่องมือและผลลัพธ์ ดังนั้นบริบทของการสนทนาหลายรอบจึงถูกรักษาไว้โดยที่ client ไม่ต้องจัดการ

ตัวอย่างคำขอ:

{
  "model": "hermes-agent",
  "input": "What files are in my project?",
  "instructions": "You are a helpful coding assistant.",
  "store": true
}

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

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "hermes-agent",
  "output": [
    {"type": "function_call", "status": "completed", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
    {"type": "function_call_output", "status": "completed", "call_id": "call_1", "output": "README.md src/ tests/"},
    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
  ],
  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

สังเกตว่าการเรียกใช้เครื่องมือมี "status": "completed" — Hermes รันมันบนเซิร์ฟเวอร์เรียบร้อยแล้ว client เพียงแค่แสดงผล UI ของเครื่องมือที่มีโครงสร้าง

การสนทนาหลายรอบทำได้ง่าย เพียงแค่เชื่อมโยงการตอบกลับ:

{
  "input": "Now show me the README",
  "previous_response_id": "resp_abc123"
}

เซิร์ฟเวอร์จะสร้างประวัติการสนทนาทั้งหมดขึ้นมาใหม่ รวมถึงการเรียกใช้เครื่องมือทั้งหมด และดำเนินการต่อจากจุดที่คุณค้างไว้

พร้อมที่จะให้บริการหรือยัง?

API Server เปลี่ยน Hermes จากเครื่องมือในเครื่องให้กลายเป็นบริการเต็มรูปแบบ ไม่ว่าคุณจะชอบความเรียบง่ายของ Chat Completions หรือพลังของ Responses ที่มีสถานะ ตอนนี้คุณมี backend สากลสำหรับ frontend ที่เข้ากันได้กับ OpenAI ทุกตัว ลองดูสิ — agent ของคุณพร้อมที่จะให้บริการแล้ว

---