Competenza AML in una pipeline di arricchimento di Ricerca intelligenza artificiale di Azure

  • Articolo

Importante

Questa competenza è disponibile in anteprima pubblica in condizioni supplementari per l'utilizzo. L'API REST di anteprima supporta questa competenza.

La competenza AML consente di estendere l'arricchimento tramite intelligenza artificiale con un modello AML (Azure Machine Learning) personalizzato. Dopo aver eseguito il training e la distribuzione di un modello AML, una competenza AML lo integra nell'arricchimento tramite intelligenza artificiale.

Come le competenze predefinite, una competenza AML ha input e output. Gli input vengono inviati all'endpoint online AML distribuito come oggetto JSON, che restituisce un payload JSON come risposta insieme a un codice di stato dell'esito positivo. La risposta dovrebbe avere gli output specificati dalla competenza AML . Qualsiasi altra risposta è considerata un errore e non vengono eseguiti arricchimenti.

Nota

L'indicizzatore ritenta due volte per determinati codici di stato HTTP standard restituiti dall'endpoint online AML. Questi codici di stato HTTP sono:

  • 503 Service Unavailable
  • 429 Too Many Requests

Prerequisiti

@odata.type

Microsoft.Skills.Custom.AmlSkill

Parametri della competenza

I parametri fanno distinzione tra maiuscole e minuscole. Quali parametri si sceglie di usare dipendono dall'autenticazione richiesta dall'endpoint online AML, se disponibile

Nome parametro Descrizione
uri (Obbligatorio per l'autenticazione della chiave) URI di assegnazione dei punteggi dell'endpoint online AML a cui viene inviato il payload JSON . È consentito solo lo schema URI https .
key (Obbligatorio per l'autenticazione della chiave) Chiave per l'endpoint online AML.
resourceId (Obbligatorio per l'autenticazione del token). ID risorsa di Azure Resource Manager dell'endpoint online AML. Deve essere nel formato sottoscrizioni/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}.
region (Facoltativo per l'autenticazione del token). L'area in cui viene distribuito l'endpoint online AML.
timeout (facoltativo) Se specificato, indica il timeout per il client HTTP che effettua la chiamata API. Il valore deve essere formattato come valore XSD "dayTimeDuration" (un subset limitato di un valore duration ISO 8601 ). Ad esempio, PT60S per 60 secondi. Se non impostato, viene scelto un valore predefinito di 30 secondi. Il timeout può essere impostato su un massimo di 230 secondi e un minimo di 1 secondo.
degreeOfParallelism (Facoltativo) Se specificato, indica il numero di chiamate effettuate dall'indicizzatore in parallelo all'endpoint specificato. È possibile ridurre questo valore se l'endpoint non riesce con un carico eccessivo di richieste. È possibile generarlo se l'endpoint è in grado di accettare più richieste e si desidera un aumento delle prestazioni dell'indicizzatore. Se non è impostato, viene usato un valore predefinito pari a 5. Il degreeOfParallelism può essere impostato su un massimo di 10 e un minimo di 1.

Quali parametri della competenza usare

I parametri di competenza AML necessari dipendono dall'autenticazione usata dall'endpoint online AML, se disponibile. Gli endpoint online AML offrono due opzioni di autenticazione:

  • Autenticazione basata su chiave. Viene fornita una chiave statica per autenticare le richieste di assegnazione dei punteggi dalle competenze AML
    • Usare i parametri URI e chiave
  • Autenticazione basata su token. L'endpoint online AML viene distribuito usando l'autenticazione basata su token. L'identità gestita dell'servizio di ricerca di intelligenza artificiale di Azure deve essere abilitata. La competenza AML usa quindi l'identità gestita del servizio per l'autenticazione nell'endpoint online AML, senza chiavi statiche necessarie. All'identità deve essere assegnato il ruolo di proprietario o collaboratore.
    • Usare il parametro resourceId .
    • Se il servizio di ricerca si trova in un'area diversa dall'area di lavoro AML, usare il parametro region per impostare l'area in cui è stato distribuito l'endpoint online AML

Input competenze

Non ci sono input predefiniti per questa competenza. È possibile scegliere uno o più campi che sarebbero già disponibili al momento dell'esecuzione di questa competenza come input e il payload JSON inviato all'endpoint online AML avrà campi diversi.

Output competenze

Non ci sono output predefiniti per questa competenza. A seconda della risposta restituita dall'endpoint online AML, aggiungere campi di output in modo che possano essere prelevati dalla risposta JSON .

Definizione di esempio

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Struttura JSON di input di esempio

Questa struttura JSON rappresenta il payload inviato all'endpoint online AML. I campi di primo livello della struttura corrispondono ai "nomi" specificati nella inputs sezione della definizione della competenza. I valori di questi campi provengono da source questi campi (che possono essere provenienti da un campo nel documento o potenzialmente da un'altra competenza)

{
  "text": "Este es un contrato en Inglés"
}

Struttura JSON di output di esempio

L'output corrisponde alla risposta restituita dall'endpoint online AML. L'endpoint online AML deve restituire solo un payload JSON (verificato esaminando l'intestazione della Content-Type risposta) e deve essere un oggetto in cui i campi sono arricchimenti corrispondenti ai "nomi" in e il output cui valore è considerato l'arricchimento.

{
    "detected_language_code": "es"
}

Definizione dell'esempio di modellazione inline

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Struttura JSON di data shaping inline

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

Struttura JSON di output di esempio di data shaping inline

{
    "detected_language_code": "es"
}

Casi di errore

Oltre a non essere disponibile o inviare codici di stato non autorizzati, i seguenti sono considerati casi errati:

  • Se l'endpoint online AML 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 l'endpoint online AML restituisce json non valido

Per i casi in cui l'endpoint online AML non è disponibile o restituisce un errore HTTP, verrà aggiunto un errore descrittivo con tutti i dettagli disponibili sull'errore HTTP alla cronologia di esecuzione dell'indicizzatore.

Vedi anche