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

Articolo
09/01/2024

Importante

Il supporto per le connessioni dell'indicizzatore al catalogo dei modelli di Azure AI Studio è disponibile in anteprima pubblica in condizioni supplementari per l'utilizzo. Le API REST di anteprima supportano questa competenza.

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

Analogamente ad altre competenze predefinite, una competenza AML include 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. I dati vengono elaborati nell'area geografica in cui viene distribuito il modello. È previsto che la risposta abbia gli output specificati dalla competenza AML. Qualsiasi altra risposta è considerata un errore e non vengono eseguiti arricchimenti.

La competenza AML può essere chiamata con la versione dell'API stabile 2024-07-01 o la versione dell'API 2024-05-01-preview per le connessioni al catalogo dei modelli in Azure AI Studio.

A partire dall'API REST 2024-05-01-preview e nel portale di Azure (destinato anche all'anteprima 2024-05-05-01-preview), Ricerca di Intelligenza artificiale di Azure ha introdotto il vettore del catalogo dei modelli di Azure AI Studio per le connessioni temporali di query al catalogo dei modelli in Azure AI Studio. Se si vuole usare tale vettore per le query, la competenza AML è la controparte di indicizzazione per la generazione di incorporamenti usando un modello nel catalogo dei modelli di Azure AI Studio.

Durante l'indicizzazione, la competenza AML può connettersi al catalogo dei modelli per generare vettori per l'indice. In fase di query, le query possono usare un vettore per connettersi allo stesso modello per vettorizzare le stringhe di testo per una query vettoriale. In questo flusso di lavoro, la competenza AML e il vettore del catalogo dei modelli devono essere usati insieme in modo da usare lo stesso modello di incorporamento sia per l'indicizzazione che per le query. Per informazioni dettagliate su questo flusso di lavoro, vedere Come implementare la vettorizzazione integrata usando modelli di Azure AI Studio .

Nota

L'indicizzatore riproverà 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

Un'areadi lavoro AML
Endpoint online (in tempo reale) in questa area di lavoro.

@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 eventualmente richiesta dall'endpoint online AML

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 tramite 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 tramite 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 eventualmente usata dall'endpoint online AML. 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 del servizio Azure AI Search 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 regione 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 della competenza come input e il payloadJSON 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

La struttura JSON rappresenta il payload inviato all'endpoint online AML. I campi di livello superiore della struttura corrisponderanno ai "nomi" specificati nella sezione inputs della definizione della competenza. Il valore di questi campi viene da source (che può essere un campo nel documento o potenzialmente 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 risposta Content-Type) e deve essere un oggetto in cui i campi sono arricchimenti corrispondenti ai "nomi" in output e il 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 input shaping inline

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

Struttura JSON di output di esempio di shaping inline

{
    "detected_language_code": "es"
}

Casi di errore

Oltre alla non disponibilità dell'AML o all'invio di codici di stato che non indicano un esito positivo, sono considerati casi di errore i seguenti:

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

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

Condividi tramite