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

La competenza dell'API Web personalizzata consente di estendere l'arricchimento tramite intelligenza artificiale chiamando un endpoint dell'API Web che fornisce operazioni personalizzate. Analogamente alle competenze predefinite, una competenza API Web personalizzata ha input e output. In base agli input, l'API Web riceve un payload JSON durante l'esecuzione dell'indicizzatore e restituisce come risposta un payload JSON con un codice di stato di esito positivo. È previsto che la risposta abbia gli output specificati dalla competenza personalizzata. Qualsiasi altra risposta è considerata un errore e non vengono eseguiti arricchimenti. La struttura dei payload JSON è descritta ulteriormente più avanti in questo documento.

La competenza dell'API Web personalizzata viene usata anche nell'implementazione della funzionalità Azure OpenAI sui dati. Se Azure OpenAI è configurato per l'accesso basato sui ruoli e si ricevono chiamate 403 Forbidden durante la creazione dell'indice vettoriale, assicurarsi che Azure AI Search abbia un'identità assegnata dal sistema e che sia eseguito come servizio attendibile in Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parametri della competenza

I parametri fanno distinzione tra maiuscole e minuscole.

Input competenze

Non esistono input predefiniti per questa competenza. Gli input sono costituiti da qualsiasi campo esistente o qualsiasi nodo nell'albero di arricchimento che si desidera passare alla competenza personalizzata.

Output competenze

Non esistono output predefiniti per questa competenza. 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"
    }
  ]
}

Struttura JSON di input di esempio

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

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

• Ogni oggetto nella matrice values ha:

  • Una proprietà recordId che è una stringa univoca usata per identificare tale record.

  • Una proprietà data che è un oggetto JSON. I campi della proprietà data corrispondono ai "nomi" specificati nella sezione inputs della definizione della competenza. Il valore di questi campi proviene da source, che può essere un campo nel documento o provenire 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 alla non disponibilità dell'API Web o all'invio di codici di stato che non indicano un esito positivo, sono considerati casi di errore i seguenti:

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

• Se nella matrice di risposta values sono presenti record non validi (ad esempio, recordId manca o è duplicato), non viene eseguito alcun arricchimento per i record non validi. È importante rispettare il contratto di competenza dell'API Web quando si sviluppano competenze personalizzate. È 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, un errore descrittivo con i dettagli disponibili sull'errore HTTP viene aggiunto alla cronologia di esecuzione dell'indicizzatore.

Vedi 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