ayoonistory 님의 블로그

FastAPI + Google STT + Gemini로 진료 음성 분석 백엔드 만들기

ayoonistory — Sun, 10 May 2026 00:11:15 +0900

MedExplain

환자가 진료실에서 의사의 설명을 녹음하면 AI가 핵심 내용을 요약하고, 어려운 의료 용어를 쉽게 풀어서 설명해주는 앱이다. Flutter로 만든 안드로이드 앱이 프론트엔드고, 이 글에서 다룰 FastAPI 서버가 백엔드다.

이 글에서는 오디오가 서버에 도착한 이후, 최종 요약이 앱에 돌아가기까지의 전체 백엔드 파이프라인을 단계별로 설명한다.

전체 흐름

Flutter 앱 (오디오 파일 전송)
↓ WebSocket
FastAPI 서버
↓
[1단계] Google STT → 텍스트 변환
↓
[2단계] 후처리 → 구어체/약어 정규화, 필러 단어 제거
↓
[3단계] STT 교정 → 규칙 기반 + Gemini 의료 문맥 교정
↓
[4단계] Gemini 요약 → 환자 친화적 요약 + 구조화 정보 추출
↓
Flutter 앱 (결과 표시)

1단계 — Google STT 의료 용어 인식 최적화

Google Cloud Speech-to-Text API를 기본 설정으로 쓰면 의료 용어 인식률이 낮다. SpeechContext로 의료 용어 힌트를 미리 넣어줘야 한다.

def _medical_phrase_hints() -> list[str]:
return [
"CRP", "CBC", "CT", "MRI", "HbA1c", "eGFR", "BMI",
"위선암", "위암", "내시경", "항암화학요법", "림프절",
"혈당", "공복 혈당", "당화혈색소", "혈압",
"고혈압", "당뇨", "고지혈증", "갑상선",
]

def _build_recognition_config(sample_rate: int, channels: int):
speech_context = speech.SpeechContext(
phrases=_medical_phrase_hints(),
boost=25.0, # 해당 단어 인식 시 가중치 높임
)
return speech.RecognitionConfig(
encoding=speech.RecognitionConfig.AudioEncoding.LINEAR16,
sample_rate_hertz=sample_rate,
language_code="ko-KR",
alternative_language_codes=["en-US"], # 영어 의료 용어도 인식
enable_automatic_punctuation=True,
model="latest_long",
use_enhanced=True,
speech_contexts=[speech_context],
)

boost=25.0으로 설정하면 힌트 목록에 있는 단어를 우선 인식한다. alternative_language_codes에 en-US를 추가해서 CRP, MRI 같은 영어 약어도 자연스럽게 인식되도록 했다.

2단계 — STT 후처리

Google STT가 텍스트를 뱉어줘도 그대로 쓰기엔 문제가 있다. 구어체가 그대로 살아있고 필러 단어도 섞여있다.

예시) "음 그 HbA1c 수치가 어 육점팔 퍼센트 나왔고요" → "HbA1c 수치가 6.8% 나왔고요"

# 의료 약어 구어체 교정
_ABBR_CORRECTIONS = {
"씨알피": "CRP",
"엠알아이": "MRI",
"에이치비에이원씨": "HbA1c",
"당화혈색소": "HbA1c",
}

# 단위 구어체 표준화
_UNIT_CORRECTIONS = {
"밀리그램": "mg",
"퍼센트": "%",
"프로": "%",
"밀리리터": "mL",
}

# 소수점 구어체: "영점오" → "0.5"
_DECIMAL_PATTERN = re.compile(
r"([영일이삼사오육칠팔구십]+)점([영일이삼사오육칠팔구십]+)"
)

# 필러 단어 제거
_FILLER_PATTERN = re.compile(r"\b(음+|아+|어+|그+|저+|뭐+|에+)\b\.?\s*")

def postprocess_stt_text(text: str) -> str:
for ko, en in _ABBR_CORRECTIONS.items():
text = re.sub(ko, en, text, flags=re.IGNORECASE)
for ko, unit in _UNIT_CORRECTIONS.items():
text = re.sub(ko, unit, text)
text = _DECIMAL_PATTERN.sub(_fix_decimal, text)
text = _FILLER_PATTERN.sub("", text)
text = re.sub(r" {2,}", " ", text).strip()
return text

이 함수는 STT 스트리밍 중 최종 결과(is_final=True)에만 적용한다.

for result in resp.results:
text = result.alternatives[0].transcript
processed = postprocess_stt_text(text) if result.is_final else text
self._emit_result(processed, result.is_final)

3단계 — STT 교정 파이프라인

후처리로도 못 잡는 오류가 있다. 대표적인 게 척추 레벨 표기다. "L4 L5"를 STT가 "L4 LO"로 인식하는 경우가 실제로 발생하는데, O(알파벳)와 0(숫자)을 혼동하기 때문이다.

이를 위해 규칙 기반 교정과 LLM 기반 교정을 합친 stt_corrector.py를 별도로 만들었다.

규칙 기반 교정 (1차)

_SPINAL_RULES = [
# L4 LO → L4 L5
(re.compile(r'\bL([1-4])\s+L[Oo0]\b'), r'L\1 L5'),
(re.compile(r'\bL([1-4])-L[Oo0]\b'), r'L\1-L5'),
# 단독 LO → L5 (요추는 L1~L5, L0이 없음)
(re.compile(r'\bL[Oo0]\b'), 'L5'),
# 소문자 붙여쓰기 교정: l4l5 → L4-L5
(re.compile(r'\bl([1-5])l([1-5])\b', re.IGNORECASE), r'L\1-L\2'),
]

def rule_based_correct(text: str) -> str:
for pattern, repl in _SPINAL_RULES:
text = pattern.sub(repl, text)
return text

LLM 기반 교정 (2차)

규칙으로 잡히지 않는 문맥적 오류는 Gemini에게 넘긴다. 프롬프트에서 "의미가 통하지 않는 단어만 교정하고 내용은 절대 추가하지 말 것"을 명시하는 게 핵심이다. 넣지 않으면 LLM이 내용을 임의로 채워넣어서 의료 정보가 왜곡될 수 있다.

def llm_correct(text: str) -> str:
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
prompt = f"""
너는 의료 STT 교정 시스템이다.
STT 오류로 의료 용어가 잘못 인식된 부분만 교정하라.

교정 규칙:
1. 척추 레벨 표기 교정 (예: LO→L5, C0→C6)
2. 약어 오인식 교정 (예: 씨알피→CRP)
3. 의미가 통하지 않는 단어만 교정할 것
4. 원문 내용을 추가하거나 삭제하지 말 것
5. 출력은 교정된 텍스트만 반환

원문:
\"\"\"{text}\"\"\"
"""
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=prompt,
config=types.GenerateContentConfig(temperature=0.1),
)
corrected = (response.text or "").strip()
return corrected if corrected else text

def correct_stt_text(text: str, use_llm: bool = True) -> str:
if not text or not text.strip():
return text
text = rule_based_correct(text) # 1차: 빠르고 비용 없음
if use_llm:
text = llm_correct(text) # 2차: 문맥 이해
return text

4단계 — Gemini로 구조화된 요약 만들기

교정된 텍스트를 Gemini에 넘겨서 요약을 만든다. 처음에는 원문을 줄이는 방식으로 프롬프트를 짰는데 결과가 아래처럼 나왔다.

"공복 혈당이 128이 나왔고 HbA1c가 6.8%이며 당뇨 전 단계입니다."

환자 입장에서 128이 높은 건지 낮은 건지, 어떻게 해야 하는지 여전히 모른다. 원문 축약이 아니라 환자 언어로 재구성하되 수치는 반드시 그대로 보존하도록 프롬프트를 바꿨다.

def _build_prompt(text: str) -> str:
return f"""
너는 환자가 진료 내용을 이해할 수 있도록 돕는 요약 도우미다.

요약 방식:
- 원문을 그대로 줄이는 것이 아니라, 핵심 정보를 환자 언어로 재구성할 것
- 의학 용어는 쉬운 말로 풀되, 실제 수치는 반드시 괄호로 병기할 것
(예: "혈당이 당뇨 직전 수준이다 (공복혈당 128, HbA1c 6.8%)")
- 환자에게 중요한 순서로 작성 (진단/결과 → 치료 방향 → 주의사항)
- 원문에 없는 내용은 추가하지 말 것
- 최대 3개 bullet, 출력은 JSON만 할 것

출력 형식:
{{
"summary": ["문장1", "문장2", "문장3"],
"symptoms": ["증상1"],
"measurements": ["HbA1c 6.8%", "공복혈당 128"],
"medications": ["메트포르민 500mg"]
}}

입력 텍스트:
\"\"\"{text}\"\"\"
"""

5단계 — FastAPI 엔드포인트에서 연결

지금까지 만든 모듈들이 /summary 엔드포인트 하나에서 순서대로 호출된다.

# models/schemas.py
class StructuredInfo(BaseModel):
symptoms: List[str] = []
measurements: List[str] = []
medications: List[str] = []

class SummaryResponse(BaseModel):
summary: List[str]
structured: Optional[StructuredInfo] = None

# routes/summary.py
@router.post("/summary", response_model=SummaryResponse)
def summarize(request: TextRequest):
corrected_text = correct_stt_text(request.text, use_llm=True) # STT 교정
result = summarize_text(corrected_text) # 요약
structured = StructuredInfo(
symptoms=result.get("symptoms", []),
measurements=result.get("measurements", []),
medications=result.get("medications", []),
)
return SummaryResponse(
summary=result.get("summary", []),
structured=structured
)

용어 추출도 동일하게 교정 후 처리한다.

# routes/explain.py
@router.post("/explain", response_model=ExplainResponse)
def explain_terms(request: TextRequest):
corrected_text = correct_stt_text(request.text, use_llm=True)
terms_result = extract_terms(corrected_text)
return ExplainResponse(terms=[TermItem(**t) for t in terms_result])

실제 결과

STT 원문
"이번에 혈액 검사 결과 보면요 공복 혈당이 128이 나왔고 음 에이치비에이원씨가 육점팔 퍼센트예요."

후처리 + 교정 후
"이번에 혈액 검사 결과 보면요 공복 혈당이 128이 나왔고 HbA1c가 6.8%예요."

최종 요약
"혈당이 당뇨 직전 수준으로 나왔습니다 (공복혈당 128, HbA1c 6.8%). 아직 약 처방은 없지만 지금부터 관리하지 않으면 당뇨로 빠르게 진행될 수 있습니다."

마무리

이번 파이프라인에서 핵심은 두 가지였다.

첫째, STT 결과를 그냥 쓰지 않는 것이다. 구어체 정규화 → 규칙 교정 → LLM 교정을 단계별로 쌓아야 실제로 쓸 수 있는 텍스트가 나온다.

둘째, LLM 프롬프트에서 하지 말 것을 명확히 하는 것이다. 교정 단계와 요약 단계 모두 원문에 없는 내용 추가 금지를 명시하지 않으면 의료 정보가 왜곡될 수 있다.

전체 코드는 https://github.com/kelly96110jung/Growth_Backend 에서 확인할 수 있다.

5/5 STT 품질 개선 + 실험

ayoonistory — Wed, 6 May 2026 10:40:59 +0900

3. 이번 작업에서 구현한 기능

3-1. STT 후처리 파이프라인

음성 인식(STT) 과정에서 발생하는 오류를 자동으로 교정하는 파이프라인을 신규 구현하였다 (stt_corrector.py).

교정은 두 단계로 이루어진다.

1단계 — 규칙 기반 교정 (정규식)

자주 발생하는 오탈자 패턴을 정규식으로 사전 정의하여 즉시 교정한다.

척추 기호 오류: L4 LO, L4 L0 → L4 L5 로 자동 변환
한글 숫자/단위 표현 정규화: "이 백" → "200", "삼십 밀리그램" → "30mg"
필러 단어 제거: "음", "어", "그", "저" 등 불필요한 간투사 삭제

2단계 — LLM 기반 교정 (Gemini 2.5-flash, temperature=0.3)

규칙으로 처리되지 않는 문맥적 오류를 LLM이 의료 문맥을 이해하고 교정한다. 원문의 구조와 내용은 유지하고 오인식된 부분만 수정한다.

이 교정 파이프라인은 요약(/summary), 용어 추출(/explain), 실시간 스트리밍 결과 모두에 적용된다.

3-2. 요약 품질 개선

기존 요약은 원문을 거의 그대로 줄이는 방식이어서 환자가 이해하기 어렵고, 소수점 숫자에서 문장이 잘리는 버그가 있었다. 이를 아래와 같이 개선하였다.

요약 방식 변경

원문 축약 방식에서 환자 친화적 재구성 방식으로 프롬프트를 전면 수정하였다. 수치는 반드시 괄호로 함께 표기하도록 하였다.

변경 전: "공복 혈당 128이 나왔고 HbA1c 6.8%이며 당뇨 전 단계입니다."
변경 후: "혈당이 당뇨 직전 수준으로 나왔습니다 (공복혈당 128, HbA1c 6.8%). 지금 관리하지 않으면 당뇨로 진행될 수 있습니다."

소수점 버그 수정

0.5와 같은 소수점 숫자에서 문장이 끊기던 문제를 정규식 조건 분기로 수정하였다.

출력 구조 확장

기존에는 요약 문장 목록만 반환하던 것을 아래와 같이 구조화된 형태로 확장하였다.

summary: 요약 문장 (최대 3개)
symptoms: 언급된 증상 목록
measurements: 검사 수치 목록
medications: 약물 및 용량 목록

3-3. 의료 용어 사전 구축

LLM을 통한 용어 추출이 실패할 경우를 대비한 fallback 용어 사전을 직접 구축하였다 (medical_terms.json). 내과, 정형외과, 심장내과, 신경과 등 주요 진료과 기준으로 60개 이상의 한국어 의료 용어와 쉬운 설명을 수록하였다.

예시)

HbA1c: 지난 2~3개월간 평균 혈당 수준을 나타내는 지표
공복혈당: 8시간 이상 금식 후 측정한 혈당 수치
L4-L5: 허리뼈 4번과 5번 사이 디스크 위치

3-4. 진료 기록 API 확장

기존 기록 저장/조회 기능에 다음을 추가하였다.

DELETE /records/{id} 신규 추가

특정 진료 기록을 삭제하는 엔드포인트를 구현하였다. 존재하지 않는 id 요청 시 404를 반환한다.

저장 항목 확장

기록 저장 및 조회 시 다음 두 필드를 추가로 처리한다.

memo: 환자가 직접 입력하는 자유 메모
structured: 구조화된 증상/수치/약물 정보 (3-2에서 확장한 요약 결과와 연동)

3-5. 질문 자동 분류 기능

환자가 질문을 입력하면 AI가 내용을 분석하여 아래 세 가지로 자동 분류하고, AI 답변 가능한 경우 즉시 답변까지 생성한다.

ai_answer: AI가 바로 답변 가능한 정보성 질문 (예: "HbA1c가 뭔가요?")
ask_doctor: 다음 진료 때 의사에게 직접 확인이 필요한 질문 (예: "이 약 오래 먹어도 되나요?")
urgent: 즉시 병원 또는 응급 확인이 필요한 상황 (예: "가슴이 갑자기 너무 아파요")

사용자가 별도로 카테고리를 선택하지 않아도 AI가 자동 판단한다.

3-6. UI 목업 제작

프론트엔드 개발 방향 결정을 위한 HTML 목업을 두 종류 제작하였다.

홈 화면 목업 (mockup.html)

현재 화면과 개선안을 나란히 배치하여 비교하였다. 개선안은 녹음 전 / 녹음 중 / 녹음 완료 세 가지 상태를 각각 별도 화면으로 구성하였다.

분석 결과 및 질문하기 탭 목업 (mockup_result.html)

분석 결과 탭에서 AI가 자동 추정한 진료과를 표시하는 방식으로 두 가지 안을 제시하였다.

A안: 상단 배너 카드 방식 — AI 추정 진료과를 카드 형태로 표시하고 변경 버튼 포함
B안: 인라인 칩 방식 — 날짜 옆에 작은 칩으로 진료과를 표시하고 탭하여 변경

질문하기 탭은 단일 입력창 → 자동 분류 → AI 답변 카드 / 다음 진료 체크리스트 / 긴급 항목 섹션으로 구성하였다.

4. 파일별 변경 내역

신규 생성

medexplain/server/app/services/stt_corrector.py
medexplain/server/app/data/medical_terms.json

수정

medexplain/server/app/services/summarizer.py — 요약 프롬프트 개선, 소수점 버그 수정, temperature=0.3
medexplain/server/app/services/term_extractor.py — medical_terms.json fallback 추가, temperature=0.3
medexplain/server/app/services/question_analyzer.py — temperature=0.3
medexplain/server/app/routes/summary.py — STT 교정 연동, structured 반환
medexplain/server/app/routes/explain.py — STT 교정 연동
medexplain/server/app/routes/records.py — DELETE 엔드포인트 추가, memo/structured 저장
medexplain/server/app/models/schemas.py — StructuredInfo 모델, memo/structured 필드 추가
medexplain/server/app/stt_google_streaming.py — 숫자/단위 교정, 필러 단어 제거 후처리 추가
lib/api/app_config.dart — 서버 IP 업데이트

5. 앞으로 해야 할 작업

백엔드

진료과 자동 추출 서비스 구현 — STT 텍스트에서 Gemini로 내과/정형외과 등 자동 추론

프론트엔드 (개발자 직접 구현)

홈 화면 UI 개선 (mockup.html 참고)
분석 결과 탭에 structured 정보 표시 (증상/수치/약물)
진료과 표시 및 변경 기능 (mockup_result.html A안 또는 B안 선택 후 구현)
질문하기 탭 전체 구현 (mockup_result.html 참고)
진료 기록 삭제 버튼 연동 (DELETE /records/{id})
memo 입력 및 수정 기능

4/3 데모 직전 수정하기

ayoonistory — Fri, 3 Apr 2026 11:13:09 +0900

1. 버그 수정

1-1. 진료 기록 저장 오류 (Critical)

파일: app/routes/records.py
문제: 용어 저장 시 description 키 대신 easy 키를 참조해서 용어 설명이 항상 빈 문자열로 저장됨
수정: item.get("easy", "") → item.get("description", "") or item.get("easy", "")
영향: 저장 후 진료 기록 상세 조회 시 용어 설명이 정상적으로 표시됨

1-2. records.json 데이터 정리

중복 레코드 5개 제거
description 없이 easy: ""만 있는 오염 레코드 정리

2. STT 인식 품질 개선

파일: app/stt_google_streaming.py
문제: language_code="ko-KR" 단일 언어 설정으로 인해 영어 의료 용어가 한국어 음성으로 인식됨 (예: CRP → 씨알피)
수정 1: alternative_language_codes=["en-US"] 추가 → 영어 단어는 영어로 인식
수정 2: phrase hints에서 한국어 음성 표기 제거 (씨알피, 씨비씨 등) → 해당 힌트가 오히려 한국어 음성 인식을 유도하고 있었음

3. 의료 용어 추출 개선

파일: app/services/term_extractor.py
문제: 4개 단어(CRP, 내시경, 염증, 검사)만 하드코딩되어 있어 대부분의 진료 텍스트에서 용어 추출 불가
수정: Gemini 기반 동적 추출로 전환
- 텍스트에 등장한 의료 용어를 자동 감지 및 설명 생성 (최대 6개)
- Gemini 실패 시 18개 단어 fallback 사전으로 대체

4. 신규 기능: 사전 질문 정리

스펙 기준 B안(MVP) 구현

추가 파일

파일내용

app/services/question_analyzer.py	Gemini 기반 질문 분류 서비스
app/routes/questions.py	질문 관련 API 라우터
app/data/questions.json	질문 데이터 저장소

추가 API

MethodEndpoint설명

POST	/questions/analyze	질문 텍스트 분류 (저장 없음)
POST	/questions	분류 결과 저장
GET	/questions	목록 조회
GET	/questions/{id}	상세 조회

분류 기준

general_info: 의학 기본 지식으로 설명 가능한 것 → 한두 줄 설명 제공
ask_doctor: 담당 의사에게 직접 물어봐야 하는 것 → 질문 리스트로 정리
caution: 응급/즉각 주의가 필요한 것

저장 시 record_id 연결 가능 (진료 기록과 연결, B안)

5. 환경 설정 개선

파일: app/main.py, server/.env
Gemini API 키를 .env 파일에 저장하도록 변경
서버 시작 시 자동 로드 → 매번 환경변수 수동 설정 불필요

6. 주소 수정

파일: lib/main.dart, lib/api/app_config.dart
WebSocket URL: ws://10.240.66.72:8000 → ws://127.0.0.1:8000
API URL: http://10.240.66.72:8000 → http://127.0.0.1:8000

현재 미완성 항목

항목상태

사전 질문 정리 — Flutter UI	미구현 (백엔드만 완료)
진료 기록 상세화면에 질문 연결 표시	미구현

3/26 서버(STT/저장/기록 조회) 안정화 및 예외 처리 보완 작업 보고서

ayoonistory — Thu, 26 Mar 2026 17:11:49 +0900

1. 오늘 작업 목표

오늘 작업의 목표는 MedExplain의 서버 흐름 중에서
STT 결과 처리, 빈 결과 예외 처리, 기록 저장/조회 안정화를 점검하고,
프론트와 연동되는 records 흐름이 실제로 동작하는지 확인하는 것이었다.

특히 MedExplain은 단순히 결과를 한 번 보여주는 데서 끝나는 것이 아니라,
진료 날짜 / 진료과 / 원문 텍스트 / 요약 / 의료 용어가 기록으로 저장되고 다시 조회되는 구조가 중요하기 때문에 이 흐름을 우선적으로 확인하였다.

2. 오늘 진행한 주요 작업

(1) 프론트 최신 코드 반영 및 실행 환경 정리

GitHub에 올라온 프론트 최신 코드를 로컬에 pull하여 반영함
실행 과정에서 누락된 파일(section_card.dart) 문제를 확인하였고, A가 push한 후 다시 pull하여 해결함
웹소켓 주소가 팀원 로컬 IPv4로 설정되어 있어 연결 오류가 발생하였고, 이를 사용자 환경에 맞게 수정하여 실행되도록 조정함

(2) WebSocket STT 연결 및 빈 결과 처리 보완

STT 웹소켓 연결이 정상적으로 이루어지는지 확인함
무음 또는 실질적 인식 실패 시 text='' 형태의 final STT 결과가 반환되는 것을 로그로 확인함
이 경우 그냥 정상 흐름처럼 넘어가지 않도록, 서버에서 warning 이벤트를 전송하도록 ws_stt.py를 수정함
warning 메시지는
“음성이 인식되지 않았습니다. 다시 녹음해주세요.”
형태로 내려가도록 처리함

(3) 빈 STT 결과의 저장 차단

기록 저장 API인 POST /records에서 clean_text가 비어 있거나 공백뿐인 경우 저장되지 않도록 records.py를 수정함
이를 통해 무음/인식 실패 상태가 records 목록에 의미 없는 기록으로 쌓이는 문제를 방지함

(4) records 저장/조회 구조 안정화

records.py에서 저장/조회 흐름을 점검함
records 목록은 날짜 / 진료과 / 요약 한 줄 카드 형태로 표시되고,
상세 화면은 날짜 / 진료과 / 원문 텍스트 / 요약 / 의료 용어를 보여주는 구조임을 기준으로 삼았음
저장 데이터의 summary, terms 구조를 점검하고, 프론트가 쓰기 쉽게 summary와 terms가 항상 안정적인 형태로 내려가도록 정리함

(5) records 상세 조회 500 에러 수정

저장은 성공했지만 GET /records/{record_id}에서 500 에러가 발생하는 문제를 확인함
원인은 저장된 terms 구조와 RecordDetailResponse 스키마가 기대하는 필드명이 서로 달랐기 때문이었음
저장된 terms는 easy 기반이었고, 상세 조회 응답은 description을 요구하고 있어 mismatch가 발생함
이를 수정하여, 상세 조회 시 기존 저장 데이터도 읽을 수 있도록 easy -> description 매핑을 보완함
이후 POST /records, GET /records, GET /records/{record_id}가 모두 200으로 동작하는 것을 확인함

(6) WebSocket 전송 안정화

기존 ws_stt.py에서는 asyncio.run_coroutine_threadsafe(...).result(timeout=5) 구조를 사용하고 있었고,
이 때문에 push_stt thread-safe failed와 같은 로그가 발생함
실제 전송은 되었지만 timeout 대기 구조 때문에 실패 로그가 남는 것으로 판단됨
이를 submit-only 방식으로 수정하여 unnecessary timeout을 제거하였고,
이후 push_stt thread-safe failed 로그가 사라진 것을 확인함

(7) 영어 의료용어 인식 개선 실험

stt_google_streaming.py에서 한국어 문장 속 영어 의료용어 인식 개선을 위해 phrase hint를 추가함
PRP, CRP, biopsy, gastrectomy, chemotherapy, adenocarcinoma 등 핵심 용어를 영어 표기와 한국식 발음 형태로 일부 보강함
테스트 결과 일부 짧은 용어는 약간 개선되었으나,
gastric adenocarcinoma, gastrectomy, chemotherapy 등 긴 영어 의료용어는 여전히 부정확하게 인식되는 한계가 확인됨
이 부분은 추후 고도화 과제로 남기고, 오늘은 핵심 저장/조회 안정화에 우선순위를 둠

3. 오늘 확인된 동작 결과

정상 케이스

STT 결과가 정상적으로 반환됨
/summary 호출 성공
/explain 호출 성공
/records 저장 성공
/records 목록 조회 성공
/records/{record_id} 상세 조회 성공

예외 케이스

무음 또는 인식 실패 시 warning 이벤트 전송 성공
빈 clean_text는 저장 차단됨

4. 오늘 작업의 의미

오늘 작업을 통해 MedExplain은 단순히 STT 결과를 보여주는 수준에서 벗어나,
실제 진료 기록을 저장하고 다시 조회할 수 있는 구조가 서버 기준으로 상당 부분 안정화되었다.

또한 무음/인식 실패 상태를 별도로 처리하고,
빈 결과가 records에 저장되지 않도록 방어 로직을 추가하여
사용자 경험과 데이터 품질을 함께 보완할 수 있었다.

5. 아직 남은 과제

프론트에서 warning, translate, stt, error 이벤트를 정확히 분기 처리
warning 상태에서는 자동 저장이 타지 않도록 프론트 로직 보완
department를 자동 확정이 아니라 추천 후보 + 사용자 수정 가능한 형태로 UI 개선
의료 용어(terms)는 하단 목록 UI로 정리하고, 추후 의료용 사전/API와 연동
영어 의료용어 STT 정확도 향상을 위한 후속 실험
- phrase hint 추가 보강
- 후처리 치환
- bilingual 설정 검토

3/19 제미나이 연결해서 요약 하기 + 프엔 코드 살짝 수정

ayoonistory — Thu, 19 Mar 2026 15:47:47 +0900

1. 작업 목표

MedExplain의 녹음 → STT → 요약 → 의료 용어 표시 흐름을 실제로 연결하고, 프론트와 백엔드 간 데이터 전달 문제를 해결하는 것을 목표로 작업하였다.
특히 결과 화면에서 원문 텍스트, 요약, 의료 용어가 비어 보이던 문제를 중점적으로 수정하였다.

2. 프론트엔드 작업 내용

초기 확인 결과, 프론트는 Windows 데스크톱 환경에서 실행 중이었으나 websocket 및 summary API 일부가 Android emulator용 주소인 10.0.2.2를 사용하고 있었다.
이를 Windows 로컬 서버 주소인 127.0.0.1로 수정하여 websocket /ws/stt 및 HTTP /summary 요청이 정상적으로 백엔드로 전달되도록 변경하였다.

또한 녹음 종료 직후 transcript를 바로 결과 화면에 넘기고 있었는데, 실제 final STT 결과는 websocket으로 조금 뒤에 도착하기 때문에 결과 화면으로 빈 문자열이 전달되는 문제가 있었다.
이를 해결하기 위해 녹음 종료 시점에는 transcript를 확정하지 않고 “STT 결과를 기다리는 중...” 상태만 표시하도록 수정하였다. 이후 websocket 이벤트 수신 시 transcriptStore를 갱신하고, 최신 transcript를 기준으로 결과 화면으로 이동하도록 변경하였다.

추가로 결과 보기 버튼도 실제 transcript가 존재할 때만 보이도록 조건을 수정하여, 빈 결과 화면으로 진입하는 문제를 줄였다.

3. STT 이벤트 파싱 관련 수정

프론트 models.dart와 transcript_store.dart를 점검하여 websocket으로 들어오는 STT 이벤트를 파싱하는 로직을 수정하였다.
초기에는 isFinal, text 필드가 기대한 형태로 들어오지 않아 transcriptStore에 값이 누적되지 않았고, 그 결과 combinedText가 빈 값으로 유지되었다.

이를 해결하기 위해 STT 이벤트 파싱 시 isFinal / final 값을 모두 처리할 수 있도록 보완하고, text가 실제로 존재하는 경우만 transcriptStore에 반영되도록 수정하였다.

4. 백엔드 websocket 처리 수정

백엔드 ws_stt.py에서 websocket 이벤트 형식과 전송 타이밍 문제를 수정하였다.
기존에는 STT 및 translation 이벤트를 payload 내부 중첩 구조로 전송하고 있었는데, 프론트는 top-level text, isFinal 등의 필드를 기대하고 있어 형식 불일치가 발생하였다.
이를 프론트가 읽을 수 있는 flat 구조로 수정하였다.

또한 recognize_once() 이후 결과 전송을 asyncio.create_task()로 처리하면서 websocket 연결 종료 후 send를 시도하는 문제가 발생하였다.
이를 asyncio.run_coroutine_threadsafe() 기반으로 바꿔 STT 및 translation 결과가 event loop에 즉시 안전하게 전달되도록 수정하였다.

5. 요약 기능 개선

백엔드 /summary 라우터를 확인한 결과, 기존 요약은 문장 분리 후 앞 3문장을 반환하는 단순 규칙 기반 로직이었다.
이를 유지하면서도 고도화를 위해 외부 LLM 요약을 도입하는 방향으로 구조를 정리하였다.

현재 방향은 다음과 같다.

/summary는 그대로 백엔드 엔드포인트 유지
내부 summarizer.py에서 Gemini API를 우선 호출
응답 실패 시 기존 규칙 기반 요약으로 fallback
프론트는 별도 수정 없이 기존 /summary 호출 구조 유지

이를 위해 Gemini API 키를 발급받고, 백엔드 실행 cmd 창에서 set GEMINI_API_KEY=... 방식으로 환경변수를 설정한 뒤 서버에서 외부 요약 호출이 가능하도록 준비하였다.

6. STT 언어 설정 확인

stt_google_streaming.py를 확인한 결과 language_code가 ko-KR로 고정되어 있어 영어 발화 테스트 시 빈 결과가 나올 가능성이 있었다.
테스트 과정에서 영어/한국어 발화에 따라 STT 결과 차이가 발생할 수 있음을 확인하였고, 필요 시 language_code를 테스트 언어에 맞게 조정해야 함을 점검하였다.

7. 최종 결과

최종적으로 다음 흐름이 정상 동작하는 상태까지 확인하였다.

프론트 Windows 앱 실행
websocket /ws/stt 정상 연결
녹음 데이터 전송
백엔드 STT final 결과 생성
프론트 결과 화면에 원문 텍스트 표시
/summary 호출 후 요약 표시
/explain 호출 후 의료 용어 영역 표시 구조 유지
백엔드와 프론트 간 기본 연동 성공

즉, MedExplain의 핵심 1차 흐름인 녹음 → STT → 요약 출력까지는 동작 가능한 상태로 정리되었다.

8. 이후 과제

이후에는 다음 작업을 진행하면 된다.

explain 기능을 의료 사전 기반 또는 외부 API 기반으로 고도화
Gemini 요약 품질 안정화
websocket/session 종료 처리 추가 안정화
저장된 records 화면과 상세 화면 연결 점검
실제 의료 시나리오 기반 테스트 데이터 확장

6. 커밋 메시지 추천

프론트:

git commit -m "STT 결과 반영 흐름 수정 및 결과 화면 연동 개선"

백엔드:

git commit -m "웹소켓 STT 이벤트 형식 수정 및 Gemini 요약 구조 반영"

코테 공부 시작

ayoonistory — Mon, 16 Mar 2026 13:15:10 +0900

지피티가 시키는대로 가볼게요,,,하다 보면 되겄지 샤갈

0주차 (3/12, 3/16)

GOAT - Ch.05 읽기

2557 Hello World
이걸 왜 시키나 라고 한동안 고민했음 공대도서관에서 하기엔 민망했어
1000 A+B
map(int, input().split()) 알기
2753 윤년
python에서는 &&가 아니라 and, or
조건문 끝날때 :
문자열일때 '' 잊지 말기
2438 별 찍기 - 1
1부터 해서 n까지 하기 range
10871 X보다 작은 수
문제를 똑바로 읽자,,,,주어진다고 해도 random 생성인줄,,,,

3/12 응 결국 수정

ayoonistory — Thu, 12 Mar 2026 17:29:28 +0900

MedExplain 서버 개발 진행 보고서

1. 작업 개요
이번 작업에서는 MedExplain 프로젝트의 서버(B) 파트에서 모바일(A)와 연결 가능한 1차 API 뼈대를 구축하였다.
기존에는 STT 연결 및 WebSocket 기반 텍스트 수신 구조가 중심이었다면, 이번 작업에서는 STT 이후 결과를 사용자가 실제로 활용할 수 있는 형태로 가공하고 저장하는 기능을 우선 구현하는 방향으로 범위를 확장하였다.

2. 변경 배경 및 이유
초기 구상에서는 음성 입력 이후 STT 결과를 얻는 것 자체에 초점이 맞춰져 있었다.
하지만 프로젝트 방향이 점차 “환자/보호자가 진료 내용을 이해하고 다시 확인할 수 있도록 돕는 앱” 쪽으로 구체화되면서, 단순 전사 결과만으로는 사용자 가치가 부족하다는 문제가 있었다.

또한 교수님 피드백 및 팀 논의 과정에서 다음과 같은 점이 중요해졌다.

- 단순 음성 인식 기능만으로는 프로젝트 차별성이 약함
- 사용자가 실제로 필요로 하는 것은 긴 진료 내용을 이해 가능한 형태로 정리해주는 기능임
- 모바일 화면 구현을 위해서는 서버가 정리된 데이터 구조를 먼저 제공해야 함
- STT 고도화보다 요약, 용어 설명, 기록 저장 같은 후속 처리 구조를 먼저 만드는 것이 전체 구현 흐름상 더 효율적임

이러한 이유로 이번 단계에서는 STT 이후 파이프라인 중에서도 모바일과 직접 연결되는 기능을 우선 구현하였다.

3. 이번 작업 목표
이번 작업의 목표는 다음과 같았다.

- summary API 구현
- explain API 구현
- records 저장 및 조회 API 구현
- A가 Flutter에서 바로 붙일 수 있는 요청/응답 구조 확정
- Swagger에서 각 기능 정상 동작 확인

4. 구현 내용

4-1. 데이터 구조 통일
A와 B가 동일한 형식으로 데이터를 주고받을 수 있도록 API 응답 구조를 먼저 확정하였다.

- summary 응답: 배열(list)
- terms 응답: {term, description} 객체 배열
- records 저장 필드: record_id, date, department, clean_text, summary, terms
- records 목록 조회: summary_preview 포함
- records 상세 조회: clean_text, summary, terms 전체 포함

이 과정을 통해 모바일과 서버가 같은 기준으로 개발될 수 있도록 하였다.

4-2. 스키마 파일 작성
app/models/schemas.py를 생성하여 요청 및 응답 형식을 Pydantic 모델로 정의하였다.

구현한 모델
- TextRequest
- TermItem
- SummaryResponse
- ExplainResponse
- RecordCreateRequest
- RecordListItem
- RecordListResponse
- RecordDetailResponse

이를 통해 서버 응답 형식을 일관되게 유지할 수 있도록 하였다.

4-3. summary 기능 구현
app/services/summarizer.py를 생성하여 입력 텍스트를 문장 단위로 분리하고 최대 3문장까지 배열로 반환하는 1차 더미 요약 기능을 구현하였다.

app/routes/summary.py를 생성하여 POST /summary 엔드포인트를 연결하였다.

Swagger 테스트 결과
- 요청 성공
- summary 배열 형식으로 응답 확인 완료

4-4. explain 기능 구현
app/services/term_extractor.py를 생성하여 내부 dictionary 기반 의료 용어 추출 기능을 구현하였다.

현재는
- CRP
- 내시경
- 염증
- 검사
등 일부 용어를 예시로 등록해두고, 입력 텍스트에 포함된 용어를 탐지하여 설명과 함께 반환하도록 하였다.

app/routes/explain.py를 생성하여 POST /explain 엔드포인트를 연결하였다.

Swagger 테스트 결과
- 요청 성공
- terms 배열 형식으로 응답 확인 완료

4-5. records 기능 구현
app/data/records.json 파일을 생성하여 로컬 JSON 기반 저장소를 마련하였다.
app/routes/records.py를 생성하여 다음 기능을 구현하였다.

- POST /records : 기록 저장
- GET /records : 기록 목록 조회
- GET /records/{record_id} : 기록 상세 조회

Swagger 테스트 결과
- 기록 저장 성공
- 목록 조회 성공
- 상세 조회 성공

5. 테스트 결과
Swagger를 이용해 직접 엔드포인트를 테스트한 결과, 아래 기능이 모두 정상 동작함을 확인하였다.

- POST /summary
- POST /explain
- POST /records
- GET /records
- GET /records/{record_id}

6. 현재 단계의 의미
이번 작업으로 서버는 단순 STT 처리 수준을 넘어서, 모바일 앱이 바로 활용할 수 있는 구조화된 데이터 제공이 가능해졌다.
특히 A 파트에서는 현재 구현된 API를 바탕으로 다음 기능을 바로 연결할 수 있다.

- 진료 요약 화면 표시
- 의료 용어 설명 UI 표시
- 기록 저장 기능
- 기록 목록 화면
- 기록 상세 화면

7. 한계점
이번 단계는 1차 뼈대 구현이므로 다음과 같은 한계가 있다.

- summary는 실제 AI 요약 모델이 아닌 단순 분리 기반 더미 로직임
- explain은 외부 의료 용어 API가 아닌 내부 dictionary 기반임
- records는 DB가 아닌 JSON 파일 로컬 저장 방식임
- STT 결과와 summary/explain/records가 자동 연동된 상태는 아님

8. 향후 계획
다음 단계에서는 아래 항목들을 순차적으로 개선할 예정이다.

- STT 결과 후처리용 text_cleaner 추가
- summary를 실제 요약 모델 또는 LLM과 연결
- explain 기능을 의료 용어 API 또는 확장 사전과 연결
- records 저장 구조를 DB 기반으로 전환
- STT 결과가 생성되면 summary/explain/records로 자연스럽게 이어지는 서버 흐름 구성
- Flutter(A)와의 실제 연결 및 UI 테스트 진행

9. 결론
이번 작업에서는 MedExplain 서버 파트에서 모바일과 연동 가능한 핵심 API 뼈대를 우선 구현하였다.
이를 통해 프로젝트의 방향을 단순 음성 인식 중심에서, 환자/보호자가 진료 내용을 이해하고 다시 확인할 수 있도록 돕는 구조로 구체화하였다.
현재는 더미 및 로컬 저장 기반이지만, 전체 시스템 연결의 출발점이 되는 핵심 구조는 확보한 상태이며, 이후에는 이를 실제 모델 및 저장 구조와 연결하여 기능을 고도화할 예정이다.

1/25 API 계약 최종 고정,JSON 깨짐 방어 로직

ayoonistory — Sat, 7 Mar 2026 20:58:18 +0900

1. 담당 역할 개요 (B 담당)

본 프로젝트에서 B 담당은 FastAPI 기반 서버를 구축하고,

STT 결과 텍스트를 입력받아 환자 친화적 요약 JSON으로 변환하는 /summarize API를 구현하였다.

특히 프론트엔드와의 안정적인 연동을 위해 API 계약 고정 및 JSON 안정성 확보를 핵심 목표로 두었다.

2. API 설계 및 구현

(1) API 계약 고정

shared/schema.md를 단일 기준으로 삼아, 요청·응답 구조를 변경하지 않고 구현하였다.

요청

POST /summarize
{
"raw_text":"string"
}

응답

{
"summary_3sent":"string",
"easy_terms":[
{"term":"string","easy":"string"}
],
"next_actions":[
{"title":"string","detail":"string"}
],
"warnings":["string"]
}

FastAPI의 Pydantic 모델을 활용하여 필드 누락이나 타입 오류가 발생하지 않도록 강제하였다.

(2) 요약 로직 및 방어 설계

요약 결과는 항상 3문장이 되도록 보정 로직을 적용하였다.
어떤 입력이 들어와도 응답 JSON 구조가 깨지지 않도록 설계하였다.
실제 LLM 연동 이전 단계로, 현재는 더미 요약 결과를 사용하되
구조와 흐름은 그대로 유지되도록 구현하였다.

(3) 서버 안정성 확보

/health 엔드포인트를 통해 서버 상태를 즉시 확인할 수 있도록 구성하였다.
Swagger UI(/docs)를 통해 프론트엔드 및 팀원들이 직접 API 테스트 가능하도록 하였다.
curl / Swagger 테스트 결과, 여러 차례 호출에서도 모두 200 OK 응답을 반환함을 확인하였다.

3. 테스트 결과

Swagger UI 및 curl을 이용해 다양한 의료 텍스트 입력 테스트 수행
모든 테스트에서 JSON 구조가 유지됨
프론트엔드에서 바로 사용 가능한 형태의 응답 확인

4. 한계점 및 향후 개선 방향

현재 의료 용어 설명(easy_terms)은 더미 데이터 수준으로 제한적임
의료 용어 사전 API 연동 또는 LLM 기반 동적 설명 생성이 필요함
추후 프롬프트 설계를 통해 의료 표현의 정확성과 범용성을 개선할 예정

5. 결론

본 단계에서는 서버의 구조적 안정성과 계약 준수를 최우선으로 구현을 완료하였다.

의료 내용의 품질 개선은 다음 단계에서 확장 가능하도록 설계되어 있으며,

현재 상태로 프론트엔드 연동 및 데모 시연이 가능한 수준임을 확인하였다.

1/19 서버 Google Cloud Speech-to-Text(STT) 연동 설정 및 REST 요청/응답 확정

ayoonistory — Sat, 7 Mar 2026 20:57:05 +0900

1. 목표

Google Cloud Speech-to-Text API를 프로젝트에 연결하고,
WAV 파일을 REST로 전송했을 때 어떤 JSON이 오며,
응답에서 최종 텍스트(transcript)를 추출하는 방법을 확정한다.
“샘플 오디오로 STT 1회 성공”을 기준으로 기능 검증을 완료한다.

2. GCP 콘솔 설정 절차

2.1 프로젝트 생성 및 결제 연결

Google Cloud Console에서 신규 프로젝트 생성(예: medexplain-stt)
결제(Billing) 계정 생성/연결

STT API는 유료 과금 가능성이 있으므로 결제 계정 연결이 필요함

비용 통제 목적의 Budget/알림 설정은 선택(추가로 설정 가능)

2.2 Speech-to-Text API 활성화

API 및 서비스 → 라이브러리
Cloud Speech-to-Text API 검색 후 “사용” 활성화

2.3 인증(키) 준비

API 및 서비스 → 사용자 인증 정보
API 키 생성
보안상 권장 사항

생성한 키는 Cloud Speech-to-Text API만 호출 가능하도록 제한(API 제한사항 설정)
키 노출 위험이 있으므로 테스트 후 키 회전(재생성) 권장

3. 테스트 오디오 준비 및 로컬 테스트 방식

3.1 오디오 파일 준비

Windows 기본 “음성 녹음기”로 녹음 시 기본 저장은 m4a가 많아,
STT 테스트를 위해 온라인 변환 도구 등을 이용해 wav로 변환하였다.
최종 테스트 파일: test.wav

3.2 로컬에서 REST 호출 테스트 환경

CMD에서 멀티라인 JSON 작성이 깨지는 문제가 있어(줄 이어쓰기/따옴표 이슈),
PowerShell 기반으로 다음을 수행하였다:
1. wav 파일을 byte로 읽기
2. base64로 인코딩
3. 요청 JSON을 생성
4. Invoke-RestMethod로 POST 호출

4. STT REST 호출 규격 확정(요청/응답)

4.1 Endpoint

POST <https://speech.googleapis.com/v1/speech:recognize?key=API_KEY>

4.2 Request JSON 구조

WAV 파일을 base64로 담아 전송한다.

{
"config":{
"encoding":"LINEAR16",
"languageCode":"ko-KR",
"audioChannelCount":2
},
"audio":{
"content":"<BASE64_ENCODED_WAV_BYTES>"
}
}

languageCode: ko-KR
encoding: LINEAR16 (PCM WAV 기준)
audioChannelCount: 파일이 스테레오(2채널)일 경우 2 명시
(선택) 파일 헤더가 48000Hz인 경우 sampleRateHertz: 48000을 추가할 수 있음
(파일과 다르게 지정하면 오류 발생)

5. 시행착오 및 해결 과정(핵심)

5.1 문제 1) JSON payload 오류(400 Invalid JSON)

CMD에서 줄바꿈/이스케이프가 꼬이면서 JSON이 깨지는 현상이 발생
해결: PowerShell로 전환하여 JSON 생성/요청을 처리함

5.2 문제 2) sample_rate_hertz 불일치 오류

오류 메시지 요약:
sample_rate_hertz(16000) must match WAV header(48000)
원인: 변환된 WAV 파일의 실제 샘플레이트가 48000Hz인데 요청에 16000Hz를 넣어 충돌
해결:
- sampleRateHertz를 파일에 맞추거나(48000),
- 또는 sampleRateHertz 항목을 생략하여 해결 시도

5.3 문제 3) 채널 수 불일치(스테레오/모노) 오류

오류 메시지 요약:
Must use single channel (mono) audio, but WAV header indicates 2 channels.
원인: WAV 파일이 2채널(스테레오) 인데 요청 config가 이를 반영하지 못함
해결: audioChannelCount: 2를 요청 config에 추가하여 성공

6. 성공 결과(샘플 오디오 STT 1회 성공)

6.1 PowerShell 실행 흐름(요약)

파일 경로 설정 및 존재 확인
파일을 base64로 변환
config + audio(content)로 JSON 생성
recognize endpoint로 POST 호출
응답에서 transcript 추출

6.2 transcript 추출 결과

추출 경로: results[*].alternatives[0].transcript
실제 출력 예시:
- Google 스피치 텍스트 테스트 음성입니다

7. 응답에서 최종 텍스트 추출 로직(확정)

기본 규칙: results 배열을 순회하며
alternatives[0].transcript를 순서대로 이어 붙여 최종 텍스트 생성

의사코드:

final_text = join(" ", for each r in results: r.alternatives[0].transcript)

8. 팀 통일 포맷 제안(추후 안정화)

실제 오류의 대부분이 “파일 포맷/샘플레이트/채널수 불일치”에서 발생했으므로, 팀 내 통일 권장:

권장 통일안(A): mono(1채널) + 16kHz + PCM LINEAR16 WAV
- config 단순화 가능
- 오류 감소
대안(B): 원본 그대로 사용할 경우
- 파일 헤더에 맞춰 sampleRateHertz, audioChannelCount를 반드시 맞춤

9. 결론

GCP 프로젝트/결제/API 활성화/키 발급/REST 규격 확정 완료
샘플 wav 파일 기반으로 STT recognize 호출 성공 및 transcript 추출 성공 확인
보고서에 포함 가능한 수준으로 요청/응답 구조 및 파싱 로직을 확정함