Vlastní dovednosti webového rozhraní API v kanálu rozšiřování služby Azure AI Search

Článek
03/06/2024

Dovednost vlastního webového rozhraní API umožňuje rozšířit rozšiřování umělé inteligence voláním do koncového bodu webového rozhraní API poskytujícího vlastní operace. Podobně jako u předdefinovaných dovedností má dovednost vlastního webového rozhraní API vstupy a výstupy. V závislosti na vstupech obdrží webové rozhraní API datovou část JSON, když se indexer spustí, a 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ší vlastní dovedností. Jakákoli jiná odpověď se považuje za chybu a neprovádí se žádné rozšiřování. Struktura datové části JSON je podrobněji popsána v tomto dokumentu.

Dovednost vlastního webového rozhraní API se používá také při implementaci funkce Azure OpenAI on Your Data. Pokud je Azure OpenAI nakonfigurovaný pro přístup na základě role a při vytváření vektorového indexu získáte 403 Forbidden volání, ověřte, že azure AI Search má identitu přiřazenou systémem a běží jako důvěryhodná služba v Azure OpenAI.

Poznámka:

Indexer opakuje dvakrát u některých standardních stavových kódů HTTP vrácených z webového rozhraní API. Tyto stavové kódy HTTP jsou:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parametry dovedností

Parametry rozlišují malá a velká písmena.

Název parametru	Popis
`uri`	Identifikátor URI webového rozhraní API, do kterého se odesílá datová část JSON. Je povoleno pouze schéma identifikátoru URI https .
`authResourceId`	(Volitelné) Řetězec, který je nastavený, označuje, že tato dovednost by měla používat spravovanou identitu v připojení k funkci nebo aplikaci hostující kód. Tato vlastnost přebírá ID aplikace (klienta) nebo registraci aplikace v Microsoft Entra ID v podporovaném formátu: `api://<appId>`. Tato hodnota se používá k určení rozsahu ověřovacího tokenu, který indexer načítá, a odesílá se spolu s požadavkem rozhraní API vlastních webových dovedností do funkce nebo aplikace. Nastavení této vlastnosti vyžaduje, aby vaše vyhledávací služba byla nakonfigurovaná pro spravovanou identitu a aplikace funkcí Azure je nakonfigurovaná pro přihlášení k Microsoft Entra. Chcete-li použít tento parametr, zavolejte rozhraní API s `api-version=2023-10-01-Preview`.
`httpMethod`	Metoda, která se má použít při odesílání datové části. Povolené metody jsou `PUT` nebo `POST`
`httpHeaders`	Kolekce párů klíč-hodnota, kde klíče představují názvy hlaviček a hodnoty představují hodnoty hlaviček odesílané do webového rozhraní API spolu s datovou částí. V této kolekci nesmí být následující hlavičky: `Accept`, `Accept-Charset`, `Accept-Encoding`, `Content-Length`, `Content-Type`, `Cookie`, , `Host`, `TE`, `Upgrade`. `Via`
`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.
`batchSize`	(Volitelné) Určuje, kolik "datových záznamů" (viz níže uvedená struktura datové části JSON) se odesílá na volání rozhraní API. Pokud není nastavená, vybere se výchozí hodnota 1000. Tento parametr doporučujeme použít k dosažení vhodného kompromisu mezi indexováním propustnosti a zatížením vašeho rozhraní API.
`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 váš koncový bod selhává pod tlakem, nebo ji zvýšit, pokud koncový bod dokáže zpracovat zatížení. Pokud není nastavená, použije se výchozí hodnota 5. Lze `degreeOfParallelism` nastavit na maximálně 10 a minimálně 1.

Vstupy dovedností

Pro tuto dovednost neexistují žádné předdefinované vstupy. Vstupy jsou jakékoli existující pole nebo jakýkoli uzel ve stromu rozšiřování, který chcete předat vlastní dovednosti.

Výstupy dovedností

Pro tuto dovednost neexistují žádné předdefinované výstupy. Pokud se má výstup dovednosti odeslat do pole v indexeru, nezapomeňte v indexu vyhledávání definovat mapování výstupních polí.

Ukázková definice

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

Ukázka vstupní struktury JSON

Tato struktura JSON představuje datovou část, která se odesílá do webového rozhraní API. Vždy se řídí těmito omezeními:

Volá se values entita nejvyšší úrovně a je pole objektů. Počet takovýchobjektůch batchSize
Každý objekt v values poli má:
- VlastnostrecordId, která je jedinečným řetězcem sloužícím k identifikaci daného záznamu.
- Vlastnost data , která je objektEM JSON. Pole data vlastnosti 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).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Ukázková výstupní struktura JSON

Výstup odpovídá odpovědi vrácené z webového rozhraní API. Webové rozhraní API by mělo vrátit pouze datovou část JSON (ověřenou pomocí Content-Type hlavičky odpovědi) a měla by splňovat následující omezení:

Měla by existovat entita nejvyšší úrovně s názvem values, která by měla být pole objektů.
Počet objektů v poli by měl být stejný jako počet objektů odesílaných do webového rozhraní API.
Každý objekt by měl mít:
- Vlastnost recordId .
- Vlastnost data , která je objektem, kde pole jsou obohacení odpovídající "názvům" v output a jehož hodnota je považována za obohacení.
- Vlastnost errors , pole uvádějící všechny chyby, ke kterým došlo při přidání do historie provádění indexeru. Tato vlastnost je povinná, ale může mít null hodnotu.
- Vlastnost warnings , pole zobrazující všechna upozornění, která byla zjištěna při přidání do historie provádění indexeru. Tato vlastnost je povinná, ale může mít null hodnotu.
Pořadí objektů v values požadavku nebo odpovědi není důležité. Používá se recordId však pro korelaci, takže se zahodí jakýkoli záznam v odpovědi obsahující záznam recordId, který nebyl součástí původního požadavku webového rozhraní API.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Chybové případy

Kromě nedostupnosti webového rozhraní API nebo odeslání nespravených stavových kódů se považují za chybné případy:

Pokud webové rozhraní API vrátí stavový kód úspěchu, ale odpověď značí, že není application/json , odpověď se považuje za neplatnou a neprovádí se žádné rozšiřování.
Pokud v poli odpovědí values existují neplatné záznamy (například recordId chybí nebo jsou duplicitní), pro neplatné záznamy se neprovádí žádné rozšiřování. Při vývoji vlastních dovedností je důležité dodržovat kontrakt dovedností webového rozhraní API. Na tento příklad se můžete podívat v úložišti Power Skill, které se řídí očekávaným kontraktem.

V případě nedostupnosti webového rozhraní API nebo vrácení chyby HTTP se do historie spouštění indexeru přidá popisná chyba s podrobnostmi o chybě HTTP.