Conversational Language Understanding-containers (CLU) installeren en uitvoeren

Notitie

De gegevenslimieten in één synchrone API-aanroep voor de CLU-container zijn 5.120 tekens per document en maximaal 10 documenten per aanroep.

Met containers kunt u de CLU-API hosten op uw eigen infrastructuur. Als u vereisten voor beveiliging of gegevensbeheer hebt die niet kunnen worden voldaan door externe CLU aan te roepen, is het mogelijk dat containers een goede optie zijn.

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Vereisten

U moet voldoen aan de volgende vereisten voordat u CLU-containers gebruikt.

• Als u nog geen Azure-abonnement hebt, maakt u een gratis account.
• Docker geïnstalleerd op een hostcomputer. Docker moet zo worden geconfigureerd dat de containers verbinding kunnen maken met en factureringsgegevens naar Azure kunnen verzenden.
  • In Windows moet Docker ook worden geconfigureerd ter ondersteuning van Linux-containers.
  • U moet basiskennis hebben van Docker-concepten.
• Een taalresource

Vereiste parameters verzamelen

Er zijn drie primaire parameters vereist voor alle Azure AI-containers. De licentievoorwaarden voor Microsoft-software moeten aanwezig zijn met een waarde van accepteren. Er is ook een eindpunt-URI en API-sleutel nodig.

Eindpunt-URI

De {ENDPOINT_URI} waarde is beschikbaar op de overzichtspagina van Azure Portal van de bijbehorende Azure AI-servicesresource. Ga naar de pagina Overzicht, plaats de muisaanwijzer op het eindpunt en er wordt een pictogram Kopiëren naar klembord weergegeven. Kopieer en gebruik waar nodig het eindpunt.

Toetsen

De {API_KEY} waarde wordt gebruikt om de container te starten en is beschikbaar op de pagina Sleutels van azure Portal van de bijbehorende Azure AI-servicesresource. Ga naar de pagina Sleutels en selecteer het pictogram Kopiëren naar klembord.

Belangrijk

Deze abonnementssleutels worden gebruikt voor toegang tot uw Azure AI-services-API. Deel je sleutels niet. Bewaar ze veilig. Gebruik bijvoorbeeld Azure Key Vault. We raden u ook aan deze sleutels regelmatig opnieuw te genereren. Er is slechts één sleutel nodig om een API-aanroep te maken. Wanneer u de eerste sleutel opnieuw genereert, kunt u de tweede sleutel gebruiken voor continue toegang tot de service.

Vereisten en aanbevelingen voor hostcomputers

De host is een x64-computer waarop de Docker-container wordt uitgevoerd. Het kan een computer op uw locatie of een Docker-hostingservice in Azure zijn, zoals:

• Azure Kubernetes Service.
• Azure Container Instances.
• Een Kubernetes-cluster dat is geïmplementeerd in Azure Stack. Zie Kubernetes implementeren in Azure Stack voor meer informatie.

In de volgende tabel worden de minimale en aanbevolen specificaties voor de beschikbare container beschreven. Elke CPU-kern moet ten minste 2,6 gigahertz (GHz) of sneller zijn.

Het is raadzaam om een CPU met AVX-512-instructieset te hebben voor de beste ervaring (prestaties en nauwkeurigheid).

	Minimale hostspecificaties	Aanbevolen hostspecificaties
CLU	1 kern, 2 GB geheugen	4 kernen, 8 GB geheugen

DE CPU-kern en het geheugen komen overeen met de --cpus en --memory instellingen, die worden gebruikt als onderdeel van de docker run opdracht.

Uw Conversational Language Understanding-model exporteren

Voordat u verdergaat met het uitvoeren van de Docker-installatiekopieën, moet u uw eigen getrainde model exporteren om het beschikbaar te maken voor uw container. Gebruik de volgende opdracht om uw model te extraheren en de onderstaande tijdelijke aanduidingen te vervangen door uw eigen waarden:

Tijdelijke aanduiding	Weergegeven als	Opmaak of voorbeeld
{API_KEY}	De sleutel voor uw taalresource. U vindt deze op de pagina Sleutel en eindpunt van uw resource, in Azure Portal.	xxxxxxxxxxx
{ENDPOINT_URI}	Het eindpunt voor toegang tot de Conversational Language Understanding-API. U vindt deze op de pagina Sleutel en eindpunt van uw resource, in Azure Portal.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT_NAME}	De naam van het project met het model dat u wilt exporteren. U vindt deze op het tabblad Projecten in de Language Studio-portal.	myProject
{TRAINED_MODEL_NAME}	De naam van het getrainde model dat u wilt exporteren. U vindt uw getrainde modellen op het tabblad Modelevaluatie onder uw project in de Language Studio-portal	myTrainedModel
{EXPORTED_MODEL_NAME}	De naam die moet worden toegewezen voor het nieuwe geëxporteerde model dat is gemaakt.	myExportedModel

curl --location --request PUT '{ENDPOINT_URI}/language/authoring/analyze-conversations/projects/{PROJECT_NAME}/exported-models/{EXPORTED_MODEL_NAME}?api-version=2024-11-15-preview' \ 
--header 'Ocp-Apim-Subscription-Key: {API_KEY}' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
    "TrainedModelLabel": "{TRAINED_MODEL_NAME}" 
}' 

De containerinstallatiekopieën ophalen met docker pull

De CLU-containerinstallatiekopie vindt u in het mcr.microsoft.com containerregistersyndicaat. Deze bevindt zich in de azure-cognitive-services/language/ opslagplaats en heeft de naam clu. De volledig gekwalificeerde naam van de containerinstallatiekopieën is, mcr.microsoft.com/azure-cognitive-services/language/clu

Als u de nieuwste versie van de container wilt gebruiken, kunt u de latest tag gebruiken, die voor engels is. U vindt ook een volledige lijst met containers voor ondersteunde talen met behulp van de tags op de MCR.

De nieuwste CLU-container is beschikbaar in verschillende talen. Gebruik de onderstaande opdracht om de container voor de Engelse container te downloaden.

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

Tip

U kunt de opdracht docker-installatiekopieën gebruiken om uw gedownloade containerinstallatiekopieën weer te geven. De volgende opdracht bevat bijvoorbeeld de id, opslagplaats en tag van elke gedownloade containerinstallatiekopieën, opgemaakt als een tabel:

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

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

De container uitvoeren in de downloadmodelmodus

Nadat het geëxporteerde model in de bovenstaande sectie is gemaakt, moeten gebruikers de container uitvoeren om het implementatiepakket te downloaden dat speciaal is gemaakt voor hun geëxporteerde modellen.

Tijdelijke aanduiding	Weergegeven als	Opmaak of voorbeeld
{API_KEY}	De sleutel voor uw taalresource. U vindt deze op de pagina Sleutel en eindpunt van uw resource, in Azure Portal.	xxxxxx
{ENDPOINT_URI}	Het eindpunt voor toegang tot de API. U vindt deze op de pagina Sleutel en eindpunt van uw resource, in Azure Portal.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{IMAGE_TAG}	De afbeeldingstag die de taal vertegenwoordigt van de container die u wilt uitvoeren. Zorg ervoor dat deze overeenkomt met de docker pull opdracht die u hebt gebruikt.	laatst
{LOCAL_CLU_PORT}	Poortnummer dat is toegewezen voor de container op de lokale computer.	5000
{LOCAL_MODEL_DIRECTORY}	Absolute map op hostcomputer waarin geëxporteerde modellen worden opgeslagen.	C:\usr\local\myDeploymentPackage
{PROJECT_NAME}	Naam van het project waartoe het geëxporteerde model behoort	myProject
{EXPORTED_MODEL_NAME}	Geëxporteerd model dat moet worden gedownload	myExportedModel

docker run --rm -it -p {LOCAL_CLU_PORT}:80 \ 
mcr.microsoft.com/azure-cognitive-services/language/clu:{IMAGE_TAG} \   
-v {LOCAL_MODEL_DIRECTORY}:/DeploymentPackage \ 
Billing={ENDPOINT_URI} \   
ApiKey={API_KEY} \ 
downloadmodel \ 
projectName={PROJECT_NAME} \ 
exportedModelName={EXPORTED_MODEL_NAME} 

Wijzig de gedownloade bestanden NIET. Zelfs het wijzigen van de naam of mapstructuur kan van invloed zijn op de integriteit van de container en kan deze verstoren.

Herhaal deze stappen om zoveel modellen te downloaden als u wilt testen. Ze kunnen deel uitmaken van verschillende projecten en verschillende geëxporteerde modelnamen hebben.

De container uitvoeren met docker run

Zodra de container zich op de hostcomputer bevindt, gebruikt u de opdracht docker run om de containers uit te voeren. De container blijft actief totdat u deze stopt. Vervang de onderstaande tijdelijke aanduidingen door uw eigen waarden:

Belangrijk

• De docker-opdrachten in de volgende secties gebruiken de back-slash, \als een regelvervolgteken. Vervang of verwijder deze op basis van de vereisten van uw hostbesturingssysteem.
• De Eula, Billingen ApiKey opties moeten worden opgegeven om de container uit te voeren. Anders wordt de container niet gestart. Zie Facturering voor meer informatie.

Voer de volgende docker run opdracht uit om de CLU-container uit te voeren. Vervang de onderstaande tijdelijke aanduidingen door uw eigen waarden:

Tijdelijke aanduiding	Weergegeven als	Opmaak of voorbeeld
{API_KEY}	De sleutel voor uw taalresource. U vindt deze op de pagina Sleutel en eindpunt van uw resource, in Azure Portal.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI}	Het eindpunt voor toegang tot de API. U vindt deze op de pagina Sleutel en eindpunt van uw resource, in Azure Portal.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{IMAGE_TAG}	De afbeeldingstag die de taal vertegenwoordigt van de container die u wilt uitvoeren. Zorg ervoor dat deze overeenkomt met de docker pull opdracht die u hebt gebruikt.	latest
{LOCAL_CLU_PORT}	Poortnummer dat is toegewezen voor de container op de lokale computer.	5000
{LOCAL_NER_PORT}	Poortnummer van de NER-container. Zie de sectie NER-container uitvoeren hieronder.	5001 (moet afwijken van het bovenstaande poortnummer)
{LOCAL_LOGGING_DIRECTORY}	Absolute map op hostcomputer waarin die logboeken worden opgeslagen.	C:\usr\local\mylogs
{LOCAL_MODEL_DIRECTORY}	Absolute map op hostcomputer waarin geëxporteerde modellen worden opgeslagen.	C:\usr\local\myDeploymentPackage

docker run --rm -it -p 5000:5000 --memory 8g --cpus 1 \
mcr.microsoft.com/azure-cognitive-services/language/clu:{IMAGE_TAG} \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

Met deze opdracht gebeurt het volgende:

• Voert een CLU-container uit vanuit de containerinstallatiekopie
• Wijst één CPU-kern en 8 gigabyte (GB) geheugen toe
• Maakt TCP-poort 5000 beschikbaar en wijst een pseudo-TTY toe voor de container
• Hiermee wordt de container automatisch verwijderd nadat deze is afgesloten. De containerinstallatiekopie is nog steeds beschikbaar op de hostcomputer.

Meerdere containers op dezelfde host uitvoeren

Als u van plan bent om meerdere containers met blootgestelde poorten uit te voeren, moet u ervoor zorgen dat u elke container uitvoert met een andere weergegeven poort. Voer bijvoorbeeld de eerste container uit op poort 5000 en de tweede container op poort 5001.

U kunt deze container en een andere Azure AI-servicescontainer laten uitvoeren op de HOST. U kunt ook meerdere containers van dezelfde Azure AI-servicescontainer uitvoeren.

NER-container uitvoeren

CLU is afhankelijk van NER om vooraf gemaakte entiteiten te verwerken. De CLU-container werkt goed zonder NER als gebruikers besluiten deze niet te integreren. NER-facturering is uitgeschakeld wanneer deze wordt gebruikt via CLU, er worden geen extra kosten gegenereerd, tenzij er rechtstreeks een aanroep naar de container van NER wordt gedaan.

NER instellen in CLU-container

• Volg de documentatie van de NER-container.
• Wanneer u CLU-container uitvoert, moet u de parameter Ner_Url zo instellen dat Ner_Url=http://host.docker.internal:{LOCAL_NER_PORT}

Een query uitvoeren op het voorspellingseindpunt van de container

De container bevat op REST gebaseerde eindpunt-API's voor queryvoorspelling.

Gebruik de host, http://localhost:5000, voor container-API's.

Controleren of een container wordt uitgevoerd

Er zijn verschillende manieren om te controleren of de container wordt uitgevoerd. Zoek het externe IP-adres en de weergegeven poort van de betreffende container en open uw favoriete webbrowser. Gebruik de verschillende aanvraag-URL's die volgen om te controleren of de container wordt uitgevoerd. De hier vermelde voorbeeldaanvraag-URL's zijn http://localhost:5000, maar uw specifieke container kan variëren. Zorg ervoor dat u vertrouwt op het externe IP-adres van uw container en de weergegeven poort.

Aanvraag-URL	Doel
http://localhost:5000/	De container bevat een startpagina.
http://localhost:5000/ready	Aangevraagd met GET biedt deze URL een verificatie dat de container gereed is voor het accepteren van een query voor het model. Deze aanvraag kan worden gebruikt voor Kubernetes-liveness - en gereedheidstests.
http://localhost:5000/status	Deze URL wordt ook aangevraagd met GET en controleert of de API-sleutel die wordt gebruikt om de container te starten, geldig is zonder een eindpuntquery te veroorzaken. Deze aanvraag kan worden gebruikt voor Kubernetes-liveness - en gereedheidstests.
http://localhost:5000/swagger	De container bevat een volledige set met documentatie voor de eindpunten en een functie Uitproberen. Met deze functie kunt u uw instellingen invoeren in een HTML-webformulier en de query maken zonder dat u code hoeft te schrijven. Nadat de query is geretourneerd, wordt er een voorbeeld van een CURL-opdracht gegeven om de HTTP-headers en de hoofdtekstindeling te demonstreren die vereist is.

Zie onze gids voor meer informatie over hoe u CLU belt.

De container uitvoeren die is losgekoppeld van internet

Als u deze container wilt gebruiken die is losgekoppeld van internet, moet u eerst toegang aanvragen door een toepassing in te vullen en een toezeggingsplan aan te schaffen. Zie Docker-containers gebruiken in niet-verbonden omgevingen voor meer informatie.

Als u bent goedgekeurd om de container uit te voeren die is losgekoppeld van internet, ziet u in het volgende voorbeeld de opmaak van de docker run opdracht die u gaat gebruiken, met tijdelijke aanduidingen. Vervang deze tijdelijke aanduidingen door uw eigen waarden.

Met DownloadLicense=True de parameter in uw docker run opdracht wordt een licentiebestand gedownload waarmee uw Docker-container kan worden uitgevoerd wanneer deze niet is verbonden met internet. Het bevat ook een vervaldatum, waarna het licentiebestand ongeldig is om de container uit te voeren. U kunt alleen een licentiebestand gebruiken met de juiste container waarvoor u bent goedgekeurd. U kunt bijvoorbeeld geen licentiebestand gebruiken voor een spraak-naar-tekstcontainer met een Document Intelligence-container.

Tijdelijke aanduiding	Weergegeven als	Opmaak of voorbeeld
{IMAGE}	De containerinstallatiekopieën die u wilt gebruiken.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{LICENSE_MOUNT}	Het pad waar de licentie wordt gedownload en gekoppeld.	/host/license:/path/to/license/directory
{ENDPOINT_URI}	Het eindpunt voor het verifiëren van uw serviceaanvraag. U vindt deze op de pagina Sleutel en eindpunt van uw resource, in Azure Portal.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{API_KEY}	De sleutel voor uw Text Analytics-resource. U vindt deze op de pagina Sleutel en eindpunt van uw resource, in Azure Portal.	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{CONTAINER_LICENSE_DIRECTORY}	Locatie van de licentiemap in het lokale bestandssysteem van de container.	/path/to/license/directory

docker run --rm -it -p 5000:5000 \ 
-v {LICENSE_MOUNT} \
{IMAGE} \
eula=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY} 

Zodra het licentiebestand is gedownload, kunt u de container uitvoeren in een niet-verbonden omgeving. In het volgende voorbeeld ziet u de opmaak van de docker run opdracht die u gaat gebruiken, met tijdelijke aanduidingen. Vervang deze tijdelijke aanduidingen door uw eigen waarden.

Waar de container ook wordt uitgevoerd, moet het licentiebestand worden gekoppeld aan de container en moet de locatie van de licentiemap in het lokale bestandssysteem van de container worden opgegeven met Mounts:License=. Er moet ook een uitvoerkoppeling worden opgegeven, zodat factureringsgebruiksrecords kunnen worden geschreven.

Tijdelijke aanduiding	Weergegeven als	Opmaak of voorbeeld
{IMAGE}	De containerinstallatiekopieën die u wilt gebruiken.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{MEMORY_SIZE}	De juiste grootte van het geheugen dat moet worden toegewezen voor uw container.	4g
{NUMBER_CPUS}	Het juiste aantal CPU's dat moet worden toegewezen voor uw container.	4
{LICENSE_MOUNT}	Het pad waar de licentie zich bevindt en wordt gekoppeld.	/host/license:/path/to/license/directory
{OUTPUT_PATH}	Het uitvoerpad voor het vastleggen van gebruiksrecords.	/host/output:/path/to/output/directory
{CONTAINER_LICENSE_DIRECTORY}	Locatie van de licentiemap in het lokale bestandssysteem van de container.	/path/to/license/directory
{CONTAINER_OUTPUT_DIRECTORY}	Locatie van de uitvoermap in het lokale bestandssysteem van de container.	/path/to/output/directory

docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \ 
-v {LICENSE_MOUNT} \ 
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}

De container stoppen

Als u de container wilt afsluiten, selecteert u Ctrl+C in de opdrachtregelomgeving waarin de container wordt uitgevoerd.

Probleemoplossing

Als u de container uitvoert waarvoor uitvoerkoppeling en logboekregistratie zijn ingeschakeld, genereert de container logboekbestanden die handig zijn om problemen op te lossen die optreden tijdens het starten of uitvoeren van de container.

Tip

Zie veelgestelde vragen over Azure AI-containers voor meer informatie en richtlijnen voor probleemoplossing.

Billing

De CLU-containers verzenden factureringsgegevens naar Azure met behulp van een taalresource in uw Azure-account.

Query's naar de container worden gefactureerd in de prijscategorie van de Azure-resource die wordt gebruikt voor de ApiKey parameter.

Azure AI-servicescontainers hebben geen licentie om te worden uitgevoerd zonder verbinding te maken met het meter- of factureringseindpunt. U moet de containers inschakelen om factureringsgegevens te communiceren met het factureringseindpunt. Azure AI-servicescontainers verzenden geen klantgegevens, zoals de afbeelding of tekst die wordt geanalyseerd, naar Microsoft.

Verbinding maken met Azure

De container moet de waarden voor factureringsargumenten uitvoeren. Met deze waarden kan de container verbinding maken met het factureringseindpunt. De container rapporteert ongeveer om de 10 tot 15 minuten het gebruik. Als de container niet binnen het toegestane tijdvenster verbinding maakt met Azure, blijft de container actief, maar voert deze geen query's uit totdat het factureringseindpunt is hersteld. De verbinding wordt 10 keer geprobeerd met hetzelfde tijdsinterval van 10 tot 15 minuten. Als er geen verbinding kan worden gemaakt met het factureringseindpunt binnen de 10 pogingen, stopt de container met het verwerken van aanvragen. Zie de veelgestelde vragen over de Azure AI-servicescontainer voor een voorbeeld van de informatie die naar Microsoft is verzonden voor facturering.

Factureringsargumenten

Met docker run de opdracht wordt de container gestart wanneer alle drie de volgende opties geldige waarden bevatten:

Optie	Omschrijving
ApiKey	De API-sleutel van de Azure AI-servicesresource die wordt gebruikt om factureringsgegevens bij te houden. De waarde van deze optie moet worden ingesteld op een API-sleutel voor de ingerichte resource die is opgegeven in Billing.
Billing	Het eindpunt van de Azure AI-servicesresource die wordt gebruikt om factureringsgegevens bij te houden. De waarde van deze optie moet worden ingesteld op de eindpunt-URI van een ingerichte Azure-resource.
Eula	Geeft aan dat u de licentie voor de container hebt geaccepteerd. De waarde van deze optie moet worden ingesteld op accepteren.

Zie Containers configureren voor meer informatie over deze opties.

Samenvatting

In dit artikel hebt u concepten en werkstroom geleerd voor het downloaden, installeren en uitvoeren van CLU-containers. Samengevat:

• CLU biedt Linux-containers voor Docker
• Containerinstallatiekopieën worden gedownload vanuit het Microsoft Container Registry (MCR).
• Containerinstallatiekopieën worden uitgevoerd in Docker.
• U moet factureringsgegevens opgeven bij het instantiëren van een container.

Belangrijk

Azure AI-containers hebben geen licentie om te worden uitgevoerd zonder verbinding te maken met Azure voor meting. Klanten moeten ervoor zorgen dat de containers altijd factureringsgegevens kunnen communiceren met de meterservice. Azure AI-containers verzenden geen klantgegevens (bijvoorbeeld tekst die wordt geanalyseerd) naar Microsoft.

Volgende stappen

• Zie Containers configureren voor configuratie-instellingen.