Niestandardowa umiejętność internetowego interfejsu API w potoku wzbogacania usługi Azure AI Search

Artykuł
03/06/2024

Umiejętność niestandardowego internetowego interfejsu API umożliwia rozszerzenie wzbogacania sztucznej inteligencji przez wywołanie punktu końcowego internetowego interfejsu API zapewniającego operacje niestandardowe. Podobnie jak w przypadku wbudowanych umiejętności, umiejętność niestandardowego internetowego interfejsu API zawiera dane wejściowe i wyjściowe. W zależności od danych wejściowych internetowy interfejs API odbiera ładunek JSON po uruchomieniu indeksatora i generuje ładunek JSON jako odpowiedź wraz z kodem stanu powodzenia. Oczekuje się, że odpowiedź będzie zawierać dane wyjściowe określone przez niestandardową umiejętność. Każda inna odpowiedź jest uważana za błąd i nie są wykonywane żadne wzbogacenia. Struktura ładunku JSON została opisana w dalszej części tego dokumentu.

Niestandardowa umiejętność internetowego interfejsu API jest również używana w implementacji funkcji Azure OpenAI On Your Data . Jeśli usługa Azure OpenAI jest skonfigurowana pod kątem dostępu opartego na rolach i otrzymujesz 403 Forbidden wywołania podczas tworzenia indeksu wektorowego, sprawdź, czy usługa Azure AI Search ma tożsamość przypisaną przez system i działa jako zaufana usługa w usłudze Azure OpenAI.

Uwaga

Indeksator ponawia próbę dwukrotnie dla niektórych standardowych kodów stanu HTTP zwróconych z internetowego interfejsu API. Te kody stanu HTTP to:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parametry umiejętności

W parametrach jest rozróżniana wielkość liter.

Nazwa parametru	opis
`uri`	Identyfikator URI internetowego interfejsu API, do którego jest wysyłany ładunek JSON. Dozwolony jest tylko schemat identyfikatora URI https.
`authResourceId`	(Opcjonalnie) Ciąg, który w przypadku ustawienia wskazuje, że ta umiejętność powinna używać tożsamości zarządzanej w połączeniu z funkcją lub aplikacją hostująca kod. Ta właściwość przyjmuje identyfikator aplikacji (klienta) lub rejestrację aplikacji w identyfikatorze Entra firmy Microsoft w obsługiwanym formacie: `api://<appId>`. Ta wartość służy do określania zakresu tokenu uwierzytelniania pobranego przez indeksator i jest wysyłana wraz z niestandardowym żądaniem internetowego interfejsu API umiejętności do funkcji lub aplikacji. Ustawienie tej właściwości wymaga skonfigurowania usługi wyszukiwania pod kątem tożsamości zarządzanej, a aplikacja funkcji platformy Azure jest skonfigurowana na potrzeby logowania w usłudze Microsoft Entra. Aby użyć tego parametru, wywołaj interfejs API za pomocą `api-version=2023-10-01-Preview`polecenia .
`httpMethod`	Metoda do użycia podczas wysyłania ładunku. Dozwolone metody są `PUT` lub `POST`
`httpHeaders`	Kolekcja par klucz-wartość, w których klucze reprezentują nazwy nagłówków i wartości reprezentują wartości nagłówków wysyłane do internetowego interfejsu API wraz z ładunkiem. Następujące nagłówki nie mogą być w tej kolekcji: `Accept`, `Accept-CharsetUpgradeAccept-EncodingContent-LengthTEContent-TypeCookieHost`. `Via`
`timeout`	(Opcjonalnie) Po określeniu wskazuje limit czasu dla klienta http wykonującego wywołanie interfejsu API. Musi być sformatowana jako wartość XSD "dayTimeDuration" (ograniczony podzestaw wartości czasu trwania ISO 8601). Na przykład `PT60S` przez 60 sekund. Jeśli nie zostanie ustawiona, zostanie wybrana wartość domyślna 30 sekund. Limit czasu można ustawić na maksymalnie 230 sekund i co najmniej 1 sekundę.
`batchSize`	(Opcjonalnie) Wskazuje, ile "rekordów danych" (zobacz strukturę ładunku JSON poniżej) jest wysyłanych na wywołanie interfejsu API. Jeśli nie zostanie ustawiona, zostanie wybrana wartość domyślna 1000. Zalecamy użycie tego parametru w celu osiągnięcia odpowiedniego kompromisu między indeksowaniem przepływności i obciążeniem interfejsu API.
`degreeOfParallelism`	(Opcjonalnie) Po określeniu wskazuje liczbę wywołań, które indeksator wykonuje równolegle do podanego punktu końcowego. Tę wartość można zmniejszyć, jeśli punkt końcowy ulega awarii pod presją, lub podnieść go, jeśli punkt końcowy może obsłużyć obciążenie. Jeśli nie zostanie ustawiona, zostanie użyta wartość domyślna 5. `degreeOfParallelism` Można ustawić wartość maksymalnie 10 i co najmniej 1.

Dane wejściowe umiejętności

Dla tej umiejętności nie ma wstępnie zdefiniowanych danych wejściowych. Dane wejściowe to dowolne istniejące pole lub dowolny węzeł w drzewie wzbogacania, które chcesz przekazać do swojej umiejętności niestandardowej.

Dane wyjściowe umiejętności

Dla tej umiejętności nie ma wstępnie zdefiniowanych danych wyjściowych. Pamiętaj, aby zdefiniować mapowanie pól wyjściowych w indeksatorze, jeśli dane wyjściowe umiejętności powinny być wysyłane do pola w indeksie wyszukiwania.

Przykładowa definicja

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

Przykładowa struktura danych wejściowych JSON

Ta struktura JSON reprezentuje ładunek wysyłany do internetowego interfejsu API. Zawsze jest to zgodne z następującymi ograniczeniami:

Jednostka najwyższego poziomu jest wywoływana values i jest tablicą obiektów. Liczba takich obiektów jest w większości .batchSize
Każdy obiekt w tablicy values ma:
- recordId Właściwość, która jest unikatowym ciągiem służącym do identyfikowania tego rekordu.
- data Właściwość, która jest obiektem JSON. Pola data właściwości odpowiadają wartościom "names" określonym w inputs sekcji definicji umiejętności. Wartości tych pól pochodzą z tych pól (które mogą pochodzić z source pola w dokumencie lub potencjalnie z innej umiejętności).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Przykładowa struktura danych wyjściowych JSON

Wyrażenie "output" odpowiada odpowiedzi zwróconej z internetowego interfejsu API. Internetowy interfejs API powinien zwracać tylko ładunek JSON (zweryfikowany przez sprawdzenie nagłówka Content-Type odpowiedzi) i powinien spełniać następujące ograniczenia:

Powinna istnieć jednostka najwyższego poziomu o nazwie values, która powinna być tablicą obiektów.
Liczba obiektów w tablicy powinna być taka sama jak liczba obiektów wysyłanych do internetowego interfejsu API.
Każdy obiekt powinien mieć:
- Właściwość recordId .
- Właściwość data , która jest obiektem, w którym pola są wzbogacane pasujące do "nazw" w output obiekcie i którego wartość jest traktowana jako wzbogacanie.
- Właściwość, tablica zawierająca errors listę błędów, które zostały dodane do historii wykonywania indeksatora. Ta właściwość jest wymagana null , ale może mieć wartość.
- Właściwość, tablica warnings zawierająca listę wszystkich napotkanych ostrzeżeń, które są dodawane do historii wykonywania indeksatora. Ta właściwość jest wymagana null , ale może mieć wartość.
Kolejność obiektów w values obiekcie w żądaniu lub odpowiedzi nie jest ważna. Parametr jest jednak używany do korelacji, recordId więc każdy rekord w odpowiedzi zawierającej recordIdelement , który nie był częścią oryginalnego żądania do internetowego interfejsu API, zostanie odrzucony.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Przypadki błędów

Oprócz niedostępności internetowego interfejsu API lub wysyłania nieudanych kodów stanu są uznawane za błędne przypadki:

Jeśli internetowy interfejs API zwróci kod stanu powodzenia, ale odpowiedź wskazuje, że nie application/json jest to odpowiedź uważana za nieprawidłową i nie są wykonywane żadne wzbogacania.
Jeśli w tablicy odpowiedzi values brakuje nieprawidłowych rekordów (na przykład recordId brakuje ich lub zduplikowane), dla nieprawidłowych rekordów nie jest wykonywana wzbogacanie. Ważne jest, aby stosować się do umowy umiejętności internetowego interfejsu API podczas opracowywania niestandardowych umiejętności. Możesz odwołać się do tego przykładu podanego w repozytorium Umiejętności power, które jest zgodne z oczekiwanym kontraktem.

W przypadku, gdy internetowy interfejs API jest niedostępny lub zwraca błąd HTTP, przyjazny błąd z wszelkimi dostępnymi szczegółami dotyczącymi błędu HTTP jest dodawany do historii wykonywania indeksatora.