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

Článek
01/12/2024

Důležité

Tato dovednost je ve verzi Public Preview v rámci doplňkových podmínek použití. Rozhraní REST API ve verzi Preview tuto dovednost podporuje.

Dovednost AML umožňuje rozšířit rozšiřování AI pomocí vlastního modelu azure Machine Učení (AML). Jakmile se model AML vytrénuje a nasadí, dovednost AML ji integruje do rozšiřování AI.

Stejně jako předdefinované dovednosti má dovednost AML vstupy a výstupy. Vstupy se odešlou do nasazeného online koncového bodu AML jako objekt JSON, který vypíše datovou část JSON jako odpověď spolu se stavovým kódem úspěchu. Očekává se, že odpověď bude obsahovat výstupy určené vaší dovedností 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

Požadavky

Pracovní prostor AML
Koncové body Online (v reálném čase) v tomto pracovním prostoru.

@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 .
`key`	(Požadováno pro ověřování klíčů) Klíč pro online koncový bod AML.
`resourceId`	(Požadováno pro ověřování tokenů). ID prostředku Azure Resource Manageru online koncového bodu AML. Měla by být ve formátu předplatných/{guid}/resourceGroups/{resource-group-name}/Microsoft.Machine Učení Services/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.

Jaké parametry dovedností se mají použít

Které parametry dovednosti AML jsou povinné, závisí na tom, jaké ověřování používá váš online koncový bod AML, pokud existuje. 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íč.
- Použití parametrů identifikátoru URI a klíče
Ověřování založené na tokenech Online koncový bod AML se nasadí pomocí ověřování na základě tokenu. Spravovaná identita azure AI Search musí být povolená. Dovednost AML pak použije spravovanou identitu služby k ověření vůči online koncovému bodu AML bez nutnosti statických klíčů. Identitě musí být přiřazena role vlastníka nebo přispěvatele.
- Použijte parametr resourceId.
- Pokud je vyhledávací služba v jiné oblasti než pracovní prostor AML, použijte parametr oblasti k nastavení oblasti, ve které byl nasazen online koncový bod AML.

Vstupy dovedností

Pro tuto dovednost neexistují žádné předdefinované vstupy. Můžete zvolit jedno nebo více polí, která by už byla v době provádění této dovednosti k dispozici jako vstupy a datová část JSON odeslaná do online koncového bodu AML bude obsahovat různá pole.

Výstupy dovedností

Pro tuto dovednost neexistují žádné předdefinované výstupy. V závislosti na odpovědi, kterou váš online koncový bod AML vrátí, přidejte výstupní pole, aby je bylo možné vyzvednout z odpovědi JSON .

Ukázková definice

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.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://contoso.count-things.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:

Pokud online koncový bod AML vrátí stavový kód úspěchu, ale odpověď značí, že není application/json, považuje se odpověď za neplatnou a neprovedou se žádné rozšiřování.
Pokud 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 spuštění indexeru přidá popisná chyba s podrobnostmi o chybě HTTP.