Справочник по API каталога

Это важно

• Foundry Local доступен в предварительной версии. Общедоступные предварительные выпуски предоставляют ранний доступ к функциям, которые находятся в активном развертывании.
• Функции, подходы и процессы могут изменяться или иметь ограниченные возможности до общедоступной доступности.

Foundry Local позволяет разрабатывать и интегрировать собственную службу каталогов. В этом документе приведены рекомендации по следующим вопросам:

• Формат модели, необходимый для API каталога.
• Формат запроса и ответа, необходимый для интеграции API каталога с Foundry Local.

Формат модели

Файлы модели, размещенные в каталоге моделей, должны находиться в формате Open Neural Network Exchange (ONNX) для работы с Foundry Local. Дополнительные сведения о компиляции моделей Hugging Face и PyTorch в ONNX см. в статье о компиляции моделей hugging Face, которые будут выполняться в статье Foundry Local .

Формат API

Просьба

Служба каталога должна поддерживать конечную точку POST, принимающую текст запроса JSON. Формат запроса для API каталога выглядит следующим образом:

• Метод: POST
• Тип контента: application/json

Текст запроса должен быть объектом JSON, принимаюющим следующие поля:

• resourceIds: массив идентификаторов ресурсов, указывающих запрашиваемые ресурсы.
  • resourceId: идентификатор ресурса.
  • entityContainerType: тип контейнера сущностей (например, Registry, Workspaceи т. д.).
• indexEntitiesRequest: объект, содержащий параметры поиска.
  • filters: массив объектов фильтра, указывающий критерии фильтрации результатов поиска.
    • field: поле для фильтрации (например, type, kindи т. д.).
    • operator: оператор, используемый для фильтра. Например, eq (равно), ne (не равно), gt (больше), lt (меньше), и т. д.
    • values: массив значений для сопоставления с полем.
  • orderBy: массив полей для упорядочивания результатов.
  • searchText: строка для поиска в результатах.
  • pageSize: максимальное количество возвращаемых результатов (для разбиения на страницы).
  • skip: количество пропускаемых результатов (для разбиения на страницы).
  • continuationToken: маркер для разбиения на страницы для продолжения предыдущего запроса.

Фильтруемые поля (необязательно)

Необходимо реализовать API каталога, который принимает формат запроса, но необязательно, чтобы реализовать фильтрацию на стороне сервера в службе каталога. Не реализация фильтрации на стороне сервера — это быстрый способ реализации службы каталога, но это может оказаться не эффективным способом поиска моделей.

Если вы решили реализовать фильтрацию на стороне сервера, можно использовать следующие поля для фильтрации результатов:

• type: тип модели (например, models, datasetsи т. д.).
• kind: тип модели (например, Versioned, Unversionedи т. д.).
• properties/variantInfo/variantMetadata/device: тип устройства (например, cpu, gpuи т. д.).
• properties/variantInfo/variantMetadata/executionProvider: поставщик выполнения (например, cpuexecutionprovider, webgpuexecutionproviderи т. д.).

Пример запроса

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

Ответ

Ответ от API каталога — это объект JSON, содержащий результаты поиска. Схема ответа выглядит следующим образом:

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