Katalog API'si başvurusu

Önemli

Foundry Local önizleme aşamasındadır. Genel önizleme sürümleri, etkin dağıtımdaki özelliklere erken erişim sağlar.
Özellikler, yaklaşımlar ve işlemler, Genel Kullanılabilirlik (GA) öncesinde değişebilir veya sınırlı özelliklere sahip olabilir.

Foundry Local, kendi katalog hizmetinizi oluşturmanıza ve tümleştirmenize olanak tanır. Bu makalede aşağıdakiler ele alınmaktadır:

Katalog API'si için gereken model biçimi
Katalog API'nizin Foundry Local ile tümleştirilmesi için gereken istek ve yanıt biçimi

Önkoşullar

Foundry Local yüklüdür.
Uç noktayı kullanıma sunan bir POST web hizmeti çalıştırabilirsiniz.
Model yapıtlarınız ONNX biçiminde kullanılabilir.
Azure rol tabanlı erişim denetimi (RBAC): Geçerli değildir.

Model biçimi

Foundry Local ile çalışmak için model kataloğunuzun Açık Sinir Ağı Değişimi (ONNX) biçiminde model dosyaları içermesi gerekir. Hugging Face ve PyTorch modellerini ONNX'e derlemeyi öğrenmek için bkz. Foundry Local üzerinde çalıştırılacak Sarılma Yüzü modellerini derleme.

API biçimi

İstek

Katalog hizmetinizde JSON istek gövdesini kabul eden bir POST uç noktası uygulayın. Katalog API'sinin istek biçimi aşağıdaki gibidir:

Yöntem: POST
İçerik Türü: application/json

Örnek istek

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
  }
}'

değerini katalog hizmeti URL'nizle değiştirin <your-catalog-api-endpoint> .

Neler bekleyebileceğiniz

Başarılı bir yanıt bir indexEntitiesResponse nesnesi içerir.
Arama sonuçları içinde indexEntitiesResponse.valuedöndürülür.

Referans:

İstek gövdesi aşağıdaki alanlara sahip bir JSON nesnesi olmalıdır:

resourceIds: Sorgulanan kaynakları belirten kaynak kimlikleri dizisi. Her öğe şunları içerir:
- resourceId: Kaynağın kimliği.
- entityContainerType: , Registryve diğerleri gibi Workspacevarlık kapsayıcısının türü.
indexEntitiesRequest: Arama parametrelerini içeren bir nesne.
- filters: Arama sonuçlarını filtreleme ölçütlerini belirten bir filtre nesneleri dizisi. Her filtre şunları içerir:
  - field: Filtre uygulamak için , typeve diğerleri gibi kindalan.
  - operator: Filtre için kullanılacak işleç. Örneğin, eq (eşittir), ne (eşit değil), gt (büyüktür), lt (küçüktür) ve diğerleri.
  - values: Alanıyla eşleşecek bir değer dizisi.
- orderBy: Sonuçları sıralamak için bir alan dizisi.
- searchText: Sonuçlarda aranacak dize.
- pageSize: Döndürülecek en fazla sonuç sayısı (sayfalandırma için).
- skip: Atlanması gereken sonuç sayısı (sayfalandırma için).
- continuationToken: Önceki bir istekten devam etmek için sayfalandırma belirteci.

Filtrelenebilir alanlar (isteğe bağlı)

İstek biçimini kabul etmek için katalog API'sini uygulayın. Sunucu tarafı filtreleme isteğe bağlıdır. Sunucu tarafı filtrelemenin atlanması daha hızlıdır ancak model arama için daha az verimlidir.

Sunucu tarafı filtrelemesi uygularsanız aşağıdaki alanları kullanın:

type: Modelin türü, örneğin models, datasetsve diğerleri.
kind: Modelin türü, örneğin Versioned, Unversionedve diğerleri.
properties/variantInfo/variantMetadata/device: Cihaz türü , ve diğerleri gibicpugpu.
properties/variantInfo/variantMetadata/executionProvider: , ve diğerleri gibi cpuexecutionproviderwebgpuexecutionprovideryürütme sağlayıcısı.

Yanıt

Katalog API'si, arama sonuçlarını içeren bir JSON nesnesi döndürür.

Örnek yanıt

{
  "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
  }
}

Yanıt şeması

{
  "$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."
        }
      }
    }
  }
}