اكتشاف الخدمات | LMSP 1.0 مسودة

3.1 طرق الاكتشاف

يكتشف العميل الخدمة بتجربة هذه الطرق بالترتيب:

الإعداد اليدوي. يُدخل المستخدم عنوان الخدمة مباشرة.
فحص العناوين المحلية المتعارف عليها. يطلب العميل /.well-known/lmsp.json من عناوين مرشحة. والعناوين المرشحة المتعارف عليها هي http://127.0.0.1:17832 وhttp://[::1]:17832.
الاكتشاف على الشبكة المحلية. يتصفح العميل بحثًا عن _lmsp._tcp.local. باستخدام mDNS وDNS-SD.

تنجح الطريقة عندما تُنتج وصف خدمة صالحًا (القسم 3.3). والعنوان الذي يُدخله المستخدم يدويًا له الأسبقية دائمًا على العناوين المكتشفة.

3.2 الإعلان على الشبكة المحلية

يستخدم DNS-SD سجلات PTR للعثور على نسخ الخدمة، وسجلات SRV للحصول على المضيف والمنفذ، وسجلات TXT لحمل قدر صغير من المعلومات الإضافية. ومع mDNS يوفر اكتشافًا بلا إعداد على الشبكة المحلية (RFC 6763، RFC 6762).

مثال على إعلان:

Service type:   _lmsp._tcp.local.
Instance name:  Workstation LMSP._lmsp._tcp.local.

TXT record:
  v=1
  id=svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2
  path=/
  auth=pairing

مفتاح TXT	المعنى
`v`	إصدار صيغة الإعلان. `1` لـ LMSP 1.0.
`id`	معرّف الخدمة، ويساوي `service.id` في وصف الخدمة.
`path`	مسار URL لجذر الخدمة. يطلب العملاء `{path}.well-known/lmsp.json`.
`auth`	تلميح للمصادقة. `pairing` يعني أن على العميل إجراء الاقتران قبل استخدام الخدمة.

القواعد:

لا يجوز للخدمة أن تضع رموز وصول أو قوائم نماذج أو مسارات ملفات أو أي معلومات حساسة أخرى في سجل TXT. فالسجل يحدد موقع الخدمة فحسب. ويجب أن تُقرأ القدرات الفعلية من وصف الخدمة.
يجب على الخدمة أن تُبقي إعلان mDNS معطلًا افتراضيًا. ولا يُفعَّل إلا عندما يشغّل المستخدم اكتشاف الشبكة المحلية صراحةً. والخدمة المستخدمة على الجهاز المحلي وحده لا تعلن عن نفسها.
الخدمة التي تعلن على الشبكة المحلية مضطرة إلى الاستماع خارج loopback، وهذا غير مسموح إلا في وضع LAN (القسم 10.5).
يجب على العميل أن يعامل سجل TXT بوصفه تلميحًا غير موثَّق، وأن يؤكد الخدمة بقراءة وصفها.

3.3 وصف الخدمة

GET /.well-known/lmsp.json

يجب على الخدمة أن تقدّم هذه الوثيقة بصيغة application/json دون اشتراط مصادقة.

{
  "protocol": "lmsp",
  "versions": ["1.0"],
  "service": {
    "id": "svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2",
    "name": "Workstation Local Models",
    "version": "1.0.0"
  },
  "interfaces": [
    {
      "kind": "lmsp",
      "version": "1.0",
      "url": "http://127.0.0.1:17832/lmsp/v1",
      "transport": "http+json"
    },
    {
      "kind": "openai",
      "version": "responses+chat",
      "url": "http://127.0.0.1:17832/v1",
      "transport": "http+json"
    }
  ],
  "capabilities": {
    "streaming": true,
    "tasks": true,
    "event_resume": true,
    "conversations": true,
    "model_management": true
  },
  "authentication": {
    "type": "bearer",
    "pairing_url": "http://127.0.0.1:17832/lmsp/v1/pair"
  },
  "openapi": "http://127.0.0.1:17832/lmsp/v1/openapi.json"
}

الحقل	المعنى
`protocol`	دائمًا `"lmsp"`.
`versions`	إصدارات LMSP التي تدعمها الخدمة، على هيئة سلاسل `major.minor`.
`service`	`id` معرّف ثابت للخدمة، و`name` اسم للعرض، و`version` إصدار برنامج الخدمة.
`interfaces`	الواجهات المعروضة. لكل واحدة `kind` (`lmsp` أو `openai` أو `ollama`) و`version` و`url` أساسي و`transport`. وفي حالة `openai` يسمّي `version` عائلات الواجهات البرمجية المقدَّمة، مثل `responses+chat`.
`capabilities`	رايات منطقية للميزات، مذكورة أدناه.
`authentication`	`type` هو `bearer`. و`pairing_url` هو المكان الذي يستبدل فيه العملاء رمز الاقتران برمز (القسم 10.2).
`openapi`	عنوان URL لوثيقة OpenAPI التي تصف واجهة LMSP.

رايات القدرات:

الراية	المعنى
`streaming`	يمكن بث الاستجابات بوصفها أحداثًا يرسلها الخادم. يجب أن تكون `true` في الإصدار 1.0.
`tasks`	المهام غير المتزامنة متاحة. يجب أن تكون `true` في الإصدار 1.0.
`event_resume`	يمكن الاشتراك في تدفقات أحداث المهام واستئنافها (`GET /lmsp/v1/tasks/{task_id}/events`).
`conversations`	تخزّن الخدمة الاستجابات، فيعمل `store` و`previous_response_id` ويتوافر `GET /lmsp/v1/responses/{response_id}`.
`model_management`	يمكن تحميل النماذج وإلغاء تحميلها صراحةً.

3.4 سلوك العميل

العميل:

ينبغي أن يختار أعلى إصدار في versions يدعمه هو أيضًا.
ينبغي أن يختار واجهة LMSP أو واجهة OpenAI من interfaces بحسب ما يستطيع التحدث به.
يجب أن يقتصر على استخدام القدرات التي يعلنها الوصف. والراية الغائبة تعني false.
يجب أن يتجاهل حقول الامتداد التي لا يتعرف عليها.
ينبغي أن يعيد قراءة وصف الخدمة دوريًا وعند فشل أي طلب، بدلًا من تخزينه مؤقتًا إلى الأبد.
ينبغي أن يتذكر الخدمة المختارة بواسطة service.id لا بالعنوان، لأن العناوين قد تتغير.