Katalog-API-referens

Viktigt!

• Foundry Local är tillgängligt i förhandsversionen. Offentliga förhandsversioner ger tidig åtkomst till funktioner som är i aktiv distribution.
• Funktioner, metoder och processer kan ändra eller ha begränsade funktioner, före allmän tillgänglighet (GA).

Med Foundry Local kan du utveckla och integrera din egen katalogtjänst. Det här dokumentet innehåller vägledning om:

• Modellformatet som krävs för katalog-API:et.
• Det format för begäran och svar som krävs för att katalog-API:et ska kunna integreras med Foundry Local.

Modellformat

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

API-format

Begäran

Katalogtjänsten måste ha stöd för en POST-slutpunkt som accepterar en JSON-begärandetext. Begärandeformatet för katalog-API:et är följande:

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

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

• resourceIds: En matris med resurs-ID:t som anger vilka resurser som ska efterfrå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 villkoret 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 som resultatet ska sorteras 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)

Du måste implementera katalog-API:et som accepterarbegärandeformatet , men det är valfritt om du implementerar filtrering på serversidan i katalogtjänsten. Att inte implementera filtrering på serversidan är ett snabbt sätt att implementera katalogtjänsten, men det kanske inte är ett effektivt sätt att söka efter modeller.

Om du väljer att implementera filtrering på serversidan kan du använda följande fält för att filtrera resultatet:

• 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 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."
        }
      }
    }
  }
}