Lägga till en anpassad färdighet i en berikningspipeline med Azure AI-sökning

Note

Azure AI-sökning är tillgängligt via Azure-portalen, REST-API:er och Azure-SDK:er. Den ligger också till grund för Foundry IQ, det hanterade kunskapsskiktet som omvandlar företagsinnehåll till återanvändbara, behörighetsmedvetna kunskapsbaser för agenter i Microsoft Foundry-portalen.

En AI-berikningspipeline kan innehålla både inbyggda färdigheter och anpassade färdigheter som du skapar och publicerar. Din anpassade kod körs utanför söktjänsten (till exempel som en Azure funktion), men den accepterar indata och skickar utdata till kompetensuppsättningen precis som andra kunskaper. Dina data bearbetas i geography där din modell distribueras.

Anpassade kunskaper kan låta komplexa, men de kan vara enkla att implementera. Om du har befintliga paket som tillhandahåller mönstermatchnings- eller klassificeringsmodeller kan du skicka innehåll som extraherats från blobar till dessa modeller för bearbetning. Eftersom AI-berikande är Azure baserat bör du även vara värd för din modell på Azure. Vanliga värdalternativ är Azure Functions eller containers.

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å ett sätt som kunskapsuppsättningen kan använda som helhet. Därför ligger fokus i den här artikeln på de in- och utdataformaten som krävs för berikningspipeline.

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. 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

Ange gränssnittet för en anpassad färdighet 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 du är värd för koden i en Azure funktionsapp ska du inkludera en API-nyckel i huvudet eller som en URI-parameter i URI:n för att auktorisera begäran.

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

Se till att uri pekar på slutpunkten för programmet som identifieras av authResourceId. Felaktiga värden kan orsaka autentiseringsfel eller begäranden som skickas till en oavsiktlig slutpunkt. Säkerhetsvägledning, rekommenderade metoder och steg för att verifiera konfigurationen finns i Säkerhetsöverväganden för hanterad identitetsautentisering.

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

Om en slutpunkt som skyddas av IP-åtkomstbegränsningar inte svarar anger du timeout tillfälligt ett kort värde, till exempel PT10S, för att visa timeout-felet snabbare. För en Azure funktionsapp hanterar du inkommande IP-regler under Inställningar>Nätverksåtkomstbegränsningar>. Information om vilka IP-adresser som ska tillåtas finns i Konfigurera IP-brandväggsregler för att tillåta indexeringsanslutningar.

Formatera indata för webb-API

Webb-API:t måste acceptera ett fält med poster som ska bearbetas. För varje post tillhandahåller du en parameteruppsättning som indata till ditt webb-API.

Anta att du vill skapa en grundläggande berikare som identifierar det första datumet som anges i kontraktstexten. I det här exemplet accepterar den anpassade färdigheten en enda indata, contractText. Kompetensen har också en enda utmatning, nämligen kontraktsdatumet. För att göra berikaren mer intressant, returnera 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 din berikare returnerar resultat måste den innehålla detta recordId så att anroparen kan matcha resultatposter mot indataposter.

  • Ett data element, det vill säga en samling inmatningsfä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 issued on November 3, 2023 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

Utdataformatet är en uppsättning poster som innehåller en recordId och en egenskapsväska. Det här exemplet har bara en utgång, men så kan du returnera 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" : 2023 }                    
        }
      },
      {
        "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 definiera 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"
          }
        ]
      }
  ]
}

Note

När du hämtar kunskapsuppsättningen med GET, returnerar tjänsten <redacted> för alla httpHeaders-värden för att förhindra att autentiseringsuppgifter exponeras. Om du vill uppdatera kunskapen utan att ändra lagrade rubrikvärden anger du varje värde till <unchanged>. Mer information och exempel finns i Custom Web API skill – Skill parameters (Anpassad webb-API-skicklighet – Kunskapsparametrar).

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. Mer information om anpassade kunskaper och sammansättning av färdigheter finns i följande resurser:

  • Uppdaterades senast