Erste Schritte mit multimodalen Vision-Chat-Apps mit Azure OpenAI

In diesem Artikel erfahren Sie, wie Sie Azure multimodalen OpenAI-Modelle verwenden, um Antworten auf Benutzernachrichten und hochgeladene Bilder in einer Chat-App zu generieren. Dieses Beispiel einer Chat-App umfasst auch alle Infrastruktur und Konfiguration, die für die Bereitstellung von Azure OpenAI-Ressourcen und die Bereitstellung der App in Azure Container Apps mithilfe der Azure Developer CLI erforderlich sind.

Indem Sie die Anweisungen in diesem Artikel befolgen, werden Sie:

• Stellen Sie eine Azure Containerchat-App bereit, die verwaltete Identität für die Authentifizierung verwendet.
• Laden Sie Bilder hoch, die als Teil des Chatstreams verwendet werden sollen.
• Chatten Sie mit einem Azure OpenAI multimodal large Language Model (LLM) mithilfe der Antwort-API der OpenAI-Bibliothek.

Nachdem Sie das Verfahren in diesem Artikel abgeschlossen haben, können Sie mit dem Ändern des neuen Projekts mit Ihrem benutzerdefinierten Code beginnen.

Übersicht über die Architektur

Eine einfache Architektur der Chat-App wird im folgenden Diagramm gezeigt:

Die Chat-App wird als Azure Container-App ausgeführt. Die App verwendet verwaltete Identität über Microsoft Entra ID zur Authentifizierung mit Azure OpenAI in der Produktion anstelle eines API-Schlüssels. Während der Entwicklung unterstützt die App mehrere Authentifizierungsmethoden, einschließlich Azure Entwickler-CLI-Anmeldeinformationen und API-Schlüssel.

Die Anwendungsarchitektur basiert auf den folgenden Diensten und Komponenten:

• Azure OpenAI stellt den KI-Anbieter dar, an den die Abfragen des Benutzers gesendet werden.
• Azure Container Apps ist die Containerumgebung, in der die Anwendung gehostet wird.
• Managed Identity hilft uns dabei, eine erstklassige Sicherheit zu gewährleisten und die Anforderung für Sie als Entwickler zu beseitigen, einen geheimen Schlüssel sicher zu verwalten.
• Bicep-Dateien für die Bereitstellung von Azure-Ressourcen, darunter Azure OpenAI, Azure Container Apps, Azure Container Registry, Azure Log Analytics und rollenbasierte Zugriffssteuerung (RBAC).
• Eine Python Quart-App, die das paket openai verwendet, um Antworten auf Benutzernachrichten mit hochgeladenen Bilddateien zu generieren.
• Ein einfaches HTML/JavaScript-Frontend, das Antworten aus dem Back-End mithilfe von JSON-Zeilen über einen ReadableStream streamt.

Kosten

Bei dem Versuch, die Preise in diesem Beispiel so niedrig wie möglich zu halten, verwenden die meisten Ressourcen ein Einfaches oder Verbrauchspreisniveau. Ändern Sie Ihre Stufe bei Bedarf basierend auf Ihrer beabsichtigten Nutzung. Löschen Sie die Ressourcen, wenn Sie den Artikel abgeschlossen haben, um weitere Gebühren zu vermeiden.

Erfahren Sie mehr über Cost im Beispielrepo.

Voraussetzungen

Eine Entwicklungscontainerumgebung ist mit allen Abhängigkeiten verfügbar, die zum Abschließen dieses Artikels erforderlich sind. Sie können den Entwicklungscontainer in GitHub Codespaces (in einem Browser) oder lokal mit Visual Studio Code ausführen.

Um diesen Artikel zu verwenden, müssen Sie die folgenden Voraussetzungen erfüllen:

Öffnen Sie die Entwicklungsumgebung

Verwenden Sie die folgenden Anweisungen, um eine vorkonfigurierte Entwicklungsumgebung bereitzustellen, die alle erforderlichen Abhängigkeiten enthält, um diesen Artikel abzuschließen.

Bereitstellen und Ausführen

Das Beispiel-Repository enthält alle Code- und Konfigurationsdateien für die Bereitstellung der Chat-App auf Azure. Die folgenden Schritte führen Sie durch den Bereitstellungsprozess der Beispiel-Chat-App auf Azure.

Bereitstellen einer Chat-App für Azure

1. Führen Sie den folgenden Azure Developer CLI-Befehl für Azure Ressourcenbereitstellung und Quellcodebereitstellung aus:

   azd up
   

2. Gehen Sie zum Beantworten der Eingabeaufforderungen gemäß der folgenden Tabelle vor:

   Eingabeaufforderung	Antwort
   Umgebungsname	Halten Sie dies kurz, und verwenden Sie nur Kleinbuchstaben. Fügen Sie Ihren Namen oder Alias hinzu. Beispiel: chat-vision. Er wird als Teil des Ressourcengruppennamens verwendet.
   Abonnement	Wählen Sie das Abonnement aus, in dem Sie die Ressourcen erstellen möchten.
   Standort (für Hosting)	Wählen Sie aus der Liste einen Standort in Ihrer Nähe aus.
   Standort für das Azure OpenAI-Modell	Wählen Sie aus der Liste einen Standort in Ihrer Nähe aus. Wenn derselbe Speicherort wie Ihr erster Speicherort verfügbar ist, wählen Sie diesen Speicherort aus.

3. Warten Sie, bis die App bereitgestellt wird. Die Bereitstellung dauert normalerweise zwischen 5 und 10 Minuten.

Verwenden der Chat-App zum Stellen von Fragen zum Großen Sprachmodell

1. Das Terminal zeigt eine URL nach erfolgreicher Anwendungsbereitstellung an.

2. Wählen Sie diese URL aus, die als Deploying service web beschriftet ist, um die Chatanwendung in einem Browser zu öffnen.

   

3. Laden Sie im Browser ein Bild hoch, indem Sie auf " Datei auswählen" klicken und ein Bild auswählen.

4. Stellen Sie eine Frage zu dem hochgeladenen Bild, z. B. "Worum handelt es sich um das Bild?".

5. Die Antwort stammt aus Azure OpenAI und das Ergebnis wird angezeigt.

Erkunden des Beispielcodes

In diesem Beispiel wird ein Azure multimodales OpenAI-Modell verwendet, um Antworten auf Benutzernachrichten und hochgeladene Bilder zu generieren.

Base64 Codieren des hochgeladenen Bilds im Frontend

Das hochgeladene Bild muss Base64-codiert sein, damit es direkt als Daten-URI als Teil der Nachricht verwendet werden kann.

Im Beispiel behandelt der folgende Frontend-Codeausschnitt im scriptTag der src/quartapp/templates/index.html Datei diese Funktionalität. Die toBase64 Pfeilfunktion verwendet die readAsDataURL Methode, um die hochgeladene Bilddatei asynchron als base64-codierte Zeichenfolge einzulesen.

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

Die toBase64 Funktion wird von einem Listener für das Ereignis des Formulars submit aufgerufen.

Der submit Ereignislistener behandelt den vollständigen Chatinteraktionsfluss. Wenn der Benutzer eine Nachricht sendet, tritt der folgende Ablauf auf:

1. Ruft die hochgeladene Bilddatei (sofern vorhanden) ab und codiert als Base64
2. Erstellt und zeigt die Nachricht des Benutzers im Chat an, einschließlich des hochgeladenen Bilds
3. Bereitet einen Assistentennachrichtencontainer mit einem "Tippen..."-Indikator vor.
4. Fügt die Nachricht des Benutzers zum Nachrichtenverlaufsarray im Antwort-API-Format hinzu.
5. Sendet eine fetch POST-Anforderung mit dem Nachrichtenverlauf und dem Kontext an den /chat/stream Endpunkt (einschließlich des Base64-codierten Bilds und Dateinamens)
6. Verarbeitet die gestreamte JSON-Zeilenantwort , um jedes Textdelta inkrementell anzuzeigen.
7. Behandelt Fehler während des Streamings
8. Fügt eine Sprachausgabeschaltfläche hinzu, nachdem die vollständige Antwort empfangen wurde, damit Benutzer die Antwort hören können.
9. Löscht das Eingabefeld und gibt den Fokus für die nächste Nachricht zurück.

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": [{"type": "input_text", "text": message}]
    });

    try {
        messageDiv.scrollIntoView();
        const response = await fetch("/chat/stream", {
            method: "POST",
            headers: {"Content-Type": "application/json"},
            body: JSON.stringify({
                messages: messages,
                context: {
                    file: fileData,
                    file_name: file ? file.name : null
                }
            })
        });

        if (!response.ok || !response.body) {
            throw new Error(`Request failed (${response.status})`);
        }

        let answer = "";
        for await (const chunk of readNDJSONStream(response.body)) {
            if (chunk.type === "error" || chunk.type === "response.failed") {
                messageDiv.innerHTML = "Error: " + (chunk.error || "Unknown error");
                break;
            }
            if (chunk.type === "response.output_text.delta") {
                // Clear out the DIV if its the first answer chunk we've received
                if (answer == "") {
                    messageDiv.innerHTML = "";
                }
                answer += chunk.delta;
                messageDiv.innerHTML = converter.makeHtml(answer);
                messageDiv.scrollIntoView();
            }
        }

        messages.push({
            "role": "assistant",
            "content": [{"type": "output_text", "text": 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;
    }
});

Verarbeitung des Bildes mit dem Backend

In der src\quartapp\chat.py Datei beginnt der Back-End-Code für die Bildverarbeitung nach der Konfiguration der schlüssellosen Authentifizierung.

Authentifizierungskonfiguration

Die configure_openai() Funktion richtet den OpenAI-Client ein, bevor die App Anforderungen verarbeitet. Es verwendet den Dekorateur von Quart @bp.before_app_serving, um die Authentifizierung basierend auf Umgebungsvariablen zu konfigurieren. Mit diesem flexiblen System können Entwickler in verschiedenen Kontexten arbeiten, ohne Code zu ändern.

Erläuterte Authentifizierungsmodi

• Lokale Entwicklung (OPENAI_HOST=local): Stellt eine Verbindung mit einem lokalen openAI-kompatiblen API-Dienst (z. B. Ollama oder LocalAI) ohne Authentifizierung bereit. Verwenden Sie diesen Modus zum Testen ohne Internet- oder API-Kosten.
• Azure OpenAI mit API-Schlüssel (AZURE_OPENAI_KEY_FOR_CHATVISION Umgebungsvariable): Verwendet einen API-Schlüssel für die Authentifizierung. Vermeiden Sie diesen Modus in der Produktionsumgebung, da API-Schlüssel eine manuelle Rotation erfordern und ein Sicherheitsrisiko darstellen, wenn sie offengelegt werden. Verwenden Sie sie für lokale Tests innerhalb eines Docker-Containers ohne Azure CLI Anmeldeinformationen.
• Produktion mit verwalteter Identität (RUNNING_IN_PRODUCTION=true): Verwendet ManagedIdentityCredential, um sich über die verwaltete Identität der Container-App bei Azure OpenAI zu authentifizieren. Diese Methode wird für die Produktion empfohlen, da sie die Notwendigkeit zum Verwalten von geheimen Schlüsseln entfernt. Azure Container Apps stellen die verwaltete Identität automatisch bereit und erteilen während der Bereitstellung über Bicep die erforderlichen Berechtigungen.
• Development with Azure CLI (Standardmodus): Verwendet AzureDeveloperCliCredential zum Authentifizieren mit Azure OpenAI mithilfe von lokal angemeldeten Azure CLI Anmeldeinformationen. Dieser Modus vereinfacht die lokale Entwicklung, ohne API-Schlüssel zu verwalten.

Wichtige Implementierungsdetails

• Die get_bearer_token_provider()-Funktion aktualisiert Azure Anmeldeinformationen und verwendet sie als Bearertoken.
• Der Azure OpenAI-Endpunktpfad endet mit /openai/v1/, dem allgemein verfügbaren OpenAI-kompatiblen Endpunkt für Microsoft Foundry Models.
• Die Funktion ist asynchron, da Quart ein asynchrones Web App-Framework ist. Mit Quart können Anforderungshandler asynchron sein. Während die App auf langsame LLM-API-Antworten wartet, kann der Server andere Anforderungen weiterhin verarbeiten.

Hier ist der vollständige Code für die Authentifizierungseinrichtung aus 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", "azure")

    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 os.getenv("AZURE_OPENAI_KEY_FOR_CHATVISION"):
        bp.openai_client = AsyncOpenAI(
            base_url=os.environ["AZURE_OPENAI_ENDPOINT"].rstrip("/") + "/openai/v1",
            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"].rstrip("/") + "/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"].rstrip("/") + "/openai/v1",
            api_key=token_provider,
        )
        current_app.logger.info("Using Azure OpenAI with az CLI credential for tenant ID: %s", tenant_id)

Chathandlerfunktion

Die chat_handler() Funktion verarbeitet Chatanfragen, die an den /chat/stream Endpunkt gesendet werden. Sie empfängt eine POST-Anforderung mit einer JSON-Nutzlast.

Die JSON-Nutzlast umfasst:

• nachrichten: Eine Liste der Aufgezeichneten Unterhaltungen. Jede Nachricht verfügt über einen role ("Benutzer" oder "Assistenten") und content (ein Array von Inhaltsteilen mithilfe des Eingabeformats der Antwort-API).
• Kontext: Zusätzliche Daten für die Verarbeitung, einschließlich:
  • datei: Base64-codierte Bilddaten (z. B data:image/png;base64,.... ).
  • file_name: Der ursprüngliche Dateiname des hochgeladenen Bilds (nützlich für die Protokollierung oder Identifizierung des Bildtyps).

Der Handler extrahiert den Nachrichtenverlauf und Bilddaten. Wenn kein Bild hochgeladen wird, lautet der Bildwert null, und der Code behandelt diesen Fall.

@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"]

Erstellen des Eingabearrays für Vision-Anforderungen

Die response_stream()-Funktion bereitet das Eingabearray vor, das an die Azure OpenAI-Antwort-API gesendet wird. Der @stream_with_context Dekorateur behält den Anforderungskontext bei, während die Antwort gestreamt wird.

Eingabevorbereitungslogik

1. Beginnen Sie mit dem Unterhaltungsverlauf: Die Funktion beginnt mit all_input, die alle vorherigen Nachrichten mit Ausnahme der letzten (request_messages[0:-1]) enthält. Nachrichten befinden sich bereits im Antwort-API-Format aus dem Frontend.
2. Behandeln Sie die aktuelle Benutzernachricht basierend auf der Bildpräsenz:
   • Mit Bild: Einen input_image Inhaltsteil zum vorhandenen Inhaltsarray des Benutzers hinzufügen.
   • Ohne Bild: Fügen Sie die Nachricht des Benutzers unverändert an.

    @stream_with_context
    async def response_stream():
        # This sends all messages, so API request may exceed token limits
        all_input = list(request_messages[0:-1])

        # Add the current user message, appending image if provided
        if image:
            user_content = request_messages[-1]["content"] + [{"type": "input_image", "image_url": image}]
            all_input.append({"role": "user", "content": user_content})
        else:
            all_input.append(request_messages[-1])

Als Nächstes ruft bp.openai_client.responses.create die Azure OpenAI-Antwort-API auf und streamt die Antwort. Der store=False Parameter weist die API an, keine Antworten auf dem Server zu speichern, wodurch der Aufruf zustandslos wird.

        openai_stream = await bp.openai_client.responses.create(
            model=bp.model_name,
            input=all_input,
            stream=True,
            temperature=0.3,
            store=False,
        )

Schließlich wird die Antwort zurück an den Client gestreamt. Die Antwort-API gibt viele Ereignistypen aus, aber nur das response.output_text.delta Ereignis wird für das Streaming generierter Text benötigt. Fehlerereignisse werden protokolliert und an das Frontend weitergeleitet.

        try:
            async for event in openai_stream:
                if event.type == "response.output_text.delta":
                    yield json.dumps({"type": event.type, "delta": event.delta}, ensure_ascii=False) + "\n"
                elif event.type in ("response.failed", "error"):
                    current_app.logger.error("Responses API error: %s", event)
                    yield json.dumps({"type": event.type}, ensure_ascii=False) + "\n"
        except Exception as e:
            current_app.logger.exception("Error in response stream")
            yield json.dumps({"error": str(e)}, ensure_ascii=False) + "\n"

    return Response(response_stream())

Frontend-Bibliotheken und -Features

Das Frontend verwendet moderne Browser-APIs und -Bibliotheken, um eine interaktive Chaterfahrung zu erstellen. Entwickler können die Schnittstelle anpassen oder Features hinzufügen, indem Sie die folgenden Komponenten verstehen:

1. Spracheingabe/Ausgabe: Benutzerdefinierte Webkomponenten verwenden die Sprach-APIs des Browsers:

   • <speech-input-button>: Wandelt Die Sprache mithilfe der Web speech-API SpeechRecognitionin Text um. Es stellt eine Mikrofon-Taste bereit, die die Spracheingabe überwacht und ein speech-input-result Ereignis mit dem transkribierten Text ausgibt.

   • <speech-output-button>: Liest Text mit der SpeechSynthesis API laut vor. Sie wird nach jeder Assistentenantwort mit einem Lautsprechersymbol angezeigt, sodass Benutzer die Antwort hören können.

   Warum Browser-APIs anstelle von Azure Speech Services verwenden?

   • Keine Kosten - wird vollständig im Browser ausgeführt
   • Sofortige Antwort – keine Netzwerklatenz
   • Datenschutz – Sprachdaten bleiben auf dem Gerät des Benutzers
   • Keine Notwendigkeit für zusätzliche Azure Ressourcen

   Diese Komponenten befinden sich in src/quartapp/static/speech-input.js und speech-output.js.

2. Bildvorschau: Zeigt das hochgeladene Bild im Chat vor der Analyseübermittlung zur Bestätigung an. Die Vorschau wird automatisch aktualisiert, wenn eine Datei ausgewählt wird.

   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- und Bootstrap-Symbole: Stellt reaktionsfähige UI-Komponenten und Symbole bereit. Die App verwendet das Cosmo-Design von Bootswatch für ein modernes Aussehen.

4. Vorlagenbasiertes Nachrichtenrendering: Verwendet HTML-Elemente<template> für wiederverwendbare Nachrichtenlayouts und stellt eine konsistente Formatierung und Struktur sicher.

Weitere Beispielressourcen zum Erkunden

Zusätzlich zum Beispiel einer Chat-App gibt es weitere Ressourcen im Repository, um weitere Informationen zu erhalten. Sehen Sie sich die folgenden Notizbücher im notebooks Verzeichnis an:

Lokalisierter Inhalt: Spanische Versionen der Notizbücher befinden sich im notebooks/Spanish/ Verzeichnis und bieten das gleiche praktische Lernen für spanischsprachige Entwickler. Sowohl englische als auch spanische Notizbücher zeigen:

• So rufen Sie Visionsmodelle direkt zum Experimentieren auf
• Konvertieren von PDF-Seiten in Bilder für die Analyse
• Anpassen von Parametern und Testaufforderungen

Bereinigen von Ressourcen

Bereinigen Azure Ressourcen

Die in diesem Artikel erstellten Azure Ressourcen werden Ihrem Azure-Abonnement in Rechnung gestellt. Wenn Sie nicht erwarten, dass diese Ressourcen in Zukunft benötigt werden, löschen Sie sie, um weitere Gebühren zu vermeiden.

Um die Azure Ressourcen zu löschen und den Quellcode zu entfernen, führen Sie den folgenden Azure Developer CLI-Befehl aus:

azd down --purge

Bereinigen GitHub Codespaces

Hilfe erhalten

Tragen Sie Ihr Problem in die Issues des Repository ein.

Nächste Schritte