Referência da API do catálogo

O Foundry Local permite que você crie e integre seu próprio serviço de catálogo. Este artigo aborda:

• Formato de modelo necessário para a API de catálogo
• Formato de solicitação e resposta necessário para que a API do catálogo se integre ao Foundry Local

Pré-requisitos

• Você instalou o Foundry Local.
• Você pode executar um serviço Web que expõe um POST ponto de extremidade.
• Seus artefatos de modelo estão disponíveis no formato ONNX.
• RBAC (controle de acesso baseado em função) do Azure: não aplicável.

Formato de modelo

Para trabalhar com o Foundry Local, seu catálogo de modelos deve conter arquivos de modelo no formato ONNX (Open Neural Network Exchange ). Para saber como compilar modelos de Detecção Facial e PyTorch no ONNX, consulte Compilar modelos de Detecção Facial para serem executados no Foundry Local.

Formato de API

Solicitação

Implemente um ponto de extremidade POST em seu serviço de catálogo que aceite um corpo de solicitação JSON. O formato de solicitação para a API de catálogo é o seguinte:

• Método: POST
• Tipo de conteúdo: application/json

Solicitação de exemplo

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

Substitua pela <your-catalog-api-endpoint> URL do serviço de catálogo.

O que esperar

• Uma resposta bem-sucedida inclui um indexEntitiesResponse objeto.
• Os resultados da pesquisa são retornados em indexEntitiesResponse.value.

Referência:

• Referência da API REST local do Foundry
• Práticas recomendadas e solução de problemas

O corpo da solicitação deve ser um objeto JSON com os seguintes campos:

• resourceIds: uma matriz de IDs de recurso que especificam os recursos a serem consultados. Cada item inclui:
  • resourceId: a ID do recurso.
  • entityContainerType: o tipo de contêiner de entidade, como Registry, Workspacee outros.
• indexEntitiesRequest: um objeto que contém os parâmetros de pesquisa.
  • filters: uma matriz de objetos de filtro que especificam os critérios para filtrar os resultados da pesquisa. Cada filtro inclui:
    • field: o campo no qual filtrar, como type, kinde outros.
    • operator: o operador a ser usado para o filtro. Por exemplo, eq (igual a), ne (não é igual), gt (maior que), lt (menor que) e outros.
    • values: uma matriz de valores a serem correspondentes ao campo.
  • orderBy: uma matriz de campos para ordenar os resultados.
  • searchText: uma cadeia de caracteres a ser pesquisada nos resultados.
  • pageSize: o número máximo de resultados a serem retornados (para paginação).
  • skip: o número de resultados a serem ignoradas (para paginação).
  • continuationToken: um token para paginação para continuar de uma solicitação anterior.

Campos filtreáveis (opcional)

Implemente a API de catálogo para que ela aceite o formato de solicitação . A filtragem do lado do servidor é opcional. Ignorar a filtragem do lado do servidor é mais rápido de implementar, mas é menos eficiente para pesquisar modelos.

Se você implementar a filtragem do lado do servidor, use os seguintes campos:

• type: o tipo do modelo, como models, datasetse outros.
• kind: o tipo do modelo, como Versioned, Unversionede outros.
• properties/variantInfo/variantMetadata/device: o tipo de dispositivo, como cpu, gpue outros.
• properties/variantInfo/variantMetadata/executionProvider: o provedor de execução, como cpuexecutionprovider, webgpuexecutionprovidere outros.

Resposta

A API do catálogo retorna um objeto JSON que contém os resultados da pesquisa.

Resposta de exemplo

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

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

Referência:

• Introdução
• O que é o Foundry Local?