Lägga till en anpassad färdighet i en Azure AI Search-pipeline för berikande

Artikel
10/20/2023

En PIPELINE för AI-berikande kan innehålla både inbyggda färdigheter och anpassade färdigheter som du skapar och publicerar personligen. Din anpassade kod körs externt till söktjänsten (till exempel som en Azure-funktion), men accepterar indata och skickar utdata till kompetensuppsättningen precis som andra kunskaper.

Anpassade kunskaper kan låta komplexa men kan vara enkla och enkla när det gäller implementering. Om du har befintliga paket som tillhandahåller mönstermatchnings- eller klassificeringsmodeller kan innehållet du extraherar från blobar skickas till dessa modeller för bearbetning. Eftersom AI-berikande är Azure-baserat bör din modell också finnas i Azure. Några vanliga värdmetoder är att använda Azure Functions eller Containrar.

Om du skapar en anpassad färdighet beskriver den här artikeln gränssnittet som du använder för att integrera kunskapen i pipelinen. Det primära kravet är möjligheten att acceptera indata och generera utdata på sätt som kan användas inom kompetensuppsättningen som helhet. Därför ligger fokus i den här artikeln på de indata- och utdataformat som krävs för berikande pipelinen.

Fördelar med anpassade färdigheter

Genom att skapa en anpassad färdighet kan du infoga transformeringar som är unika för ditt innehåll. En anpassad färdighet körs oberoende och tillämpar det berikande steg du behöver. Du kan till exempel skapa anpassade klassificeringsmodeller för att särskilja affärskontrakt och finansiella kontrakt och dokument, eller lägga till en taligenkänningsfärdighet för att nå djupare in i ljudfiler för relevant innehåll. Ett steg-för-steg-exempel finns i Exempel: Skapa en anpassad färdighet för AI-berikning.

Ange slutpunkts- och tidsgränsintervallet

Gränssnittet för en anpassad färdighet anges via den anpassade webb-API-färdigheten.

"@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",

URI:n är HTTPS-slutpunkten för din funktion eller app. När du ställer in URI:n kontrollerar du att URI:n är säker (HTTPS). Om koden finns i en Azure-funktionsapp bör URI:n innehålla en API-nyckel i huvudet eller som en URI-parameter för att auktorisera begäran.

Om din funktion eller app i stället använder Azure-hanterade identiteter och Azure-roller för autentisering och auktorisering kan den anpassade färdigheten inkludera en autentiseringstoken på begäran. Följande punkter beskriver kraven för den här metoden:

Söktjänsten, som skickar begäran för indexerarens räkning, måste konfigureras för att använda en hanterad identitet (antingen system eller användartilldelad) så att anroparen kan autentiseras av Microsoft Entra-ID.
Din funktion eller app måste konfigureras för Microsoft Entra-ID.
Din anpassade kompetensdefinition måste innehålla egenskapen "authResourceId". Den här egenskapen tar ett program-ID (klient)-ID i ett format som stöds: api://<appId>.

Som standard överskrids tidsgränsen för anslutningen till slutpunkten om ett svar inte returneras inom ett 30-sekundersfönster. Indexeringspipelinen är synkron och indexeringen ger ett timeoutfel om ett svar inte tas emot inom den tidsramen. Du kan öka intervallet till ett maximalt värde på 230 sekunder genom att ange timeout-parametern:

Formatera indata för webb-API

Webb-API:et måste acceptera en matris med poster som ska bearbetas. Varje post måste innehålla en egenskapsväska som är indata som tillhandahålls till webb-API:et.

Anta att du vill skapa en grundläggande berikare som identifierar det första datumet som anges i texten i ett kontrakt. I det här exemplet accepterar den anpassade färdigheten en enda indata "contractText" som kontraktstext. Färdigheten har också en enda utdata, vilket är datumet för kontraktet. Om du vill göra berikaren mer intressant returnerar du denna "contractDate" i form av en komplex typ av flera delar.

Webb-API:et bör vara redo att ta emot en batch med indataposter. Varje medlem i matrisen "values" representerar indata för en viss post. Varje post måste ha följande element:

En "recordId"-medlem som är den unika identifieraren för en viss post. När berikaren returnerar resultatet måste den ange detta "recordId" för att anroparen ska kunna matcha postresultatet med sina indata.
En "data"-medlem, som i huvudsak är en påse med indatafält för varje post.

Den resulterande webb-API-begäran kan se ut så här:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2017 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
           }
      }
    ]
}

I praktiken kan koden anropas med hundratals eller tusentals poster i stället för bara de tre som visas här.

Formatera webb-API-utdata

Formatet för utdata är en uppsättning poster som innehåller ett "recordId" och en egenskapspåse. Det här exemplet har bara en utdata, men du kan mata ut fler än en egenskap. Som bästa praxis bör du överväga att returnera fel- och varningsmeddelanden om en post inte kunde bearbetas.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2017 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Lägga till en anpassad färdighet i en kompetensuppsättning

När du skapar en webb-API-berikare kan du beskriva HTTP-huvuden och parametrar som en del av begäran. Följande kodfragment visar hur begärandeparametrar och valfria HTTP-huvuden kan ingå i kompetensuppsättningsdefinitionen. Det är användbart att ange ett HTTP-huvud om du behöver skicka konfigurationsinställningarna till koden.

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

Titta på den här videon

För en videointroduktion och demo, titta på följande demo.

Nästa steg

I den här artikeln beskrivs de gränssnittskrav som krävs för att integrera en anpassad färdighet i en kompetensuppsättning. Fortsätt med de här länkarna om du vill veta mer om anpassade kunskaper och komposition för kompetensuppsättningar.