Node.js 음성 전사 미저장 버그, conversation_id 브리지 전달로 해결

음성 전사 기능에서 내용이 저장되지 않는 문제가 발생했나요? 저도 비슷한 경험을 했는데, conversation_id를 제대로 전달하지 않아 생긴 문제였습니다. 이 글에서 어떻게 해결했는지 공유해 드릴게요.

시도와 함정

처음에는 음성 전사 API 응답 자체에 문제가 있는 줄 알았습니다. API 호출 시 conversation_id를 제대로 전달하지 않으면, 서버에서 전사 결과를 제대로 매칭하지 못하는 상황을 예상했죠. 그래서 API 호출 시 conversation_id를 명시적으로 브리지(bridge)를 통해 전달하는 방식을 시도했습니다.

// 이전 코드 (가정)
async function transcribeAudio(audioBlob) {
  const response = await fetch('/api/transcribe', {
    method: 'POST',
    body: audioBlob,
    headers: {
      'Content-Type': 'audio/wav',
      // conversation_id 누락 또는 잘못된 전달
    },
  });
  const data = await response.json();
  return data;
}

하지만 예상대로 conversation_id를 브리지로 전달해도 문제는 해결되지 않았습니다. 서버 로그에는 별다른 에러 메시지가 없었고, 전사 결과만 텅 비어있었죠. 3시간 정도 삽질 끝에, conversation_id가 API 요청 본문이나 헤더가 아닌, 다른 방식으로 전달되어야 한다는 것을 깨달았습니다.

원인

문제의 근본 원인은 conversation_id가 API 요청의 일부로 제대로 전달되지 않았기 때문입니다. 음성 전사 서비스는 각 음성 세션을 고유하게 식별하기 위해 conversation_id를 사용하는데, 이 값이 누락되거나 잘못된 경로로 전달되면 서버는 어떤 대화에 대한 전사 결과인지 알 수 없어 데이터를 저장하지 못했습니다.

해결

해결 방법은 conversation_id를 API 요청의 특정 필드로 명확하게 지정하여 전달하는 것이었습니다. 또한, 혹시 모를 상황에 대비해 WARNING 로깅을 추가하고, 응답에 text 필드가 없을 경우를 대비해 폴백(fallback)으로 응답 텍스트를 저장하도록 수정했습니다.

// 수정된 코드
async function transcribeAudio(audioBlob, conversationId) {
  const formData = new FormData();
  formData.append('audio', audioBlob);
  formData.append('conversation_id', conversationId); // 명확하게 필드로 전달
try {
const response = await fetch('/api/transcribe', {
method: 'POST',
body: formData,
});
const data = await response.json();

if (!data.text) {
  console.warn(`[Transcribe] No text found for conversation_id: ${conversationId}. Response:`, data);
  // 응답에 text 필드가 없을 경우, 임시로 response.text를 저장하는 로직 추가 (예시)
  // 실제 구현에서는 상황에 맞게 처리 필요
  if (data.raw_response) { // 임의의 필드명, 실제 API 응답에 따라 달라짐
     // 저장 로직...
  }
}
return data;

} catch (error) {
console.error([Transcribe] Error transcribing audio for conversation_id: ${conversationId}, error);
throw error;
}
}

이렇게 conversation_id를 FormData에 명시적으로 추가하고, 서버에서도 해당 필드를 파싱하도록 수정하니 전사 내용이 정상적으로 저장되기 시작했습니다.

결과

• 음성 전사 내용 미저장 버그가 완전히 해결되었습니다.
• WARNING 로깅 및 폴백 저장 로직 추가로 문제 발생 시 원인 파악 및 디버깅이 훨씬 수월해졌습니다.
• API 요청 구조를 명확히 하여 코드의 가독성과 유지보수성이 향상되었습니다.

정리 — 같은 함정 안 빠지려면

• [ ] 음성 전사 API 사용 시 conversation_id가 어떻게 전달되어야 하는지 API 문서를 다시 한번 확인하세요.
• [ ] conversation_id는 보통 요청 본문(body)의 특정 필드나 헤더로 명시적으로 전달해야 합니다.
• [ ] 문제 발생 시 서버 로그뿐만 아니라, 클라이언트 측 로깅을 강화하여 요청/응답 데이터를 상세히 확인하세요.
• [ ] API 응답에 예상치 못한 값이 없을 경우를 대비한 폴백(fallback) 로직을 고려하세요.