Dokumentacja interfejsu API wykazu

Usługa Foundry Local umożliwia tworzenie i integrowanie własnej usługi katalogu. Ten artykuł dotyczy:

• Format modelu wymagany dla interfejsu API wykazu
• Format żądania i odpowiedzi wymagany do integracji interfejsu API katalogu z usługą Foundry Local

Wymagania wstępne

• Zainstalowano program Foundry Local.
• Możesz uruchomić usługę internetową, która uwidacznia POST punkt końcowy.
• Artefakty modelu są dostępne w formacie ONNX.
• Kontrola dostępu oparta na rolach (RBAC) platformy Azure: nie dotyczy.

Format modelu

Aby pracować z programem Foundry Local, katalog modeli musi zawierać pliki modelu w formacie Open Neural Network Exchange (ONNX). Aby dowiedzieć się, jak skompilować modele Hugging Face i PyTorch do onNX, zobacz Kompilowanie modeli rozpoznawania twarzy hugging do uruchamiania w środowisku lokalnym foundry.

Format interfejsu API

Żądanie

Zaimplementuj punkt końcowy POST w usłudze katalogu, który akceptuje treść żądania JSON. Format żądania dla interfejsu API wykazu jest następujący:

• Metoda: POST
• Typ zawartości: application/json

Przykładowe żądanie

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

Zastąp <your-catalog-api-endpoint> ciąg adresem URL usługi katalogu.

Czego można się spodziewać

• Pomyślna odpowiedź zawiera indexEntitiesResponse obiekt.
• Wyniki wyszukiwania są zwracane w pliku indexEntitiesResponse.value.

Reference:

• Dokumentacja lokalnego interfejsu API REST usługi Foundry
• Najlepsze rozwiązania i rozwiązywanie problemów

Treść żądania musi być obiektem JSON z następującymi polami:

• resourceIds: tablica identyfikatorów zasobów określających zasoby do wykonywania zapytań. Każdy element zawiera:
  • resourceId: identyfikator zasobu.
  • entityContainerType: typ kontenera jednostek, taki jak Registry, Workspacei inne.
• indexEntitiesRequest: obiekt zawierający parametry wyszukiwania.
  • filters: tablica obiektów filtru, które określają kryteria filtrowania wyników wyszukiwania. Każdy filtr obejmuje:
    • field: pole do filtrowania, takie jak type, kindi inne.
    • operator: operator do użycia dla filtru. Na przykład eq (równa się), (nie równa się), negt (większe niż), lt (mniejsze niż) i inne.
    • values: tablica wartości, które mają być zgodne z polem.
  • orderBy: tablica pól do porządkowenia wyników według.
  • searchText: ciąg do wyszukania w wynikach.
  • pageSize: maksymalna liczba wyników do zwrócenia (w przypadku stronicowania).
  • skip: liczba wyników do pominięcia (w przypadku stronicowania).
  • continuationToken: token do stronicowania, który będzie kontynuowany z poprzedniego żądania.

Pola z możliwością filtrowania (opcjonalnie)

Zaimplementuj interfejs API wykazu, aby akceptował format żądania . Filtrowanie po stronie serwera jest opcjonalne. Pomijanie filtrowania po stronie serwera jest szybsze do zaimplementowania, ale jest mniej wydajne w przypadku wyszukiwania modeli.

W przypadku implementowania filtrowania po stronie serwera użyj następujących pól:

• type: typ modelu, taki jak models, datasetsi inne.
• kind: rodzaj modelu, taki jak Versioned, Unversionedi inne.
• properties/variantInfo/variantMetadata/device: typ urządzenia, taki jak cpu, gpui inne.
• properties/variantInfo/variantMetadata/executionProvider: dostawca wykonywania, taki jak cpuexecutionprovider, webgpuexecutionprovideri inne.

Odpowiedź

Interfejs API wykazu zwraca obiekt JSON zawierający wyniki wyszukiwania.

Przykładowa odpowiedź

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

Schemat odpowiedzi

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

Reference:

• Rozpocznij
• Co to jest lokalna usługa Foundry?