Dovednost AML v kanálu rozšiřování azure AI Search

Článek
12/18/2024

Důležité

Podpora připojení indexeru ke katalogu modelů Azure AI Foundry je ve verzi Public Preview v rámci doplňkových podmínek použití. Tato dovednost podporuje rozhraní REST API ve verzi Preview.

Dovednost AML umožňuje rozšířit rozšiřování AI o vlastní model služby Azure Machine Learning (AML) nebo nasazený základní vložený model v Azure AI Foundry. Jakmile se model AML vytrénuje a nasadí, dovednost AML ji integruje do sady dovedností.

Využití dovedností AML

Stejně jako jiné předdefinované dovednosti má vlastní dovednost AML vstupy a výstupy. Vstupy se odesílají do nasazeného online koncového bodu AML jako objekt JSON. Výstupem koncového bodu musí být datová část JSON v odpovědi spolu se stavovým kódem úspěchu. Vaše data se zpracovávají v geografické oblasti, ve které je váš model nasazený. Očekává se, že odpověď poskytne výstupy zadané definicí dovednosti AML . Jakákoli jiná odpověď se považuje za chybu a neprovádí se žádné rozšiřování.

Poznámka:

Indexer se bude opakovat dvakrát pro určité standardní stavové kódy HTTP vrácené z online koncového bodu AML. Tyto stavové kódy HTTP jsou:

503 Service Unavailable
429 Too Many Requests

Dovednosti AML je možné volat pomocí stabilní verze rozhraní API 2024-07-01 nebo ekvivalentní sady Azure SDK 2024-05-01-preview pro připojení ke katalogu modelů na portálu Azure AI Foundry.

Dovednost AML pro modely v Azure AI Foundry

Od verze 2024-05-01-preview rozhraní REST API a na webu Azure Portal (který také cílí na 2024-05-01-preview), azure AI Search poskytuje vektorizátor katalogu modelů Azure AI Foundry pro připojení času dotazů k katalogu modelů na portálu Azure AI Foundry. Pokud chcete tento vektorizátor použít pro dotazy, dovednost AML je protějšek indexování pro generování vkládání pomocí modelu v katalogu modelů Azure AI Foundry.

Během indexování se dovednost AML může připojit k katalogu modelů a generovat vektory pro index. V době dotazu můžou dotazy použít vektorizátor pro připojení ke stejnému modelu k vektorizaci textových řetězců pro vektorový dotaz. V tomto pracovním postupu by se měla společně používat dovednost AML a vektorizátor katalogu modelů, takže pro indexování i dotazy používáte stejný model vkládání. Podrobnosti a seznam podporovaných modelů vkládání najdete v tématu Použití modelů vkládání z katalogu modelů Azure AI Foundry.

Doporučujeme použít Průvodce importem a vektorizací dat k vygenerování sady dovedností, která zahrnuje dovednost AML pro nasazené vložené modely v Azure AI Foundry. Definice dovedností AML pro vstupy, výstupy a mapování jsou generovány průvodcem, což vám umožňuje snadný způsob, jak otestovat model před napsáním jakéhokoli kódu.

Požadavky

Pracovní prostor AML pro vlastní model, který vytvoříte, nebo projekt v Azure AI Foundry, pokud je vložený model nasazený z katalogu.
Koncové body Online (v reálném čase) v tomto pracovním prostoru pro vlastní model nebo koncový bod modelu pro vkládání modelů nasazených z katalogu.

@odata.type

Microsoft.Skills.Custom.AmlSkill

Parametry dovedností

Parametry rozlišují malá a velká písmena. Jaké parametry se rozhodnete použít, závisí na tom, jaké ověřování vyžaduje online koncový bod AML, pokud nějaké

Název parametru	Popis
`uri`	(Požadováno pro ověření klíče) Identifikátor URI bodování online koncového bodu AML, do kterého se odešle datová část JSON . Je povoleno pouze schéma identifikátoru URI https . Pro vkládání modelů do katalogu modelů Azure AI Foundry se jedná o cílový identifikátor URI.
`key`	(Požadováno pro ověřování klíčů) Klíč pro online koncový bod AML nebo
`resourceId`	(Požadováno pro ověřování tokenů). ID prostředku Azure Resource Manageru online koncového bodu AML. Měla by mít formát `subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}`.
`region`	(Volitelné pro ověřování tokenů). Oblast, ve které je online koncový bod AML nasazený.
`timeout`	(Volitelné) Po zadání označuje časový limit pro klienta HTTP, který volá rozhraní API. Musí být formátovaná jako hodnota XSD dayTimeDuration (omezená podmnožina hodnoty doby trvání ISO 8601). Například `PT60S` 60 sekund. Pokud není nastavená, vybere se výchozí hodnota 30 sekund. Časový limit je možné nastavit na maximálně 230 sekund a minimálně 1 sekundu.
`degreeOfParallelism`	(Volitelné) Po zadání určuje počet volání, která indexer provede paralelně s zadaným koncovým bodem. Tuto hodnotu můžete snížit, pokud koncový bod selhává pod příliš vysokou zátěží požadavku. Můžete ho zvýšit, pokud váš koncový bod dokáže přijmout více požadavků a chcete zvýšit výkon indexeru. Pokud není nastavená, použije se výchozí hodnota 5. StupeňOfParallelism lze nastavit na maximálně 10 a minimálně 1.

Ověřování

Online koncové body AML poskytují dvě možnosti ověřování:

Ověřování založené na klíčích Pro ověření žádostí o bodování z dovedností AML se poskytuje statický klíč. uri Nastavte parametry a key parametry pro toto připojení.
Ověřování na základě tokenů, kde je online koncový bod AML nasazen pomocí ověřování na základě tokenu. Spravovaná identita azure AI Search musí být povolená a musí mít v pracovním prostoru přiřazenou roli. Dovednost AML pak použije spravovanou identitu služby k ověření vůči online koncovému bodu AML bez nutnosti statických klíčů. Identita vyhledávací služby musí být vlastníkem nebo přispěvatelem. resourceId Nastavte parametr a pokud je vyhledávací služba v jiné oblasti než pracovní prostor AML, nastavte region parametr.

Vstupy dovedností

Vstupy dovedností jsou uzlem rozšířeného dokumentu , který se vytvoří během prolomení dokumentu. Může to být například kořenový dokument, normalizovaný obrázek nebo obsah objektu blob. Pro tuto dovednost neexistují žádné předdefinované vstupy. Pro vstupy byste měli zadat jeden nebo více uzlů, které jsou naplněny v době provádění dovednosti AML.

Výstupy dovedností

Výstupy dovedností jsou nové uzly rozšířeného dokumentu vytvořeného dovedností. Pro tuto dovednost neexistují žádné předdefinované výstupy. Pro výstupy byste měli poskytnout uzly, které se dají naplnit z odpovědi JSON dovednosti AML.

Ukázková definice

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A custom model that detects the language in a document.",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Ukázka vstupní struktury JSON

Tato struktura JSON představuje datovou část, která se odešle do online koncového bodu AML. Pole nejvyšší úrovně struktury odpovídají "názvům" zadaným v inputs části definice dovednosti. Hodnoty těchto polí pocházejí z source těchto polí (které můžou být z pole v dokumentu nebo potenciálně z jiné dovednosti).

{
  "text": "Este es un contrato en Inglés"
}

Ukázková výstupní struktura JSON

Výstup odpovídá odpovědi vrácené z vašeho online koncového bodu AML. Online koncový bod AML by měl vrátit jenom datovou část JSON (ověřenou na Content-Type základě hlavičky odpovědi) a měl by to být objekt, ve kterém pole rozšiřuje hodnoty odpovídající "názvům" a output jejichž hodnota je považována za obohacení.

{
    "detected_language_code": "es"
}

Vložená definice ukázky tvarování

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Vložené tvarování vstupní struktury JSON

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

Vložené tvarování ukázkové výstupní struktury JSON

{
    "detected_language_code": "es"
}

Chybové případy

Kromě nedostupnosti nebo odesílání nedostupných stavových kódů AML se považují za chybné případy:

Online koncový bod AML vrátí stavový kód úspěchu, ale odpověď značí, že není application/json, pak se odpověď považuje za neplatnou a neprovádí se žádné rozšiřování.
Online koncový bod AML vrátí neplatný kód JSON.

V případě nedostupnosti online koncového bodu AML nebo vrácení chyby HTTP se do historie provádění indexeru přidá popisná chyba s podrobnostmi o chybě HTTP.

Sdílet prostřednictvím