Referencia de api de catálogo

Importante

Foundry Local está disponible en versión preliminar. Las versiones preliminares públicas proporcionan acceso anticipado a las características que se encuentran en la implementación activa.
Las características, los enfoques y los procesos pueden cambiar o tener funcionalidades limitadas, antes de la disponibilidad general (GA).

Foundry Local le permite crear e integrar su propio servicio de catálogo. Este artículo cubre:

Formato de modelo necesario para la API de catálogo
Formato de solicitud y respuesta necesario para que la API de catálogo se integre con Foundry Local

Prerrequisitos

Ha instalado Foundry Local.
Puede ejecutar un servicio web que exponga un POST punto de conexión.
Los artefactos del modelo están disponibles en formato ONNX.
Control de acceso basado en rol (RBAC) de Azure: no aplicable.

Formato de modelo

Para trabajar con Foundry Local, el catálogo de modelos debe contener archivos de modelo en el formato Open Neural Network Exchange (ONNX). Para obtener información sobre cómo compilar modelos de Hugging Face y PyTorch en ONNX, consulte Compile Hugging Face models to run on Foundry Local (Compilar modelos de Face hugging para ejecutarse en Foundry Local).

Formato de API

Solicitud

Implemente un punto de conexión POST en el servicio de catálogo que acepte un cuerpo de solicitud JSON. El formato de solicitud de la API de catálogo es el siguiente:

Método: POST
Tipo de contenido: application/json

Solicitud de ejemplo

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

Reemplace por <your-catalog-api-endpoint> la dirección URL del servicio de catálogo.

Qué cabe esperar

Una respuesta correcta incluye un indexEntitiesResponse objeto .
Los resultados de la búsqueda se devuelven en indexEntitiesResponse.value.

Referencia:

El cuerpo de la solicitud debe ser un objeto JSON con los siguientes campos:

resourceIds: matriz de identificadores de recursos que especifican los recursos que se van a consultar. Cada elemento incluye:
- resourceId: el identificador del recurso.
- entityContainerType: el tipo de contenedor de entidades, como Registry, Workspacey otros.
indexEntitiesRequest: objeto que contiene los parámetros de búsqueda.
- filters: matriz de objetos de filtro que especifican los criterios para filtrar los resultados de la búsqueda. Cada filtro incluye:
  - field: el campo en el que se va a filtrar, como type, kindy otros.
  - operator: el operador que se va a usar para el filtro. Por ejemplo, eq (iguales), (no iguales), gtne (mayor que), lt (menor que) y otros.
  - values: matriz de valores que debe coincidir con el campo.
- orderBy: matriz de campos por la que ordenar los resultados.
- searchText: cadena que se va a buscar en los resultados.
- pageSize: el número máximo de resultados que se van a devolver (para la paginación).
- skip: número de resultados que se van a omitir (para la paginación).
- continuationToken: un token para que la paginación continúe desde una solicitud anterior.

Campos filtrables (opcional)

Implemente la API de catálogo para que acepte el formato de solicitud . El filtrado del lado servidor es opcional. Omitir el filtrado del lado servidor es más rápido de implementar, pero es menos eficaz para buscar modelos.

Si implementa el filtrado del lado servidor, use los siguientes campos:

type: el tipo del modelo, como models, datasetsy otros.
kind: el tipo del modelo, como Versioned, Unversionedy otros.
properties/variantInfo/variantMetadata/device: el tipo de dispositivo, como cpu, gpuy otros.
properties/variantInfo/variantMetadata/executionProvider: el proveedor de ejecución, como cpuexecutionprovider, webgpuexecutionprovidery otros.

Respuesta

La API de catálogo devuelve un objeto JSON que contiene los resultados de la búsqueda.

Respuesta de ejemplo

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

Esquema de respuesta

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