Installera och kör Docker-behållare för LUIS

Anteckning

Behållar avbildningens plats har nyligen ändrats. Läs den här artikeln om du vill se den uppdaterade platsen för den här behållaren.

Med behållare kan du använda LUIS i din egen miljö. Containrar är bra för specifika säkerhets- och datastyrningskrav. I den här artikeln får du lära dig hur du hämtar, installerar och kör en LUIS-behållare.

Behållaren Language Understanding (LUIS) läser in din utbildade eller publicerade Language Understanding modell. Som en Luis-appger Docker-behållaren åtkomst till frågan förutsägelser från BEHÅLLAREns API-slutpunkter. Du kan samla in loggar från behållaren och överföra tillbaka dem till Language Understanding-appen för att förbättra appens förutsägelse noggrannhet.

Följande video visar hur du använder den här behållaren.

Demonstration av behållare för Cognitive Services

Om du inte har någon Azure-prenumeration kan du skapa ett kostnadsfritt konto innan du börjar.

Förutsättningar

Observera följande krav för att köra LUIS-behållaren:

Obligatorisk Syfte
Docker-motorn Du behöver Docker-motorn installerad på en värddator. Docker innehåller paket som konfigurerar Docker-miljön på macOS, Windows och Linux. En introduktion till grunderna för Docker och containrar finns i Docker-översikt.

Docker måste konfigureras för att tillåta att behållarna ansluter till och skicka fakturerings data till Azure.

I Windows måste Docker också konfigureras för att stödja Linux-behållare.

Bekant med Docker Du bör ha grundläggande kunskaper om Docker-koncept, t. ex. register, databaser, behållare och behållar avbildningar, samt kunskaper om grundläggande docker kommandon.
Azure Cognitive Services Resource och Luis paketerad app -fil För att du ska kunna använda behållaren måste du ha:

* En Cognitive Services Azure-resurs och den associerade fakturerings nyckeln för fakturerings slut punktens URI. Båda värdena är tillgängliga på sidorna översikt och nycklar för resursen och krävs för att starta behållaren.
* En utbildad eller publicerad app paketeras som monterad inström till behållaren med dess associerade app-ID. Du kan hämta den paketerade filen från LUIS-portalen eller redigera-API: er. Om du får LUIS paketerad app från redigerings-API: er, behöver du också din redigerings nyckel.

Dessa krav används för att skicka kommando rads argument till följande variabler:

{AUTHORING_KEY}: den här nyckeln används för att hämta den paketerade appen från Luis-tjänsten i molnet och ladda upp frågan loggar tillbaka till molnet. Formatet är xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

{APP_ID}: detta ID används för att välja appen. Formatet är xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

{Api_key}: den här nyckeln används för att starta behållaren. Du kan hitta slut punkts nyckeln på två platser. Det första är Azure Portal i Cognitive Services resursens nyckel lista. Slut punkts nyckeln är också tillgänglig i LUIS-portalen på sidan nycklar och inställningar för slut punkt. Använd inte start nyckeln.

{ENDPOINT_URI}: slut punkten enligt vad som anges på översikts sidan.

Redigerings nyckeln och slut punkts nyckeln har olika syfte. Använd dem inte interoförändrade.

Nödvändiga parametrar samlas in

Det finns tre primära parametrar för alla Cognitive Services behållare som krävs. Licens avtalet för slutanvändare (EULA) måste vara närvarande med värdet accept . Dessutom behövs både en slut punkts-URL och API-nyckel.

Slut punkts-URI {ENDPOINT_URI}

URI-värdet för slut punkten är tillgängligt på sidan Azure Portal Översikt för motsvarande kognitiva tjänst resurs. Gå till sidan Översikt , Hovra över slut punkten och en Copy to clipboard ikon visas. Kopiera och använd vid behov.

Samla in slut punkts-URI för senare användning

Nyckel {API_KEY}

Den här nyckeln används för att starta behållaren och är tillgänglig på sidan Azure Portals nycklar för motsvarande kognitiva tjänst resurser. Gå till sidan nycklar och klicka på Copy to clipboard ikonen.

Hämta en av de två nycklarna för senare användning

Viktigt

Dessa prenumerations nycklar används för att få åtkomst till ditt kognitiva tjänst-API. Dela inte dina nycklar. Lagra dem på ett säkert sätt, till exempel med hjälp av Azure Key Vault. Vi rekommenderar också att du återskapar nycklarna regelbundet. Endast en nyckel krävs för att göra ett API-anrop. När du återskapar den första nyckeln kan du använda den andra nyckeln för fortsatt åtkomst till tjänsten.

Redigera API: er för paketfil

Redigera API: er för paketerade appar:

Värddatorn

Värden är en x64-baserad dator som kör Docker-behållaren. Det kan vara en dator på din lokala dator eller en Docker-värd tjänst i Azure, till exempel:

Krav och rekommendationer för behållare

I tabellen nedan visas de lägsta och rekommenderade värdena för behållar värden. Dina krav kan ändras beroende på trafik volym.

Container Minimum Rekommenderas TPS
(Minimum, maximum)
LUIS 1 kärna, 2 GB minne 1 kärna, 4 GB minne 20, 40
  • Varje kärna måste vara minst 2,6 gigahertz (GHz) eller snabbare.
  • TPS-transaktioner per sekund

Core och minne motsvarar --cpus --memory inställningarna och som används som en del av docker run kommandot.

Hämta behållar avbildningen med docker pull

Använd docker pull kommandot för att ladda ned en behållar avbildning från mcr.microsoft.com/azure-cognitive-services/language/luis lagrings platsen:

docker pull mcr.microsoft.com/azure-cognitive-services/language/luis:latest

En fullständig beskrivning av tillgängliga taggar, till exempel som latest används i föregående kommando, finns i Luis på Docker Hub.

Tips

Du kan använda kommandot Docker images för att visa en lista över hämtade behållar avbildningar. Följande kommando visar till exempel ID, lagrings plats och tagg för varje Hämtad behållar avbildning, formaterad som en tabell:

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

Använda behållaren

När behållaren är på värddatornanvänder du följande process för att arbeta med behållaren.

Process för att använda Language Understanding-behållare (LUIS)

  1. Exportera paket för container från Luis-portalen eller Luis-API: er.
  2. Flytta paket filen till den nödvändiga indatafilenvärddatorn. Byt inte namn på, ändra, Skriv över eller expandera LUIS-paketfilen.
  3. Kör behållarenmed nödvändiga inställningar för montering och fakturering av indatakälla . Fler exempeldocker run kommandot är tillgängliga.
  4. Fråga efter behållarens förutsägelse slut punkt.
  5. När du är färdig med behållaren importerar du slut punkts loggarna från utmatnings monteringen i Luis-portalen och stoppar behållaren.
  6. Använd LUIS-portalens aktiva utbildning på sidan Granska slut punkt yttranden för att förbättra appen.

Appen som körs i behållaren kan inte ändras. För att kunna ändra appen i behållaren måste du ändra appen i LUIS-tjänsten med hjälp av Luis -portalen eller använda Luis- redigerings-API: erna. Träna och/eller publicera och hämta sedan ett nytt paket och kör behållaren igen.

LUIS-appen i behållaren kan inte exporteras tillbaka till LUIS-tjänsten. Endast fråga loggar kan överföras.

Exportera paketerad app från LUIS

LUIS-containern kräver en utbildad eller publicerad LUIS-app för att besvara förutsägelse frågor för användar yttranden. För att hämta LUIS-appen använder du antingen det utbildade eller publicerade paket-API: et.

Standard platsen är input under katalogen i relation till den plats där du kör docker run kommandot.

Placera paket filen i en katalog och referera till den här katalogen som indata-montering när du kör Docker-behållaren.

Paket typer

Monterings katalogen för indatamängden kan innehålla produktions-, mellanlagrings-och versions modeller för appen samtidigt. Alla paket är monterade.

Typ av paket API för frågans slut punkt Tillgänglighet för fråga Paketets fil namns format
Versions HÄMTA, PUBLICERA Endast behållare {APP_ID}_v{APP_VERSION}.gz
Mellanlagring HÄMTA, PUBLICERA Azure och container {APP_ID}_STAGING.gz
Produktion HÄMTA, PUBLICERA Azure och container {APP_ID}_PRODUCTION.gz

Viktigt

Byt inte namn på, ändra, Skriv över eller expandera LUIS-paketfilerna.

Förpacknings krav

Innan du packar ett LUIS-program måste du ha följande:

Förpacknings krav Information
Resurs instans för Azure Cognitive Services Regioner som stöds är

USA, västra ( westus )
Västeuropa ( westeurope )
Östra Australien ( australiaeast )
Tränad eller publicerad LUIS-app Utan stödda beroenden.
Åtkomst till värd datornsfil system Värddatorn måste tillåta en indata-montering.

Exportera appaket från LUIS-portalen

LUIS- portalen ger möjlighet att exportera den utbildade eller publicerade appens paket.

Exportera den publicerade appens paket från LUIS-portalen

Den publicerade appens paket är tillgängligt från List sidan Mina appar .

  1. Logga in på LUIS- portalen.
  2. Markera kryss rutan till vänster om appens namn i listan.
  3. Välj Exportera objekt från kontext verktygsfältet ovanför listan.
  4. Välj export for container (gzip).
  5. Välj miljö för produktions plats eller mellanlagringsplats.
  6. Paketet laddas ned från webbläsaren.

Exportera det publicerade paketet för behållaren från App-sidans export meny

Exportera den versions bara appens paket från LUIS-portalen

Den versions bara appens paket är tillgängligt på sidan versions lista.

  1. Logga in på LUIS- portalen.
  2. Välj appen i listan.
  3. Välj Hantera i appens navigerings fält.
  4. Välj versioner i det vänstra navigerings fältet.
  5. Markera kryss rutan till vänster om versions namnet i listan.
  6. Välj Exportera objekt från kontext verktygsfältet ovanför listan.
  7. Välj export for container (gzip).
  8. Paketet laddas ned från webbläsaren.

Exportera det utbildade paketet för behållaren från sidan Exportera på versioner-menyn

Exportera den publicerade appens paket från API

Använd följande REST API metod för att paketera en LUIS-app som du redan har publicerat. Ersätt dina egna lämpliga värden för plats hållarna i API-anropet med hjälp av tabellen under HTTP-specifikationen.

GET /luis/api/v2.0/package/{APP_ID}/slot/{SLOT_NAME}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}
Platshållare Värde
{APP_ID} Program-ID för den publicerade LUIS-appen.
{SLOT_NAME} Den publicerade LUIS-appens miljö. Använd något av följande värden:
PRODUCTION
STAGING
{AUTHORING_KEY} Redigerings nyckeln för LUIS-kontot för den publicerade LUIS-appen.
Du kan hämta din redigerings nyckel från sidan användar inställningar på Luis-portalen.
{AZURE_REGION} Lämplig Azure-region:

westus – Västra USA
westeurope – Västeuropa
australiaeast – Australien, öst

Information om hur du hämtar det publicerade paketet finns i API-dokumentationen här. Om det har hämtats är svaret en LUIS-paketfil. Spara filen på den lagrings plats som angetts för behållaren för indata-montering.

Exportera det versions bara programmets paket från API

Använd följande REST API metod för att paketera ett LUIS-program som du redan har tränat. Ersätt dina egna lämpliga värden för plats hållarna i API-anropet med hjälp av tabellen under HTTP-specifikationen.

GET /luis/api/v2.0/package/{APP_ID}/versions/{APP_VERSION}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}
Platshållare Värde
{APP_ID} Program-ID för den tränade LUIS-appen.
{APP_VERSION} Program versionen av den tränade LUIS-appen.
{AUTHORING_KEY} Redigerings nyckeln för LUIS-kontot för den publicerade LUIS-appen.
Du kan hämta din redigerings nyckel från sidan användar inställningar på Luis-portalen.
{AZURE_REGION} Lämplig Azure-region:

westus – Västra USA
westeurope – Västeuropa
australiaeast – Australien, öst

Information om hur du hämtar det versions bara paketet finns i API-dokumentationen här. Om det har hämtats är svaret en LUIS-paketfil. Spara filen på den lagrings plats som angetts för behållaren för indata-montering.

Kör behållaren med docker run

Använd kommandot Docker Run för att köra behållaren. Läs om hur du samlar in nödvändiga parametrar för information om hur du hämtar {ENDPOINT_URI} och- {API_KEY} värden.

Exempeldocker run kommandot är tillgängliga.

docker run --rm -it -p 5000:5000 ^
--memory 4g ^
--cpus 2 ^
--mount type=bind,src=c:\input,target=/input ^
--mount type=bind,src=c:\output\,target=/output ^
mcr.microsoft.com/azure-cognitive-services/language/luis ^
Eula=accept ^
Billing={ENDPOINT_URI} ^
ApiKey={API_KEY}
  • I det här exemplet används katalogen utanför C: enheten för att undvika eventuella behörighets konflikter i Windows. Om du behöver använda en speciell katalog som indatalistan kan du behöva ge Docker-tjänstens behörighet.
  • Ändra inte ordningen på argumenten om du inte är bekant med Docker-behållare.
  • Om du använder ett annat operativ system använder du rätt konsol/Terminal, kommandosyntax för montering och linje fortsättnings text för systemet. Dessa exempel förutsätter en Windows-konsol med ett linje fortsättnings steg ^ . Eftersom behållaren är ett Linux-operativsystem använder mål-Mount en syntax för en mappvy i Linux-typ.

Det här kommandot:

  • Kör en behållare från LUIS container image
  • Läser in LUIS-appen från indataports montering vid C:\input, som finns på behållar värden
  • Allokerar två processor kärnor och 4 GB minne
  • Exponerar TCP-port 5000 och allokerar en pseudo-TTY för behållaren
  • Sparar behållaren och LUIS loggar för att mata ut montering vid C:\output, som finns på behållar värden
  • Tar automatiskt bort behållaren när den har avslut ATS. Behållar avbildningen är fortfarande tillgänglig på värddatorn.

Fler exempeldocker run kommandot är tillgängliga.

Viktigt

EulaAlternativen, Billing och ApiKey måste anges för att köra behållaren, annars startar inte behållaren. Mer information finns i fakturering. ApiKey-värdet är nyckeln från sidan Azure-resurser på Luis-portalen och finns också på sidan med Azures Cognitive Services resurs nycklar.

Kör flera behållare på samma värd

Om du tänker köra flera behållare med exponerade portar ska du se till att köra varje behållare med en annan exponerad port. Kör till exempel den första behållaren på port 5000 och den andra behållaren på port 5001.

Du kan ha den här behållaren och en annan Azure Cognitive Services-behållare som körs på värden tillsammans. Du kan också ha flera behållare av samma Cognitive Services-behållare som kör.

Slut punkts-API: er som stöds av behållaren

Både v2-och v3 -versioner av API: et är tillgängliga med behållaren.

Köra frågor mot containerns förutsägelseslutpunkt

Containern innehåller REST-baserade slutpunkts-API:er för frågeförutsägelse. Slut punkter för publicerade appar (mellanlagring eller produktion) har en annan väg än slut punkter för versions program.

Använd värden, http://localhost:5000, för container-API:er.

Pakettyp HTTP-verb Väg Frågeparametrar
Publicerad HÄMTA, PUBLICERA /luis/v3.0/apps/{appId}/slots/{slotName}/predict? query={query}
[&verbose]
[&log]
[&show-all-intents]
Versions HÄMTA, PUBLICERA /luis/v3.0/apps/{appId}/versions/{versionId}/predict? query={query}
[&verbose]
[&log]
[&show-all-intents]

Frågeparametrarna konfigurerar hur och vad som returneras i svaret för frågan:

Frågeparameter Typ Syfte
query sträng Användarens uttryck.
verbose boolean Ett booleskt värde som anger om alla metadata ska returneras för de förväntade modellerna. Standardvärdet är false.
log boolean Loggar frågor som kan användas senare för aktiv inlärning. Standardvärdet är false.
show-all-intents boolean Ett booleskt värde som anger om alla intentor eller den översta bedömnings metoden ska returneras. Standardvärdet är false.

Fråga LUIS-appen

Ett exempel på en spiral-kommando för att skicka frågor till behållaren för en publicerad app är:

Om du vill fråga en modell på en plats använder du följande API:

curl -G \
-d verbose=false \
-d log=true \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/slots/production/predict"

Om du vill göra frågor till mellanlagrings miljön ersätter du production i vägen med staging :

http://localhost:5000/luis/v3.0/apps/{APP_ID}/slots/staging/predict

Om du vill fråga en versions modell använder du följande API:

curl -G \
-d verbose=false \
-d log=false \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/versions/{APP_VERSION}/predict"

Importera slut punkts loggarna för aktiv inlärning

Om en utgående montering har angetts för LUIS-behållaren, sparas i utdatakatalogen, där {INSTANCE_ID} är behållar-ID. Appens fråga logg innehåller frågan, svaret och tidsstämplar för varje förutsägelse fråga som skickats till behållaren LUIS.

Följande plats visar den kapslade katalog strukturen för behållarens loggfiler.

/output/luis/{INSTANCE_ID}/

Välj din app från LUIS-portalen och välj sedan Importera slut punkts loggar för att ladda upp loggarna.

Importera behållarens loggfiler för aktiv inlärning

När loggen har laddats upp granskar du slut punkts yttranden i Luis-portalen.

Verifiera att en behållare körs

Det finns flera sätt att verifiera att behållaren körs. Leta reda på den externa IP- adressen och den exponerade porten för den aktuella behållaren och öppna din favorit webbläsare. Använd de olika URL: erna för begäran nedan för att verifiera att behållaren körs. URL: erna för exempel begär Anden som anges nedan är http://localhost:5000 , men din speciella behållare kan variera. Tänk på att du är beroende av behållarens externa IP -adress och exponerad port.

URL för begäran Syfte
http://localhost:5000/ Containern tillhandahåller en startsida.
http://localhost:5000/ready Begärd med GET, detta ger en verifiering av att behållaren är redo att acceptera en fråga mot modellen. Den här begäran kan användas för Kubernetes Live och beredskaps avsökningar.
http://localhost:5000/status Begärd med GET, kontrollerar detta om den API-nyckel som används för att starta behållaren är giltig utan att orsaka en slut punkts fråga. Den här begäran kan användas för Kubernetes Live och beredskaps avsökningar.
http://localhost:5000/swagger Containern tillhandahåller en fullständig uppsättning dokumentation för slutpunkterna samt en Prova-funktion. Med den här funktionen kan du ange dina inställningar i ett webbaserat HTML-formulär och göra frågan utan att behöva skriva någon kod. När frågan returnerar visas ett exempel på ett spiral kommando som visar de HTTP-rubriker och det text format som krävs.

Behållarens start sida

Stoppa containern

Om du vill stänga av behållaren trycker du på CTRL + C i den kommando rads miljö där behållaren körs.

Felsökning

Om du kör behållaren med en utgående montering och loggning aktive rad genererar behållaren loggfiler som är till hjälp vid fel sökning av problem som inträffar när du startar eller kör behållaren.

Tips

Mer felsöknings information och vägledning finns i Cognitive Services behållare vanliga frågor och svar.

Fakturering

LUIS-behållaren skickar fakturerings information till Azure med hjälp av en Cognitive Services resurs på ditt Azure-konto.

Frågor till behållaren debiteras enligt pris nivån för den Azure-resurs som används för ApiKey .

Azure Cognitive Services-behållare är inte licensierade för att köras utan att vara anslutna till avläsnings-/fakturerings slut punkten. Du måste göra det möjligt för behållarna att kommunicera fakturerings information med fakturerings slut punkten hela tiden. Cognitive Services behållare skickar inte kund information, till exempel den bild eller text som analyseras, till Microsoft.

Anslut till Azure

Containern behöver de fakturerings argument värden som ska köras. Dessa värden tillåter att behållaren ansluter till fakturerings slut punkten. Behållar rapporteringen visar var 10 till 15: e minut. Om behållaren inte ansluter till Azure inom den tillåtna tids perioden fortsätter behållaren att köras men hanterar inte frågor förrän fakturerings slut punkten återställs. Anslutnings försöket görs 10 gånger med samma tidsintervall 10 till 15 minuter. Om den inte kan ansluta till fakturerings slut punkten inom 10 försök slutar behållaren att betjäna begär Anden. Se vanliga frågor och svar om Cognitive Services container för att få ett exempel på den information som skickas till Microsoft för fakturering.

Fakturerings argument

docker run Kommandot startar behållaren när alla tre av följande alternativ finns med giltiga värden :

Alternativ Beskrivning
ApiKey API-nyckeln för den Cognitive Services resurs som används för att spåra fakturerings information.
Värdet för det här alternativet måste anges till en API-nyckel för den etablerade resurs som anges i Billing .
Billing Slut punkten för den Cognitive Services resursen som används för att spåra fakturerings information.
Värdet för det här alternativet måste anges till slut punkts-URI för en etablerad Azure-resurs.
Eula Anger att du har accepterat licensen för behållaren.
Värdet för det här alternativet måste vara inställt på acceptera.

Mer information om dessa alternativ finns i Configure containers.

Sammanfattning

I den här artikeln har du lärt dig begrepp och arbets flöde för att ladda ned, installera och köra Language Understanding-behållare (LUIS). Sammanfattningsvis:

  • Language Understanding (LUIS) innehåller en Linux-behållare för Docker som tillhandahåller slut punkts frågan förutsägelser av yttranden.
  • Behållar avbildningar hämtas från Microsoft Container Registry (MCR).
  • Behållar avbildningar körs i Docker.
  • Du kan använda REST API för att fråga behållarens slut punkter genom att ange behållarens värd-URI.
  • Du måste ange fakturerings information när du instansierar en behållare.

Viktigt

Cognitive Services behållare är inte licensierade att köras utan att vara anslutna till Azure för mätning. Kunderna behöver göra det möjligt för behållarna att kommunicera fakturerings information med mät tjänsten hela tiden. Cognitive Services behållare skickar inte kund information (till exempel den bild eller text som analyseras) till Microsoft.

Nästa steg