Competenza API Web personalizzata in una pipeline di arricchimento di Azure AI Search

Usare la competenza API Web personalizzata per estendere l'arricchimento tramite intelligenza artificiale chiamando un endpoint API Web che fornisce operazioni personalizzate. Analogamente alle competenze predefinite, una competenza dell'API Web personalizzata include input e output. A seconda degli input, l'API Web riceve un payload JSON quando viene eseguito l'indicizzatore e restituisce un payload JSON come risposta, insieme a un codice di stato di esito positivo. La risposta deve includere gli output specificati dalla competenza personalizzata. Qualsiasi altra risposta è considerata un errore e non vengono eseguiti arricchimenti. La struttura del payload JSON è descritta più avanti in questo documento.

La competenza API Web personalizzata viene usata anche nell'implementazione della funzionalità OpenAI di Azure Sui dati. Se Azure OpenAI è configurato per l'accesso in base al ruolo e si verificano 403 Forbidden errori durante la creazione dell'indice vettoriale, verificare che Azure AI Search abbia un'identità assegnata dal sistema ed eseguito come servizio attendibile in Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parametri della competenza

I parametri fanno distinzione tra maiuscole e minuscole.

Comprendere il authResourceId valore

Quando una competenza API Web personalizzata usa l'autenticazione dell'identità gestita, Azure AI Search ottiene un token di accesso Microsoft Entra e lo invia all'endpoint di competenza personalizzato. La authResourceId proprietà specifica l'identificatore della risorsa, noto anche come gruppo di destinatari o URI ID applicazione, per cui viene richiesto il token. Il valore deve corrispondere a quello previsto dall'applicazione di destinazione durante la convalida del token. In caso contrario, l'autenticazione non riesce con una 401 Unauthorized risposta.

Il authResourceId valore identifica l'applicazione che ospita la competenza personalizzata. Non è l'URL del servizio di ricerca o dell'indicizzatore.

La tabella seguente illustra i formati comuni:

La proprietà accetta formati con e senza il suffisso dell'ambito .default . Usare api://<appId> per trovare la corrispondenza diretta con l'URI ID applicazione. Se si include un .default suffisso, ad esempio api://<appId>/.default, l'attestazione del token di aud accesso contiene l'URI dell'ID applicazione di base senza il suffisso .

Per la procedura per configurare l'autenticazione Microsoft Entra per una funzione Azure e impostare authResourceId, vedere Usare un'identità gestita del servizio di ricerca per connettersi a un'app per le funzioni Azure.

Esempio: funzione Azure protetta da Microsoft Entra ID

In questo esempio, Azure AI Search acquisisce un token di accesso per il gruppo di destinatari specificato da authResourceId e include il token quando si richiama l'endpoint della competenza personalizzata.

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

Input delle competenze

Questa competenza non ha input predefiniti. Gli input sono costituiti da qualsiasi campo esistente o qualsiasi nodo nell'albero di arricchimento che si desidera passare alla competenza personalizzata.

Output delle competenze

Questa competenza non ha output predefiniti. Assicurarsi di definire un mapping dei campi di output nell'indicizzatore se l'output della competenza deve essere inviato a un campo nell'indice di ricerca.

Definizione di esempio

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

Struttura JSON di input di esempio

Questa struttura JSON rappresenta il payload inviato all'API Web. Segue sempre questi vincoli:

• L'entità di primo livello è denominata values ed è una matrice di oggetti. Il numero di questi oggetti è al massimo .batchSize

• Ogni oggetto nella matrice values ha:

  • Proprietà recordId che è una stringa univoca , utilizzata per identificare il record.

  • Proprietà data che è un oggetto JSON. I campi della data proprietà corrispondono ai "nomi" specificati nella inputs sezione della definizione della competenza. I valori di tali campi provengono da source questi campi (che possono provenire da un campo nel documento o potenzialmente da un'altra competenza).

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

Struttura JSON di output di esempio

L'"output" corrisponde alla risposta restituita dall'API Web. L'API Web deve restituire solo un payload JSON verificato esaminando l'intestazione della risposta Content-Type, e deve soddisfare i vincoli seguenti:

• Deve contenere un'entità di primo livello denominata values che deve essere una matrice di oggetti.

• Il numero di oggetti nella matrice deve essere lo stesso degli oggetti inviati all'API Web.

• Ogni oggetto deve avere:

  • Una proprietà recordId.

  • Una proprietà data, che è un oggetto in cui i campi sono arricchimenti corrispondenti ai "nomi" nell'output e il cui valore viene considerato l'arricchimento.

  • Una proprietà errors, una matrice che elenca eventuali errori rilevati che vengono aggiunti alla cronologia di esecuzione dell'indicizzatore. Questa proprietà è obbligatoria, ma può avere un valore null.

  • Una proprietà warnings, una matrice che elenca eventuali avvisi rilevati che vengono aggiunti alla cronologia di esecuzione dell'indicizzatore. Questa proprietà è obbligatoria, ma può avere un valore null.

• L'ordinamento degli oggetti in values nella richiesta o nella risposta non è importante. Tuttavia, il valore recordId viene usato per la correlazione in modo che eventuali record nella risposta contenenti un recordId che non fa parte della richiesta originale all'API Web vengano rimossi.

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

Casi di errore

Oltre all'API Web non disponibile o all'invio di codici di stato non riusciti, considerare i casi seguenti come errori:

• Se l'API Web restituisce un codice di stato di esito positivo, ma la risposta indica che non application/jsonè , la risposta non è valida e non vengono eseguiti arricchimenti.

• Se la matrice di risposta values contiene record non validi (ad esempio, mancanti o duplicati recordId), i record non validi non vengono arricchiti. Quando si sviluppano competenze personalizzate, attenersi al contratto di competenza dell'API Web. È possibile fare riferimento a questo esempio fornito nel repository Power skill che segue il contratto previsto.

Nei casi in cui l'API Web non è disponibile o restituisce un errore HTTP, la cronologia di esecuzione dell'indicizzatore include un errore descrittivo con tutti i dettagli disponibili sull'errore HTTP.

Considerazioni sulla sicurezza per l'autenticazione dell'identità gestita

Quando si usa l'autenticazione dell'identità gestita con una competenza API Web personalizzata, Azure AI Search ottiene un token di accesso Microsoft Entra per l'applicazione identificata da authResourceId e include tale token nelle richieste inviate all'endpoint specificato da uri. L'endpoint a cui fa uri riferimento è in genere la funzione Azure, Servizio app di Azure, l'endpoint Gestione API di Azure o un'altra applicazione protetta da Microsoft Entra. Si è responsabili della configurazione e della gestione della relazione tra l'endpoint e l'applicazione identificata da authResourceId.

Indipendentemente dal metodo di autenticazione, gli input di competenza personalizzati possono contenere valori di documenti o valori forniti dal cliente derivati da tali documenti. Considera tutti gli input di competenza personalizzati come non attendibili. Azure AI Search inoltra gli input configurati nel set di competenze all'endpoint senza interpretare, convalidare o vincolare il contenuto per l'implementazione personalizzata.

Convalidare e vincolare i valori derivati dai documenti nella competenza personalizzata prima di usarli nelle richieste in uscita o in altre operazioni sensibili alla sicurezza. Usare la convalida di input, gli elenchi di indirizzi consentiti di destinazione, la convalida url e il nome host, le restrizioni del protocollo e l'accesso alla rete con privilegi minimi che consenta solo le destinazioni e le porte richieste dalla competenza. Per altre informazioni, vedere Strategie di architettura per la rete e la connettività.

Procedure di sicurezza consigliate

Per mantenere una distribuzione sicura, seguire queste procedure:

• Configurare la uri proprietà in modo che punti solo a endpoint attendibili destinati a ricevere richieste da Azure AI Search.
• Configurare authResourceId per identificare l'applicazione Microsoft Entra che dovrebbe ricevere e convalidare il token di accesso.
• Assicurarsi che l'applicazione che riceve le richieste convalide le attestazioni di token standard, inclusi destinatari (aud), autorità di certificazione (iss), tenant (tid) e eventuali ruoli o autorizzazioni dell'applicazione necessari, prima di elaborare le richieste.
• Applicare il principio dei privilegi minimi quando si concedono autorizzazioni all'identità gestita Azure AI Search.
• Esaminare periodicamente le definizioni di competenza dell'API Web personalizzata, Microsoft Entra le registrazioni delle applicazioni e le assegnazioni di ruolo e le autorizzazioni concesse a Azure AI Search identità gestite. Esaminare le modifiche alla configurazione tramite i processi di gestione delle modifiche e di revisione della sicurezza stabiliti.
• Esaminare periodicamente le configurazioni degli endpoint per Funzioni di Azure, Servizi app, API e gateway API.
• Monitorare i log di accesso delle applicazioni, gli eventi di autenticazione e i log di accesso alle API per attività impreviste o non autorizzate.
• Rimuovere endpoint, autorizzazioni, registrazioni dell'applicazione e assegnazioni di ruolo inutilizzate che non sono più necessarie.

Limitare l'accesso alla configurazione del set di competenze

Gli utenti che possono creare, modificare o eseguire set di competenze possono controllare sia l'endpoint di destinazione che la configurazione di autenticazione usata da una competenza DELL'API Web personalizzata. Limitare queste autorizzazioni agli amministratori attendibili e seguire i processi standard di revisione delle modifiche e della sicurezza quando si configurano competenze personalizzate abilitate per l'identità gestita.

Vedere anche

• Definire un set di competenze
• Aggiungere una competenza personalizzata a una pipeline di arricchimento tramite intelligenza artificiale
• Esempio: creazione di una competenza personalizzata per l'arricchimento tramite intelligenza artificiale
• Repository Power skill