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

Använd den anpassade webb-API-färdigheten för att utöka AI-berikandet genom att anropa en webb-API-slutpunkt som tillhandahåller anpassade åtgärder. Precis som 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 returnerar en JSON-nyttolast som ett svar, tillsammans med en statuskod för lyckad körning. Svaret måste innehålla 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 senare i det här dokumentet.

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

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Kompetensparametrar

Parametrar är skiftlägeskänsliga.

Förstå värdet authResourceId

När en anpassad webb-API-färdighet använder hanterad identitetsautentisering hämtar Azure AI-sökning en Microsoft Entra åtkomsttoken och skickar den till den anpassade kunskapsslutpunkten. Egenskapen authResourceId anger resursidentifieraren, även kallad målgrupp eller program-ID-URI, för vilken token begärs. Värdet måste matcha vad målprogrammet förväntar sig under tokenverifieringen. Annars misslyckas autentiseringen med ett 401 Unauthorized svar.

Värdet authResourceId identifierar programmet som är värd för din anpassade kompetens. Det är inte URL:en för din söktjänst eller indexerare.

I följande tabell visas vanliga format:

Egenskapen accepterar format med och utan omfångssuffixet .default . Använd api://<appId> för att matcha program-ID-URI:n direkt. Om du inkluderar ett .default suffix, till exempel api://<appId>/.default, innehåller åtkomsttokens aud anspråk den grundläggande program-ID-URI:n utan suffixet.

Anvisningar för hur du konfigurerar Microsoft Entra autentisering för en Azure funktion och anger authResourceIdfinns i Använda en hanterad identitet för söktjänsten för att ansluta till en Azure Funktionsapp.

Exempel: Azure funktion som skyddas av Microsoft Entra ID

I det här exemplet hämtar Azure AI-sökning en åtkomsttoken för målgruppen som anges av authResourceId och inkluderar token när du anropar den anpassade kunskapsslutpunkten.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso-function.azurewebsites.net/api/enrich",
  "authResourceId": "api://contoso-customskill"
}

Kunskapsindata

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

Färdighetsresultat

Den här färdigheten har inga fördefinierade utdata. 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"
    }
  ]
}

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso.example.org/api?code=<redacted>",
  "httpMethod": "POST",
  "name": "myCustomSkill",
  "httpHeaders": {
    "Authorization": "<redacted>",
    "Ocp-Apim-Subscription-Key": "<redacted>"
  }
}

{
  "uri": "<unchanged>",
  "httpHeaders": {
    "Authorization": "<unchanged>",
    "Ocp-Apim-Subscription-Key": "<unchanged>"
  }
}

Exempel på JSON-struktur för indata

Den här JSON-strukturen representerar nyttolasten som du skickar 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 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"
              }
            ]
        },
    ]
}

Felhanteringsfall

Utöver att webb-API:et inte är tillgängligt eller skickar statuskoder som inte lyckas kan du betrakta följande fall som fel:

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

• Om svarsmatrisen values innehåller ogiltiga poster (till exempel saknas eller dupliceras recordId) utökas inte de ogiltiga posterna. När du utvecklar anpassade kunskaper följer du kunskapskontraktet för webb-API:et. Du kan se det här exemplet som finns på lagringsplatsenför Power Skill som följer det förväntade kontraktet.

Om webb-API:et inte är tillgängligt eller returnerar ett HTTP-fel innehåller indexerarens körningshistorik ett användarvänligt fel med all tillgänglig information om HTTP-felet.

Säkerhetsöverväganden för hanterad identitetsautentisering

När du använder hanterad identitetsautentisering med en anpassad webb-API-färdighet hämtar Azure AI-sökning en Microsoft Entra åtkomsttoken för programmet som identifieras av authResourceId och inkluderar den token i begäranden som skickas till slutpunkten som anges av uri. Slutpunkten som refereras av uri är vanligtvis din Azure-funktion, Azure App Service, Azure API Management slutpunkt eller ett annat Microsoft Entra-skyddat program. Du ansvarar för att konfigurera och underhålla relationen mellan slutpunkten och programmet som identifieras av authResourceId.

Oavsett autentiseringsmetod kan anpassade kunskapsindata innehålla värden från dokument som tillhandahålls av kunden eller värden som härletts från dessa dokument. Behandla alla anpassade kunskapsindata som ej betrodda. Azure AI-sökning vidarebefordrar indata som konfigurerats i kunskapsuppsättningen till slutpunkten utan att tolka, validera eller begränsa deras innehåll för din anpassade implementering.

Verifiera och begränsa dokument härledda värden i din anpassade kompetens innan du använder dem i utgående begäranden eller andra säkerhetskänsliga åtgärder. Använd validering av indata, tillåtna mållistor, validering av URL och värdnamn, protokollbegränsningar och nätverksåtkomst med minst privilegier som endast tillåter de mål och portar som kompetensen kräver. Mer information finns i Arkitekturstrategier för nätverk och anslutning.

Rekommenderade säkerhetsmetoder

Följ dessa metoder för att upprätthålla en säker distribution:

• Konfigurera egenskapen så att den uri endast pekar på betrodda slutpunkter som är avsedda att ta emot begäranden från Azure AI-sökning.
• Konfigurera authResourceId för att identifiera det Microsoft Entra program som förväntas ta emot och verifiera åtkomsttoken.
• Kontrollera att programmet som tar emot begäranden validerar standardtokenanspråk, inklusive målgrupp (aud), utfärdare (iss), klientorganisation (tid) och eventuella nödvändiga programroller eller behörigheter innan begäranden bearbetas.
• Tillämpa principen om lägsta behörighet när du beviljar behörigheter till den Azure AI-sökning hanterade identiteten.
• Granska regelbundet anpassade webb-API:ers kunskapsdefinitioner, Microsoft Entra programregistreringar och approlltilldelningar och behörigheter som beviljats Azure AI-sökning hanterade identiteter. Granska konfigurationsändringar via dina etablerade processer för ändringshantering och säkerhetsgranskning.
• Granska regelbundet slutpunktskonfigurationer för Azure Functions, App Services, API:er och API-gatewayer.
• Övervaka inloggningsloggar för program, autentiseringshändelser och API-åtkomstloggar för oväntad eller obehörig aktivitet.
• Ta bort oanvända slutpunkter, behörigheter, programregistreringar och rolltilldelningar som inte längre krävs.

Begränsa åtkomsten till konfiguration av kompetensuppsättningar

Användare som kan skapa, ändra eller köra kompetensuppsättningar kan styra både målslutpunkten och autentiseringskonfigurationen som används av en anpassad webb-API-färdighet. Begränsa dessa behörigheter till betrodda administratörer och följ standardprocesserna för ändringshantering och säkerhetsgranskning när du konfigurerar hanterade identitetsaktiverade anpassade kunskaper.

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