مرجع واجهة برمجة تطبيقات الكتالوج

مهم

• يتوفر Foundry Local في المعاينة. توفر إصدارات المعاينة العامة access مبكرة للميزات الموجودة في النشر النشط.
• يمكن أن تتغير الميزات والنهج والعمليات أو لديها قدرات محدودة، قبل التوفر العام (GA).

يتيح لك Foundry Local إنشاء خدمة الكتالوج الخاصة بك ودمجها. تتناول هذه المقالة ما يلي:

• تنسيق النموذج المطلوب لواجهة برمجة تطبيقات الكتالوج
• تنسيق الطلب والاستجابة المطلوب لواجهة برمجة تطبيقات الكتالوج للتكامل مع Foundry Local

المتطلبات المسبقه

• لديك Foundry Local مثبت.
• يمكنك تشغيل خدمة ويب تعرض POST نقطة نهاية.
• تتوفر artifacts النموذج بتنسيق ONNX.
• Azure access control المستندة إلى الأدوار (RBAC): غير قابل للتطبيق.

شكل النموذج

للعمل مع Foundry Local، يجب أن يحتوي كتالوج النموذج على ملفات نموذج بتنسيق Open Neural Network Exchange (ONNX). لمعرفة كيفية تحويل نماذج Hugging Face وPyTorch برمجيا إلى ONNX، راجع التحويل البرمجي لنماذج Hugging Face لتشغيلها على Foundry Local.

تنسيق واجهة برمجة التطبيقات

طلب

تنفيذ نقطة نهاية POST في خدمة الكتالوج التي تقبل نص طلب JSON. تنسيق الطلب لواجهة برمجة تطبيقات الكتالوج كما يلي:

• الطريقة: POST
• نوع المحتوى: application/json

عينة طلب

curl -X POST <your-catalog-api-endpoint> \
-H "Content-Type: application/json" \
-d '{
  "resourceIds": [
    {
      "resourceId": "azureml",
      "entityContainerType": "Registry"
    }
  ],
  "indexEntitiesRequest": {
    "filters": [
      {
        "field": "type",
        "operator": "eq",
        "values": [
          "models"
        ]
      },
      {
        "field": "kind",
        "operator": "eq",
        "values": [
          "Versioned"
        ]
      },
      {
        "field": "properties/variantInfo/variantMetadata/device",
        "operator": "eq",
        "values": [
          "cpu",
          "gpu"
        ]
      },
      {
        "field": "properties/variantInfo/variantMetadata/executionProvider",
        "operator": "eq",
        "values": [
          "cpuexecutionprovider",
          "webgpuexecutionprovider"
        ]
      }
    ],
    "pageSize": 10,
    "skip": null,
    "continuationToken": null
  }
}'

استبدل <your-catalog-api-endpoint> بعنوان URL لخدمة الكتالوج.

ما يمكن توقعه

• تتضمن الاستجابة الناجحة كائنا indexEntitiesResponse .
• يتم إرجاع نتائج البحث في indexEntitiesResponse.value.

المصدر:

• مرجع واجهة برمجة تطبيقات REST المحلي ل Foundry
• أفضل الممارسات وتحري الخلل وإصلاحه

يجب أن يكون نص الطلب كائن JSON مع الحقول التالية:

• resourceIds: صفيف من معرفات الموارد التي تحدد الموارد للاستعلام. يتضمن كل عنصر ما يلي:
  • resourceId: معرف المورد.
  • entityContainerType: نوع حاوية الكيان، مثل Registry، Workspaceو، وغيرها.
• indexEntitiesRequest: كائن يحتوي على معلمات البحث.
  • filters: صفيف من عناصر التصفية التي تحدد معايير تصفية نتائج البحث. يتضمن كل عامل تصفية ما يلي:
    • field: الحقل الذي يجب التصفية عليه، مثل typeو kindوغيرها.
    • operator: عامل التشغيل المراد استخدامه لعامل التصفية. على سبيل المثال، eq (يساوي)، ne (لا يساوي)، gt (أكبر من)، lt (أقل من)، وغيرها.
    • values: صفيف من القيم لمطابقتها مع الحقل.
  • orderBy: صفيف من الحقول لترتيب النتائج حسبها.
  • searchText: سلسلة للبحث عن في النتائج.
  • pageSize: الحد الأقصى لعدد النتائج التي سيتم إرجاعها (لفصل الصفحات).
  • skip: عدد النتائج التي يجب تخطيها (لفصل الصفحات).
  • continuationToken: رمز مميز لفصل الصفحات للمتابعة من طلب سابق.

الحقول القابلة للتصفية (اختياري)

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

إذا قمت بتنفيذ التصفية من جانب الخادم، فاستخدم الحقول التالية:

• type: نوع النموذج، مثل models، datasetsو، وغيرها.
• kind: نوع النموذج، مثل Versioned، Unversionedو، وغيرها.
• properties/variantInfo/variantMetadata/device: نوع الجهاز، مثل cpuو gpuو وغيرها.
• properties/variantInfo/variantMetadata/executionProvider: موفر التنفيذ، مثل cpuexecutionproviderو webgpuexecutionproviderو وغيرها.

الرد

تقوم واجهة برمجة تطبيقات الكتالوج بإرجاع كائن JSON الذي يحتوي على نتائج البحث.

مثال على الاستجابة

{
  "indexEntitiesResponse": {
    "totalCount": 1,
    "value": [
      {
        "assetId": "example-asset-id",
        "version": "1",
        "properties": {
          "name": "example-model",
          "version": 1,
          "variantInfo": {
            "variantMetadata": {
              "device": "cpu",
              "executionProvider": "cpuexecutionprovider"
            }
          }
        }
      }
    ],
    "nextSkip": null,
    "continuationToken": null
  }
}

مخطط الاستجابة

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "indexEntitiesResponse": {
      "type": "object",
      "properties": {
        "totalCount": {
          "type": "integer",
          "description": "The total count of entities."
        },
        "value": {
          "type": "array",
          "description": "An array of LocalModel objects.",
          "items": {
            "$ref": "#/definitions/LocalModel"
          }
        },
        "nextSkip": {
          "type": "integer",
          "description": "The number of items to skip for the next request."
        },
        "continuationToken": {
          "type": "string",
          "description": "A token to continue fetching results."
        }
      }
    }
  },
  "definitions": {
    "LocalModel": {
      "type": "object",
      "properties": {
        "annotations": {
          "type": "object",
          "description": "Annotations associated with the model.",
          "properties": {
            "tags": {
              "type": "object",
              "description": "Tags associated with the annotation.",
              "properties": {
                "author": { "type": "string" },
                "alias": { "type": "string" },
                "directoryPath": { "type": "string" },
                "license": { "type": "string" },
                "licenseDescription": { "type": "string" },
                "promptTemplate": { "type": "string" },
                "task": { "type": "string" }
              }
            },
            "systemCatalogData": {
              "type": "object",
              "properties": {
                "publisher": { "type": "string" },
                "displayName": { "type": "string" }
              }
            },
            "name": { "type": "string" }
          }
        },
        "properties": {
          "type": "object",
          "description": "Properties of the model.",
          "properties": {
            "name": { "type": "string" },
            "version": { "type": "integer" },
            "alphanumericVersion": { "type": "string" },
            "variantInfo": {
              "type": "object",
              "properties": {
                "parents": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "assetId": { "type": "string" }
                    }
                  }
                },
                "variantMetadata": {
                  "type": "object",
                  "properties": {
                    "modelType": { "type": "string" },
                    "device": { "type": "string" },
                    "executionProvider": { "type": "string" },
                    "fileSizeBytes": { "type": "integer" }
                  }
                }
              }
            }
          }
        },
        "version": {
          "type": "string",
          "description": "The version of the model."
        },
        "assetId": {
          "type": "string",
          "description": "The asset ID of the model."
        }
      }
    }
  }
}

المصدر:

• Get started
• ما هو Foundry Local؟