Dodawanie niestandardowej umiejętności do potoku wzbogacania w Wyszukiwanie AI platformy Azure

Potok wzbogacania sztucznej inteligencji może obejmować zarówno wbudowane umiejętności, jak i umiejętności niestandardowe, które tworzysz i publikujesz. Kod niestandardowy działa poza usługą wyszukiwania (na przykład jako funkcja Azure), ale akceptuje dane wejściowe i wysyła dane wyjściowe do zestawu umiejętności tak samo jak każda inna umiejętność. Dane są przetwarzane w regionie, w którym wdrożono model.

Umiejętności niestandardowe mogą wydawać się skomplikowane, ale mogą być proste do zaimplementowania. Jeśli masz istniejące pakiety, które zapewniają dopasowywanie wzorców lub modele klasyfikacji, możesz przekazać zawartość wyodrębnianą z obiektów blob do tych modeli na potrzeby przetwarzania. Ponieważ wzbogacanie sztucznej inteligencji jest oparte na Azure, należy również hostować model na Azure. Typowe opcje hostingu obejmują Azure Functions lub containers.

Jeśli tworzysz niestandardowy skill, w tym artykule opisano interfejs, którego używasz do integracji skillu z potokiem. Podstawowym wymaganiem jest możliwość akceptowania danych wejściowych i emitowania danych wyjściowych w sposób, który zestaw umiejętności może wykorzystywać jako całość. W związku z tym głównym tematem tego artykułu są formaty wejściowe i wyjściowe, których wymaga potok wzbogacania.

Zalety umiejętności niestandardowych

Tworzenie dostosowanej umiejętności daje możliwość wstawiania transformacji unikalnych dla Twojej zawartości. Można na przykład tworzyć niestandardowe modele klasyfikacji w celu rozróżnienia umów i dokumentów biznesowych oraz finansowych lub dodać umiejętność rozpoznawania mowy w celu dokładniejszego analizowania plików audio pod kątem istotnej zawartości. Aby zapoznać się z przykładem krok po kroku, zobacz Przykład: tworzenie niestandardowych umiejętności wzbogacania sztucznej inteligencji.

Ustawianie punktu końcowego i interwału limitu czasu

Określ interfejs dla umiejętności niestandardowych za pomocą umiejętności niestandardowego internetowego interfejsu API.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230-second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

Identyfikator URI to punkt końcowy HTTPS funkcji lub aplikacji. Podczas ustawiania identyfikatora URI upewnij się, że identyfikator URI jest bezpieczny (HTTPS). Jeśli hostujesz swój kod w aplikacji funkcji platformy Azure, dołącz klucz interfejsu API w nagłówku lub jako parametr URI w identyfikatorze URI, aby autoryzować żądanie.

Jeśli Twoja funkcja lub aplikacja używa tożsamości zarządzanych platformy Azure i ról platformy Azure do uwierzytelniania i autoryzacji, umiejętność niestandardowa może dołączać token uwierzytelniania do żądania. W poniższych punktach opisano wymagania dotyczące tego podejścia:

• Usługa wyszukiwania, która wysyła żądanie w imieniu indeksatora, musi być skonfigurowana do używania tożsamości zarządzanej (przypisanej przez użytkownika lub systemu), aby Microsoft Entra ID mógł uwierzytelnić obiekt wywołujący.

• Musisz skonfigurować funkcję lub aplikację dla Microsoft Entra ID.

• Definicja niestandardowej umiejętności musi obejmować właściwość authResourceId. Ta właściwość przyjmuje identyfikator aplikacji (klienta) w formacie obsługiwanym: api://<appId>.

Upewnij się, że uri wskazuje punkt końcowy aplikacji zidentyfikowanej przez authResourceIdelement . Niezgodne wartości mogą powodować błędy uwierzytelniania lub żądania wysyłane do niezamierzonego punktu końcowego. Aby uzyskać wskazówki dotyczące zabezpieczeń, zalecane rozwiązania i kroki weryfikacji konfiguracji, zobacz Zagadnienia dotyczące zabezpieczeń dotyczące uwierzytelniania tożsamości zarządzanej.

Domyślnie połączenie z punktem końcowym przekracza limit czasu, jeśli odpowiedź nie zostanie zwrócona w ciągu 30 sekund (PT30S). Potok indeksowania jest synchroniczny, a indeksowanie generuje błąd przekroczenia limitu czasu, jeśli odpowiedź nie zostanie odebrana w tym przedziale czasu. Interwał można zwiększyć do maksymalnej wartości 230 sekund, ustawiając timeout parametr (PT230S).

Jeśli punkt końcowy chroniony przez ograniczenia dostępu do adresu IP nie odpowiada, tymczasowo ustaw timeout wartość krótką, taką jak PT10S, aby szybciej wyświetlić błąd przekroczenia limitu czasu. W przypadku aplikacji funkcji Azure zarządzaj regułami adresów IP dla ruchu przychodzącego w obszarze Ustawienia>Ograniczenia dostępu do>. Aby uzyskać dozwolone adresy IP, zobacz Konfigurowanie reguł zapory ip w celu zezwalania na połączenia indeksatora.

Formatowanie danych wejściowych internetowego interfejsu API

Internetowy interfejs API musi zaakceptować tablicę rekordów do przetworzenia. W każdym rekordzie podaj zbiór właściwości jako dane wejściowe do interfejsu API.

Załóżmy, że chcesz utworzyć podstawowy moduł wzbogacający, który identyfikuje pierwszą datę wymienioną w tekście kontraktu. W tym przykładzie niestandardowa umiejętność akceptuje pojedyncze dane wejściowe: contractText. Umiejętność ma również pojedyncze dane wyjściowe, czyli datę kontraktu. Aby moduł wzbogacający był bardziej interesujący, zwróć contractDate w postaci wieloczęściowego typu złożonego.

Internetowy interfejs API powinien być gotowy do odbierania partii rekordów wejściowych. Każdy element członkowski tablicy values reprezentuje dane wejściowe dla określonego rekordu. Każdy rekord jest wymagany do posiadania następujących elementów:

• Składowa recordId, która jest unikatowym identyfikatorem danego rekordu. Gdy moduł wzbogacający zwraca wyniki, musi zwrócić element recordId, aby element wywołujący mógł powiązać wyniki rekordów z danymi wejściowymi.

• Składowa data, która jest zbiorem pól wejściowych dla każdego rekordu.

Wynikowe żądanie internetowego interfejsu API może wyglądać następująco:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

W praktyce kod może być wywoływany z setkami lub tysiącami rekordów, zamiast tylko tych trzech pokazanych tutaj.

Formatowanie danych wyjściowych internetowego interfejsu API

Format wyjściowy to zestaw rekordów zawierających element recordId oraz zbiór właściwości. Ten konkretny przykład zawiera tylko jedno dane wyjściowe, ale można zwrócić więcej niż jedną właściwość. Najlepszym rozwiązaniem jest zwrócenie komunikatów o błędach i ostrzeżeniach, jeśli nie można przetworzyć rekordu.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Dodawanie niestandardowej umiejętności do zestawu umiejętności

Podczas tworzenia wzbogacacza internetowego interfejsu API można zdefiniować nagłówki i parametry HTTP w ramach żądania. Poniższy fragment kodu pokazuje, jak parametry żądania i opcjonalne nagłówki HTTP można uwzględnić w definicji zestawu umiejętności. Ustawienie nagłówka HTTP jest przydatne, jeśli musisz przekazać ustawienia konfiguracji do kodu.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Obejrzyj ten film wideo

Aby zapoznać się z wprowadzeniem wideo i demonstracją, obejrzyj poniższy pokaz.

Następne kroki

W tym artykule opisano wymagania interfejsu niezbędne do zintegrowania niestandardowej umiejętności z zestawem umiejętności. Aby dowiedzieć się więcej na temat niestandardowych umiejętności i kompozycji zestawu umiejętności, zobacz następujące zasoby:

• Power Skills: repozytorium umiejętności niestandardowych
• Przykład: tworzenie niestandardowych umiejętności wzbogacania sztucznej inteligencji
• Jak zdefiniować zestaw umiejętności
• Tworzenie zestawu umiejętności (REST)
• Jak mapować wzbogacone pola