Referência da API do catálogo

O Foundry Local permite-lhe criar e integrar o seu próprio serviço de catálogo. Este artigo abrange:

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

Pré-requisitos

• Tem o Foundry Local instalado.
• Podes executar um serviço web que expõe um POST endpoint.
• Os artefactos do seu modelo estão disponíveis em formato ONNX.
• Controlo de acesso baseado em funções Azure (RBAC): Não aplicável.

Formato do modelo

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

Formato da API

Solicitação

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

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

Exemplo de pedido

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 <your-catalog-api-endpoint> pelo URL do seu 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 local REST 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: Um conjunto de IDs de recursos que especificam os recursos a consultar. Cada item inclui:
  • resourceId: O ID do recurso.
  • entityContainerType: O tipo de recipiente de entidade, como Registry, Workspace, e outros.
• indexEntitiesRequest: Um objeto que contém os parâmetros de pesquisa.
  • filters: Um array de objetos de filtro que especificam os critérios para filtrar os resultados da pesquisa. Cada filtro inclui:
    • field: O campo para filtrar, como type, kind, e outros.
    • operator: O operador a utilizar para o filtro. Por exemplo, eq (igual), ne (não igual gt ), (maior que), lt (menor que) e outros.
    • values: Um conjunto de valores para corresponder ao campo.
  • orderBy: Um array de campos para ordenar os resultados.
  • searchText: Uma sequência para procurar nos resultados.
  • pageSize: O número máximo de resultados a devolver (para paginação).
  • skip: O número de resultados a saltar (para paginação).
  • continuationToken: Um token para a paginação continuar a partir de um pedido anterior.

Campos filtráveis (opcional)

Implemente a API do 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, datasets, e outros.
• kind: O tipo de modelo, como Versioned, Unversioned, e outros.
• properties/variantInfo/variantMetadata/device: O tipo de dispositivo, como cpu, gpu, e outros.
• properties/variantInfo/variantMetadata/executionProvider: O fornecedor de execução, como cpuexecutionprovider, webgpuexecutionprovider, e outros.

Resposta

A API de catálogo devolve 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 é a Foundry Local?