Přidání vlastní dovednosti do kanálu rozšiřování služby Azure AI Search

Článek
10/20/2023

Kanál rozšiřování AI může zahrnovat integrované dovednosti i vlastní dovednosti, které vy osobně vytváříte a publikujete. Váš vlastní kód se provádí externě do vyhledávací služby (například jako funkce Azure), ale přijímá vstupy a odesílá výstupy do sady dovedností stejně jako jakákoli jiná dovednost.

Vlastní dovednosti můžou znít složitě, ale můžou být jednoduché a jednoduché z hlediska implementace. Pokud máte existující balíčky, které poskytují porovnávání vzorů nebo klasifikační modely, může být obsah extrahovaný z objektů blob předán těmto modelům ke zpracování. Vzhledem k tomu, že rozšiřování AI je založené na Azure, měl by být váš model také v Azure. Mezi běžné metodologie hostování patří použití Azure Functions nebo kontejnerů.

Pokud vytváříte vlastní dovednosti, tento článek popisuje rozhraní, které používáte k integraci dovednosti do kanálu. Primárním požadavkem je schopnost přijímat vstupy a generovat výstupy způsoby, které jsou využitelné v rámci sady dovedností jako celku. Proto je fokus tohoto článku na vstupní a výstupní formáty, které kanál rozšiřování vyžaduje.

Výhody vlastních dovedností

Vytvářením vlastních dovedností získáte možnost vkládat transformace jedinečné pro váš obsah. Vlastní dovednosti se spouští nezávisle a provádějí libovolné požadované kroky rozšiřování. Můžete například vytvořit vlastní modely klasifikace, které vám umožní rozlišovat mezi obchodními a finančními smlouvami a dokumenty, nebo přidat dovednost rozpoznávání řeči, která vám umožní hlouběji proniknout do zvukových souborů a získat relevantní obsah. Podrobný příklad najdete v tématu Příklad: Vytvoření vlastní dovednosti pro rozšiřování AI.

Nastavení intervalu koncového bodu a časového limitu

Rozhraní pro vlastní dovednost se zadává prostřednictvím dovednosti vlastního webového rozhraní 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",

Identifikátor URI je koncový bod HTTPS vaší funkce nebo aplikace. Při nastavování identifikátoru URI se ujistěte, že je identifikátor URI zabezpečený (HTTPS). Pokud je váš kód hostovaný v aplikaci funkcí Azure, měl by identifikátor URI obsahovat klíč rozhraní API v hlavičce nebo jako parametr identifikátoru URI pro autorizaci požadavku.

Pokud místo toho vaše funkce nebo aplikace používá spravované identity Azure a role Azure k ověřování a autorizaci, může vlastní dovednost v požadavku obsahovat ověřovací token. Následující body popisují požadavky pro tento přístup:

Vyhledávací služba, která odesílá požadavek jménem indexeru, musí být nakonfigurovaná tak, aby používala spravovanou identitu (systém nebo přiřazenou uživatelem), aby volající mohl ověřit ID Microsoft Entra.
Vaše funkce nebo aplikace musí být nakonfigurované pro MICROSOFT Entra ID.
Definice vlastní dovednosti musí obsahovat vlastnost authResourceId. Tato vlastnost přebírá ID aplikace (klienta) v podporovaném formátu: api://<appId>.

Ve výchozím nastavení vyprší časový limit připojení ke koncovému bodu, pokud se odpověď nevrátí v rámci 30sekundového okna. Kanál indexování je synchronní a indexování způsobí chybu časového limitu, pokud se v daném časovém rámci neobdrží odpověď. Nastavením parametru časového limitu můžete interval zvýšit na maximální hodnotu 230 sekund:

Formátování vstupů webového rozhraní API

Webové rozhraní API musí přijmout pole záznamů, které se mají zpracovat. Každý záznam musí obsahovat tašku vlastností, která je vstupem poskytnutým webovému rozhraní API.

Předpokládejme, že chcete vytvořit základní obohacení, které identifikuje první datum uvedené v textu smlouvy. V tomto příkladu vlastní dovednost přijímá jako text kontraktu jeden vstup "contractText". Dovednost má také jeden výstup, což je datum smlouvy. Aby bylo rozšiřování zajímavější, vraťte tento "contractDate" ve tvaru komplexního typu s více částmi.

Webové rozhraní API by mělo být připravené k přijetí dávky vstupních záznamů. Každý člen pole "values" představuje vstup pro konkrétní záznam. Každý záznam musí mít následující prvky:

Člen "recordId", který je jedinečným identifikátorem konkrétního záznamu. Když váš rozšiřující nástroj vrátí výsledky, musí zadat tento "recordId", aby volající mohl odpovídat výsledkům záznamu s jejich vstupem.
Člen "data", což je v podstatě taška vstupních polí pro každý záznam.

Výsledný požadavek webového rozhraní API může vypadat takto:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2017 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
           }
      }
    ]
}

V praxi se váš kód může volat se stovkami nebo tisíci záznamů místo jenom se třemi zobrazenými záznamy.

Formátování výstupů webového rozhraní API

Formát výstupu je sada záznamů obsahujících "recordId" a kontejner vlastností. Tento konkrétní příklad má pouze jeden výstup, ale můžete vyčíst více než jednu vlastnost. Osvědčeným postupem je vrátit chybové a upozorňující zprávy, pokud se nepodařilo zpracovat záznam.

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

Přidání vlastní dovednosti do sady dovedností

Při vytváření rozšíření webového rozhraní API můžete v rámci požadavku popsat hlavičky a parametry HTTP. Následující fragment kódu ukazuje, jak lze do definice sady dovedností zahrnout parametry požadavku a volitelné hlavičky HTTP. Nastavení hlavičky HTTP je užitečné, pokud potřebujete předat nastavení konfigurace kódu.

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

Podívejte se na toto video

Úvodní video a ukázku najdete v následující ukázce.

Další kroky

Tento článek se zabýval požadavky na rozhraní nezbytné pro integraci vlastní dovednosti do sady dovedností. Pokračujte těmito odkazy a získejte další informace o vlastních dovednostech a složení sady dovedností.