Azure OpenAI를 사용하여 멀티모달 비전 채팅 앱 시작

이 문서에서는 Azure OpenAI 멀티모달 모델을 사용하여 채팅 앱에서 사용자 메시지 및 업로드된 이미지에 대한 응답을 생성하는 방법을 보여 줍니다. 또한 이 채팅 앱 샘플에는 Azure OpenAI 리소스를 프로비전하고 Azure Developer CLI를 사용하여 Azure Container Apps에 앱을 배포하는 데 필요한 모든 인프라 및 구성이 포함되어 있습니다.

이 문서의 지침을 따르면 다음을 수행할 수 있습니다.

• 인증에 관리 ID를 사용하는 Azure Container Chat 앱을 배포합니다.
• 채팅 스트림의 일부로 사용할 이미지를 업로드합니다.
• OpenAI 라이브러리를 사용하여 Azure OpenAI LLM(Multimodal Large Language Model)과 채팅합니다.

이 문서를 완료하면 사용자 지정 코드를 사용하여 새 프로젝트 수정을 시작할 수 있습니다.

아키텍처 개요

채팅 앱의 간단한 아키텍처는 다음 다이어그램에 나와 있습니다.

채팅 앱이 Azure Container App으로 실행되고 있습니다. 앱은 Microsoft Entra ID를 통해 관리 ID를 사용하여 API 키 대신 프로덕션 환경에서 Azure OpenAI로 인증합니다. 개발하는 동안 앱은 Azure 리소스 없이 테스트하기 위해 Azure 개발자 CLI 자격 증명, API 키 및 GitHub 모델을 비롯한 여러 인증 방법을 지원합니다.

애플리케이션 아키텍처는 다음 서비스 및 구성 요소를 사용합니다.

• Azure OpenAI 는 사용자의 쿼리를 보내는 AI 공급자를 나타냅니다.
• Azure Container Apps 는 애플리케이션이 호스트되는 컨테이너 환경입니다.
• 관리 ID는 동급 최고의 보안을 보장하고 개발자가 비밀을 안전하게 관리하기 위한 요구 사항을 제거하는 데 도움이 됩니다.
• Azure OpenAI, Azure Container Apps, Azure Container Registry, Azure Log Analytics 및 RBAC(역할 기반 액세스 제어) 역할을 포함하여 Azure 리소스를 프로비전하기 위한 Bicep 파일 입니다.
• Microsoft AI 채팅 프로토콜 은 AI 솔루션 및 언어에서 표준화된 API 계약을 제공합니다. 채팅 앱은 Microsoft AI 채팅 프로토콜을 준수합니다.
• 패키지를 사용하여 업로드된 이미지 파일을 사용하여 사용자 메시지에 대한 응답을 생성하는 Python openai입니다.
• ReadableStream을 통해 JSON 선을 사용하여 백 엔드에서 응답을 스트리밍하는 기본 HTML/JavaScript 프런트 엔드입니다.

비용

이 샘플에서 가격을 최대한 낮게 유지하기 위해 대부분의 리소스는 기본 또는 소비 가격 책정 계층을 사용합니다. 의도한 사용량에 따라 필요에 따라 계층 수준을 변경합니다. 요금 발생을 중지하려면 문서를 완료하면 리소스를 삭제합니다.

샘플 리포지토리의 비용에 대해 자세히 알아봅니다.

필수 조건

이 문서를 완료하는 데 필요한 모든 종속성을 갖춘 개발 컨테이너 환경을 사용할 수 있습니다. GitHub Codespaces(브라우저)에서 개발 컨테이너를 실행하거나 Visual Studio Code를 사용하여 로컬로 실행할 수 있습니다.

이 문서를 사용하려면 다음 필수 조건을 충족해야 합니다.

개방형 개발 환경

다음 지침을 사용하여 이 문서를 완료하는 데 필요한 모든 종속성을 포함하는 미리 구성된 개발 환경을 배포합니다.

배포 및 실행

샘플 리포지토리에는 채팅 앱 Azure 배포에 대한 모든 코드 및 구성 파일이 포함되어 있습니다. 다음 단계에서는 샘플 채팅 앱 Azure 배포 프로세스를 안내합니다.

Azure에 채팅 앱 배포

1. Azure 리소스 프로비저닝 및 소스 코드 배포에 대해 다음 Azure Developer CLI 명령을 실행합니다.

   azd up
   

2. 다음 표를 사용하여 프롬프트에 응답합니다.

   prompt	답변
   환경 이름	짧고 소문자를 유지합니다. 이름 또는 별칭을 추가합니다. 예들 들어 chat-vision입니다. 리소스 그룹 이름의 일부로 사용됩니다.
   구독	리소스를 만들 구독을 선택합니다.
   위치(호스팅용)	목록에서 가까운 위치를 선택합니다.
   Azure OpenAI 모델의 위치	목록에서 가까운 위치를 선택합니다. 첫 번째 위치와 동일한 위치를 사용할 수 있는 경우 해당 위치를 선택합니다.

3. 앱이 배포될 때까지 기다립니다. 배포를 완료하는 데 일반적으로 5~10분이 걸립니다.

채팅 앱을 사용하여 큰 언어 모델에 질문하기

1. 터미널은 애플리케이션 배포에 성공한 후 URL을 표시합니다.

2. 브라우저에서 채팅 애플리케이션을 열려면 Deploying service web이라고 표시된 URL을 선택합니다.

   

3. 브라우저에서 파일 선택을 클릭하고 이미지를 선택하여 이미지를 업로드합니다.

4. 업로드된 이미지에 대한 질문(예: "이미지는 무엇인가요?").

5. 답변은 Azure OpenAI에서 제공되며 결과가 표시됩니다.

샘플 코드 탐색

OpenAI 및 Azure OpenAI 서비스는 일반적인 Python 클라이언트 라이브러리를 사용하지만 Azure OpenAI 엔드포인트를 사용할 때는 작은 코드 변경이 필요합니다. 이 샘플에서는 Azure OpenAI 멀티모달 모델을 사용하여 사용자 메시지 및 업로드된 이미지에 대한 응답을 생성합니다.

Base64 프런트 엔드에 업로드된 이미지 인코딩

업로드된 이미지는 메시지의 일부로 데이터 URI로 직접 사용할 수 있도록 Base64로 인코딩되어야 합니다.

샘플에서 파일 태그의 다음 프런트 엔드 코드 조각 script은 src/quartapp/templates/index.html 해당 기능을 처리합니다. 화살표 함수는 toBase64 업로드된 이미지 파일에서 base64로 인코딩된 문자열로 비동기적으로 읽는 메서드readAsDataURL를 사용합니다FileReader.

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

toBase64 함수는 폼의 submit 이벤트에 대한 수신기에 의해 호출됩니다.

이벤트 수신기는 submit 전체 채팅 상호 작용 흐름을 처리합니다. 사용자가 메시지를 제출하면 다음 흐름이 발생합니다.

1. "no-messages-heading" 요소를 숨겨 대화를 시작했음을 표시합니다.
2. 업로드된 이미지 파일을 가져오고 Base64로 인코딩합니다(있는 경우).
3. 업로드된 이미지를 포함하여 채팅에서 사용자의 메시지를 만들고 표시합니다.
4. "입력 중..." 표시가 있는 도우미 메시지 컨테이너를 준비합니다.
5. 메시지 기록 배열에 사용자의 메시지를 추가합니다.
6. 메시지 기록 및 컨텍스트(Base64로 인코딩된 이미지 및 파일 이름 포함)를 사용하여 AI 채팅 프로토콜 클라이언트의 getStreamedCompletion() 메서드를 호출합니다.
7. 스트리밍된 응답 청크를 처리하고 Showdown.js 사용하여 Markdown을 HTML로 변환합니다.
8. 스트리밍 중 오류 처리
9. 사용자가 응답을 들을 수 있도록 전체 응답을 받은 후 음성 출력 단추를 추가합니다.
10. 입력 필드를 지우고 다음 메시지에 대한 포커스를 반환합니다.

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

백 엔드를 사용하여 이미지 처리

파일에서 src\quartapp\chat.py 이미지 처리에 대한 백 엔드 코드는 키 없는 인증을 구성한 후에 시작됩니다.

인증 구성

이 함수는 configure_openai() 앱이 요청 처리를 시작하기 전에 OpenAI 클라이언트를 설정합니다. Quart의 @bp.before_app_serving 데코레이터를 사용하여 환경 변수에 따라 인증을 구성합니다. 이 유연한 시스템을 통해 개발자는 코드를 변경하지 않고도 다양한 컨텍스트에서 작업할 수 있습니다.

인증 모드 설명

• 로컬 개발 (OPENAI_HOST=local): 인증 없이 로컬 OpenAI 호환 API 서비스(예: Ollama 또는 LocalAI)에 연결합니다. 인터넷 또는 API 비용 없이 테스트하려면 이 모드를 사용합니다.
• GitHub 모델 (OPENAI_HOST=github): 인증을 위해 GitHub의 AI 모델 마켓플레이스를 GITHUB_TOKEN 사용합니다. GitHub 모델을 사용하는 경우 모델 이름 앞에 접두사를 추가 openai/ 합니다(예: openai/gpt-4o). 이 모드를 사용하면 개발자가 Azure 리소스를 프로비전하기 전에 모델을 시도할 수 있습니다.
• API 키 (AZURE_OPENAI_KEY_FOR_CHATVISION 환경 변수)를 사용하는 Azure OpenAI: 인증에 API 키를 사용합니다. API 키에는 수동 회전이 필요하고 노출될 경우 보안 위험이 있으므로 프로덕션에서 이 모드를 사용하지 마세요. Azure CLI 자격 증명이 없는 Docker 컨테이너 내에서 로컬 테스트에 사용합니다.
• 관리 ID를 사용한 프로덕션 (RUNNING_IN_PRODUCTION=true): 컨테이너 앱의 관리 ID를 통해 Azure OpenAI로 인증하는 데 사용됩니다 ManagedIdentityCredential . 이 메서드는 비밀을 관리할 필요가 없으므로 프로덕션에 권장됩니다. Azure Container Apps는 Bicep을 통해 배포하는 동안 관리 ID를 자동으로 제공하고 권한을 부여합니다.
• Azure CLI를 사용한 개발 (기본 모드): 로컬로 로그인한 Azure CLI 자격 증명을 사용하여 Azure OpenAI로 인증하는 데 사용합니다 AzureDeveloperCliCredential . 이 모드는 API 키를 관리하지 않고 로컬 개발을 간소화합니다.

주요 구현 세부 정보

• 함수는 get_bearer_token_provider() Azure 자격 증명을 새로 고치고 전달자 토큰으로 사용합니다.
• Azure OpenAI 엔드포인트 경로에는 OpenAI 클라이언트 라이브러리의 요구 사항과 일치하는 경로가 포함 /openai/v1/ 됩니다.
• 로깅은 활성 상태인 인증 모드를 보여 줍니다.
• 이 함수는 Azure 자격 증명 작업을 지원하기 위한 비동기입니다.

다음은 다음의 전체 인증 설정 코드입니다.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)

채팅 처리기 함수

함수는 chat_handler() 엔드포인트로 /chat/stream 전송된 채팅 요청을 처리합니다. Microsoft AI 채팅 프로토콜을 따르는 JSON 페이로드를 사용하여 POST 요청을 받습니다.

JSON 페이로드에는 다음이 포함됩니다.

• messages: 대화 기록 목록입니다. 각 메시지에는 role ("user" 또는 "assistant") 및 content (메시지 텍스트)가 있습니다.
• 컨텍스트: 다음을 포함하여 처리를 위한 추가 데이터입니다.
  • file: Base64로 인코딩된 이미지 데이터(예: data:image/png;base64,...).
  • file_name: 업로드된 이미지의 원래 파일 이름입니다(이미지 형식을 로깅하거나 식별하는 데 유용).
• 온도 (선택 사항): 응답 임의성을 제어하는 float입니다(기본값은 0.5).

처리기는 메시지 기록 및 이미지 데이터를 추출합니다. 업로드된 이미지가 없으면 이미지 값이 null반환되고 코드에서 이 경우를 처리합니다.

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

비전 요청에 대한 메시지 배열 빌드

이 함수는 response_stream() Azure OpenAI API로 전송되는 메시지 배열을 준비합니다. 데코레이터는 @stream_with_context 응답을 스트리밍하는 동안 요청 컨텍스트를 유지합니다.

메시지 준비 논리

1. 대화 기록으로 시작: 함수는 시스템 메시지와 가장 최근의all_messages 메시지를 제외한 모든 이전 메시지를 포함하는 것으로 시작request_messages[0:-1]합니다.
2. 이미지 현재 상태를 기반으로 현재 사용자 메시지를 처리합니다.
   • 이미지 사용: 텍스트 및 image_url 개체를 사용하여 사용자의 메시지를 여러 부분으로 구성된 콘텐츠 배열로 서식을 지정합니다. 개체에는 image_url Base64로 인코딩된 이미지 데이터와 매개 변수가 detail 포함됩니다.
   • 이미지 없음: 사용자의 메시지를 일반 텍스트로 추가합니다.
3. detail 매개 변수: 모델이 이미지 크기에 따라 "낮음" 및 "높음" 세부 정보 중에서 선택할 수 있도록 하려면 "auto"로 설정합니다. 낮은 세부 정보는 더 빠르고 저렴하며, 높은 세부 정보는 복잡한 이미지에 대한 보다 정확한 분석을 제공합니다.

    @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 Azure OpenAI API 호출을 통해 채팅 완료를 가져오고 응답을 스트리밍합니다.

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

마지막으로, 응답은 예외에 대한 오류 처리와 함께 클라이언트로 다시 스트리밍됩니다.

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

프런트 엔드 라이브러리 및 기능

프런트 엔드는 최신 브라우저 API 및 라이브러리를 사용하여 대화형 채팅 환경을 만듭니다. 개발자는 다음 구성 요소를 이해하여 인터페이스를 사용자 지정하거나 기능을 추가할 수 있습니다.

1. 음성 입력/출력: 사용자 지정 웹 구성 요소는 브라우저의 Speech API를 사용합니다.

   • <speech-input-button>: Web Speech API를 사용하여 음성을 텍스트로 변환합니다 SpeechRecognition. 음성 입력을 수신 대기하고 전사된 텍스트로 이벤트를 내보내는 speech-input-result 마이크 단추를 제공합니다.

   • <speech-output-button>: SpeechSynthesis API를 사용하여 텍스트를 소리 내어 읽습니다. 스피커 아이콘이 있는 각 도우미 응답 후에 표시되어 사용자가 응답을 들을 수 있도록 합니다.

   Azure Speech Services 대신 브라우저 API를 사용하는 이유는 무엇인가요?

   • 비용 없음 - 브라우저에서 전적으로 실행
   • 즉각적인 응답 - 네트워크 대기 시간 없음
   • 개인 정보 보호 - 음성 데이터가 사용자의 디바이스에 유지됩니다.
   • 추가 Azure 리소스가 필요하지 않음

   이러한 구성 요소는 src/quartapp/static/speech-input.js 및 speech-output.js에 있습니다.

2. 이미지 미리 보기: 확인을 위해 분석 제출 전에 채팅에 업로드된 이미지를 표시합니다. 파일이 선택되면 미리 보기가 자동으로 업데이트됩니다.

   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. 부트스트랩 5 및 부트스트랩 아이콘: 반응형 UI 구성 요소 및 아이콘을 제공합니다. 이 앱은 부트스워치의 Cosmo 테마를 사용하여 현대적인 룩을 연출합니다.

4. 템플릿 기반 메시지 렌더링: 재사용 가능한 메시지 레이아웃에 HTML <template> 요소를 사용하여 일관된 스타일 지정 및 구조를 보장합니다.

탐색할 기타 샘플 리소스

채팅 앱 샘플 외에도 추가 학습을 위해 탐색할 수 있는 다른 리소스가 리포지토리에 있습니다. 디렉터리에서 다음 Notebook을 notebooks 확인합니다.

지역화된 콘텐츠: 스페인어 버전의 Notebook은 디렉터리에 있으며 notebooks/Spanish/ 스페인어를 사용하는 개발자에게 동일한 실습 학습을 제공합니다. 영어 및 스페인어 전자 필기장 모두 다음을 보여 줍니다.

• 실험을 위해 비전 모델을 직접 호출하는 방법
• 분석을 위해 PDF 페이지를 이미지로 변환하는 방법
• 매개 변수를 조정하고 프롬프트를 테스트하는 방법

리소스 정리

Azure 리소스 정리

이 문서에서 만들어진 Azure 리소스는 Azure 구독에 요금이 청구됩니다. 앞으로 이러한 리소스가 필요하지 않을 것으로 예상되는 경우 추가 요금이 발생하지 않도록 삭제합니다.

Azure 리소스를 삭제하고 소스 코드를 제거하려면 다음 Azure Developer CLI 명령을 실행합니다.

azd down --purge

GitHub Codespaces 정리

도움말 보기

리포지토리의 문제에 문제를 기록합니다.

다음 단계