Dodawanie umiejętności niestandardowych do potoku wzbogacania usługi Azure AI Search

  • Artykuł

Potok wzbogacania sztucznej inteligencji może obejmować zarówno wbudowane umiejętności, jak i niestandardowe umiejętności, które tworzysz i publikujesz osobiście. Kod niestandardowy jest wykonywany zewnętrznie z usługi wyszukiwania (na przykład jako funkcja platformy 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ść.

Umiejętności niestandardowe mogą wydawać się skomplikowane, ale mogą być proste i proste w zakresie implementacji. Jeśli masz istniejące pakiety, które zapewniają dopasowywanie wzorców lub modele klasyfikacji, zawartość wyodrębniona z obiektów blob może zostać przekazana do tych modeli na potrzeby przetwarzania. Ponieważ wzbogacanie sztucznej inteligencji jest oparte na platformie Azure, model powinien być również na platformie Azure. Niektóre typowe metodologie hostingu obejmują używanie usługi Azure Functions lub kontenerów.

Jeśli tworzysz umiejętności niestandardowe, w tym artykule opisano interfejs używany do integracji umiejętności z potokiem. Podstawowym wymaganiem jest możliwość akceptowania danych wejściowych i emitowania danych wyjściowych w sposób, który jest używany w ramach zestawu umiejętności jako całości. W związku z tym celem tego artykułu są formaty danych wejściowych i wyjściowych, których wymaga potok wzbogacania.

Zalety umiejętności niestandardowych

Tworzenie niestandardowych umiejętności to sposób na wstawianie przekształceń unikatowych dla konkretnej 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

Interfejs umiejętności niestandardowej jest określany za pomocą umiejętności niestandardowego interfejsu API sieci Web.

"@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 kod jest hostowany w aplikacji funkcji platformy Azure, identyfikator URI powinien zawierać klucz interfejsu API w nagłówku lub jako parametr identyfikatora URI w celu autoryzowania żądania.

Jeśli zamiast tego funkcja lub aplikacja używa tożsamości zarządzanych platformy Azure i ról platformy Azure do uwierzytelniania i autoryzacji, niestandardowa umiejętność może zawierać token uwierzytelniania w żądaniu. 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 (systemu lub przypisanego przez użytkownika), aby można było uwierzytelnić obiekt wywołujący za pomocą identyfikatora Entra firmy Microsoft.

  • Funkcja lub aplikacja musi być skonfigurowana dla identyfikatora entra firmy Microsoft.

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

Domyślnie połączenie z punktem końcowym jest przekroczone limit czasu, jeśli odpowiedź nie jest zwracana w 30-sekundowym oknie (PT30S). Potok indeksowania jest synchroniczny, a indeksowanie spowoduje wygenerowanie błędu 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 parametr limitu czasu (PT230S).

Formatowanie danych wejściowych internetowego interfejsu API

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

Załóżmy, że chcesz utworzyć podstawowy wzbogacacz, który identyfikuje pierwszą datę wymienioną w tekście kontraktu. W tym przykładzie niestandardowa umiejętność akceptuje pojedyncze dane wejściowe "contractText" jako tekst kontraktu. Umiejętność ma również pojedyncze dane wyjściowe, czyli datę kontraktu. Aby uczynić wzbogacacz bardziej interesujący, należy zwrócić ten "contractDate" w kształcie 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:

  • Element członkowski "recordId", który jest unikatowym identyfikatorem określonego rekordu. Gdy wzbogacacz zwraca wyniki, musi podać ten "recordId", aby umożliwić obiektowi wywołującym dopasowanie wyników rekordu do ich danych wejściowych.

  • Element członkowski "dane", który jest zasadniczo workiem 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 issues 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, a nie tylko z trzech pokazanych tutaj.

Formatowanie danych wyjściowych internetowego interfejsu API

Format danych wyjściowych to zestaw rekordów zawierających "recordId" i torbę właściwości. Ten konkretny przykład zawiera tylko jedno dane wyjściowe, ale można wyprowadzić 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 opisać 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 do wideo i pokazem, 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. Kontynuuj pracę z tymi linkami, aby dowiedzieć się więcej na temat niestandardowych umiejętności i kompozycji zestawu umiejętności.