거리 청소 로봇: 시맨틱 커널이 텔레그램 채팅을 실행 가능한 도시 트리아지로 바꾸는 방법

프로젝트 목표 및 영향

이 CivicBot 프로젝트의 핵심 목표는 다음과 같습니다:

보고 간소화: 텔레그램과 같은 친숙한 플랫폼을 통해 시민들이 문제를 매우 쉽게 보고할 수 있도록 합니다.
접근성 향상: 모든 사용자를 위해 다양한 입력(텍스트, 오디오, 이미지)을 지원합니다.
트리아지 및 로깅 자동화: 문제를 자동으로 분류하고, 세부 정보를 추출하여 구조화된 데이터베이스에 기록합니다.
가이드라인 준수: AI를 사용하여 관련 없거나 부적절한 제출을 엄격히 걸러내고, 유효한 시민 문제에 집중합니다.

도움이 되는 방법: 사용자가 도로의 쓰레기 사진을 간단히 보내는 것만으로도 시스템은 시민 참여의 마찰을 크게 줄이고, 도시 서비스가 정확하고, 타임스탬프가 찍히며, 위치가 기록된 증거를 받아 더 빠른 문제 해결 시간을 보장합니다.

필수 구성 요소: 시작하기

1. 텔레그램 봇 토큰 얻기

텔레그램 봇 API는 애플리케이션 인증을 위한 고유 토큰을 필요로 합니다. 이 토큰은 텔레그램의 공식 봇 생성 도구인 BotFather와 상호 작용하여 얻습니다.

필요한 텔레그램 봇 토큰을 얻는 단계는 다음과 같습니다:

BotFather 찾기: 텔레그램을 열고 인증된 사용자 @BotFather를 검색합니다.
대화 시작: BotFather에게 /start 명령을 보냅니다.
새 봇 생성: /newbot 명령을 보냅니다.
봇 이름 지정: BotFather가 표시 이름을 요청합니다 (예: "Civic Reporting Bot"). 원하는 이름을 입력합니다.
사용자 이름 설정: BotFather가 고유한 사용자 이름을 요청합니다. 이 이름은 "bot"으로 끝나야 합니다 (예: CivicBot_Demo). 고유한 사용자 이름을 입력합니다.
토큰 수신: 성공하면 BotFather가 단일 텍스트 문자열을 제공합니다: "HTTP API에 액세스하려면 이 토큰을 사용하세요:" 다음에 토큰 문자열이 나옵니다.
토큰 저장: 이 토큰을 복사합니다. 이것은 애플리케이션 설정(예: appsettings.json 또는 Azure App Service 구성)에서 구성할 TelegramBotToken입니다.

2. FFmpeg 다운로드 및 구성

텔레그램은 OGG/Opus 오디오 형식을 사용하므로, Azure AI Speech-to-Text에서 요구하는 WAV 형식으로 파일을 변환하기 위해 오픈 소스 도구인 FFmpeg를 사용합니다.

FFmpeg 다운로드: 공식 FFmpeg 사이트로 이동하여 Windows용 최신 안정 빌드를 다운로드합니다.
실행 파일 압축 해제: 다운로드 파일은 일반적으로 ZIP 파일입니다. 전체 파일을 압축 해제합니다.
폴더 생성: 프로젝트의 루트 디렉토리에 ffmpeg라는 새 폴더를 만듭니다.
실행 파일 배치: ffmpeg.exe 파일과 모든 관련 파일을 새로 생성된 ffmpeg 폴더에 직접 배치합니다.
appsettings.json 구성: appsettings.json 파일에 다음 키-값 쌍을 추가합니다. C# 코드가 런타임에 실행 파일을 찾는 방법입니다:

아키텍처 개요

아키텍처는 Azure App Service에서 호스팅되는 .NET Core 애플리케이션에 의해 조율되는 Azure 서비스의 심포니입니다.

아키텍처 다이어그램 (원문에는 이미지 경로가 없어 설명을 위해 임의 경로를 추가했습니다)

기술 심층 분석: 시맨틱 커널 구성 요소

핵심 인텔리전스는 시맨틱 커널 오케스트레이터에 의해 구동되며, 이는 다섯 가지 개별 플러그인(구성 요소)을 조율합니다:

구성 요소 이름 (코드 내)	단순화된 역할	핵심 기능
SessionManagementPlugin	오케스트레이터 (의사 결정 로직)	LLM 추론을 사용하여 다음 최적의 작업(Next Best Action)을 결정합니다: CREATE_TICKET, COLLECT_MORE_INFO, REQUEST_CONFIRMATION 등
AIAnalysisPlugin	이미지 / 오디오 (인텔리전스)	콘텐츠 분류, 가이드라인 준수, AI Foundry Vision Endpoint를 통한 분석을 위한 시맨틱 함수 (프롬프트)를 포함합니다.
MediaProcessingPlugin	오디오 / 이미지 (처리)	분석을 위한 파일 준비 및 위임을 포함하여 파일 수명 주기를 관리합니다.
CosmosDbPlugin	티켓팅 (영구 저장)	최종 ComplaintTicket 객체 및 대화 기록을 Azure Cosmos DB에 저장합니다.
BlobStoragePlugin	티켓팅 (증거 저장)	원본 미디어 파일을 Azure Blob Storage에 업로드하고, 티켓 기록을 위한 보안 URL을 반환합니다.

다중 모달 전처리: FFmpeg 단계

텔레그램 오디오(OGG/Opus 형식) 처리에 있어 중요한 세부 사항은 Azure AI Speech-to-Text에서 요구하는 변환 단계입니다. FFmpeg를 애플리케이션의 오디오 처리 로직에 직접 통합하여 AI 서비스에 호환되는 스트림만 전송하도록 합니다.

// TelegramBotUpdateHandler.cs에서 FFmpeg 변환 단계를 보여주는 코드 조각
using (var proc = new System.Diagnostics.Process())
{
    // ... FFmpeg 경로 설정
    // 입력 (OGG)을 Azure Speech용 16kHz 모노 WAV로 변환
    proc.StartInfo.Arguments = $"-y -i \"{tempIn}\" -ar 16000 -ac 1 -f wav \"{tempWav}\"";
    // 변환 실행...
}
// 변환된 스트림은 Azure AI Speech SDK로 전달됩니다.

대화 스크린샷

사용자가 쓰레기 사진을 보낸 후, 봇의 확인 프롬프트

사용자 쓰레기 사진 전송 후 봇 응답 이 시나리오에서 봇은 이미지를 처리한 후 진행 확인을 요청했습니다.

이 시나리오에서 채팅 중 콘솔 로그

콘솔 로그

이 대화 후 Cosmos DB 로그

{
  "id": "6672d3d5-48c6-42d7-90c4-05bda042a4d4",
  "userId": 801,
  "chatId": 801,
  "userFullName": "K T",
  "mobileNumber": null,
  "textSummary": "Location: Street 16, Sector 19, Gurugram 
Issue: Garbage 
Severity: High; Location: Street 16, Sector 19, Gurugram 
Issue: Garbage removal 
Severity: High",
  "attachments": [
    {
      "fileType": "Image",
      "blobUrl": "https://abc.blob.core.windows.net/complaints/fc3bb274-5566-47a8-b56c-ae2577eed040.jpeg",
      "caption": "Please help removing this garbage from Street 16, Sector 19, Gurugram",
      "Transcript": null
    }
  ],
  "conversations": [
    {
      "role": "user",
      "content": "/start",
      "timestamp": "2025-11-18T18:45:27.5063715Z",
      "messageType": "text"
    },
    {
      "role": "assistant",
      "content": "Hello there! I'm CivicBot, your friendly sanitation assistant here to help with any garbage, waste, drains, or sewage concerns you may have. What can I assist you with today?",
      "timestamp": "2025-11-18T18:45:31.0887884Z",
      "messageType": "text"
    },
    {
      "role": "user",
      "content": "Please help removing this garbage from Street 16, Sector 19, Gurugram",
      "timestamp": "2025-11-18T18:46:08.1713574Z",
      "messageType": "photo"
    },
    {
      "role": "assistant",
      "content": "I've noted your request for garbage removal on Street 16, Sector 19, Gurugram, marked as a high-severity issue. Ready to log this?",
      "timestamp": "2025-11-18T18:46:27.8353554Z",
      "messageType": "text"
    },
    {
      "role": "user",
      "content": "Yes",
      "timestamp": "2025-11-18T18:46:45.242703Z",
      "messageType": "text"
    }
  ],
  "status": "New",
  "timestamp": "2025-11-18T18:45:27.5038736Z",
  "_rid": "UAwVAKY1fTQyAAAAAAAAAA==",
  "_self": "dbs/UAwVAA==/colls/UAwVAKY1fTQ=/docs/UAwVAKY1fTQyAAAAAAAAAA==/",
  "_etag": "\"0301a222-0000-0800-0000-691cbf1b0000\"",
  "_attachments": "attachments/",
  "_ts": 1763491611
}

2. 사용자가 음성 메시지(오디오)를 보낸 후 봇의 전사 및 분석

사용자 음성 메시지 전송 후 봇 응답 이 시나리오에서 사용자는 오디오 노트로 응답했지만, 봇은 여전히 이를 티켓 처리의 맥락으로 이해합니다.

3) 사용자가 시민 문제와 관련 없는 주제 외의 사진을 보낸 후, 봇의 확인 프롬프트.

사용자 관련 없는 사진 전송 후 봇 응답 이 시나리오에서 봇은 Azure AI Vision을 통해 분석한 후 원하는 주제로 자연스럽게 전환했습니다.

일반적인 흐름은 다음과 같습니다:

사용자 행동: 시민이 문제의 사진이나 오디오 녹음을 보냅니다.
봇 처리: 미디어가 처리되고(오디오는 FFmpeg, 이미지는 AI Foundry Vision Endpoint) 분석됩니다.
봇 응답: 오케스트레이터가 확인을 요청합니다: "도로를 막고 있는 큰 쓰레기 더미가 보입니다. 즉시 신고할까요?"
해결: 사용자가 확인하면 티켓팅 구성 요소가 Azure Cosmos DB에 티켓을 기록하고 추적 ID를 반환합니다.

미래 개선 사항: 에이전트 역량 강화의 길

시맨틱 커널 아키텍처는 견고하지만, 미래 발전을 위한 훌륭한 플랫폼을 제공합니다. 우리의 로드맵에는 두 가지 중요한 기술 업그레이드가 포함됩니다:

1. Azure Video Indexer를 사용한 고급 비디오 처리

현재 솔루션은 비디오 및 비디오 노트 파일 처리에 대한 자리 표시자 기능을 사용합니다. 중요한 업그레이드는 Azure Video Indexer를 통합하는 것입니다. 이 변화는 다음을 가능하게 합니다:

객체 및 장면 감지: 비디오 프레임 내에서 "쓰레기," "더미," 또는 **"막힌 거리"**와 같은 주요 시각적 증거를 직접 식별합니다.
키프레임 추출: 최종 티켓에 첨부할 고신뢰 증거로 가장 관련성이 높은 시각적 순간을 자동으로 선택합니다.
실행 가능한 인사이트: 단순한 전사를 넘어 녹화된 증거에 대한 심층적인 시각 및 청각 분석을 제공합니다.

2. Microsoft Agent Framework로 마이그레이션

시맨틱 커널이 단일 에이전트 오케스트레이터를 효율적으로 관리하지만, 고도로 정교한 시스템으로 확장하려면 Microsoft Agent Framework (MAF)가 도움이 될 것입니다. MAF는 다중 에이전트 워크플로우를 위해 설계되었으며, 다음을 가능하게 합니다:

복잡한 라우팅 구현: 단일 라우터에서 여러 전문 에이전트(예: 트리아지 에이전트가 확인 에이전트로 작업을 넘기는 등)에 걸쳐 대화 흐름을 관리하는 프레임워크로 전환합니다.
병렬 에이전트: "이력 조회 에이전트" 또는 **"주소 확인 에이전트"**와 같은 전용 에이전트를 병렬 작업에 배포하고, 이들 모두를 중앙 MAF 감독자가 조율합니다.

결론

시맨틱 커널을 AI Foundry Vision Endpoint 및 Azure AI Speech와 같은 전문 서비스와 결합함으로써, 우리는 단순한 챗봇을 넘어 진정한 에이전트 워크플로우를 구현했습니다. 이 봇은 단지 채팅만 하는 것이 아닙니다. 쓰레기를 보고, 오디오를 변환하며, 긴급성을 이해하고, 보고서를 제출하기 위해 행동합니다. 이 아키텍처는 확장 가능하고, 안전하며, 가장 중요하게는 시민들이 도시를 깨끗하게 유지하는 데 대한 장벽을 낮춥니다.

참고 자료

이 프로젝트의 전체 소스 코드와 기술 구현 세부 정보는 GitHub에서 확인할 수 있습니다:

Github - vikaspandeyazure/CivicBot

참고: 이 코드는 POC(개념 증명) 코드 스켈레톤이며, 이미지, 오디오 또는 기타 첨부 파일의 완벽한 분석을 위해서는 프롬프트 튜닝이 필요할 수 있습니다.