Quando le prestazioni del modello sono soddisfacenti, il modello è pronto per la distribuzione e le query, per le stime dalle espressioni. La distribuzione di un modello consente di renderlo disponibile per l'uso tramite l'API di stima.
Prerequisiti
Per altre informazioni, vedere il ciclo di vita di sviluppo di un progetto.
Distribuire un modello
Dopo aver esaminato le prestazioni del modello e aver deciso che è adatto all’uso nel proprio ambiente, è necessario assegnarlo a una distribuzione per l’esecuzione delle query. L’assegnazione di un modello a una distribuzione consente di renderlo disponibile all'uso tramite l'API di stima. È preferibile creare una distribuzione denominata production
a cui assegnare il modello migliore generato finora e usarlo nel proprio 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.
Per distribuire un modello all’interno di Studio di linguaggio:
Selezionare Distribuzione di un modello nel menu a sinistra.
Selezionare Aggiungi distribuzione per avviare la procedura guidata Aggiungi distribuzione.
Selezionare Crea un nuovo nome di distribuzione per creare una nuova distribuzione e assegnare un modello sottoposto a training dall'elenco a discesa seguente. In alternativa, selezionare Sovrascrivi un nome di distribuzione esistente per sostituire effettivamente il modello usato da una distribuzione esistente.
Nota
La sovrascrittura di una distribuzione esistente non richiede modifiche alla chiamata API di previsione, ma i risultati ottenuti saranno basati sul modello appena assegnato.
Selezionare un modello sottoposto a training dall'elenco a discesa Modello.
Fare clic su Distribuisci per avviare il processo di distribuzione.
Al termine della distribuzione verrà visualizzata una data di scadenza. La scadenza della distribuzione indica quando il modello non potrà essere usato per la stima, ossia generalmente dodici mesi dopo la scadenza di una configurazione di training.
Invia processo di distribuzione
Creare una richiesta PUT usando l'URL, le intestazioni e il corpo JSON seguenti per iniziare a distribuire un modello di comprensione del linguaggio di conversazione.
Richiesta URL
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?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} |
Nome della distribuzione. Per questo valore viene applicata la distinzione tra maiuscole e minuscole. |
staging |
{API-VERSION} |
La versione dell'API che si sta richiamando. |
2023-04-01 |
Usare l'intestazione seguente per autenticare la richiesta.
Chiave |
valore |
Ocp-Apim-Subscription-Key |
La chiave della risorsa. È usata per l’autenticazione delle richieste API. |
Corpo della richiesta
{
"trainedModelLabel": "{MODEL-NAME}",
}
Chiave |
Segnaposto |
Valore |
Esempio |
trainedModelLabel |
{MODEL-NAME} |
Nome del modello che verrà 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, si riceverà una risposta 202
indicante l'esito positivo. Nelle intestazioni della risposta, estrarre il valore operation-location
. Il formato sarà simile al seguente:
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
È possibile usare questo URL per ottenere lo stato del processo di distribuzione.
Ottieni stato del processo di distribuzione
Quando si invia una richiesta di distribuzione con esito positivo, l'URL completo della richiesta per verificare lo stato del processo (incluso l'endpoint, il nome del progetto e l'ID processo) è contenuto nell'intestazione operation-location
della risposta.
Usare la richiesta GET seguente per ottenere lo stato del processo di distribuzione. Sostituire i valori segnaposto con i propri valori.
Richiesta URL
{ENDPOINT}/language/authoring/analyze-conversations/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} |
Nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole. |
myProject |
{DEPLOYMENT-NAME} |
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. |
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
La versione dell'API che viene richiamata. |
2023-04-01 |
Usare l'intestazione seguente per autenticare la richiesta.
Chiave |
valore |
Ocp-Apim-Subscription-Key |
La chiave della risorsa. È usata per l’autenticazione delle richieste API. |
Testo della risposta
Dopo aver inviato la richiesta, si otterrà la risposta seguente. Mantenere 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"
}
Scambiare distribuzioni
Dopo aver completato il test di un modello assegnato a una distribuzione, è possibile assegnarlo a un'altra distribuzione. Lo scambio delle distribuzioni prevede:
- Acquisizione del modello assegnato alla prima distribuzione e assegnazione di tale modello alla seconda distribuzione.
- Acquisizione del modello assegnato alla seconda distribuzione e assegnazione di tale modello alla prima distribuzione.
Può essere usato per lo scambio di distribuzioni production
e staging
quando si desidera acquisire il modello assegnato a staging
e assegnarlo a production
.
Per scambiare le distribuzioni da Studio di linguaggio
Nella pagina Distribuisci modello, selezionare le due distribuzioni da scambiare e selezionare Scambia distribuzioni nel menu in alto.
Nella finestra che viene visualizzata, selezionare i nomi delle distribuzioni da scambiare.
Creare una richiesta POST usando l'URL, le intestazioni e il corpo JSON seguenti per avviare un processo di scambio delle distribuzioni.
Richiesta URL
{ENDPOINT}/language/authoring/analyze-conversations/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 si sta richiamando. |
2023-04-01 |
Usare l'intestazione seguente per autenticare la richiesta.
Chiave |
valore |
Ocp-Apim-Subscription-Key |
La chiave della risorsa. È usata per l’autenticazione delle richieste API. |
Corpo della richiesta
{
"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 riceverà una risposta 202
indicante l'esito positivo.
Eliminare una distribuzione
Per eliminare una distribuzione da Studio di linguaggio, selezionare la pagina Distribuisci modello. Successivamente, selezionare la distribuzione da eliminare e selezionare Elimina distribuzione nel menu in alto.
Creare una richiesta ELIMINA usando l'URL, le intestazioni e il corpo JSON seguenti per eliminare una distribuzione di comprensione del linguaggio di conversazione.
Richiesta URL
{ENDPOINT}/language/authoring/analyze-conversations/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} |
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 si sta richiamando. |
2023-04-01 |
Usare l'intestazione seguente per autenticare la richiesta.
Chiave |
valore |
Ocp-Apim-Subscription-Key |
La chiave della risorsa. È usata per l’autenticazione delle richieste API. |
Dopo aver inviato la richiesta API, si riceverà una risposta 202
con l'esito positivo indicante che la distribuzione è stata eliminata.
Assegnare risorse di distribuzione
È possibile distribuire un progetto in più aree assegnando diverse risorse Lingua esistenti in aree differenti.
Per assegnare risorse di distribuzione in altre aree in Studio di linguaggio:
- Assicurarsi di aver assegnato a se stessi il ruolo Proprietario linguaggio Servizi cognitivi per la risorsa usata per la creazione del progetto.
- Andare alla pagina Distribuzione di un modello in Language Studio.
- Selezionare la scheda Aree.
- Selezionare Aggiungi risorsa di distribuzione.
- Selezionare una risorsa lingua in un'altra area.
A questo punto, è possibile distribuire il progetto nelle aree in cui sono state assegnate le risorse.
L'assegnazione programmatica delle risorse di distribuzione richiede l'autenticazione di Microsoft Entra**. Microsoft Entra ID viene usato per accertarsi di disporre dell'accesso alle risorse da assegnare al progetto per la distribuzione in più aree. Per usare l'autenticazione di Microsoft Entra programmaticamente quando si effettuano chiamate API REST, vedere la documentazione relativa all'autenticazione di Servizi di Azure AI.
Assegnare una risorsa
Inviare una richiesta POST usando l'URL, le intestazioni e il corpo JSON seguenti per assegnare risorse di distribuzione.
Richiesta URL
Usare l'URL seguente durante la creazione della richiesta API. Sostituire i valori segnaposto seguenti con i propri valori.
{ENDPOINT}/language/authoring/analyze-conversations/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 |
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 ID risorsa completo da assegnare. Disponibile nel portale di Azure nella scheda Proprietà per la risorsa, all'interno del 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 parte del 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, come parte del 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 seguenti con i propri valori.
Richiesta URL
{ENDPOINT}/language/authoring/analyze-conversations/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 |
Usare l'intestazione seguente per autenticare la richiesta.
Chiave |
valore |
Ocp-Apim-Subscription-Key |
La chiave della risorsa. È usata per l’autenticazione delle richieste API. |
Testo della risposta
Dopo aver inviato la richiesta, si otterrà la risposta seguente. Mantenere 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"
}
Annullare l’assegnazione di risorse di distribuzione
Quando si annulla l'assegnazione o si rimuove una risorsa di distribuzione da un progetto, verranno eliminate anche tutte le distribuzioni distribuite nell'area di tale risorsa.
Per annullare l’assegnazione o rimuovere risorse di distribuzione in altre usando Studio di linguaggio:
- Accedere alla scheda Aree nella pagina Distribuisci un modello.
- Selezionare la risorsa di cui annullare l'assegnazione.
- Selezionare il pulsante Rimuovi assegnazione.
- Nella finestra che viene visualizzata, digitare il nome della risorsa da rimuovere.
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.
Richiesta URL
Usare l'URL seguente durante la creazione della richiesta API. Sostituire i valori segnaposto seguenti con i propri valori.
{ENDPOINT}/language/authoring/analyze-conversations/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 |
Usare l'intestazione seguente per autenticare la richiesta.
Chiave |
valore |
Ocp-Apim-Subscription-Key |
La chiave della 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 dell’ID risorsa completo di cui annullare l’assegnazione. Disponibile nel portale di Azure nella scheda Proprietà per la risorsa come campo ID risorsa. |
/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 seguenti con i propri valori.
Richiesta URL
{ENDPOINT}/language/authoring/analyze-conversations/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 |
Usare l'intestazione seguente per autenticare la richiesta.
Chiave |
valore |
Ocp-Apim-Subscription-Key |
La chiave della risorsa. È usata per l’autenticazione delle richieste API. |
Testo della risposta
Dopo aver inviato la richiesta, si otterrà 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