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.

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.

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