# فهرس النماذج

> كيف تسرد خدمة LMSP نماذجها المحلية، وكائن النموذج ورايات قدراته، وحالات دورة حياة النموذج، ومعرّفات النماذج الثابتة، ونسخ الفهرس.

Source: https://madeforagent.com/ar/lmsp/1.0/models/
Language: ar
Specification: LMSP 1.0 (draft)
Updated: 2026-11-08

## 5.1 سرد النماذج {#list}

```http
GET /lmsp/v1/models?capability=chat&ready_only=false
Authorization: Bearer <token>
```

| معامل الاستعلام | المعنى |
| --- | --- |
| `capability` | يعيد النماذج التي لها القدرة المسماة فقط، مثل `chat` أو `embeddings` أو `tools`. |
| `ready_only` | عندما تكون `true` يعيد النماذج التي حالتها `status` هي `ready` فقط. والقيمة الافتراضية `false`. |

```json
{
  "object": "list",
  "catalog_revision": "42",
  "data": [
    {
      "id": "qwen3:14b-q4_k_m",
      "object": "model",
      "display_name": "Qwen3 14B Q4_K_M",
      "owned_by": "local",
      "family": "qwen3",
      "revision": "sha256:8f27c1a4e9b05d36f2a7c8e1b4d90a63c5e2f7b8a1d4c9e60b3f5a7d2c8e1b04",
      "status": "ready",
      "capabilities": {
        "chat": true,
        "completion": true,
        "embeddings": false,
        "tools": true,
        "vision": false,
        "structured_output": true,
        "streaming": true
      },
      "input_modalities": ["text"],
      "output_modalities": ["text"],
      "context_window": 32768,
      "max_output_tokens": 8192,
      "runtime": {
        "backend": "llama.cpp",
        "device": "metal",
        "load_on_demand": true
      }
    }
  ]
}
```

لتجنيب العملاء جلب الفهرس كاملًا مرارًا، **ينبغي** للخدمة أن تعيد ترويسة `ETag` أو الحقل `catalog_revision` أو كليهما:

- `catalog_revision` سلسلة معتمة تتغير كلما تغير الفهرس.
- **ينبغي** للخدمة التي ترسل `ETag` أن ترد على `If-None-Match` المطابق بـ `304 Not Modified`.

## 5.2 كائن النموذج {#object}

| الحقل | المعنى |
| --- | --- |
| `id` | معرّف النموذج الثابت، ويُستخدم في كل طلب يسمّي نموذجًا. |
| `object` | دائمًا `"model"`. |
| `display_name` | اسم مقروء للبشر. يستطيع المستخدم تغييره. |
| `aliases` | قائمة اختيارية بأسماء بديلة. وهي للإعلام فقط. |
| `owned_by` | مصدر النموذج. `local` للنماذج المثبَّتة على هذا الجهاز. |
| `family` | عائلة النموذج، مثل `qwen3`. |
| `revision` | بصمة محتوى النموذج، مثل `sha256:8f27...`. |
| `status` | حالة دورة الحياة ([القسم 5.3](https://madeforagent.com/ar/lmsp/1.0/models.md#lifecycle)). |
| `capabilities` | رايات منطقية: `chat` و`completion` و`embeddings` و`tools` و`vision` و`structured_output` و`streaming`. |
| `input_modalities`, `output_modalities` | أنواع المحتوى التي يقرؤها النموذج ويكتبها. و`text` هو النمط الوحيد المعرَّف في الإصدار 1.0. |
| `context_window` | الحد الأقصى لعدد رموز السياق. |
| `max_output_tokens` | الحد الأقصى لعدد الرموز في استجابة واحدة. |
| `runtime` | `backend` (مثل `llama.cpp`) و`device` (مثل `metal`) و`load_on_demand`. |
| `error` | موجود عندما تكون `status` هي `error`. كائن مشكلة ([القسم 9.3](https://madeforagent.com/ar/lmsp/1.0/common-rules.md#errors)). |

**يجب** أن يكون `id` النموذج ثابتًا. ويستطيع المستخدم تغيير اسم العرض والأسماء البديلة، ولذلك **لا يجوز** استخدامهما مفتاحًا أساسيًا.

## 5.3 دورة حياة النموذج {#lifecycle}

```text
installed --> loading --> ready --> unloading --> installed
                 |
                 +-----> error
```

| الحالة | المعنى |
| --- | --- |
| `installed` | النموذج موجود لكنه غير محمَّل. |
| `loading` | تُخصَّص الذاكرة أو تُهيَّأ بيئة التشغيل. |
| `ready` | يستطيع النموذج معالجة الطلبات فورًا. |
| `unloading` | تُحرَّر الموارد. |
| `error` | فشل التحميل. **ينبغي** أن يحمل كائن النموذج خطأً منظَّمًا. |

طلب تحميل جديد ينقل النموذج من حالة `error` إلى `loading` من جديد.

عندما يسمّي طلب نموذجًا حالته `installed` وقيمة `runtime.load_on_demand` له `true`، تحمّله الخدمة ضمن الطلب. وإذا تعذّر استخدام النموذج فورًا ولم يكن يُحمَّل عند الطلب، ترد الخدمة بـ `409` مع `model_not_ready`. وإذا فشل التحميل فالخطأ هو `model_load_failed`.

## 5.4 عمليات النماذج {#operations}

يعيد `GET /lmsp/v1/models/{model_id}` كائن نموذج واحدًا. والمعرّف المجهول يعطي `404` مع `model_not_found`.

نقطتا نهاية اختياريتان تتحكمان في التحميل صراحةً. وهما متاحتان عندما تكون القدرة `model_management` هي `true`، وتتطلبان النطاق `models:manage` ([القسم 10.3](https://madeforagent.com/ar/lmsp/1.0/security.md#scopes)):

| نقطة النهاية | السلوك |
| --- | --- |
| `POST /lmsp/v1/models/{model_id}/load` | يحمّل النموذج مسبقًا. ويعيد كائن النموذج مع `202 Accepted` عندما يبدأ التحميل، أو `200` عندما يكون النموذج `ready` أصلًا. |
| `POST /lmsp/v1/models/{model_id}/unload` | يلغي تحميل النموذج. ويعيد كائن النموذج. وتكرار الطلب غير ضار. |

كلتاهما تقبل `Idempotency-Key` ([القسم 9.2](https://madeforagent.com/ar/lmsp/1.0/common-rules.md#idempotency)).