API Documentation

폐음 진단 API

개요

폐음 진단 API는 사용자가 업로드한 폐음(호흡 소리) 오디오 파일을 분석하여 정상 폐음(Normal), 수포음(Crackles), 천명음(Wheezes), 혼합음(Both) 중 어떤 종류인지 예측합니다.

폐음 예시 및 재생

1. 정상 폐음 (Normal Lung Sound)

정상적인 폐 소리는 숨을 들이쉬고 내쉴 때 나는 부드럽고 깨끗한 소리입니다.
마치 조용한 방에서 귀를 기울이면 들리는 바람 소리처럼 특별한 잡음이 섞여 있지 않습니다.

2. 수포음 (Crackle)

머리카락을 비비거나 장작이 타는 듯한 ‘타닥’거리는 소리가 특징입니다.
주로 숨을 들이쉴 때 들리며, 폐에 액체(가래 등)가 차 있거나 폐포가 갑자기 열릴 때 나는 소리입니다.
폐렴이나 폐부종 등 질환을 의심할 수 있습니다.

3. 천명음 (Wheeze)

휘파람 소리나 ‘쌕쌕’거리는 소리가 특징입니다.
주로 숨을 내쉴 때 들리며, 기도가 좁아졌을 때 공기가 통과하면서 나는 소리입니다.
천식(asthma)이나 만성 폐쇄성 폐질환(COPD) 등에서 흔히 들을 수 있습니다.

4. 혼합음 (Both)

수포음과 천명음이 동시에 들리는 경우입니다.
복합적인 폐 질환이나 심각한 호흡기 문제를 나타낼 수 있어 주의가 필요합니다.

참고: 혼합음의 경우 별도 샘플 파일이 없으나, 위의 샘플들을 통해 각 소리의 특징을 이해할 수 있습니다.

API 엔드포인트

메서드	경로	설명
GET	`/`	서비스 상태 확인
GET	`/health`	모델 로딩 상태 확인
POST	`/predict`	단일 폐음 파일 분류
GET	`/info`	모델 정보 조회

요청(Request)

HTTP 메서드 & URL

POST /predict
Host: localhost:9000

요청 헤더(Request Headers)

이름	설명
`Accept`	`application/json`
`Content-Type`	`multipart/form-data`
`X-Internal-Auth`	내부 인증 토큰 (필수)

요청 바디(Request Body)

multipart/form-data 형식으로 오디오 파일을 업로드합니다.

필드명	타입	설명
`file`	`file`	분석할 오디오 파일 (mp3, wav, m4a, flac 등)

응답(Response)

성공 응답 (200)

{
  "prediction": 1,
  "predicted_label": "Crackles",
  "confidence": 0.892,
  "probabilities": {
    "Normal": 0.045,
    "Crackles": 0.892,
    "Wheezes": 0.051,
    "Both": 0.012
  },
  "metadata": {
    "filename": "lung_sound.wav",
    "file_size": 156780,
    "model_used": "beats"
  }
}

응답 필드 설명

prediction: 예측된 클래스 번호 (0: Normal, 1: Crackles, 2: Wheezes, 3: Both)
predicted_label: 예측된 클래스의 라벨명
confidence: 예측 신뢰도 (0.0 ~ 1.0)
probabilities: 각 클래스별 확률값
metadata: 파일 및 모델 관련 메타데이터

일괄 처리 응답 (POST /predict_batch)

{
  "results": [
    {
      "prediction": 0,
      "predicted_label": "Normal",
      "confidence": 0.934,
      "probabilities": {
        "Normal": 0.934,
        "Crackles": 0.032,
        "Wheezes": 0.024,
        "Both": 0.010
      },
      "metadata": {
        "filename": "normal_breath.wav",
        "file_size": 145230,
        "index": 0
      }
    }
  ]
}

오류 응답

서비스 이용 불가 (503)

{
  "detail": "Classifier not loaded"
}

잘못된 요청 (400)

{
  "detail": "Invalid request parameters"
}

지원하지 않는 파일 형식 (400)

{
  "detail": "Unsupported file format. Please use wav, mp3, m4a, or flac"
}

내부 서버 오류 (500)

{
  "detail": "Internal server error: [오류 메시지]"
}

샘플 CURL

# 내부 인증 토큰 생성 (Node.js/Python 예시)
timestamp=$(date +%s)
signature=$(echo -n "$timestamp" | openssl dgst -sha256 -hmac "dev_secret" -binary | base64 -w 0)
auth_token="$timestamp.$signature"

# API 호출
curl -X POST "http://localhost:9000/predict" \
  -H "Accept: application/json" \
  -H "X-Internal-Auth: $auth_token" \
  -F "file=@lung_sound.wav"

🔍 직접 테스트해보기

아래에 폐음 파일을 업로드하고 예측 결과를 확인하세요.

💡 팁: 위의 샘플 폐음을 다운로드해서 테스트해보세요!

🎧 샘플 폐음 다운로드

📊 예측 결과

참고

파일 형식: WAV, MP3, M4A, FLAC 지원
파일 크기: 최대 10MB 권장
오디오 길이: 3초로 자동 조정 (짧은 경우 반복, 긴 경우 자름)
샘플 레이트: 16kHz로 자동 변환
응답 시간: 파일 크기에 따라 다르나, 평균 1–3초 소요
CORS: 모든 도메인에서 접근 가능 (Access-Control-Allow-Origin: *)

성능 지표

정확도: 약 85-90% (ICBHI 데이터셋 기준)
지원 클래스: Normal, Crackles, Wheezes, Both (4개 클래스)
추론 시간: GPU 환경에서 평균 100-200ms

이 문서를 통해 폐음 진단 API를 손쉽게 통합하고, 실시간 호흡 소리 분석 기능을 구현해 보세요!