Přidání vlastní dovednosti do kanálu pro rozšiřování Azure AI Vyhledávač

Note

Azure AI Vyhledávač je k dispozici prostřednictvím portálu Azure, rozhraní REST API a Sady Azure SDK. Podporuje také Foundry IQ, spravovanou znalostní vrstvu, která transformuje podnikový obsah na opakovaně použitelné znalostní báze s podporou oprávnění pro agenty na portálu Microsoft Foundry.

Kanál rozšiřování AI může zahrnovat integrované dovednosti i vlastní dovednosti, které vytvoříte a publikujete. Váš vlastní kód běží mimo vyhledávací službu (například jako Azure funkce), ale přijímá vstupy a odesílá výstupy do sady dovedností stejně jako jakákoli jiná dovednost. Vaše data se zpracovávají v geografii kde je váš model nasazený.

Vlastní dovednosti můžou znít složitě, ale jejich implementace může být jednoduchá. Pokud máte existující balíčky, které poskytují porovnávání vzorů nebo klasifikační modely, můžete předat obsah extrahovaný z objektů blob do těchto modelů ke zpracování. Vzhledem k tomu, že rozšiřování AI je Azure založené, měli byste model hostovat také na Azure. Mezi běžné možnosti hostování patří Azure Functions nebo kontejnery.

Pokud vytváříte vlastní dovednost, tento článek popisuje rozhraní, které použijete k integraci dovednosti do datového toku. Primárním požadavkem je schopnost přijímat vstupy a generovat výstupy způsobem, který může sada dovedností využívat jako celek. Proto je zaměření tohoto článku na vstupní a výstupní formáty, které obohacovací kanál vyžaduje.

Výhody vlastních dovedností

Vytvářením vlastních schopností získáte možnost implementovat transformace jedinečné pro váš obsah. 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

Definujte rozhraní pro vlastní dovednost pomocí dovednosti Custom Web 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 kód hostujete v aplikaci funkcí Azure, zahrňte do hlavičky klíč rozhraní API nebo jako parametr URI pro autorizaci požadavku.

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

Ujistěte se, že uri odkazuje na koncový bod aplikace identifikované uživatelem authResourceId. Neshodované hodnoty můžou způsobit selhání ověřování nebo odesílání požadavků do nezamýšleného koncového bodu. Pokyny k zabezpečení, doporučené postupy a kroky k ověření konfigurace najdete v tématu Důležité informace o zabezpečení pro ověřování spravovaných identit.

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 (PT30S). 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 parametrutimeout () můžete interval zvětšit na maximální hodnotu 230 sekundPT230S.

Pokud koncový bod chráněný omezeními přístupu IP adres nereaguje, dočasně nastavte timeout krátkou hodnotu, například PT10S, aby se zobrazila chyba časového limitu rychleji. U aplikace funkcí Azure spravujte příchozí pravidla PROTOKOLU IP v části Omezení>> nastavení. Informace o povolených IP adresách najdete v tématu Konfigurace pravidel brány firewall protokolu IP pro povolení připojení indexeru.

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

Webové rozhraní API musí přijmout pole záznamů ke zpracování. V rámci každého záznamu zadejte jako vstup do webového rozhraní API tašku vlastností.

Předpokládejme, že chcete vytvořit základní modul, který identifikuje první zmíněné datum v textu kontraktu. V tomto příkladu vlastní dovednost přijímá jeden vstup , contractText. Dovednost má také jeden výstup, což je datum smlouvy. Aby byl obohacovač zajímavější, vraťte contractDate ve formě vícedílného komplexního typu.

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áš enricher vrátí výsledky, musí poskytnout tento údaj recordId, aby volající mohl spárovat výsledky záznamů se vstupy.

  • Člen data, což je sada 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 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
           }
      }
    ]
}

V praxi může být váš kód volán se stovkami nebo tisíci záznamy, nikoliv pouze se třemi zobrazenými.

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

Výstupní formát je sada záznamů obsahujících recordId a kontejner vlastností. Tento konkrétní příklad má pouze jeden výstup, ale můžete vrátit 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" : 2023 }                    
        }
      },
      {
        "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 definovat 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 vašemu 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"
          }
        ]
      }
  ]
}

Note

Když načtete sadu dovedností pomocí get, vrátí služba <redacted> všechny httpHeaders hodnoty, aby se zabránilo vystavení přihlašovacích údajů. Chcete-li aktualizovat dovednost beze změny uložených hodnot záhlaví, nastavte každou hodnotu na <unchanged>. Podrobnosti a příklady najdete v tématu Vlastní dovednosti webového rozhraní API – parametry dovedností.

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í. Další informace o vlastních dovednostech a složení sady dovedností najdete v následujících zdrojích informací:

  • Last updated on