目录 API 参考

Foundry Local 允许生成和集成自己的目录服务。 本文介绍：

• 目录 API 所需的模型格式
• 目录 API 与 Foundry Local 集成所需的请求和响应格式

模型格式

模型目录中的模型文件必须采用 Open Neural Network Exchange （ONNX） 格式才能使用 Foundry Local。 若要了解如何将拥抱人脸和 PyTorch 模型编译到 ONNX，请参阅 编译拥抱人脸模型以在本地 Foundry 上运行。

API 格式

请求

实现接受目录服务中的 JSON 请求正文的 POST 终结点。 目录 API 的请求格式如下所示：

• 方法：POST
• Content-Type： application/json

请求正文必须是具有以下字段的 JSON 对象：

• resourceIds：指定要查询的资源的资源 ID 的数组
  • resourceId：资源的 ID
  • entityContainerType：实体容器的类型（例如，RegistryWorkspace等）
• indexEntitiesRequest：包含搜索参数的对象。
  • filters：用于指定筛选搜索结果的条件的筛选器对象的数组
    • field：要筛选的字段（例如，typekind等）
    • operator：要用于筛选器的运算符。 例如（ eq equals）、 ne （不等于）、 gt （大于）、 lt （小于）等。
    • values：要与字段匹配的值数组
  • orderBy：要按 对结果进行排序的字段数组
  • searchText：在结果中搜索的字符串
  • pageSize：要返回的最大结果数（对于分页）
  • skip：要跳过的结果数（对于分页）
  • continuationToken：分页要从上一个请求继续的令牌

可筛选字段（可选）

实现目录 API，使其接受 请求 格式。 服务器端筛选是可选的。 跳过服务器端筛选可以更快地实现，但搜索模型效率较低。

如果实现服务器端筛选，请使用以下字段：

• type：模型的类型（例如 models， datasets等等）。
• kind：模型类型（例如，VersionedUnversioned等）。
• properties/variantInfo/variantMetadata/device：设备类型（例如，cpugpu等）。
• properties/variantInfo/variantMetadata/executionProvider：执行提供程序（例如 cpuexecutionprovider， webgpuexecutionprovider等）。

示例请求

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

响应

目录 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."
        }
      }
    }
  }
}