API Server — Hermes as a Service

خادم API — Hermes كخدمة

تخيّل هذا السيناريو: لقد بنيتَ وكيل ذكاء اصطناعي مذهل باستخدام Hermes. إنه يستطيع تنفيذ أوامر الطرفية، والبحث في الويب، وإدارة الملفات، وتذكّر الأشياء. لكنه يعيش داخل الطرفية الخاصة بك. ماذا لو استطعت توصيله بواجهة محادثة جميلة مثل Open WebUI أو LobeChat؟ هذا بالضبط ما يفعله خادم API.

اعتبره كمترجمٍ عالمي. خادم API يعرض Hermes كنقطة نهاية HTTP متوافقة مع OpenAI. هذا يعني أن أي واجهة أمامية “تتحدث لغة OpenAI” — وهناك المئات منها — يمكنها الاتصال بـ Hermes واستخدامه كخلفية قوية. يحتفظ وكيلك بمجموعة أدواته الكاملة، وتصبح الواجهة الأمامية مجرد وجهٍ جميل له.

أفضل جزء؟ عندما تقوم ببثّ الاستجابات، تظهر مؤشرات تقدم الأدوات مباشرةً. لذا يمكن لمستخدميك رؤية الوكيل وهو ينفّذ أمرًا أو يبحث في الويب، بدلًا من التحديق في مؤشر وامض.

خلفية واحدة، بقوة كاملة

قبل أن نتعمق، نصيحة سريعة. يحتاج Hermes إلى مزوّد مُهيأ وخلفيات أدوات ليكون مفيدًا. اشتراك Nous Portal يغطي كليهما — ستحصل على وصول إلى أكثر من 300 نموذج بالإضافة إلى أدوات الويب والصورة وتحويل النص إلى كلام والمتصفح عبر بوابة الأدوات.

شغّل hermes setup --portal مرة واحدة، وستكون جاهزًا لإعطاء أي واجهة أمامية خلفية مجهزة بالكامل بالأدوات. إنها أسهل طريقة للبدء.

بدء سريع: ثلاث خطوات

1. تفعيل خادم API

افتح ملف ~/.hermes/.env وأضف هذه الأسطر:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# اختياري: فقط إذا كان المتصفح بحاجة لاستدعاء Hermes مباشرة
# API_SERVER_CORS_ORIGINS=http://localhost:3000

API_SERVER_KEY هي كلمة المرور الخاصة بك. غيّرها إلى شيء آمن!

2. تشغيل البوابة

نفّذ هذا الأمر:

hermes gateway

سترى رسالة مثل:

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

هذا كل شيء. وكيلك أصبح الآن خدمة.

3. توصيل واجهة أمامية

وجّه أي عميل متوافق مع 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 أو أي واجهة أمامية أخرى. اطّلع على دليل تكامل Open WebUI للحصول على تعليمات خطوة بخطوة.

نقاط النهاية: طريقتان للتحدث

يقدم خادم API نقطتي نهاية رئيسيتين.

POST /v1/chat/completions

هذه هي صيغة OpenAI Chat Completions القياسية. إنها عديمة الحالة — ترسل كامل سجل المحادثة في كل طلب عبر مصفوفة 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 البعيدة وعناوين data:image/... تعمل. لاحظ أن الملفات المرفوعة وعناوين البيانات غير الصورية سترجع خطأ 400 unsupported_content_type.

البث هو حيث يحدث السحر. اضبط "stream": true وستحصل على أحداث مرسلة من الخادم (SSE) مع استجابات رمزًا برمز. بالنسبة لـ Chat Completions، سترى أحداث chat.completion.chunk القياسية بالإضافة إلى حدث مخصص hermes.tool.progress. هذا يسمح للواجهات الأمامية بعرض نشاط الأدوات دون تلويث نص المساعد النهائي.

POST /v1/responses

هذه هي صيغة OpenAI Responses API الأحدث. الفرق الكبير؟ إنها تدعم حالة المحادثة من جانب الخادم عبر previous_response_id. يخزن الخادم سجل المحادثة الكامل، بما في ذلك استدعاءات الأدوات ونتائجها، بحيث يتم الحفاظ على سياق المحادثات متعددة الأدوار دون أن يديرها العميل.

إليك طلبًا:

{
  "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 بالفعل بتشغيلها من جانب الخادم. يقوم العميل فقط بعرض واجهة الأدوات المنظمة.

المحادثات متعددة الأدوار سهلة. فقط قم بربط الاستجابات:

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

يقوم الخادم بإعادة بناء المحادثة الكاملة، بما في ذلك جميع استدعاءات الأدوات تلك، ويستمر من حيث توقفت.

جاهز للخدمة؟

يحوّل خادم API هيرميس من أداة محلية إلى خدمة متكاملة. سواء كنت تفضل بساطة Chat Completions أو قوة Responses ذات الحالة، فلديك الآن خلفية عالمية لأي واجهة أمامية متوافقة مع OpenAI. جرّبه — وكيلك جاهز للخدمة.