Aan de slag met multimodal vision-chat-apps met behulp van Azure OpenAI

In dit artikel leest u hoe u multimodale Modellen van Azure OpenAI gebruikt om antwoorden te genereren op gebruikersberichten en geüploade afbeeldingen in een chat-app. Dit voorbeeld van een chat-app bevat ook alle infrastructuur en configuratie die nodig zijn voor het inrichten van Azure OpenAI-resources en het implementeren van de app in Azure Container Apps met behulp van de Azure Developer CLI.

Door de instructies in dit artikel te volgen, gaat u het volgende doen:

• Implementeer een Azure Container-chat-app die gebruikmaakt van beheerde identiteit voor verificatie.
• Upload afbeeldingen die moeten worden gebruikt als onderdeel van de chatstream.
• Chat met een Multimodal Large Language Model (LLM) van Azure OpenAI met behulp van de OpenAI-bibliotheek.

Zodra u dit artikel hebt voltooid, kunt u beginnen met het wijzigen van het nieuwe project met uw aangepaste code.

Architectuuroverzicht

In het volgende diagram ziet u een eenvoudige architectuur van de chat-app:

De chat-app wordt uitgevoerd als een Azure Container App. De app maakt gebruik van een beheerde identiteit via Microsoft Entra ID voor verificatie met Azure OpenAI in productie, in plaats van een API-sleutel. Tijdens de ontwikkeling ondersteunt de app meerdere verificatiemethoden, waaronder Azure Developer CLI-referenties, API-sleutels en GitHub-modellen voor testen zonder Azure-resources.

De toepassingsarchitectuur is afhankelijk van de volgende services en onderdelen:

• Azure OpenAI vertegenwoordigt de AI-provider waarnaar we de query's van de gebruiker verzenden.
• Azure Container Apps is de containeromgeving waar de toepassing wordt gehost.
• Managed Identity helpt ons om beveiliging van de beste klasse te garanderen en elimineert de vereiste voor u als ontwikkelaar om een geheim veilig te beheren.
• Bicep-bestanden voor het inrichten van Azure-resources, waaronder Azure OpenAI, Azure Container Apps, Azure Container Registry, Azure Log Analytics en RBAC-rollen (op rollen gebaseerd toegangsbeheer).
• Microsoft AI Chat Protocol biedt gestandaardiseerde API-contracten voor AI-oplossingen en -talen. De chat-app voldoet aan het Microsoft AI Chat Protocol.
• Een Python Quart dat het openai pakket gebruikt om antwoorden te genereren op gebruikersberichten met geüploade afbeeldingsbestanden.
• Een eenvoudige HTML-/JavaScript-front-end die reacties van de back-end streamt met behulp van JSON-lijnen via een ReadableStream.

Kosten

In een poging om prijzen zo laag mogelijk te houden in dit voorbeeld, gebruiken de meeste resources een prijscategorie basis- of verbruiksprijzen. Wijzig het niveau van uw laag indien nodig op basis van het beoogde gebruik. Als u wilt stoppen met het maken van kosten, verwijdert u de resources wanneer u klaar bent met het artikel.

Meer informatie over kosten in de voorbeeldopslagplaats.

Vereisten

Er is een ontwikkelcontaineromgeving beschikbaar met alle afhankelijkheden die nodig zijn om dit artikel te voltooien. U kunt de ontwikkelcontainer uitvoeren in GitHub Codespaces (in een browser) of lokaal met behulp van Visual Studio Code.

Als u dit artikel wilt gebruiken, moet u voldoen aan de volgende vereisten:

Open ontwikkelomgeving

Gebruik de volgende instructies om een vooraf geconfigureerde ontwikkelomgeving met alle vereiste afhankelijkheden te implementeren om dit artikel te voltooien.

Implementeren en uitvoeren

De voorbeeldopslagplaats bevat alle code- en configuratiebestanden voor de Azure-implementatie van de chat-app. Met de volgende stappen doorloopt u het azure-implementatieproces van de voorbeeldchat-app.

Chat-app implementeren in Azure

1. Voer de volgende Azure Developer CLI-opdracht uit voor het inrichten van Azure-resources en de implementatie van broncode:

   azd up
   

2. Gebruik de volgende tabel om de prompts te beantwoorden:

   Prompt	Antwoord
   Omgevingsnaam	Houd het kort en kleine letters. Voeg uw naam of alias toe. Bijvoorbeeld: chat-vision. Deze wordt gebruikt als onderdeel van de naam van de resourcegroep.
   Abonnement	Selecteer het abonnement waarin u de resources wilt maken.
   Locatie (voor hosting)	Selecteer een locatie bij u in de buurt in de lijst.
   Locatie voor het Azure OpenAI-model	Selecteer een locatie bij u in de buurt in de lijst. Als dezelfde locatie beschikbaar is als uw eerste locatie, selecteert u die.

3. Wacht totdat de app is geïmplementeerd. De implementatie duurt meestal tussen 5 en 10 minuten.

Chat-app gebruiken om vragen te stellen aan het grote taalmodel

1. In de terminal wordt een URL weergegeven na een geslaagde implementatie van de toepassing.

2. Selecteer die URL die is gelabeld Deploying service web om de chattoepassing in een browser te openen.

   

3. Upload een afbeelding in de browser door op Bestand kiezen te klikken en een afbeelding te selecteren.

4. Stel een vraag over de geüploade afbeelding, zoals 'Waar gaat de afbeelding over?'.

5. Het antwoord is afkomstig van Azure OpenAI en het resultaat wordt weergegeven.

De voorbeeldcode verkennen

Hoewel OpenAI en Azure OpenAI Service afhankelijk zijn van een algemene Python-clientbibliotheek, zijn kleine codewijzigingen nodig bij het gebruik van Azure OpenAI-eindpunten. In dit voorbeeld wordt gebruikgemaakt van een multimodale Azure OpenAI-model voor het genereren van antwoorden op gebruikersberichten en geüploade afbeeldingen.

Base64-codering van de geüploade afbeelding in de front-end

De geüploade afbeelding moet Base64 worden gecodeerd, zodat deze rechtstreeks als gegevens-URI kan worden gebruikt als onderdeel van het bericht.

In het voorbeeld verwerkt het volgende front-endcodefragment in de scripttag van het src/quartapp/templates/index.html bestand die functionaliteit. De toBase64 pijlfunctie gebruikt de readAsDataURL methode van deFileReader om asynchroon te lezen in het geüploade afbeeldingsbestand als een met base64 gecodeerde tekenreeks.

    const toBase64 = file => new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.readAsDataURL(file);
        reader.onload = () => resolve(reader.result);
        reader.onerror = reject;
    });

De toBase64 functie wordt aangeroepen door een listener in de gebeurtenis van submit het formulier.

De submit event handler verwerkt de volledige chats-interactiestroom. Wanneer de gebruiker een bericht verzendt, vindt de volgende stroom plaats:

1. Hiermee wordt het element 'no-messages-heading' verborgen om aan te geven dat het gesprek is begonnen.
2. Hiermee wordt het geüploade afbeeldingsbestand opgehaald en base64 gecodeerd (indien aanwezig)
3. Maakt en geeft het bericht van de gebruiker weer in de chat, inclusief de geüploade afbeelding
4. Bereidt een berichtencontainer voor een assistent voor met een "Typen..." indicator.
5. Het bericht van de gebruiker toevoegen aan de matrix met berichtgeschiedenis
6. Roept de methode van getStreamedCompletion() de AI Chat Protocol-client aan met de berichtgeschiedenis en context (inclusief de met Base64 gecodeerde afbeelding en bestandsnaam)
7. Verwerkt de gestreamde antwoordsegmenten en converteert Markdown naar HTML met behulp van Showdown.js
8. Verwerkt eventuele fouten tijdens het streamen
9. Hiermee voegt u een knop spraakuitvoer toe nadat het volledige antwoord is ontvangen, zodat gebruikers het antwoord kunnen horen
10. Hiermee wis je het invoerveld en herstelt de focus voor het volgende bericht.

form.addEventListener("submit", async function(e) {
    e.preventDefault();

    // Hide the no-messages-heading when a message is added
    document.getElementById("no-messages-heading").style.display = "none";

    const file = document.getElementById("file").files[0];
    const fileData = file ? await toBase64(file) : null;

    const message = messageInput.value;

    const userTemplateClone = userTemplate.content.cloneNode(true);
    userTemplateClone.querySelector(".message-content").innerText = message;
    if (file) {
        const img = document.createElement("img");
        img.src = fileData;
        userTemplateClone.querySelector(".message-file").appendChild(img);
    }
    targetContainer.appendChild(userTemplateClone);

    const assistantTemplateClone = assistantTemplate.content.cloneNode(true);
    let messageDiv = assistantTemplateClone.querySelector(".message-content");
    targetContainer.appendChild(assistantTemplateClone);

    messages.push({
        "role": "user",
        "content": message
    });

    try {
        messageDiv.scrollIntoView();
        const result = await client.getStreamedCompletion(messages, {
            context: {
                file: fileData,
                file_name: file ? file.name : null
            }
        });

        let answer = "";
        for await (const response of result) {
            if (!response.delta) {
                continue;
            }
            if (response.delta.content) {
                // Clear out the DIV if its the first answer chunk we've received
                if (answer == "") {
                    messageDiv.innerHTML = "";
                }
                answer += response.delta.content;
                messageDiv.innerHTML = converter.makeHtml(answer);
                messageDiv.scrollIntoView();
            }
            if (response.error) {
                messageDiv.innerHTML = "Error: " + response.error;
            }
        }
        messages.push({
            "role": "assistant",
            "content": answer
        });

        messageInput.value = "";

        const speechOutput = document.createElement("speech-output-button");
        speechOutput.setAttribute("text", answer);
        messageDiv.appendChild(speechOutput);
        messageInput.focus();
    } catch (error) {
        messageDiv.innerHTML = "Error: " + error;
    }
});

De installatiekopieën verwerken met de back-end

In het src\quartapp\chat.py bestand wordt de back-endcode voor het verwerken van afbeeldingen gestart na het configureren van sleutelloze verificatie.

Verificatieconfiguratie

De configure_openai() functie stelt de OpenAI-client in voordat de app aanvragen gaat verwerken. Het maakt gebruik van de decorator van @bp.before_app_serving Quart om verificatie te configureren op basis van omgevingsvariabelen. Met dit flexibele systeem kunnen ontwikkelaars in verschillende contexten werken zonder code te wijzigen.

Uitleg van verificatiemodi

• Lokale ontwikkeling (OPENAI_HOST=local): Maakt verbinding met een lokale OpenAI-compatibele API-service (zoals Ollama of LocalAI) zonder verificatie. Gebruik deze modus voor het testen zonder internet- of API-kosten.
• GitHub-modellen (OPENAI_HOST=github): Maakt gebruik van de AI-modelmarktplaats van GitHub met een GITHUB_TOKEN voor verificatie. Wanneer u GitHub-modellen gebruikt, moet u de modelnaam vooraf laten gaan door openai/ (bijvoorbeeld openai/gpt-4o). Met deze modus kunnen ontwikkelaars modellen proberen voordat ze Azure-resources inrichten.
• Azure OpenAI met API-sleutel (AZURE_OPENAI_KEY_FOR_CHATVISION omgevingsvariabele): maakt gebruik van een API-sleutel voor verificatie. Vermijd deze modus in productie omdat API-sleutels handmatige rotatie vereisen en beveiligingsrisico's vormen als ze worden blootgesteld. Gebruik deze voor lokale tests in een Docker-container zonder Azure CLI-referenties.
• Productie met beheerde identiteit (RUNNING_IN_PRODUCTION=true): maakt gebruik ManagedIdentityCredential van verificatie met Azure OpenAI via de beheerde identiteit van de container-app. Deze methode wordt aanbevolen voor productie omdat hiermee de noodzaak voor het beheren van geheimen wordt verwijderd. Azure Container Apps biedt automatisch de beheerde identiteit en verleent machtigingen tijdens de implementatie via Bicep.
• Ontwikkeling met Azure CLI (standaardmodus): maakt gebruik AzureDeveloperCliCredential van verificatie met Azure OpenAI met behulp van lokaal aangemelde Azure CLI-referenties. Deze modus vereenvoudigt lokale ontwikkeling zonder API-sleutels te beheren.

Belangrijke implementatiedetails

• De get_bearer_token_provider() functie vernieuwt Azure-referenties en gebruikt deze als bearer-tokens.
• Het Azure OpenAI-eindpuntpad omvat /openai/v1/ om te voldoen aan de vereisten van de OpenAI-clientbibliotheek.
• In logboekregistratie ziet u welke verificatiemodus actief is.
• De functie is asynchroon ter ondersteuning van Azure-referentiebewerkingen.

Hier volgt de volledige verificatie-instellingscode van chat.py:

@bp.before_app_serving
async def configure_openai():
    bp.model_name = os.getenv("OPENAI_MODEL", "gpt-4o")
    openai_host = os.getenv("OPENAI_HOST", "github")

    if openai_host == "local":
        bp.openai_client = AsyncOpenAI(api_key="no-key-required", base_url=os.getenv("LOCAL_OPENAI_ENDPOINT"))
        current_app.logger.info("Using local OpenAI-compatible API service with no key")
    elif openai_host == "github":
        bp.model_name = f"openai/{bp.model_name}"
        bp.openai_client = AsyncOpenAI(
            api_key=os.environ["GITHUB_TOKEN"],
            base_url="https://models.github.ai/inference",
        )
        current_app.logger.info("Using GitHub models with GITHUB_TOKEN as key")
    elif os.getenv("AZURE_OPENAI_KEY_FOR_CHATVISION"):
        bp.openai_client = AsyncOpenAI(
            base_url=os.environ["AZURE_OPENAI_ENDPOINT"],
            api_key=os.getenv("AZURE_OPENAI_KEY_FOR_CHATVISION"),
        )
        current_app.logger.info("Using Azure OpenAI with key")
    elif os.getenv("RUNNING_IN_PRODUCTION"):
        client_id = os.environ["AZURE_CLIENT_ID"]
        azure_credential = ManagedIdentityCredential(client_id=client_id)
        token_provider = get_bearer_token_provider(azure_credential, "https://cognitiveservices.azure.com/.default")
        bp.openai_client = AsyncOpenAI(
            base_url=os.environ["AZURE_OPENAI_ENDPOINT"] + "/openai/v1/",
            api_key=token_provider,
        )
        current_app.logger.info("Using Azure OpenAI with managed identity credential for client ID %s", client_id)
    else:
        tenant_id = os.environ["AZURE_TENANT_ID"]
        azure_credential = AzureDeveloperCliCredential(tenant_id=tenant_id)
        token_provider = get_bearer_token_provider(azure_credential, "https://cognitiveservices.azure.com/.default")
        bp.openai_client = AsyncOpenAI(
            base_url=os.environ["AZURE_OPENAI_ENDPOINT"] + "/openai/v1/",
            api_key=token_provider,
        )
        current_app.logger.info("Using Azure OpenAI with az CLI credential for tenant ID: %s", tenant_id)

Chathandler, functie

De chat_handler() functie verwerkt chataanvragen die naar het /chat/stream eindpunt worden verzonden. Het ontvangt een POST-verzoek met een JSON-payload die het Microsoft AI Chat Protocol volgt.

De JSON-nettolading bevat:

• berichten: Een lijst met gespreksgeschiedenis. Elk bericht heeft een role ('gebruiker' of 'assistent') en content (de berichttekst).
• context: Extra gegevens voor verwerking, waaronder:
  • bestand: Met Base64 gecodeerde afbeeldingsgegevens (bijvoorbeeld data:image/png;base64,...).
  • file_name: de oorspronkelijke bestandsnaam van de geüploade afbeelding (handig voor het vastleggen of identificeren van het afbeeldingstype).
• temperatuur (optioneel): een float die de willekeurigheid van reacties regelt (standaard is 0,5).

De handler extraheert de berichtgeschiedenis en afbeeldingsgegevens. Als er geen afbeelding wordt geüpload, is nullde waarde van de afbeelding en de code verwerkt dit geval.

@bp.post("/chat/stream")
async def chat_handler():
    request_json = await request.get_json()
    request_messages = request_json["messages"]
    # Get the base64 encoded image from the request context
    # This will be None if no image was uploaded
    image = request_json["context"]["file"]
    # The context also includes the filename for reference
    # file_name = request_json["context"]["file_name"]

De berichtmatrix bouwen voor vision-aanvragen

De response_stream() functie bereidt de berichtmatrix voor die wordt verzonden naar de Azure OpenAI-API. De @stream_with_context decorator houdt de aanvraagcontext bij terwijl het antwoord wordt gestreamd.

Berichtvoorbereidingslogica

1. Begin met gespreksgeschiedenis: De functie begint met all_messages, met daarin een systeembericht en alle vorige berichten, met uitzondering van de meest recente (request_messages[0:-1]).
2. Het huidige gebruikersbericht verwerken op basis van aanwezigheid van afbeeldingen:
   • Met afbeelding: Maak het bericht van de gebruiker op als een matrix met meerdere onderdelen met tekst en image_url objecten. Het image_url object bevat de met Base64 gecodeerde afbeeldingsgegevens en een detail parameter.
   • Zonder afbeelding: voeg het bericht van de gebruiker toe als tekst zonder opmaak.
3. De detail parameter: Stel in op 'auto' om het model te laten kiezen tussen 'low' en 'high' detail op basis van de afbeeldingsgrootte. Lage details zijn sneller en goedkoper, terwijl hoge details een nauwkeurigere analyse bieden voor complexe afbeeldingen.

    @stream_with_context
    async def response_stream():
        # This sends all messages, so API request may exceed token limits
        all_messages = [
            {"role": "system", "content": "You are a helpful assistant."},
        ] + request_messages[0:-1]
        all_messages = request_messages[0:-1]
        if image:
            user_content = []
            user_content.append({"text": request_messages[-1]["content"], "type": "text"})
            user_content.append({"image_url": {"url": image, "detail": "auto"}, "type": "image_url"})
            all_messages.append({"role": "user", "content": user_content})
        else:
            all_messages.append(request_messages[-1])

bp.openai_client.chat.completions Vervolgens wordt chat voltooid via een Azure OpenAI API-aanroep en wordt het antwoord gestreamd.

        chat_coroutine = bp.openai_client.chat.completions.create(
            # Azure OpenAI takes the deployment name as the model name
            model=bp.model_name,
            messages=all_messages,
            stream=True,
            temperature=request_json.get("temperature", 0.5),
        )

Ten slotte wordt het antwoord teruggestreamd naar de client, met foutafhandeling voor eventuele uitzonderingen.

        try:
            async for event in await chat_coroutine:
                event_dict = event.model_dump()
                if event_dict["choices"]:
                    yield json.dumps(event_dict["choices"][0], ensure_ascii=False) + "\n"
        except Exception as e:
            current_app.logger.error(e)
            yield json.dumps({"error": str(e)}, ensure_ascii=False) + "\n"

    return Response(response_stream())

Front-endbibliotheken en -functionaliteiten

De front-end maakt gebruik van moderne browser-API's en bibliotheken om een interactieve chatervaring te maken. Ontwikkelaars kunnen de interface aanpassen of functies toevoegen door inzicht te krijgen in deze onderdelen:

1. Spraakinvoer/-uitvoer: aangepaste webonderdelen maken gebruik van de Spraak-API's van de browser:

   • <speech-input-button>: converteert spraak naar tekst met behulp van de Web Speech-API' s SpeechRecognition. Het biedt een microfoonknop die luistert naar spraakinvoer en een speech-input-result gebeurtenis verzendt met de getranscribeerde tekst.

   • <speech-output-button>: leest tekst hardop voor met behulp van de SpeechSynthesis API. Deze wordt weergegeven na elk antwoord van de assistent met een luidsprekerpictogram, zodat gebruikers het antwoord kunnen horen.

   Waarom browser-API's gebruiken in plaats van Azure Speech Services?

   • Geen kosten - wordt volledig uitgevoerd in de browser
   • Directe reactie - geen netwerklatentie
   • Privacy: spraakgegevens blijven op het apparaat van de gebruiker
   • Geen extra Azure-resources nodig

   Deze onderdelen bevinden zich in src/quartapp/static/speech-input.js en speech-output.js.

2. Afbeeldingsvoorbeeld: Geeft de geüploade afbeelding weer in de chat voordat de analyse ter bevestiging wordt verzonden. De preview wordt automatisch bijgewerkt wanneer een bestand wordt geselecteerd.

   fileInput.addEventListener("change", async function() {
       const file = fileInput.files[0];
       if (file) {
           const fileData = await toBase64(file);
           imagePreview.src = fileData;
           imagePreview.style.display = "block";
       }
   });
   

3. Bootstrap 5- en Bootstrap-pictogrammen: biedt responsieve UI-onderdelen en -pictogrammen. De app maakt gebruik van het Cosmo-thema van Bootswatch voor een modern uiterlijk.

4. Op sjabloon gebaseerde berichtweergave: maakt gebruik van HTML-elementen <template> voor herbruikbare berichtindelingen, waardoor consistente stijl en structuur worden gegarandeerd.

Andere voorbeeldbronnen om te verkennen

Naast het voorbeeld van de chat-app zijn er andere bronnen in de opslagplaats om te verkennen voor meer informatie. Bekijk de volgende notebooks in de notebooks map:

Gelokaliseerde inhoud: Spaanse versies van de notebooks bevinden zich in de notebooks/Spanish/ directory, die dezelfde praktische training bieden voor Spaans sprekende ontwikkelaars. Zowel Engelse als Spaanse notitieblokken tonen:

• Vision-modellen rechtstreeks aanroepen voor experimenten
• PDF-pagina's converteren naar afbeeldingen voor analyse
• Parameters en testprompts aanpassen

Resources opschonen

Azure-resources opschonen

De Azure-resources die in dit artikel zijn gemaakt, worden gefactureerd voor uw Azure-abonnement. Als u deze resources in de toekomst niet meer nodig hebt, verwijdert u deze om te voorkomen dat er meer kosten in rekening worden gebracht.

Als u de Azure-resources wilt verwijderen en de broncode wilt verwijderen, voert u de volgende Azure Developer CLI-opdracht uit:

azd down --purge

GitHub Codespaces opschonen

Hulp vragen

Meld uw probleem aan bij de problemen van de opslagplaats.

Volgende stappen