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

Użyj umiejętności niestandardowego internetowego interfejsu API , aby rozszerzyć wzbogacanie sztucznej inteligencji przez wywołanie punktu końcowego internetowego interfejsu API, który zapewnia 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 zwraca ładunek JSON jako odpowiedź wraz z kodem stanu powodzenia. Odpowiedź musi 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 Azure interfejs OpenAI jest skonfigurowany pod kątem dostępu opartego na rolach i podczas tworzenia indeksu wektorowego występują 403 Forbidden błędy, sprawdź, czy Wyszukiwanie AI platformy Azure ma tożsamość przypisaną przez system i działa jako zaufana usługa w Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parametry umiejętności

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

Informacje o authResourceId wartości

Gdy niestandardowa umiejętność internetowego interfejsu API używa uwierzytelniania tożsamości zarządzanej, Wyszukiwanie AI platformy Azure uzyskuje token dostępu Microsoft Entra i wysyła go do niestandardowego punktu końcowego umiejętności. Właściwość authResourceId określa identyfikator zasobu, znany również jako odbiorca lub identyfikator URI identyfikatora aplikacji, dla którego żądano tokenu. Wartość musi być zgodna z oczekiwaniami aplikacji docelowej podczas walidacji tokenu. W przeciwnym razie uwierzytelnianie kończy się niepowodzeniem z odpowiedzią 401 Unauthorized .

Wartość authResourceId identyfikuje aplikację hostująca twoją niestandardową umiejętność. Nie jest to adres URL usługi wyszukiwania ani indeksatora.

W poniższej tabeli przedstawiono typowe formaty:

Właściwość akceptuje formaty z sufiksem zakresu i bez go .default . Użyj api://<appId> polecenia , aby bezpośrednio dopasować identyfikator URI identyfikatora aplikacji. Jeśli dołączysz .default sufiks, taki jak api://<appId>/.default, oświadczenie tokenu aud dostępu zawiera podstawowy identyfikator URI identyfikatora aplikacji bez sufiksu.

Aby uzyskać instrukcje konfigurowania uwierzytelniania Microsoft Entra dla funkcji Azure i zestawu authResourceId, zobacz Używanie tożsamości zarządzanej usługi wyszukiwania do nawiązywania połączenia z aplikacją funkcji Azure.

Przykład: funkcja Azure chroniona przez Microsoft Entra ID

W tym przykładzie Wyszukiwanie AI platformy Azure uzyskuje token dostępu dla odbiorców określonych przez authResourceId program i uwzględnia token podczas wywoływania niestandardowego punktu końcowego umiejętności.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso-function.azurewebsites.net/api/enrich",
  "authResourceId": "api://contoso-customskill"
}

Dane wejściowe dla umiejętności

Ta umiejętność 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

Ta umiejętność 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"
    }
  ]
}

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso.example.org/api?code=<redacted>",
  "httpMethod": "POST",
  "name": "myCustomSkill",
  "httpHeaders": {
    "Authorization": "<redacted>",
    "Ocp-Apim-Subscription-Key": "<redacted>"
  }
}

{
  "uri": "<unchanged>",
  "httpHeaders": {
    "Authorization": "<unchanged>",
    "Ocp-Apim-Subscription-Key": "<unchanged>"
  }
}

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 tych obiektów wynosi najwyżej 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.

  • Właściwość data , która jest obiektem JSON. Pola data właściwości odpowiadają "nazwam" 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 należy wziąć pod uwagę następujące przypadki jako błędy:

• Jeśli internetowy interfejs API zwraca kod stanu powodzenia, ale odpowiedź wskazuje, że nie application/jsonjest , odpowiedź jest nieprawidłowa i nie są wykonywane żadne wzbogacania.

• Jeśli tablica odpowiedzi values zawiera nieprawidłowe rekordy (na przykład brakujące lub zduplikowane recordId), nieprawidłowe rekordy nie są wzbogacone. Podczas opracowywania niestandardowych umiejętności należy przestrzegać kontraktu umiejętności internetowego interfejsu API. 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, historia wykonywania indeksatora zawiera przyjazny błąd z wszelkimi dostępnymi szczegółami dotyczącymi błędu HTTP.

Zagadnienia dotyczące zabezpieczeń uwierzytelniania tożsamości zarządzanej

W przypadku korzystania z uwierzytelniania tożsamości zarządzanej z niestandardową umiejętnością internetowego interfejsu API Wyszukiwanie AI platformy Azure uzyskuje token dostępu Microsoft Entra dla aplikacji zidentyfikowanej przez authResourceId program i zawiera ten token w żądaniach wysyłanych do punktu końcowego określonego przez uri. Punkt końcowy, do których się odwołujeuri, to zazwyczaj funkcja Azure, Azure App Service, punkt końcowy Azure API Management lub inna aplikacja chroniona Microsoft Entra. Odpowiadasz za konfigurowanie i utrzymywanie relacji między punktem końcowym a aplikacją zidentyfikowaną przez authResourceIdusługę .

Niezależnie od metody uwierzytelniania dane wejściowe umiejętności niestandardowych mogą zawierać wartości z dokumentów dostarczonych przez klienta lub wartości pochodzących z tych dokumentów. Traktuj wszystkie niestandardowe dane wejściowe umiejętności jako niezaufane. Wyszukiwanie AI platformy Azure przekazuje dane wejściowe skonfigurowane w zestawie umiejętności do punktu końcowego bez interpretowania, weryfikowania lub ograniczania ich zawartości dla implementacji niestandardowej.

Przed użyciem ich w żądaniach wychodzących lub innych operacjach poufnych na zabezpieczeniach zweryfikuj i ogranicz wartości pochodne dokumentu w ramach umiejętności niestandardowych. Użyj walidacji danych wejściowych, listy dozwolonych miejsc docelowych, walidacji adresu URL i nazwy hosta, ograniczeń protokołu i dostępu do sieci z najmniejszymi uprawnieniami, które zezwalają tylko na miejsca docelowe i porty wymagane przez umiejętności. Aby uzyskać więcej informacji, zobacz Strategie architektury dla sieci i łączności.

Zalecane rozwiązania w zakresie zabezpieczeń

Aby ułatwić utrzymanie bezpiecznego wdrożenia, postępuj zgodnie z następującymi rozwiązaniami:

• uri Skonfiguruj właściwość tak, aby wskazywała tylko zaufane punkty końcowe, które mają odbierać żądania z Wyszukiwanie AI platformy Azure.
• SkonfigurujauthResourceId, aby zidentyfikować aplikację Microsoft Entra, która ma odbierać i weryfikować token dostępu.
• Upewnij się, że aplikacja odbieraca żądania weryfikuje standardowe oświadczenia tokenu, w tym odbiorców (aud), wystawcę (iss), dzierżawę (tid) i wszystkie wymagane role lub uprawnienia aplikacji przed przetworzeniem żądań.
• Zastosuj zasadę najniższych uprawnień podczas udzielania uprawnień do tożsamości zarządzanej Wyszukiwanie AI platformy Azure.
• Okresowo przejrzyj niestandardowe definicje umiejętności internetowego interfejsu API, Microsoft Entra rejestracje aplikacji i przypisania ról aplikacji oraz uprawnienia przyznane Wyszukiwanie AI platformy Azure tożsamości zarządzanych. Przejrzyj zmiany konfiguracji za pomocą ustanowionych procesów zarządzania zmianami i przeglądu zabezpieczeń.
• Okresowo przeglądaj konfiguracje punktów końcowych dla Azure Functions, usług App Services, interfejsów API i bram interfejsów API.
• Monitoruj dzienniki logowania aplikacji, zdarzenia uwierzytelniania i dzienniki dostępu interfejsu API pod kątem nieoczekiwanych lub nieautoryzowanych działań.
• Usuń nieużywane punkty końcowe, uprawnienia, rejestracje aplikacji i przypisania ról, które nie są już wymagane.

Ograniczanie dostępu do konfiguracji zestawu umiejętności

Użytkownicy, którzy mogą tworzyć, modyfikować lub uruchamiać zestawy umiejętności, mogą kontrolować zarówno docelowy punkt końcowy, jak i konfigurację uwierzytelniania używaną przez niestandardową umiejętność internetowego interfejsu API. Ogranicz te uprawnienia do zaufanych administratorów i postępuj zgodnie ze standardowymi procesami zarządzania zmianami i przeglądu zabezpieczeń podczas konfigurowania niestandardowych umiejętności z obsługą tożsamości zarządzanej.

Zobacz także

• Definiowanie zestawu umiejętności
• Dodawanie umiejętności niestandardowych do potoku wzbogacania sztucznej inteligencji
• Przykład: tworzenie niestandardowych umiejętności wzbogacania sztucznej inteligencji
• Repozytorium umiejętności power