Distribuire un modello ed estrarre entità dal testo usando l'API di runtime

Dopo aver soddisfatto le prestazioni del modello, è pronto per essere distribuito e usato per riconoscere le entità nel testo. La distribuzione di un modello consente di renderlo disponibile per l'uso tramite l'API di stima.

Prerequisiti

• Un progetto creato correttamente con un account di archiviazione di Azure configurato.
• Dati di testo caricati nell'account di archiviazione.
• Dati etichettati e modello sottoposto a training correttamente
• Esame dei dettagli di valutazione del modello per determinare le prestazioni del modello.

Per altre informazioni, vedereCiclo di vita dello sviluppo del progetto.

Distribuire il modello

Dopo aver esaminato le prestazioni del modello e aver deciso che può essere usato nell'ambiente, è necessario assegnarlo a una distribuzione. L'assegnazione di un modello a una distribuzione consente di renderlo disponibile per l'uso tramite l'API di previsione. È consigliabile creare una distribuzione denominata production a cui assegnare il modello migliore creato finora e usarlo nel sistema. È possibile creare un'altra distribuzione denominata staging a cui è possibile assegnare il modello in uso per poterlo testare. È possibile avere fino a 10 distribuzioni in un progetto.

Microsoft Foundry

Per informazioni su come distribuire il modello personalizzato in Foundry, vedereDistribuire il modello ottimizzato .

API REST

Inviare un processo di distribuzione

Inviare una richiesta PUT usando l'URL, le intestazioni e il corpo JSON seguenti per inviare un processo di distribuzione. Sostituire i valori segnaposto con i propri valori.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}

Segnaposto	valore	Esempio
{ENDPOINT}	Endpoint per l'autenticazione della richiesta API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Il nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	myProject
{DEPLOYMENT-NAME}	Il nome della distribuzione. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	staging
{API-VERSION}	La versione dell'API che viene richiamata. Il valore a cui viene fatto riferimento è relativo alla versione più recente rilasciata. Per altre informazioni, vedereCiclo di vita del modello.	2022-05-01

Headers

Usare l'intestazione seguente per autenticare la richiesta.

Chiave	valore
Ocp-Apim-Subscription-Key	La chiave per la risorsa. È usata per l’autenticazione delle richieste API.

Corpo della richiesta

Usare il JSON seguente nel corpo della richiesta. Usare il nome del modello da assegnare alla distribuzione.

{
  "trainedModelLabel": "{MODEL-NAME}"
}

Chiave	Segnaposto	valore	Esempio
trainedModelLabel	{MODEL-NAME}	Nome del modello assegnato alla distribuzione. È possibile assegnare solo modelli il cui training è stato eseguito correttamente. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	myModel

Dopo aver inviato la richiesta API, riceverai una 202 risposta che indica che la richiesta è stata inviata correttamente. Nelle intestazioni di risposta, estrarre il valore operation-location formattato come segue:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} viene usato per identificare la richiesta, poiché questa operazione è asincrona. È possibile usare questo URL per ottenere lo stato della distribuzione.

Ottenere lo stato del processo di distribuzione

Usare la richiesta GET seguente per eseguire una query dello stato del processo di distribuzione. È possibile usare l'URL ricevuto dal passaggio precedente oppure sostituire i valori segnaposto con i propri valori.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

Segnaposto	valore	Esempio
{ENDPOINT}	Endpoint per l'autenticazione della richiesta API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Il nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	myProject
{DEPLOYMENT-NAME}	Il nome della distribuzione. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	staging
{JOB-ID}	L'ID per individuare lo stato del training del modello. Si trova nel valore dell'intestazione location ricevuto nel passaggio precedente.	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION}	La versione dell'API che viene richiamata. Il valore a cui viene fatto riferimento è relativo alla versione più recente rilasciata. Per altre informazioni, vedereCiclo di vita del modello.	2022-05-01

Headers

Usare l'intestazione seguente per autenticare la richiesta.

Chiave	valore
Ocp-Apim-Subscription-Key	La chiave per la risorsa. È usata per l’autenticazione delle richieste API.

Corpo della risposta

Dopo aver inviato la richiesta, si ottiene la risposta seguente. Continuare il polling di questo endpoint fino a quando il parametro dello stato diventa "succeeded". Si ottiene un codice 200 indicante l'esito positivo della richiesta.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Effettuare lo swapping di distribuzioni

Dopo aver completato il test di un modello assegnato a una distribuzione e si vuole assegnare questo modello a un'altra distribuzione, è possibile scambiare queste due distribuzioni. Nello scambio delle distribuzioni si prende il modello assegnato alla prima distribuzione e lo si assegna alla seconda distribuzione. Si prende quindi il modello assegnato alla seconda distribuzione e lo si assegna alla prima distribuzione. È possibile usare questo processo per scambiare le distribuzioni di produzione e staging ogni volta che si vuole prendere il modello assegnato all'ambiente di staging e assegnarlo all'ambiente di produzione.

Fonderia

Per sostituire un modello distribuito, è possibile scambiare il modello distribuito con un modello diverso nella stessa area:

1. Selezionare il nome del modello in Nome e quindi selezionare Distribuisci modello.

2. Selezionare Scambia modello.

   Il completamento della ridistribuzione richiede alcuni minuti. Nel frattempo, il modello distribuito continua a essere disponibile per l'uso con l'API Translator fino al completamento di questo processo.

API REST

Creare una richiesta POST usando l'URL, le intestazioni e il corpo JSON seguenti per avviare un processo di swapping delle distribuzioni.

URL richiesta

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/:swap?api-version={API-VERSION}

Segnaposto	valore	Esempio
{ENDPOINT}	Endpoint per l'autenticazione della richiesta API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	myProject
{API-VERSION}	La versione dell'API che viene richiamata. Il valore a cui si fa riferimento è relativo alla versione più recente del modello rilasciata.	2022-05-01

Headers

Usare l'intestazione seguente per autenticare la richiesta.

Chiave	valore
Ocp-Apim-Subscription-Key	La chiave per la risorsa. È usata per l’autenticazione delle richieste API.

Request Body

{
  "firstDeploymentName": "{FIRST-DEPLOYMENT-NAME}",
  "secondDeploymentName": "{SECOND-DEPLOYMENT-NAME}"
}

Chiave	Segnaposto	valore	Esempio
firstDeploymentName	{FIRST-DEPLOYMENT-NAME}	Il nome della prima distribuzione. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	production
secondDeploymentName	{SECOND-DEPLOYMENT-NAME}	Il nome della seconda distribuzione. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	staging

Dopo aver inviato la richiesta API, si riceve una 202 risposta che indica l'esito positivo.

Eliminare una distribuzione

Fonderia

Se il progetto non è più necessario, è possibile eliminarlo da Foundry.

1. Navigare alla pagina principale di Foundry. Avviare il processo di autenticazione eseguendo l'accesso, a meno che non sia già stato completato questo passaggio e che la sessione sia attiva.
2. Selezionare il progetto da eliminare dalla sezione Keep building with Foundry
3. Selezionare Centro gestione.
4. Selezionare Elimina progetto.

Per eliminare l'hub insieme a tutti i relativi progetti:

1. Passare alla scheda Panoramica della sezione Hub .

2. A destra selezionare Elimina hub.

3. Il collegamento apre il portale di Azure per eliminare l'hub.

API REST

Creare una richiesta DELETE usando l'URL, le intestazioni e il corpo JSON seguenti per eliminare una distribuzione.

URL richiesta

{Endpoint}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{deploymentName}?api-version={API-VERSION}

Segnaposto	valore	Esempio
{ENDPOINT}	Endpoint per l'autenticazione della richiesta API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	myProject
{DEPLOYMENT-NAME}	Il nome della distribuzione. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	prod
{API-VERSION}	La versione dell'API che viene richiamata. Il valore a cui viene fatto riferimento è relativo alla versione più recente rilasciata. Per altre informazioni, vedereCiclo di vita del modello.	2022-05-01

Headers

Usare l'intestazione seguente per autenticare la richiesta.

Chiave	valore
Ocp-Apim-Subscription-Key	La chiave per la risorsa. È usata per l’autenticazione delle richieste API.

Dopo aver inviato la richiesta API, si riceve una 202 risposta che indica l'esito positivo, il che significa che la distribuzione viene eliminata. Risultati di una chiamata con esito positivo con un'intestazione Operation-Location usata per controllare lo stato del processo.

Assegnare risorse di distribuzione

È possibile distribuire un progetto in più aree assegnando diverse risorse Lingua esistenti in aree differenti.

Fonderia

Per altre informazioni su come distribuire un modello personalizzato, vedereDistribuire il modello ottimizzato

API REST

L'assegnazione delle risorse di distribuzione a livello di codice richiede l'autenticazione di Microsoft Entra. Microsoft Entra ID viene usato per verificare di avere accesso alle risorse che si desidera assegnare al progetto per la distribuzione in più aree. Per utilizzare programmaticamente l'autenticazione di Microsoft Entra quando si effettuano chiamate API REST, consultare la documentazione di Foundry Tools.

Assegnare una risorsa

Inviare una richiesta POST usando l'URL, le intestazioni e il corpo JSON seguenti per assegnare risorse di distribuzione.

URL richiesta

Usare l'URL seguente durante la creazione della richiesta dell’API. Sostituire i valori segnaposto con i propri valori.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/:assign?api-version={API-VERSION}

Segnaposto	valore	Esempio
{ENDPOINT}	Endpoint per l'autenticazione della richiesta API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	myProject
{API-VERSION}	La versione dell'API che viene richiamata.	2022-10-01-preview

Headers

Usare l'autenticazione di Microsoft Entra per eseguire l'autenticazione di questa API.

Corpo

Usare il codice JSON di esempio seguente come corpo.

{
  "resourcesMetadata": [
    {
      "azureResourceId": "{AZURE-RESOURCE-ID}",
      "customDomain": "{CUSTOM-DOMAIN}",
      "region": "{REGION-CODE}"
    }
  ]
}

Chiave	Segnaposto	valore	Esempio
azureResourceId	{AZURE-RESOURCE-ID}	Il percorso dell’ID risorsa completo da assegnare. Disponibile nel portale di Azure nella scheda Proprietà per la risorsa nel campo ID risorsa.	/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource
customDomain	{CUSTOM-DOMAIN}	Il sottodominio personalizzato della risorsa da assegnare. Disponibile nel portale di Azure nella scheda Chiavi ed endpoint per la risorsa, come campo Endpoint nell'URL https://<your-custom-subdomain>.cognitiveservices.azure.com/	contosoresource
region	{REGION-CODE}	Un codice area che specifica l'area della risorsa da assegnare. Disponibile nel portale di Azure nella scheda Chiavi ed endpoint per la risorsa, nel campo Posizione/Area.	eastus

Ottenere lo stato di assegnazione di una risorsa

Usare la richiesta GET seguente per ottenere lo stato del processo di assegnazione di una risorsa di distribuzione. Sostituire i valori segnaposto con i propri valori.

URL richiesta

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/assign/jobs/{JOB-ID}?api-version={API-VERSION}

Segnaposto	valore	Esempio
{ENDPOINT}	Endpoint per l'autenticazione della richiesta API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	myProject
{JOB-ID}	L'ID processo per ottenere lo stato di assegnazione della distribuzione. È incluso nel valore dell'intestazione operation-location ricevuto dall'API in risposta alla richiesta di assegnazione della risorsa di distribuzione.	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION}	La versione dell'API che viene richiamata.	2022-10-01-preview

Headers

Usare l'intestazione seguente per autenticare la richiesta.

Chiave	valore
Ocp-Apim-Subscription-Key	La chiave per la risorsa. È usata per l’autenticazione delle richieste API.

Corpo della risposta

Dopo aver inviato la richiesta, si ottiene la risposta seguente. Continuare il polling di questo endpoint fino a quando il parametro status dello stato diventa succeeded.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Annullare l'assegnazione di risorse di distribuzione

Per annullare l'assegnazione o la rimozione di una risorsa di distribuzione da un progetto, eliminare anche tutte le distribuzioni per in tale area di risorse.

Fonderia

Se il progetto non è più necessario, è possibile eliminarlo da Foundry.

1. Navigare alla pagina principale di Foundry. Avviare il processo di autenticazione eseguendo l'accesso, a meno che non sia già stato completato questo passaggio e che la sessione sia attiva.
2. Selezionare il progetto da eliminare dalla sezione Keep building with Foundry
3. Selezionare Centro gestione.
4. Selezionare Elimina progetto.

Per eliminare l'hub insieme a tutti i relativi progetti:

1. Passare alla scheda Panoramica della sezione Hub .

2. A destra selezionare Elimina hub.

3. Il collegamento apre il portale di Azure per eliminare l'hub.

API REST

Annullare l'assegnazione di una risorsa

Inviare una richiesta POST usando l'URL, le intestazioni e il corpo JSON seguenti per annullare l’assegnazione o rimuovere risorse di distribuzione da un progetto.

URL richiesta

Usare l'URL seguente durante la creazione della richiesta dell’API. Sostituire i valori segnaposto con i propri valori.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/:unassign?api-version={API-VERSION}

Segnaposto	valore	Esempio
{ENDPOINT}	Endpoint per l'autenticazione della richiesta API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	myProject
{API-VERSION}	La versione dell'API che viene richiamata.	2022-10-01-preview

Headers

Usare l'intestazione seguente per autenticare la richiesta.

Chiave	valore
Ocp-Apim-Subscription-Key	La chiave per la risorsa. È usata per l’autenticazione delle richieste API.

Corpo

Usare il codice JSON di esempio seguente come corpo.

{
  "assignedResourceIds": [
    "{AZURE-RESOURCE-ID}"
  ]
}

Chiave	Segnaposto	valore	Esempio
assignedResourceIds	{AZURE-RESOURCE-ID}	Il percorso completo dell'ID risorsa di cui annullare l'assegnazione. Disponibile nel portale di Azure nella scheda Proprietà per la risorsa come campo ID risorsa.	/subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource

Ottenere lo stato di annullamento dell’assegnazione di una risorsa

Usare la richiesta GET seguente per ottenere lo stato del processo di annullamento dell’assegnazione di una risorsa di distribuzione. Sostituire i valori segnaposto con i propri valori.

URL richiesta

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/unassign/jobs/{JOB-ID}?api-version={API-VERSION}

Segnaposto	valore	Esempio
{ENDPOINT}	Endpoint per l'autenticazione della richiesta API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.	myProject
{JOB-ID}	L'ID processo per ottenere lo stato di assegnazione della distribuzione. È incluso nel valore dell'intestazione operation-location ricevuto dall'API in risposta alla richiesta di annullamento dell’assegnazione di una risorsa di distribuzione.	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION}	La versione dell'API che viene richiamata.	2022-10-01-preview

Headers

Usare l'intestazione seguente per autenticare la richiesta.

Chiave	valore
Ocp-Apim-Subscription-Key	La chiave per la risorsa. È usata per l’autenticazione delle richieste API.

Corpo della risposta

Dopo aver inviato la richiesta, si ottiene la risposta seguente. Continuare il polling di questo endpoint fino a quando il parametro dello stato diventa "succeeded".

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Passaggi successivi

Dopo aver creato una distribuzione, è possibile usarla per estrarre entità dal testo.