Referenční informace k rozhraní API katalogu

Důležité

• Foundry Local je k dispozici ve verzi Preview. Verze Public Preview poskytují dřívější access funkcím, které jsou v aktivním nasazení.
• Funkce, přístupy a procesy se můžou před obecnou dostupností měnit nebo mít omezené možnosti.

Foundry Local umožňuje sestavovat a integrovat vlastní službu katalogu. Tento článek se věnuje následujícím tématům:

• Formát modelu vyžadovaný pro rozhraní API katalogu
• Požadavek a formát odpovědi vyžadovaný pro rozhraní API katalogu pro integraci s Foundry Local

Předpoklady

• Máte nainstalovaný Foundry Local.
• Můžete spustit webovou službu, která zveřejňuje POST koncový bod.
• Váš model artifacts je k dispozici ve formátu ONNX.
• Azure access control na základě role (RBAC): Nejde použít.

Formát modelu

Pokud chcete pracovat s Foundry Local, musí katalog modelů obsahovat soubory modelu ve formátu Open neurální síť Exchange (ONNX). Informace o kompilaci modelů Hugging Face a PyTorch do ONNX najdete v tématu Kompilace modelů Hugging Face ke spuštění na Foundry Local.

Formát rozhraní API

Žádost

Implementujte koncový bod POST ve službě katalogu, který přijímá text požadavku JSON. Formát požadavku pro rozhraní API katalogu je následující:

• Metoda: POST
• Typ obsahu: application/json

Příklad požadavku

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

Nahraďte <your-catalog-api-endpoint> adresou URL služby katalogu.

Co očekávat

• Úspěšná odpověď zahrnuje indexEntitiesResponse objekt.
• Výsledky hledání se vrátí v indexEntitiesResponse.value.

Odkaz

• Referenční informace k rozhraní REST API služby Foundry Local
• Osvědčené postupy a řešení potíží

Text požadavku musí být objekt JSON s následujícími poli:

• resourceIds: Pole ID prostředků, které určují prostředky, které se mají dotazovat. Každá položka zahrnuje:
  • resourceId: ID prostředku.
  • entityContainerType: Typ kontejneru entit, například Registry, Workspacea dalších.
• indexEntitiesRequest: Objekt, který obsahuje parametry hledání.
  • filters: Pole objektů filtru, které určují kritéria pro filtrování výsledků hledání. Každý filtr zahrnuje:
    • field: Pole pro filtrování, například type, kinda další.
    • operator: Operátor, který se má použít pro filtr. Například eq (rovná se), (nerovná se), negt (větší než), lt (menší než) a další.
    • values: Pole hodnot, které se mají shodovat s polem.
  • orderBy: Pole polí k seřazení výsledků podle.
  • searchText: Řetězec, který se má vyhledat ve výsledcích.
  • pageSize: Maximální počet výsledků, které se mají vrátit (pro stránkování).
  • skip: Počet výsledků, které se mají přeskočit (pro stránkování).
  • continuationToken: Token pro stránkování, který bude pokračovat z předchozího požadavku.

Filtrovatelná pole (volitelné)

Implementujte rozhraní API katalogu, aby přijímalo formát požadavku . Filtrování na straně serveru je volitelné. Přeskočení filtrování na straně serveru je rychlejší implementovat, ale je méně efektivní pro vyhledávání modelů.

Pokud implementujete filtrování na straně serveru, použijte následující pole:

• type: Typ modelu, například models, datasetsa další.
• kind: Druh modelu, například Versioned, Unversioneda další.
• properties/variantInfo/variantMetadata/device: Typ zařízení, například cpu, gpua další.
• properties/variantInfo/variantMetadata/executionProvider: Zprostředkovatel spouštění, například cpuexecutionprovider, webgpuexecutionprovidera další.

Odezva

Rozhraní API katalogu vrátí objekt JSON, který obsahuje výsledky hledání.

Příklad odpovědi

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

Schéma odpovědi

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

Odkaz

• Get started
• Co je Foundry Local?