feat(reports): 회의록 품질 개선 (#3)

- 회의록 생성 품질 튜닝(요약 + STT). 동작 계약은 유지하고 생성 품질만 개선.
- 요약(GeminiSummarizer): temperature 0.2 로 일관성 확보 + responseSchema 로 5필드 JSON 구조를 모델단에서 강제(파싱부 throw 감소).
- STT(faster-whisper, small 유지): vad_filter 로 무음 환각 감소, initial_prompt로 기술용어 오인식 완화, condition_on_previous_text=false 로 청크 환각 억제.

Author: yuchem2

apps/ai-worker/.env.template

@@ -7,3 +7,5 @@
 # STT_LANGUAGE=ko           # STT 언어
 # STT_CPU_THREADS=1         # CPU 스레드 수
 # STT_BEAM_SIZE=1           # beam search 크기(클수록 느리고 약간 정확)
+# STT_VAD_FILTER=true       # 무음 구간 제거(환각 자막 감소). false 로 끌 수 있음
+# STT_INITIAL_PROMPT=...    # 도메인 어휘 프라이밍(영어 기술용어 오인식 감소). 빈 값이면 비활성

apps/ai-worker/main.py

@@ -40,6 +40,30 @@
 MODEL_SIZE = os.getenv("STT_MODEL_SIZE", "small")
 LANGUAGE = os.getenv("STT_LANGUAGE", "ko")
 
+
+def _env_bool(name: str, default: bool) -> bool:
+    raw = os.getenv(name)
+    # 미설정(None)뿐 아니라 빈 문자열·공백("STT_VAD_FILTER=")도 기본값으로 본다.
+    if raw is None or not raw.strip():
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+# faster-whisper small 한국어 STT 의 오인식·환각을 줄이는 디코딩 옵션.
+#
+# - VAD_FILTER: Silero VAD 로 무음 구간을 잘라낸다. 회의 오디오는 긴 정적
+#   구간이 많아 그대로 디코드하면 무음에 환각 자막이 붙는다(특히 30s 청크).
+# - INITIAL_PROMPT: 도메인 어휘를 모델에 미리 알려 영어 기술 용어 오인식
+#   (예: "MySQL" → "마이스쿨")을 줄인다. 빈 문자열이면 비활성(None).
+#   도메인이 다르면 STT_INITIAL_PROMPT 로 교체한다.
+DEFAULT_INITIAL_PROMPT = (
+    "이 녹음은 IT 개발 동아리의 화상 회의입니다. "
+    "API, OAuth, MySQL, Redis, Docker, 백엔드, 프론트엔드, 배포, 리팩터링 같은 "
+    "기술 용어와 영어 약어가 자주 등장합니다."
+)
+VAD_FILTER = _env_bool("STT_VAD_FILTER", True)
+INITIAL_PROMPT = (os.getenv("STT_INITIAL_PROMPT", DEFAULT_INITIAL_PROMPT).strip() or None)
+
 # 모듈 import 시점에 모델을 1회 로드(warm-start). 컨테이너 부팅 시 cold-load 비용
 # 한 번만 지불하고, 이후 매 요청은 transcribe 만 호출한다.
 model = WhisperModel(
@@ -74,6 +98,12 @@ async def transcribe(request: Request) -> dict[str, Any]:
             io.BytesIO(audio),
             beam_size=BEAM_SIZE,
             language=LANGUAGE,
+            vad_filter=VAD_FILTER,
+            initial_prompt=INITIAL_PROMPT,
+            # 청크 전사는 청크마다 독립 호출이라 이전 청크 문맥이 없다. 기본값
+            # (True)은 직전 텍스트에 조건을 걸어 반복·드리프트 환각을 유발하므로
+            # 청크 단위 안정성을 위해 끈다.
+            condition_on_previous_text=False,
         )
 
         segments: list[dict[str, Any]] = []

apps/backend/src/reports/infrastructure/gemini.summarizer.spec.ts

@@ -99,6 +99,48 @@ describe('GeminiSummarizer', () => {
     expect(promptText).toContain('Korean');
   });
 
+  it('generationConfig 에 낮은 temperature 와 5필드 responseSchema 가 강제된다', async () => {
+    const fetchMock = jest.fn().mockResolvedValueOnce(okResponse(validSummaryJson));
+    const summarizer = new GeminiSummarizer(options, fetchMock as unknown as typeof fetch);
+
+    await summarizer.summarize({ transcript: [], chat: [], meta });
+
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    const body = JSON.parse(init.body as string) as {
+      generationConfig: {
+        responseMimeType: string;
+        temperature: number;
+        responseSchema: {
+          type: string;
+          properties: Record<string, { type: string }>;
+          required: string[];
+          propertyOrdering?: string[];
+        };
+      };
+    };
+    // 요약 일관성을 위해 temperature 를 낮춘다(Gemini default 1.0 → 0.2).
+    expect(body.generationConfig.temperature).toBeLessThanOrEqual(0.2);
+    // 모델단에서 5필드 JSON 구조를 강제해 어댑터 파싱부의 throw 빈도를 낮춘다.
+    const schema = body.generationConfig.responseSchema;
+    // REST v1beta Schema 의 type 은 대문자 enum(OBJECT/STRING/ARRAY).
+    expect(schema.type).toBe('OBJECT');
+    expect(Object.keys(schema.properties).sort()).toEqual(
+      ['actionItems', 'decisions', 'keyTopics', 'overview', 'title'],
+    );
+    expect(schema.required).toEqual(
+      expect.arrayContaining([
+        'title',
+        'overview',
+        'decisions',
+        'actionItems',
+        'keyTopics',
+      ]),
+    );
+    // 중첩 배열 구조(actionItems/keyTopics)도 스키마에 명시한다.
+    expect(schema.properties.actionItems.type).toBe('ARRAY');
+    expect(schema.properties.keyTopics.type).toBe('ARRAY');
+  });
+
   it('응답 JSON 을 ReportSummary VO 로 변환해 돌려준다', async () => {
     const fetchMock = jest.fn().mockResolvedValueOnce(okResponse(validSummaryJson));
     const summarizer = new GeminiSummarizer(options, fetchMock as unknown as typeof fetch);

apps/backend/src/reports/infrastructure/gemini.summarizer.ts

@@ -10,13 +10,70 @@ export interface GeminiSummarizerOptions {
   readonly timeoutMs: number;
 }
 
+/**
+ * 회의록 요약은 창의적 생성이 아니라 입력 사실의 일관된 정제이므로,
+ * Gemini default(1.0)보다 낮은 temperature 로 출력 변동을 줄인다.
+ */
+const SUMMARY_TEMPERATURE = 0.2;
+
+/**
+ * `generationConfig.responseSchema` (REST v1beta, OpenAPI-subset — type 은
+ * 대문자 enum: OBJECT/STRING/ARRAY).
+ *
+ * 모델단에서 5필드(title/overview/decisions/actionItems/keyTopics) JSON 구조를
+ * 강제해 candidates 텍스트가 항상 계약에 맞는 객체로 오게 한다 → 어댑터의
+ * asString/asStringArray throw 빈도를 낮춘다(요약 실패 감소). `propertyOrdering`
+ * 은 buildPrompt 의 Output format 필드 순서와 동일하게 둬 모델 혼동을 줄인다.
+ * 문자열 본문의 한국어 작성·길이 제약은 프롬프트와 ReportSummary VO 가 계속
+ * 책임진다(스키마는 형/존재만 강제).
+ */
+const SUMMARY_RESPONSE_SCHEMA = {
+  type: 'OBJECT',
+  properties: {
+    title: { type: 'STRING' },
+    overview: { type: 'STRING' },
+    decisions: { type: 'ARRAY', items: { type: 'STRING' } },
+    actionItems: {
+      type: 'ARRAY',
+      items: {
+        type: 'OBJECT',
+        properties: {
+          owner: { type: 'STRING' },
+          task: { type: 'STRING' },
+          due: { type: 'STRING' },
+        },
+        required: ['task'],
+        propertyOrdering: ['owner', 'task', 'due'],
+      },
+    },
+    keyTopics: {
+      type: 'ARRAY',
+      items: {
+        type: 'OBJECT',
+        properties: {
+          topic: { type: 'STRING' },
+          points: { type: 'ARRAY', items: { type: 'STRING' } },
+        },
+        required: ['topic', 'points'],
+        propertyOrdering: ['topic', 'points'],
+      },
+    },
+  },
+  required: ['title', 'overview', 'decisions', 'actionItems', 'keyTopics'],
+  propertyOrdering: ['title', 'overview', 'decisions', 'actionItems', 'keyTopics'],
+} as const;
+
 /**
  * Gemini `generateContent` REST API (v1beta) 기반 SummarizerPort 어댑터.
  *
  * POST {baseUrl}/v1beta/models/{model}:generateContent?key={apiKey}
  *   body: {
  *     contents: [{ role: 'user', parts: [{ text: <prompt> }] }],
- *     generationConfig: { responseMimeType: 'application/json' }
+ *     generationConfig: {
+ *       responseMimeType: 'application/json',
+ *       temperature: <낮은 값 — 일관성>,
+ *       responseSchema: <5필드 구조 강제>
+ *     }
  *   }
  *
  * 응답 candidates[0].content.parts[0].text 를 JSON.parse → reportSummary VO
@@ -48,7 +105,11 @@ export class GeminiSummarizer implements SummarizerPort {
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
           contents: [{ role: 'user', parts: [{ text: prompt }] }],
-          generationConfig: { responseMimeType: 'application/json' },
+          generationConfig: {
+            responseMimeType: 'application/json',
+            temperature: SUMMARY_TEMPERATURE,
+            responseSchema: SUMMARY_RESPONSE_SCHEMA,
+          },
         }),
         signal: controller.signal,
       });