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

Это важно

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

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

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

Предпосылки

• Установлено локальное приложение Foundry.
• Вы можете запустить веб-службу, которая предоставляет конечную точку POST .
• Артефакты модели доступны в формате ONNX.
• Управление доступом на основе ролей Azure (RBAC): неприменимо.

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

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

Формат API

Просьба

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

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

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

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

Замените <your-catalog-api-endpoint> URL-адрес службы каталога.

Основные принципы

• Успешный indexEntitiesResponse ответ включает объект.
• Результаты поиска возвращаются в indexEntitiesResponse.value.

Ссылка:

• Справочник по локальному REST API Foundry
• Рекомендации и устранение неполадок

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

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

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

Реализуйте API каталога, чтобы он принял формат запроса . Фильтрация на стороне сервера является необязательной. Пропускание фильтрации на стороне сервера быстрее реализуется, но менее эффективно для поиска моделей.

При реализации фильтрации на стороне сервера используйте следующие поля:

• type: тип модели, например modelsdatasets, и другие.
• kind: тип модели, например VersionedUnversioned, и другие.
• properties/variantInfo/variantMetadata/device: тип устройства, например cpu, gpuи другие.
• properties/variantInfo/variantMetadata/executionProvider: поставщик выполнения, например cpuexecutionprovider, webgpuexecutionproviderи другие.

Отклик

API каталога возвращает объект JSON, содержащий результаты поиска.

Пример отклика

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

Схема ответа

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

Ссылка:

• Начало работы
• Что такое Foundry Local?