Wprowadzenie do wielomodalnych aplikacji do czatów wizyjnych przy użyciu usługi Azure OpenAI

W tym artykule pokazano, jak używać modeli wielomodalnych usługi Azure OpenAI do generowania odpowiedzi na wiadomości użytkowników i przekazywania obrazów w aplikacji do czatu. Ten przykład aplikacji do czatów zawiera również całą infrastrukturę i konfigurację wymaganą do aprowizacji zasobów usługi Azure OpenAI oraz wdrażania aplikacji w usłudze Azure Container Apps przy użyciu interfejsu wiersza polecenia dla deweloperów platformy Azure.

Postępując zgodnie z instrukcjami w tym artykule, wykonasz następujące czynności:

• Wdróż aplikację czatu kontenera platformy Azure, która używa tożsamości zarządzanej do uwierzytelniania.
• Przekazywanie obrazów do użycia w ramach strumienia czatu.
• Porozmawiaj z wielomodalnym modelem języka wielomodalnego platformy Azure OpenAI (LLM) przy użyciu biblioteki OpenAI.

Po ukończeniu tego artykułu możesz rozpocząć modyfikowanie nowego projektu przy użyciu kodu niestandardowego.

Omówienie architektury

Prosta architektura aplikacji do czatu jest pokazana na poniższym diagramie:

Aplikacja do czatu działa jako aplikacja kontenera platformy Azure. Aplikacja używa tożsamości zarządzanej za pośrednictwem Microsoft Entra ID do uwierzytelniania z Azure OpenAI w środowisku produkcyjnym zamiast klucza API. pl-PL: Podczas opracowywania aplikacja obsługuje wiele metod uwierzytelniania, w tym poświadczenia Azure CLI, klucze interfejsu API i modele GitHub do testowania bez zasobów platformy Azure.

Architektura aplikacji opiera się na następujących usługach i składnikach:

• Usługa Azure OpenAI reprezentuje dostawcę sztucznej inteligencji, do którego wysyłamy zapytania użytkownika.
• Usługa Azure Container Apps to środowisko kontenera, w którym jest hostowana aplikacja.
• Tożsamość zarządzana pomaga nam zapewnić najlepsze zabezpieczenia w klasie i wyeliminować wymaganie, aby jako deweloper bezpiecznie zarządzać wpisem tajnym.
• Pliki Bicep do aprowizowania zasobów platformy Azure, w tym azure OpenAI, Azure Container Apps, Azure Container Registry, Azure Log Analytics i ról kontroli dostępu (RBAC).
• Protokół Microsoft AI Chat Protocol udostępnia standardowe kontrakty interfejsu API w rozwiązaniach i językach sztucznej inteligencji. Aplikacja do czatu jest zgodna z protokołem Microsoft AI Chat Protocol.
• Kwart języka Python, który używa openai pakietu do generowania odpowiedzi na komunikaty użytkowników z przekazanymi plikami obrazów.
• Podstawowy fronton HTML/JavaScript, który przesyła strumieniowo odpowiedzi z zaplecza przy użyciu linii JSON za pośrednictwem elementu ReadableStream.

Koszt

Próbując zachować możliwie niskie ceny w tym przykładzie, większość zasobów korzysta z warstwy cenowej podstawowa lub zużycie. Zmień poziom warstwy zgodnie z potrzebami na podstawie zamierzonego użycia. Aby zatrzymać naliczanie opłat, usuń zasoby po zakończeniu pracy z artykułem.

Dowiedz się więcej o kosztach w repozytorium przykładowym.

Wymagania wstępne

Środowisko kontenera deweloperskiego jest dostępne ze wszystkimi zależnościami wymaganymi do ukończenia tego artykułu. Kontener deweloperski można uruchomić w usłudze GitHub Codespaces (w przeglądarce) lub lokalnie przy użyciu programu Visual Studio Code.

Aby użyć tego artykułu, należy spełnić następujące wymagania wstępne:

Otwieranie środowiska projektowego

Skorzystaj z poniższych instrukcji, aby wdrożyć wstępnie skonfigurowane środowisko programistyczne zawierające wszystkie wymagane zależności, aby ukończyć ten artykuł.

Wdrażanie i uruchamianie

Przykładowe repozytorium zawiera wszystkie pliki kodu i konfiguracji dla wdrożenia aplikacji czatu na platformie Azure. W poniższych krokach przedstawiono przykładowy proces wdrażania aplikacji czatu platformy Azure.

Wdrażanie aplikacji czatu na platformie Azure

1. Uruchom następujące polecenie interfejsu wiersza polecenia dla deweloperów platformy Azure na potrzeby aprowizacji zasobów platformy Azure i wdrożenia kodu źródłowego:

   azd up
   

2. Użyj poniższej tabeli, aby odpowiedzieć na monity:

   Monit	Odpowiedź
   Nazwa środowiska	Zachowaj krótkie i małe litery. Dodaj swoją nazwę lub alias. Na przykład chat-vision. Jest ona używana jako część nazwy grupy zasobów.
   Subskrypcja	Wybierz subskrypcję, w ramach których chcesz utworzyć zasoby.
   Lokalizacja (na potrzeby hostingu)	Wybierz lokalizację w pobliżu z listy.
   Lokalizacja modelu Azure OpenAI	Wybierz lokalizację w pobliżu z listy. Jeśli ta sama lokalizacja jest dostępna jako pierwsza lokalizacja, wybierz tę lokalizację.

3. Poczekaj na wdrożenie aplikacji. Wdrożenie zwykle trwa od 5 do 10 minut.

Używanie aplikacji do czatu w celu zadawania pytań do modelu dużego języka

1. W terminalu zostanie wyświetlony adres URL po pomyślnym wdrożeniu aplikacji.

2. Wybierz ten adres URL oznaczony Deploying service web etykietą, aby otworzyć aplikację czatu w przeglądarce.

   

3. W przeglądarce przekaż obraz, klikając pozycję Wybierz plik i wybierając obraz.

4. Zadaj pytanie dotyczące przekazanego obrazu, takiego jak "Co to jest obraz?".

5. Odpowiedź pochodzi z usługi Azure OpenAI i zostanie wyświetlony wynik.

Eksplorowanie przykładowego kodu

Chociaż interfejsy OpenAI i Azure OpenAI Service opierają się na wspólnej bibliotece klienta języka Python, podczas korzystania z punktów końcowych usługi Azure OpenAI potrzebne są niewielkie zmiany kodu. W tym przykładzie użyto wielomodalnego modelu usługi Azure OpenAI do generowania odpowiedzi na komunikaty użytkowników i przekazanych obrazów.

Base64 Kodowanie przekazanego obrazu w frontonie

Przekazany obraz musi być zakodowany w formacie Base64, aby mógł być używany bezpośrednio jako identyfikator URI danych w ramach komunikatu.

W przykładzie poniższy fragment kodu frontonu w scripttagu src/quartapp/templates/index.html pliku obsługuje te funkcje. Funkcja toBase64 arrow używa readAsDataURL metody ,FileReader aby asynchronicznie odczytywać w przekazanym pliku obrazu jako ciąg zakodowany w formacie base64.

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

Funkcja toBase64 jest wywoływana przez odbiornik zdarzenia formularza submit .

Nasłuchiwacz submit zdarzeń obsługuje pełny przepływ interakcji z czatem. Gdy użytkownik prześle komunikat, wystąpi następujący przepływ:

1. Ukrywa element "no-messages-heading", aby pokazać rozpoczętą konwersację
2. Pobiera i Base64 koduje przekazany plik obrazu (jeśli istnieje)
3. Tworzy i wyświetla komunikat użytkownika na czacie, w tym przekazany obraz
4. Przygotowuje kontener komunikatów asystenta z wskaźnikiem "Wpisywanie..."
5. Dodaje komunikat użytkownika do tablicy historii komunikatów
6. Wywołuje metodę klienta getStreamedCompletion() protokołu czatu AI z historią komunikatów i kontekstem (w tym obrazem i nazwą pliku zakodowanymi w Base64)
7. Przetwarza fragmenty przesyłane strumieniowo odpowiedzi i konwertuje język Markdown na kod HTML przy użyciu Showdown.js
8. Obsługuje błędy podczas przesyłania strumieniowego
9. Dodaje przycisk wyjścia dźwiękowego po otrzymaniu pełnej odpowiedzi, aby użytkownicy mogli odsłuchać odpowiedź.
10. Czyści pole wejściowe i zwraca fokus dla następnego komunikatu

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;
    }
});

Obsługa obrazu za pomocą zaplecza

W pliku kod zaplecza do obsługi obrazów rozpoczyna się po skonfigurowaniu src\quartapp\chat.py uwierzytelniania bez klucza.

Konfiguracja uwierzytelniania

Funkcja configure_openai() konfiguruje klienta OpenAI przed rozpoczęciem obsługi żądań przez aplikację. Używa dekoratora @bp.before_app_serving z Quart do konfigurowania uwierzytelniania na podstawie zmiennych środowiskowych. Ten elastyczny system umożliwia deweloperom pracę w różnych kontekstach bez konieczności zmieniania kodu.

Objaśnienie trybów uwierzytelniania

• Programowanie lokalne (OPENAI_HOST=local): łączy się z lokalną usługą interfejsu API zgodną z protokołem OpenAI (np. Ollama lub LocalAI) bez uwierzytelniania. Użyj tego trybu do testowania bez kosztów Internetu lub interfejsu API.
• Modele GitHub (OPENAI_HOST=github): używa rynku modeli AI GitHub do GITHUB_TOKEN uwierzytelniania. Korzystając z modeli GitHub, poprzedzaj nazwę modelu prefiksem openai/ (na przykład openai/gpt-4o). Ten tryb umożliwia deweloperom wypróbowanie modeli przed aprowizowaniem zasobów platformy Azure.
• Usługa Azure OpenAI z kluczem interfejsu API (AZURE_OPENAI_KEY_FOR_CHATVISION zmienna środowiskowa): używa klucza interfejsu API do uwierzytelniania. Unikaj tego trybu w środowisku produkcyjnym, ponieważ klucze interfejsu API wymagają ręcznego obrotu i stanowią zagrożenie bezpieczeństwa, jeśli zostaną ujawnione. Użyj go do testowania lokalnego wewnątrz kontenera Docker bez poświadczeń Azure CLI.
• Produkcja z tożsamością zarządzaną (RUNNING_IN_PRODUCTION=true): Używa się ManagedIdentityCredential do uwierzytelniania z usługą Azure OpenAI za pośrednictwem tożsamości zarządzanej aplikacji kontenera. Ta metoda jest zalecana w środowisku produkcyjnym, ponieważ eliminuje konieczność zarządzania tajnymi danymi. Usługa Azure Container Apps automatycznie udostępnia tożsamość zarządzaną i udziela uprawnień podczas wdrażania za pośrednictwem aplikacji Bicep.
• Rozwój z Azure CLI (tryb domyślny): używa AzureDeveloperCliCredential do uwierzytelniania w usłudze Azure OpenAI przy użyciu lokalnie zalogowanych poświadczeń Azure CLI. Ten tryb upraszcza programowanie lokalne bez zarządzania kluczami interfejsu API.

Kluczowe szczegóły implementacji

• Funkcja get_bearer_token_provider() odświeża poświadczenia platformy Azure i używa ich jako tokenów dostępu.
• Ścieżka punktu końcowego usługi Azure OpenAI zawiera /openai/v1/, aby spełniać wymagania biblioteki klienta OpenAI.
• Rejestrowanie pokazuje, który tryb uwierzytelniania jest aktywny.
• Funkcja jest asynchroniczna, aby obsługiwać operacje uwierzytelniania Azure.

Oto kompletny kod konfiguracji uwierzytelniania z pliku 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)

Funkcja obsługi czatów

Funkcja chat_handler() przetwarza żądania czatu wysyłane do punktu końcowego /chat/stream . Odbiera żądanie POST z ładunkiem JSON zgodnym z protokołem Microsoft AI Chat Protocol.

Ładunek JSON obejmuje:

• wiadomości: lista historii konwersacji. Każda wiadomość ma role ("użytkownika" lub "asystenta") i content (tekst wiadomości).
• context: Dodatkowe dane do przetwarzania, w tym:
  • plik: dane obrazu zakodowane w formacie Base64 (na przykład data:image/png;base64,...).
  • file_name: oryginalna nazwa pliku przekazanego obrazu (przydatna do rejestrowania lub identyfikowania typu obrazu).
• temperature (opcjonalnie): liczba zmiennoprzecinkowa określająca losowość odpowiedzi (wartość domyślna: 0,5).

Program obsługi wyodrębnia historię komunikatów i dane obrazu. Jeśli obraz nie zostanie przekazany, wartość obrazu to null, a kod obsługuje ten przypadek.

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

Budowanie tablicy komunikatów dla żądań wizji komputerowej

Funkcja response_stream() przygotowuje tablicę komunikatów, która jest wysyłana do interfejsu API usługi Azure OpenAI. Dekorator @stream_with_context przechowuje kontekst żądania podczas przesyłania strumieniowego odpowiedzi.

Logika przygotowywania komunikatów

1. Rozpocznij od historii konwersacji: funkcja zaczyna się od , która zawiera all_messageskomunikat systemowy i wszystkie poprzednie komunikaty z wyjątkiem najnowszej (request_messages[0:-1]).
2. Obsługa bieżącego komunikatu użytkownika na podstawie obecności obrazu:
   • Z obrazem: sformatuj wiadomość użytkownika jako tablicę zawartości złożonej z części tekstowych i obiektów adresu URL obrazu. Obiekt image_url zawiera dane obrazu zakodowane w formacie Base64 i detail parametr.
   • Bez obrazu: Dołącz wiadomość użytkownika jako zwykły tekst.
3. Parametrdetail: ustaw wartość "auto", aby umożliwić modelowi wybranie między "niskim" i "wysokim" szczegółem na podstawie rozmiaru obrazu. Niski poziom szczegółowości jest szybszy i tańszy, a wysoki poziom szczegółowości zapewnia dokładniejszą analizę złożonych obrazów.

    @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 Następnie uzyskuje ukończenie czatu za pośrednictwem wywołania interfejsu API usługi Azure OpenAI i przesyła strumieniowo odpowiedź.

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

Na koniec odpowiedź jest przesyłana strumieniowo do klienta z obsługą błędów dla wszystkich wyjątków.

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

Biblioteki i funkcje frontonu

Fronton używa nowoczesnych interfejsów API i bibliotek przeglądarki do tworzenia interaktywnego środowiska czatu. Deweloperzy mogą dostosowywać interfejs lub dodawać funkcje, rozumiejąc następujące składniki:

1. Wejście/wyjście mowy: niestandardowe składniki internetowe używają interfejsów API mowy przeglądarki:

   • <speech-input-button>: konwertuje mowę na tekst przy użyciu API Mowy Internetowej SpeechRecognition. Zapewnia przycisk mikrofonu, który nasłuchuje wejściowego sygnału głosowego i emituje zdarzenie speech-input-result z transkrybowanym tekstem.

   • <speech-output-button>: odczytuje tekst na głos przy użyciu interfejsu SpeechSynthesis API. Pojawia się po każdej odpowiedzi asystenta z ikoną osoby mówiącej, co pozwala użytkownikom usłyszeć odpowiedź.

   Dlaczego warto używać interfejsów API przeglądarki zamiast usług Azure Speech Services?

   • Bez kosztów — działa w całości w przeglądarce
   • Natychmiastowa odpowiedź — brak opóźnienia sieci
   • Prywatność — dane głosowe pozostają na urządzeniu użytkownika
   • Brak potrzeby dodatkowych zasobów platformy Azure

   Te składniki znajdują się w elementach src/quartapp/static/speech-input.js i speech-output.js.

2. Podgląd obrazu: wyświetla przekazany obraz na czacie przed przesłaniem analizy w celu potwierdzenia. Podgląd jest aktualizowany automatycznie po wybraniu pliku.

   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 i Bootstrap Ikony: zapewnia dynamiczne składniki interfejsu użytkownika i ikony. Aplikacja używa motywu Cosmo z bootswatch do nowoczesnego wyglądu.

4. Renderowanie komunikatów oparte na szablonach: używa elementów HTML <template> do układów komunikatów wielokrotnego użytku, zapewniając spójne style i strukturę.

Inne przykładowe zasoby do eksplorowania

Oprócz przykładowej aplikacji do czatu istnieją inne zasoby w repozytorium, które można eksplorować, aby dowiedzieć się więcej. Zapoznaj się z następującymi notesami w notebooks katalogu:

Zlokalizowana zawartość: hiszpańskie wersje notatników znajdują się w notebooks/Spanish/ katalogu, oferując takie same praktyczne możliwości nauki dla hiszpańskojęzycznych programistów. Zarówno angielski, jak i hiszpański notesy pokazują:

• Jak wywoływać modele przetwarzania obrazów bezpośrednio na potrzeby eksperymentowania
• Jak konwertować strony PDF na obrazy na potrzeby analizy
• Jak dostosować parametry i polecenia testowe

Czyszczenie zasobów

Czyszczenie zasobów platformy Azure

Zasoby platformy Azure utworzone w tym artykule są rozliczane z subskrypcją platformy Azure. Jeśli nie spodziewasz się, że te zasoby będą potrzebne w przyszłości, usuń je, aby uniknąć naliczania dodatkowych opłat.

Aby usunąć zasoby platformy Azure i usunąć kod źródłowy, uruchom następujące polecenie interfejsu wiersza polecenia dla deweloperów platformy Azure:

azd down --purge

Czyszczenie usługi GitHub Codespaces

Uzyskaj pomoc

Zarejestruj problem w problemach repozytorium.

Następne kroki