Informations de référence sur l’API catalogue

Foundry Local vous permet de créer et d’intégrer votre propre service catalogue. Cet article couvre :

• Format de modèle requis pour l’API catalogue
• Format de demande et de réponse requis pour que votre API de catalogue s’intègre à Foundry Local

Prerequisites

• Vous avez installé Foundry Local.
• Vous pouvez exécuter un service web qui expose un POST point de terminaison.
• Vos artefacts de modèle sont disponibles au format ONNX.
• Contrôle d’accès en fonction du rôle Azure (RBAC) : non applicable.

Format du modèle

Pour utiliser Foundry Local, votre catalogue de modèles doit contenir des fichiers de modèle au format ONNX (Open Neural Network Exchange). Pour savoir comment compiler des modèles Hugging Face et PyTorch sur ONNX, consultez Compiler les modèles Visage hugging à exécuter sur Foundry Local.

Format d’API

Requête

Implémentez un point de terminaison POST dans votre service catalogue qui accepte un corps de requête JSON. Le format de demande de l’API catalogue est le suivant :

• Méthode : POST
• Type de contenu : application/json

Exemple de requête

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

Remplacez <your-catalog-api-endpoint> par l’URL de votre service catalogue.

À quoi s’attendre ?

• Une réponse réussie inclut un indexEntitiesResponse objet.
• Les résultats de la recherche sont retournés dans indexEntitiesResponse.value.

Référence  :

• Informations de référence sur l’API REST locale de Foundry
• Bonnes pratiques et résolution des problèmes

Le corps de la demande doit être un objet JSON avec les champs suivants :

• resourceIds: tableau d’ID de ressource qui spécifient les ressources à interroger. Chaque élément comprend :
  • resourceId: ID de la ressource.
  • entityContainerType: type de conteneur d’entité, tel que Registry, Workspaceet d’autres.
• indexEntitiesRequest: objet qui contient les paramètres de recherche.
  • filters: tableau d’objets de filtre qui spécifient les critères de filtrage des résultats de recherche. Chaque filtre inclut :
    • field: champ sur lequel filtrer, tel que type, kindet d’autres.
    • operator: opérateur à utiliser pour le filtre. Par exemple, eq (égal à), ne (différent), gt (supérieur à), lt (inférieur à) et d’autres.
    • values: tableau de valeurs à mettre en correspondance avec le champ.
  • orderBy: tableau de champs par lequel classer les résultats.
  • searchText: chaîne à rechercher dans les résultats.
  • pageSize: nombre maximal de résultats à retourner (pour la pagination).
  • skip: nombre de résultats à ignorer (pour la pagination).
  • continuationToken: jeton pour la pagination à continuer à partir d’une requête précédente.

Champs filtrables (facultatif)

Implémentez l’API de catalogue afin qu’elle accepte le format de requête . Le filtrage côté serveur est facultatif. Ignorer le filtrage côté serveur est plus rapide à implémenter, mais est moins efficace pour la recherche de modèles.

Si vous implémentez le filtrage côté serveur, utilisez les champs suivants :

• type: type du modèle, tel que models, datasetset d’autres.
• kind: type du modèle, tel que Versioned, Unversionedet d’autres.
• properties/variantInfo/variantMetadata/device: type d’appareil, tel que cpu, gpuet d’autres.
• properties/variantInfo/variantMetadata/executionProvider: fournisseur d’exécution, tel que cpuexecutionprovider, webgpuexecutionprovideret d’autres.

Réponse

L’API catalogue retourne un objet JSON qui contient les résultats de la recherche.

Exemple de réponse

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

Schéma de réponse

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

Référence  :

• Démarrer
• Qu’est-ce que Foundry Local ?