자습서: Phi-4 사이드카 확장(Express.js)을 사용하여 App Service에서 챗봇 실행

2025-05-08

이 자습서에서는 Azure App Service의 Phi-4 사이드카 확장과 통합된 Express.js기반 챗봇 애플리케이션을 배포하는 단계를 안내합니다. 단계에 따라 확장 가능한 웹앱을 설정하고, 향상된 대화 기능을 위해 AI 기반 사이드카를 추가하고, 챗봇의 기능을 테스트하는 방법을 알아봅니다.

고유한 SLM(작은 언어 모델)을 호스팅하면 다음과 같은 몇 가지 이점이 있습니다.

귀하의 데이터에 대한 완전한 제어권. 중요한 정보는 엄격한 규정 준수 요구 사항을 가진 산업에 중요한 외부 서비스에 노출되지 않습니다.
자체 호스팅 모델은 특정 사용 사례 또는 도메인별 요구 사항을 충족하도록 미세 조정할 수 있습니다.
네트워크 대기 시간을 최소화하고 응답 시간을 단축하여 사용자 환경을 개선합니다.
리소스 할당을 완전히 제어하여 애플리케이션에 최적의 성능을 보장합니다.

필수 조건

활성 구독이 있는 Azure 계정 입니다.
GitHub 계정

샘플 애플리케이션 배포

브라우저에서 샘플 애플리케이션 리포지토리로 이동합니다.
리포지토리에서 새 Codespace를 시작합니다.
Azure 계정으로 로그인합니다.
```
az login
```
Codespace에서 터미널을 열고 다음 명령을 실행합니다.
```
cd use_sidecar_extension/expressapp
az webapp up --sku P3MV3
```

이 시작 명령은 azure App Service에 Express.js 애플리케이션을 배포하기 위한 일반적인 설정입니다. 자세한 내용은 Azure에서 Node.js 웹앱 배포를 참조하세요.

Phi-4 사이드카 확장 추가

이 섹션에서는 Azure App Service에서 호스트되는 ASP.NET Core 애플리케이션에 Phi-4 사이드카 확장을 추가합니다.

Azure Portal로 이동하여 앱의 관리 페이지로 이동합니다.
왼쪽 메뉴에서 배포>배포 센터를 선택합니다.
컨테이너 탭에서사이드카 확장>를 선택합니다.
사이드카 확장 옵션에서 AI: phi-4-q4-gguf(실험적)를 선택합니다.
사이드카 확장의 이름을 입력합니다.
변경 내용을 적용하려면 저장을 선택합니다.
사이드카 확장이 배포되기까지 몇 분 정도 기다립니다. 상태 열에 실행 중이 표시될 때까지 새로 고침을 계속 선택합니다.

이 Phi-4 사이드카 확장은 OpenAI와 같은 채팅 완료 API 를 사용하여 채팅 완료 응답에 http://localhost:11434/v1/chat/completions응답할 수 있습니다. API와 상호 작용하는 방법에 대한 자세한 내용은 다음을 참조하세요.

챗봇 테스트

앱의 관리 페이지의 왼쪽 메뉴에서 개요를 선택합니다.
기본 도메인에서 URL을 선택하여 브라우저에서 웹앱을 엽니다.
챗봇 애플리케이션이 실행 중이고 사용자 입력에 응답하고 있는지 확인합니다.

샘플 애플리케이션의 작동 방식

샘플 애플리케이션은 Express.js기반 서비스를 SLM 사이드카 확장과 통합하는 방법을 보여 줍니다. 클래스는 SLMService SLM API에 요청을 보내고 스트리밍된 응답을 처리하는 논리를 캡슐화합니다. 이 통합을 통해 애플리케이션은 대화형 응답을 동적으로 생성할 수 있습니다.

use_sidecar_extension/expressapp/src/services/slm_service.js에서 보면 다음을 볼 수 있습니다.

서비스는 SLM 엔드포인트 http://127.0.0.1:11434/v1/chat/completions에 POST 요청을 보냅니다.
```
this.apiUrl = 'http://127.0.0.1:11434/v1/chat/completions';
```

POST 페이로드에는 선택한 제품 및 사용자 쿼리에서 빌드된 시스템 메시지와 프롬프트가 포함됩니다.

const requestPayload = {
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: prompt }
  ],
  stream: true,
  cache_prompt: false,
  n_predict: 2048 // Increased token limit to allow longer responses
};

POST 요청은 응답 줄을 한 줄씩 스트리밍합니다. 각 줄은 구문 분석되어 생성된 콘텐츠(또는 토큰)를 추출합니다.

// Set up Server-Sent Events headers
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
res.flushHeaders();

const response = await axios.post(this.apiUrl, requestPayload, {
  headers: { 'Content-Type': 'application/json' },
  responseType: 'stream'
});

response.data.on('data', (chunk) => {
  const lines = chunk.toString().split('\n').filter(line => line.trim() !== '');

  for (const line of lines) {
    let parsedLine = line;
    if (line.startsWith('data: ')) {
      parsedLine = line.replace('data: ', '').trim();
    }

    if (parsedLine === '[DONE]') {
      return;
    }

    try {
      const jsonObj = JSON.parse(parsedLine);
      if (jsonObj.choices && jsonObj.choices.length > 0) {
        const delta = jsonObj.choices[0].delta || {};
        const content = delta.content;

        if (content) {
          // Use non-breaking space to preserve formatting
          const formattedToken = content.replace(/ /g, '\u00A0');
          res.write(`data: ${formattedToken}\n\n`);
        }
      }
    } catch (parseError) {
      console.warn(`Failed to parse JSON from line: ${parsedLine}`);
    }
  }
});

가격 책정 계층은 SLM 사이드카의 성능에 어떤 영향을 주나요?

AI 모델은 상당한 리소스를 사용하므로 특정 모델을 실행할 수 있는 충분한 vCPU 및 메모리를 제공하는 가격 책정 계층을 선택합니다. 이러한 이유로 기본 제공 AI 사이드카 확장은 앱이 적절한 가격 책정 계층에 있을 때만 표시됩니다. 자체 SLM 사이드카 컨테이너를 빌드하는 경우 App Service 가격 책정 계층은 CPU 전용 계층이므로 CPU 최적화 모델도 사용해야 합니다.

예를 들어 Hugging Face의 4K 컨텍스트 길이가 있는 Phi-3 미니 모델은 제한된 리소스로 실행되도록 설계되었으며 많은 일반적인 시나리오에 대해 강력한 수학 및 논리적 추론을 제공합니다. CPU 최적화 버전도 함께 제공됩니다. App Service에서 모든 프리미엄 계층에서 모델을 테스트하고 P2mv3 계층 이상에서 성능이 좋은 것으로 나타났습니다. 요구 사항이 허용되는 경우 하위 계층에서 실행할 수 있습니다.

내 SLM 사이드카를 사용하는 방법

샘플 리포지토리에는 사이드카로 사용할 수 있는 샘플 SLM 컨테이너가 포함되어 있습니다. Dockerfile에 지정된 대로 포트 8000에서 수신 대기하는 FastAPI 애플리케이션을 실행합니다. 애플리케이션은 ONNX 런타임을 사용하여 Phi-3 모델을 로드한 다음, HTTP POST 데이터를 모델에 전달하고 모델에서 클라이언트로 응답을 다시 스트리밍합니다. 자세한 내용은 model_api.py 참조하세요.

사이드카 이미지를 직접 빌드하려면 컴퓨터에 Docker Desktop을 로컬로 설치해야 합니다.

리포지토리를 로컬로 복제합니다.

git clone https://github.com/Azure-Samples/ai-slm-in-app-service-sidecar
cd ai-slm-in-app-service-sidecar

Phi-3 이미지의 원본 디렉터리로 변경하고 Huggingface CLI를 사용하여 모델을 로컬로 다운로드합니다.
```
cd bring_your_own_slm/src/phi-3-sidecar
huggingface-cli download microsoft/Phi-3-mini-4k-instruct-onnx --local-dir ./Phi-3-mini-4k-instruct-onnx
```
Dockerfile은 ./Phi-3-mini-4k-instruct-onnx에서 모델을 복사하도록 구성됩니다.
Docker 이미지를 빌드합니다. 다음은 그 예입니다.
```
docker build --tag phi-3 .
```
Docker CLI를 사용하여 첫 번째 이미지를 Azure Container Registry에 푸시하여 빌드된 이미지를 Azure Container Registry에 업로드합니다.
배포 센터>컨테이너(새) 탭에서사용자 지정 컨테이너>를 선택하고 다음과 같이 새 컨테이너를 구성합니다.
- 이름: phi-3
- 이미지 원본: Azure Container Registry
- 레지스트리: 당신의 레지스트리
- 이미지: 업로드된 이미지
- 태그: 원하는 이미지 태그
- 포트: 8000
적용을 선택합니다.

이 사용자 지정 사이드카 컨테이너와 상호 작용하는 샘플 애플리케이션은 bring_your_own_slm/src/webapp 을 참조하세요.

다음 단계

자습서: Azure App Service에서 Linux 앱용 사이드카 컨테이너 구성