目录 API 参考

Foundry Local 允许开发和集成自己的目录服务。 本文档提供有关以下方面的指导：

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

模型格式

模型目录中托管的模型文件必须采用 Open Neural Network Exchange （ONNX） 格式才能使用 Foundry Local。 有关如何将 Hugging Face 和 PyTorch 模型编译到 ONNX 的详细信息，请参阅在 Foundry Local 文章上运行的编译拥抱人脸模型 。

API 格式

请求

目录服务需要支持接受 JSON 请求正文的 POST 终结点。 目录 API 的请求格式如下所示：

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

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

• resourceIds：指定要查询的资源的资源 ID 的数组。
  • resourceId：资源的 ID。
  • entityContainerType：实体容器的类型（例如 Registry， Workspace等）。
• indexEntitiesRequest：包含搜索参数的对象。
  • filters：一组筛选器对象，用于指定筛选搜索结果的条件。
    • field：要筛选的字段（例如 type， kind等）。
    • 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 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."
        }
      }
    }
  }
}