Katalog-API-referens

Med Foundry Local kan du skapa och integrera din egen katalogtjänst. Denna artikel omfattar:

• Modellformat som krävs för katalog-API:et
• Begärande- och svarsformat som krävs för att katalog-API:et ska kunna integreras med Foundry Local

Modellformat

Modellfiler i modellkatalogen måste vara i ONNX-format (Open Neural Network Exchange) för att fungera med Foundry Local. Information om hur du kompilerar Hugging Face- och PyTorch-modeller till ONNX finns i Kompilera Hugging Face-modeller som ska köras på Foundry Local.

API-format

Begäran

Implementera en POST-slutpunkt som accepterar en JSON-begärandetext i katalogtjänsten. Begärandeformatet för katalog-API:et är följande:

• Metod: POST
• Innehållstyp: application/json

Begärandetexten måste vara ett JSON-objekt med följande fält:

• resourceIds: En matris med resurs-ID:t som anger vilka resurser som ska frågas
  • resourceId: Resursens ID
  • entityContainerType: Typen av entitetscontainer (till exempel Registry, Workspace, osv.)
• indexEntitiesRequest: Ett objekt som innehåller sökparametrarna.
  • filters: En matris med filterobjekt som anger villkor för filtrering av sökresultaten
    • field: Fältet som ska filtreras på (till exempel type, kind, osv.)
    • operator: Operatorn som ska användas för filtret. Till exempel eq (lika med), ne (inte lika med), gt (större än), lt (mindre än) osv.
    • values: En matris med värden som ska matchas mot fältet
  • orderBy: En matris med fält för att sortera resultatet efter
  • searchText: En sträng att söka efter i resultatet
  • pageSize: Det maximala antalet resultat som ska returneras (för sidnumrering)
  • skip: Antalet resultat att hoppa över (för sidnumrering)
  • continuationToken: En token för sidnumrering för att fortsätta från en tidigare begäran

Filterbara fält (valfritt)

Implementera katalog-API:et så att det accepterar formatet Begäran . Filtrering på serversidan är valfritt. Att hoppa över filtrering på serversidan är snabbare att implementera men är mindre effektivt för att söka efter modeller.

Om du implementerar filtrering på serversidan använder du följande fält:

• type: Typ av modell (till exempel models, datasets, osv.).
• kind: Typen av modell (till exempel Versioned, Unversioned, osv.).
• properties/variantInfo/variantMetadata/device: Enhetstypen (till exempel cpu, gpuosv.).
• properties/variantInfo/variantMetadata/executionProvider: Körningsprovidern (till exempel cpuexecutionprovider, webgpuexecutionproviderosv.).

Exempel på begäran

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

Svar

Svaret från katalog-API:et är ett JSON-objekt som innehåller sökresultaten. Svarsschemat är följande:

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