Informazioni di riferimento sulle API del catalogo

Foundry Local consente di compilare e integrare il proprio servizio catalogo. Questo articolo tratta:

• Formato del modello necessario per l'API del catalogo
• Formato di richiesta e risposta necessario per l'integrazione dell'API del catalogo con Foundry Local

Prerequisiti

• È stato installato Foundry Local.
• È possibile eseguire un servizio Web che espone un POST endpoint.
• Gli artefatti del modello sono disponibili in formato ONNX.
• Controllo degli accessi in base al ruolo di Azure: non applicabile.

Formato del modello

Per usare Foundry Local, il catalogo dei modelli deve contenere file di modello nel formato OPEN Neural Network Exchange (ONNX). Per informazioni su come compilare modelli Hugging Face e PyTorch in ONNX, vedere Compilare modelli viso hugging da eseguire in Foundry Local.

Formato API

Richiesta

Implementare un endpoint POST nel servizio di catalogo che accetta un corpo della richiesta JSON. Il formato di richiesta per l'API del catalogo è il seguente:

• Metodo: POST
• Tipo di contenuto: application/json

Richiesta di esempio

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

Sostituire <your-catalog-api-endpoint> con l'URL del servizio catalogo.

Cosa aspettarsi

• Una risposta con esito positivo include un indexEntitiesResponse oggetto .
• I risultati della ricerca vengono restituiti in indexEntitiesResponse.value.

Riferimento:

• Riferimento all'API REST locale di Fonderia
• Procedure consigliate e risoluzione dei problemi

Il corpo della richiesta deve essere un oggetto JSON con i campi seguenti:

• resourceIds: matrice di ID risorsa che specificano le risorse da eseguire per la query. Ogni elemento include:
  • resourceId: ID della risorsa.
  • entityContainerType: tipo di contenitore di entità, ad esempio Registry, Workspacee altri.
• indexEntitiesRequest: oggetto contenente i parametri di ricerca.
  • filters: matrice di oggetti filtro che specificano i criteri per filtrare i risultati della ricerca. Ogni filtro include:
    • field: campo da filtrare, ad esempio type, kinde altri.
    • operator: operatore da usare per il filtro. Ad esempio, eq (uguale a), ne (diverso da), gt (maggiore di), lt (minore di) e altri.
    • values: matrice di valori da associare al campo.
  • orderBy: matrice di campi per ordinare i risultati in base a .
  • searchText: stringa da cercare nei risultati.
  • pageSize: numero massimo di risultati da restituire (per la paginazione).
  • skip: numero di risultati da ignorare (per la paginazione).
  • continuationToken: token per la paginazione da continuare da una richiesta precedente.

Campi filtrabili (facoltativo)

Implementare l'API del catalogo in modo che accetti il formato richiesta . Il filtro lato server è facoltativo. Ignorare il filtro lato server è più veloce da implementare, ma è meno efficiente per la ricerca dei modelli.

Se si implementa il filtro lato server, usare i campi seguenti:

• type: tipo del modello, ad esempio models, datasetse altri.
• kind: tipo di modello, ad esempio Versioned, Unversionede altri.
• properties/variantInfo/variantMetadata/device: tipo di dispositivo, ad esempio cpu, gpue altri.
• properties/variantInfo/variantMetadata/executionProvider: provider di esecuzione, ad esempio cpuexecutionprovider, webgpuexecutionprovidere altri.

Risposta

L'API del catalogo restituisce un oggetto JSON che contiene i risultati della ricerca.

Risposta di esempio

{
  "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 della risposta

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

Riferimento:

• Introduzione
• Che cos'è Foundry Local?