Anpassad webb-API-kompetens i en pipeline för Azure AI Search-berikande

Med den anpassade webb-API-färdigheten kan du utöka AI-berikandet genom att anropa en webb-API-slutpunkt som tillhandahåller anpassade åtgärder. På samma sätt som för inbyggda kunskaper har en anpassad webb-API-färdighet indata och utdata. Beroende på indata får webb-API:et en JSON-nyttolast när indexeraren körs och matar ut en JSON-nyttolast som ett svar, tillsammans med en statuskod för lyckad körning. Svaret förväntas ha de utdata som anges av din anpassade färdighet. Andra svar anses vara ett fel och inga berikningar utförs. Strukturen för JSON-nyttolasten beskrivs längre ned i det här dokumentet.

Den anpassade webb-API-färdigheten används också i implementeringen av Azure OpenAI On Your Data-funktionen . Om Azure OpenAI har konfigurerats för rollbaserad åtkomst och du får 403 Forbidden anrop när du skapar vektorindexet kontrollerar du att Azure AI Search har en systemtilldelad identitet och körs som en betrodd tjänst i Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Kompetensparametrar

Parametrar är skiftlägeskänsliga.

Kunskapsindata

Det finns inga fördefinierade indata för den här färdigheten. Indata är ett befintligt fält eller en nod i berikande träd som du vill skicka till din anpassade kompetens.

Kunskapsutdata

Det finns inga fördefinierade utdata för den här färdigheten. Se till att definiera en mappning av utdatafält i indexeraren om kunskapens utdata ska skickas till ett fält i sökindexet.

Exempeldefinition

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

Exempel på JSON-struktur för indata

Den här JSON-strukturen representerar nyttolasten som skickas till webb-API:et. Den följer alltid dessa begränsningar:

• Entiteten på den översta nivån anropas values och är en matris med objekt. Antalet sådana objekt är som mest batchSize.

• Varje objekt i matrisen values har:

  • En recordId egenskap som är en unik sträng som används för att identifiera posten.

  • En data egenskap som är ett JSON-objekt. Fälten i data egenskapen motsvarar de "namn" som anges i inputs avsnittet i kunskapsdefinitionen. Värdena för dessa fält kommer från fälten source (som kan komma från ett fält i dokumentet eller eventuellt från en annan färdighet).

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

Exempel på JSON-struktur för utdata

"Utdata" motsvarar svaret som returneras från webb-API:et. Webb-API:et bör endast returnera en JSON-nyttolast (verifieras genom att titta på Content-Type svarshuvudet) och bör uppfylla följande begränsningar:

• Det bör finnas en entitet på den översta nivån som heter values, som ska vara en matris med objekt.

• Antalet objekt i matrisen ska vara detsamma som antalet objekt som skickas till webb-API:et.

• Varje objekt ska ha:

  • En recordId egenskap.

  • En data egenskap, som är ett objekt där fälten är berikningar som matchar "namnen" i output och vars värde anses vara berikningen.

  • En errors egenskap, en matris som visar eventuella fel som har lagts till i indexerarens körningshistorik. Den här egenskapen krävs, men kan ha ett null värde.

  • En warnings egenskap, en matris som visar eventuella varningar som har lagts till i indexerarens körningshistorik. Den här egenskapen krävs, men kan ha ett null värde.

• Ordningen på objekt i values i antingen begäran eller svaret är inte viktigt. recordId Men används för korrelation så att alla poster i svaret som innehåller en recordId, som inte ingick i den ursprungliga begäran till webb-API:et ignoreras.

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

Felfall

Förutom att webb-API:et inte är tillgängligt eller skickar ut statuskoder som inte lyckas betraktas följande som felaktiga fall:

• Om webb-API:et returnerar en statuskod för lyckade försök, men svaret anger att det inte application/json är det, anses svaret vara ogiltigt och inga berikningar utförs.

• Om det finns ogiltiga poster (till exempel recordId saknas eller dupliceras) i svarsmatrisen values utförs ingen berikning för de ogiltiga posterna. Det är viktigt att följa kunskapskontraktet för webb-API:et när du utvecklar anpassade kunskaper. Du kan se det här exemplet som finns på lagringsplatsen för Power Skill som följer det förväntade kontraktet.

Om webb-API:et inte är tillgängligt eller returnerar ett HTTP-fel läggs ett användarvänligt fel med tillgänglig information om HTTP-felet till i indexerarens körningshistorik.

Se även

• Definiera en kompetensuppsättning
• Lägga till anpassad färdighet i en PIPELINE för AI-berikning
• Exempel: Skapa en anpassad färdighet för AI-berikning
• Lagringsplats för Power Skill