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

In diesem Artikel erfahren Sie, wie Sie mithilfe von multimodalen Azure OpenAI-Modellen Antworten auf Benutzernachrichten und hochgeladene Bilder in einer Chat-App generieren. Dieses Beispiel für Eine Chat-App enthält auch alle Infrastruktur und Konfiguration, die für die Bereitstellung von Azure OpenAI-Ressourcen und die Bereitstellung der App in Azure-Container-Apps mit der Azure Developer CLI erforderlich ist.

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

• Stellen Sie eine Azure Container-Chat-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 multimodalen Large Language Model (LLM) mithilfe 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, um sich bei Azure OpenAI in der Produktion zu authentifizieren, anstatt mit einem API-Schlüssel. Während der Entwicklung unterstützt die App mehrere Authentifizierungsmethoden, einschließlich Azure Developer CLI-Anmeldeinformationen, API-Schlüssel und GitHub-Modelle zum Testen ohne Azure-Ressourcen.

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, einschließlich Azure OpenAI, Azure Container Apps, Azure Container Registry, Azure Log Analytics und rollenbasierte Zugriffssteuerungsrollen (RBAC).
• Das Microsoft KI-Chat-Protokoll bietet standardisierte API-Verträge über KI-Lösungen und Sprachen hinweg. Die Chat-App entspricht dem Microsoft AI-Chatprotokoll.
• Ein Python Quart , das das openai Paket 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 die Ebenenebene je nach Bedarf basierend auf Ihrer beabsichtigten Verwendung. Löschen Sie die Ressourcen, wenn Sie mit dem Artikel fertig sind, um die Anfallenden Gebühren zu beenden.

Weitere Informationen zu den Kosten im Beispielrepository finden Sie hier.

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 Azure-Bereitstellung der Chat-App. Die folgenden Schritte führen Sie durch den Azure-Bereitstellungsprozess der Beispielchat-App.

Bereitstellen einer Chat-App in Azure

1. Führen Sie den folgenden Azure Developer CLI-Befehl für die Bereitstellung von Azure-Ressourcen und die Quellcodebereitstellung aus:

   azd up
   

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

   Prompt	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.
   Speicherort 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 in der Regel zwischen 5 und 10 Minuten, bis die Bereitstellung abgeschlossen ist.

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

Während OpenAI und Azure OpenAI Service auf eine allgemeine Python-Clientbibliothek angewiesen sind, werden kleine Codeänderungen bei Verwendung von Azure OpenAI-Endpunkten benötigt. In diesem Beispiel wird ein multimodales Azure 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 desFileReader asynchronen Lesens in der hochgeladenen Bilddatei als base64-codierte Zeichenfolge.

    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. Blendet das Element "no-messages-heading" aus, um die gestartete Unterhaltung anzuzeigen.
2. Ruft ab und Base64 codiert die hochgeladene Bilddatei (sofern vorhanden)
3. Erstellt und zeigt die Nachricht des Benutzers im Chat an, einschließlich des hochgeladenen Bilds
4. Bereitet einen Assistentennachrichtencontainer mit einem "Tippen..."-Indikator vor.
5. Fügt die Nachricht des Benutzers zum Nachrichtenverlaufsarray hinzu.
6. Ruft die Methode des AI-Chatprotokollclients getStreamedCompletion() mit dem Nachrichtenverlauf und dem Kontext auf (einschließlich des Base64-codierten Bildes und des Dateinamens).
7. Verarbeitet die gestreamten Antwortblöcke und konvertiert Markdown mithilfe von Showdown.js
8. Behandelt Fehler während des Streamings
9. Fügt eine Sprachausgabeschaltfläche hinzu, nachdem die vollständige Antwort empfangen wurde, damit Benutzer die Antwort hören können.
10. 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": 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;
    }
});

Behandeln des Bilds mit dem Back-End

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.
• GitHub-Modelle (OPENAI_HOST=github): Verwendet den KI-Modell-Marketplace von GitHub mit einer GITHUB_TOKEN Authentifizierung. Wenn Sie GitHub-Modelle verwenden, stellen Sie dem Modellnamen das Präfix voran openai/ (z. B openai/gpt-4o. ). Mit diesem Modus können Entwickler Modelle ausprobieren, bevor Azure-Ressourcen bereitgestellt werden.
• 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 die Authentifizierung mit Azure OpenAI über die verwaltete Identität der Container-App. Diese Methode wird für die Produktion empfohlen, da sie die Notwendigkeit zum Verwalten von geheimen Schlüsseln entfernt. Azure Container-Apps stellen automatisch die verwaltete Identität bereit und erteilen Berechtigungen während der Bereitstellung über Bicep.
• Entwicklung mit Azure CLI (Standardmodus): Verwendet AzureDeveloperCliCredential die Authentifizierung 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 umfasst /openai/v1/, um die Anforderungen der OpenAI-Clientbibliothek zu erfüllen.
• Die Protokollierung zeigt an, welcher Authentifizierungsmodus aktiv ist.
• Die Funktion ist asynchron, um Azure-Anmeldedatenvorgänge zu unterstützen.

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", "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)

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 dem Microsoft AI-Chatprotokoll folgt.

Die JSON-Nutzlast umfasst:

• nachrichten: Eine Liste der Aufgezeichneten Unterhaltungen. Jede Nachricht hat einen role ("Benutzer" oder "Assistent") und content (den Nachrichtentext).
• 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).
• Temperatur (optional): Ein Float, der die Zufälligkeit der Reaktion steuert (Standardwert ist 0,5).

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"]
    # The context also includes the filename for reference
    # file_name = request_json["context"]["file_name"]

Erstellen des Nachrichtenarrays für Vision-Anforderungen

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

Nachrichtenvorbereitungslogik

1. Beginnen Sie mit dem Unterhaltungsverlauf: Die Funktion beginnt mit all_messages, die eine Systemnachricht und alle vorherigen Nachrichten mit Ausnahme der letzten (request_messages[0:-1]) enthält.
2. Behandeln Sie die aktuelle Benutzernachricht basierend auf der Bildpräsenz:
   • Mit Bild: Formatieren sie die Nachricht des Benutzers als mehrteiliges Inhaltsarray mit Text und image_url Objekten. Das image_url Objekt enthält die Base64-codierten Bilddaten und einen detail Parameter.
   • Ohne Bild: Fügen Sie die Nachricht des Benutzers als Nur-Text an.
3. Der detail Parameter: Auf "auto" setzen, damit das Modell basierend auf der Bildgröße zwischen "niedriger" und "hoher" Detailgenauigkeit wählen kann. Niedrige Details sind schneller und billiger, während hohe Details eine genauere Analyse für komplexe Bilder bieten.

    @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 Ruft als Nächstes Chatabschlusse über einen Azure OpenAI-API-Aufruf ab und streamt die Antwort.

        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),
        )

Schließlich wird die Antwort zurück an den Client gestreamt, mit der Fehlerbehandlung für ausnahmen.

        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())

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 von 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.

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

azd down --purge

Bereinigen von GitHub-Codespaces

Hilfe erhalten

Protokollieren Sie Ihr Problem mit den Problemen des Repositorys.

Nächste Schritte