형식 마스터

만든 동기

형식에 대해 접근하기 어려운 사람을 위해

어려웠던 점

1. 가장 어려웠던 3가지 난관 (Challenges) AI의 제멋대로인 답변 포맷 (JSON 파싱 에러) 웹 앱이 정상 작동하려면 AI가 정확히 주어, 동사, 목적어 등을 정해진 규칙(JSON 데이터)으로 보내줘야 합니다. 하지만 AI는 가끔 말 끝에 ```json 같은 마크다운 기호를 붙이거나 설명 텍스트를 덧붙여서 브라우저가 데이터를 읽다 터지는(SyntaxError) 일이 잦았습니다. 배포 시 API 키가 노출되는 보안 문제 구글 Gemini API를 쓰려면 개인 비밀 키(API Key)가 필요합니다. 이 키를 소스코드에 그대로 적어두고 깃허브나 넷리파이에 올리면, 전 세계 누구나 내 키를 훔쳐서 마음대로 쓸 수 있는 심각한 보안 문제가 있었습니다. 그렇다고 서버를 따로 만들자니 비용과 시간이 너무 많이 들었죠. 생소한 오디오 데이터 처리 (PCM16 ➡️ WAV) Gemini API가 지원하는 최신 TTS(음성 합성) 기능은 일반적인 .mp3나 .wav 파일 대신, 가공되지 않은 순수 음성 바이트 데이터(PCM16)를 반환합니다. 문제는 이 데이터를 브라우저의 일반적인 <audio> 태그에 넣으면 아무 소리도 나지 않는다는 점이었습니다.

해결한 방법

2. 머리를 싸매고 찾아낸 해결 방법 (Solutions) ① responseSchema로 AI에게 생각의 틀 강제하기 단순히 프롬프트로 "JSON으로만 답해줘!"라고 부탁하는 대신, 구글 API의 강력한 기능인 responseSchema를 코드 수준에서 적용했습니다. AI에게 "너는 무조건 originalSentence는 글자로, isValid는 참/거짓으로, components는 배열로 채워서 대답해!"라고 완벽한 데이터 규격(틀)을 강제한 것입니다. 덕분에 AI가 헛소리를 하거나 포맷을 깨뜨리는 에러를 0%로 만들었습니다. ② 클라이언트 소유의 API 키 방식 (LocalStorage) 채택 코딩할 때 API 키를 숨겨놓지 않고, 과감히 사용자가 직접 입력하는 설정(톱니바퀴)창을 만들었습니다. 사용자가 입력한 키는 서버로 전송되지 않고, 오직 본인의 브라우저 비밀 저장소(localStorage)에만 저장된 채 구글 서버와 다이렉트로 통신합니다. 이로 인해 서버 비용도 들지 않고, 보안 문제도 깔끔하게 해결되었습니다. ③ 순수 자바스크립트 오디오 인코더 구현 및 이중화(Fallback) 브라우저가 읽을 수 있도록 raw PCM 데이터 앞에 "이 데이터는 주파수가 어떻고, 채널이 몇 개인 오디오 파일이다"라는 정보를 담은 헤더를 직접 붙여주는 pcmToWav 변환 함수를 직접 구현했습니다. 또한 혹시나 구글 API 오류로 음성 생성이 실패할 때를 대비하여, 브라우저 자체 내장 음성 엔진인 Web Speech API로 소리를 들려주는 이중 방어막(Fallback)을 쳐두었습니다.

배운 점