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

Articolo
12/18/2024

Importante

Il supporto per le connessioni dell'indicizzatore al catalogo dei modelli di Azure AI Foundry è 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 AML (Azure Machine Learning) personalizzato o un modello di incorporamento di base distribuito in Azure AI Foundry. Dopo aver eseguito il training e la distribuzione di un modello AML, una competenza AML lo integra in un set di competenze.

Utilizzo delle competenze AML

Analogamente ad altre competenze predefinite, una competenza AML personalizzata include input e output. Gli input vengono inviati a un endpoint online AML distribuito come oggetto JSON. L'output dell'endpoint deve essere un payload JSON nella risposta, insieme a un codice di stato di esito positivo. I dati vengono elaborati nell'area geografica in cui viene distribuito il modello. La risposta dovrebbe fornire gli output specificati dalla definizione della competenza AML . Qualsiasi altra risposta è considerata un errore e non vengono eseguiti arricchimenti.

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

La competenza AML può essere chiamata con la versione dell'API stabile 2024-07-01 o azure SDK equivalente o la versione dell'API 2024-05-01-preview per le connessioni al catalogo di modelli nel portale di Azure AI Foundry.

Competenza AML per i modelli in Azure AI Foundry

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

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 e per un elenco dei modelli di incorporamento supportati, vedere Usare i modelli di incorporamento dal catalogo dei modelli di Azure AI Foundry.

È consigliabile usare la procedura guidata Importare e vettorizzare i dati per generare un set di competenze che include una competenza AML per i modelli di incorporamento distribuiti in Azure AI Foundry. La definizione di competenza AML per input, output e mapping viene generata dalla procedura guidata, che consente di testare facilmente un modello prima di scrivere codice.

Prerequisiti

Un'area di lavoro AML per un modello personalizzato creato o un progetto in Azure AI Foundry se un modello di incorporamento viene distribuito dal catalogo.
Endpoint online (in tempo reale) in questa area di lavoro per un modello personalizzato o endpoint del modello per l'incorporamento di modelli distribuiti dal catalogo.

@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. Per l'incorporamento di modelli nel catalogo dei modelli di Azure AI Foundry, si tratta dell'URI di destinazione.
`key`	(Obbligatorio per l'autenticazione della chiave) Chiave per l'endpoint online AML o
`resourceId`	(Obbligatorio per l'autenticazione tramite token). ID risorsa di Azure Resource Manager dell'endpoint online AML. Deve essere nel formato `subscriptions/{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.

Autenticazione

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. Impostare i uri parametri e key per questa connessione.
Autenticazione basata su token, in cui l'endpoint online AML viene distribuito usando l'autenticazione basata su token. L'identità gestita del servizio di ricerca di intelligenza artificiale di Azure deve essere abilitata e avere un'assegnazione di ruolo nell'area di lavoro. La competenza AML usa quindi l'identità gestita del servizio per l'autenticazione nell'endpoint online AML, senza chiavi statiche necessarie. L'identità del servizio di ricerca deve essere proprietario o collaboratore. Impostare il resourceId parametro e, se il servizio di ricerca si trova in un'area diversa dall'area di lavoro AML, impostare il region parametro .

Input competenze

Gli input delle competenze sono un nodo del documento arricchito creato durante il cracking del documento. Ad esempio, potrebbe trattarsi del documento radice, di un'immagine normalizzata o del contenuto di un BLOB. Non esistono input predefiniti per questa competenza. Per gli input, è necessario specificare uno o più nodi popolati al momento dell'esecuzione della competenza AML.

Output competenze

Gli output delle competenze sono nuovi nodi di un documento arricchito creato dalla competenza. Non esistono output predefiniti per questa competenza. Per gli output, è necessario fornire nodi che possono essere popolati dalla risposta JSON della competenza AML.

Definizione di esempio

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A custom model that detects the language in a document.",
    "uri": "https://language-model.models.contoso.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://language-model.models.contoso.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:

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.
L'endpoint online AML restituisce json non valido.

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

Condividi tramite