본문으로 건너뛰기

음성 어시스턴트 프롬프트 설정

빠른 설정

약 5분이면 인사말, 대체 응답, 지시문을 설정할 수 있습니다.

이 가이드는 투숙객이 음성 어시스턴트를 사용할 때 듣는 내용을 제어하는 방법을 안내합니다.

또한 파일 ID가 있을 때 주제 제안이 먼저 Vertex RAG를 사용하는 방식도 설명합니다. 파일 ID가 없으면 도우미는 기존 검색으로 대체됩니다. 음성 응답 타이밍도 조정할 수 있습니다. 게이트웨이는 이제 명시적 오디오 턴을 사용하기 전에 최종화된 대화 기록을 기다립니다. 투숙객의 턴이 진행되는 동안 AVA는 음성 조회 진행 상황을 한 번만 표시합니다.

런타임 기본값

OPENAI_REALTIME_MODEL이 설정되지 않으면 AVA는 gpt-realtime-2.1-mini를 사용합니다. 팀에서 다른 Realtime 모델을 사용하려면 변수를 명시적으로 설정하세요.

Vertex AI 플랫폼

음성 응답은 챗봇 응답과 동일하게 구성된 Vertex AI 플랫폼을 사용합니다. 음성 답변이 예상과 다르면 먼저 플랫폼 설정을 확인하세요.

이동: Chatbot → Voice Setup

빠른 참조​

설정제어 내용투숙객 결과
Voice Welcome Message음성 세션에서 처음 말하는 메시지투숙객이 명확한 호텔 인사말을 듣습니다
Voice Default Answer신뢰할 수 있는 답변이 없을 때의 응답투숙객이 정중한 응답을 받을 수 있습니다
Instruction음성 AI의 말투와 동작 지침답변이 호텔 커뮤니케이션 스타일에 맞습니다
Topic Suggestions자주 묻는 투숙객 질문을 위한 사이드바 프롬프트투숙객에게 Vertex RAG 제안 또는 기존 대체 주제가 표시됩니다
RAG Request Timeout음성 답변을 기다리는 최대 시간느린 응답도 최대 제한까지 계속 실행됩니다
First Chunk Timeout첫 스트리밍 답변 조각을 기다리는 시간오래 멈춘 AI 답변을 더 일찍 중단합니다
Stream Idle Timeout스트리밍 조각 사이를 기다리는 시간끊긴 스트림이 무한히 멈추기 전에 실패합니다

플랜 접근 권한​

  • 음성 설정에는 유료 플랜이 필요합니다.
  • 무료 플랜 계정에는 업그레이드 안내가 표시되며 음성 설정을 저장할 수 없습니다.

업그레이드하려면 Settings → Billing & Subscription으로 이동하세요.

시작하기 전에​

다음 요건을 확인하세요.

  • 챗봇 설정을 관리할 권한이 있습니다
  • 현재 플랜에 AI 챗봇 기능이 포함되어 있습니다
  • 사용할 인사말과 대체 응답 문구를 정해 두었습니다
  • 기술 팀이 현재 음성 게이트웨이 타임아웃 설정을 알고 있습니다

음성 메시지 구성​

  1. Chatbot → Voice Setup으로 이동합니다.

  2. Voice Messages에서 Voice Welcome Message를 수정합니다.

  3. Voice Default Answer를 수정합니다.

  4. 각 카드에서 Save를 클릭합니다.

    ✓ 성공 메시지가 표시됩니다. ✓ 버튼 옆에 저장 시각이 표시됩니다.

음성 지시문 설정​

  1. 같은 페이지에서 Voice Instruction을 찾습니다.

  2. 말투, 표현 규칙, 대체 응답 동작을 설명합니다.

  3. Save를 클릭합니다.

    ✓ 지시문이 저장되어 이후 음성 응답에 사용됩니다.

지시문이 비어 있는 경우

빈 지시문을 저장하면 기본 친화적 음성 지시문이 적용됩니다.

투숙객 투숙 정보 및 하우스키핑 요청 사용​

음성 어시스턴트는 확인된 현재 투숙 정보를 사용해 투숙객의 질문에 답할 수 있습니다. 정적 객실 QR 세션에서는 스캔한 객실과 일치하는 현재 투숙 중인 활성 투숙이 정확히 하나일 때 AVA가 음성 사용 전에 링크를 새로 고칩니다. PMS 기능 계약이 해당 상태를 지원하면 AVA는 기본 DUE_OUT 투숙 하나도 일치시킬 수 있습니다. 그 외에는 정적 객실 QR 조회가 CHECKED_IN 투숙만 일치시킵니다. 조회에는 QR 코드에 인코딩된 정확한 객실 값이 사용됩니다. 정적 위치 QR 세션에서는 AVA가 위치 컨텍스트만 유지합니다. 예약 확인, 투숙 연결 또는 예약 기반 비디오 보강은 수행하지 않습니다. 또한 투숙객이 구성된 투숙객 서비스를 요청하도록 도울 수 있습니다.

투숙객 요청음성 어시스턴트 동작
현재 투숙에 대해 질문해당 투숙객에게 제공되는 확인된 예약 컨텍스트를 사용합니다
투숙객 서비스 요청요청을 반복하고 제출 전에 투숙객에게 확인을 요청합니다
요청에 필수 세부 정보가 없음누락된 정보를 설명하거나 이용 가능한 서비스를 제안합니다
체크인 전 객실에 대해 질문음성 흐름을 통해 체크인 전 객실 번호를 노출하지 않습니다
위치 QR 세션 사용예약 정보 없이 위치 컨텍스트를 사용합니다
확인이 필요합니다

명시적으로 투숙객이 확인한 경우에만 투숙객 서비스 요청이 제출되거나 취소됩니다. 대화 내용이 바뀌면 투숙객은 요청을 다시 확인해야 합니다. 확인 후 AVA는 투숙객이 검토한 준비된 요청을 제출합니다. 투숙객은 말로 전달된 요청만 확인하며 내부 요청 필드는 제공하지 않습니다. 요청을 검증할 수 없는 경우에도 어시스턴트는 투숙객에게 안전한 설명을 유지합니다. 누락된 세부 정보를 요청하거나 호텔에 구성된 서비스를 제안할 수 있습니다.

투숙객 음성 요청 테스트​

  1. 확인된 현재 투숙 테스트 예약으로 음성 세션을 시작합니다.

  2. 투숙에 관한 질문을 합니다.

  3. 여분의 수건과 같은 투숙객 서비스를 요청합니다.

  4. 어시스턴트가 요청을 반복하면 요청을 확인합니다.

    ✓ 어시스턴트가 이용 가능한 투숙 정보로 답변합니다. ✓ 요청은 확인 후에만 제출됩니다.

테스트 중에 필수 세부 정보를 모두 제공하지 않고 서비스를 요청해 보세요.

✓ 어시스턴트가 필요한 정보를 설명합니다. ✓ 어시스턴트는 일반적인 거부 응답 대신 이용 가능한 서비스를 제안할 수 있습니다.

체크인 전 테스트 예약을 사용해 객실 번호가 비공개로 유지되는지 확인하세요.

선택적 음성 도우미 처리​

음성 사이드바는 게이트웨이에 추천 주제를 요청합니다.

요청에 Vertex RAG 파일 ID가 포함되면 AVA는 해당 문서를 먼저 읽습니다. 대화 기록 어휘나 지식 범위 같은 다른 선택적 음성 도우미도 같은 패턴을 사용합니다. 파일 ID가 없으면 AVA는 기존 벡터 저장소를 대신 사용합니다. 명시적 오디오 턴은 이제 RAG를 트리거하기 전에 최종화된 대화 기록을 기다립니다. 이렇게 하면 마이크가 조용하거나 사용할 수 없을 때 관련 없는 도구 호출이 발생하지 않습니다.

따라서 음성 흐름이 502 오류를 표시하는 대신 계속 진행됩니다.

보이는 현상: 주제 목록이 비어 있거나 오래된 것처럼 보입니다.

해결 방법:

  1. 음성 세션을 열어 두고 대화를 계속합니다.
  2. 더 최신 제안을 기대한다면 페이지를 새로 고칩니다.
  3. 관련 챗봇 문서가 Active로 표시되는지 확인합니다.
  4. 음성 요청에 Vertex RAG 파일 ID가 포함되어 있는지 확인합니다.
  5. 게이트웨이가 chat microservice에 접근할 수 있는지 확인합니다.
변경된 사항

음성 도우미는 이제 장애가 발생해도 흐름을 중단하지 않습니다. 도우미 데이터를 사용할 수 없어도 투숙객은 계속 진행할 수 있습니다.

오디오 턴이 예상한 응답을 트리거하지 않음​

보이는 현상: 투숙객이 말했지만 어시스턴트가 해당 턴을 무시하거나 늦게 답변합니다.

해결 방법:

  1. 마이크가 작동하며 음소거되지 않았는지 확인합니다.
  2. 다시 테스트하기 전에 대화 기록이 최종화될 때까지 기다립니다.
  3. 턴이 대체되었다면 새 음성 세션을 시작합니다.
  4. 런타임을 변경한 후 음성 게이트웨이를 다시 배포합니다.
원인

게이트웨이는 최종화된 대화 기록이 있을 때까지 명시적 오디오 도구 호출을 거부합니다. 이렇게 하면 무음이거나 불완전한 오디오 턴에서 관련 없는 RAG 조회가 발생하지 않습니다.

음성 응답 타이밍 조정​

음성 답변이 너무 느리거나 응답 중간에 멈추는 경우 다음 게이트웨이 설정을 사용하세요.

설정제어 내용기본값
VOICE_GATEWAY_RAG_REQUEST_TIMEOUT_MS전체 RAG 요청의 최대 시간60000
VOICE_GATEWAY_RAG_FIRST_CHUNK_TIMEOUT_MS첫 스트리밍 조각을 기다리는 시간30000
VOICE_GATEWAY_RAG_STREAM_IDLE_TIMEOUT_MS스트리밍 조각 사이를 기다리는 시간15000

타임아웃 작동 방식​

  • 스트리밍 답변은 먼저 첫 조각 타임아웃을 사용합니다.
  • 첫 조각 이후에는 유휴 타임아웃이 활성 스트림을 보호합니다.
  • 비스트리밍 답변은 최대 요청 타임아웃만 사용합니다.
  • 게이트웨이는 기본 최대 요청 타임아웃을 60초로 늘립니다.

조정이 필요한 경우​

보이는 현상: 어시스턴트가 느린 답변이 끝나기 전에 멈춥니다.

해결 방법:

  1. VOICE_GATEWAY_RAG_FIRST_CHUNK_TIMEOUT_MS를 늘립니다.
  2. 답변이 계속 시간 초과되면 VOICE_GATEWAY_RAG_REQUEST_TIMEOUT_MS를 늘립니다.
  3. 조각 사이에 스트림이 멈추면 VOICE_GATEWAY_RAG_STREAM_IDLE_TIMEOUT_MS를 늘립니다.
  4. 환경 값을 변경한 후 음성 게이트웨이를 다시 배포합니다.

보이는 현상: 답변은 계속 실행되지만 한동안 아무것도 도착하지 않습니다.

해결 방법:

  1. VOICE_GATEWAY_RAG_FIRST_CHUNK_TIMEOUT_MS를 줄입니다.
  2. VOICE_GATEWAY_RAG_STREAM_IDLE_TIMEOUT_MS를 줄입니다.
  3. AI 제공업체에 맞춰 최대 요청 타임아웃은 충분히 높게 유지합니다.
  1. Voice Welcome Message는 짧고 자연스럽게 유지합니다.
  2. Voice Default Answer는 정중하고 행동 지향적으로 유지합니다.
  3. 일회성 공지가 아니라 안정적인 규칙을 Instruction에 사용합니다.
좋은 기본 응답 예시

"죄송합니다. 지금은 해당 정보를 확인할 수 없습니다. 프런트 데스크 팀에 도움을 요청하세요."

문제 해결​

"Invalid content"로 저장 실패​

보이는 현상: Save를 클릭하면 유효성 검사 오류가 표시됩니다.

해결 방법:

  1. 필드가 일반 텍스트인지 확인합니다.
  2. 너무 긴 텍스트 블록을 제거합니다.
  3. 다시 저장합니다.

음성 응답이 지시문과 일치하지 않음​

보이는 현상: 투숙객이 기대한 말투를 따르지 않는 응답을 듣습니다.

해결 방법:

  1. Instruction을 열고 규칙을 더 구체적으로 작성합니다.
  2. Save를 클릭합니다.
  3. 새 음성 세션을 시작해 다시 테스트합니다.

Voice Setup 페이지가 보이지 않음​

보이는 현상: 사이드바에서 Voice Setup을 찾을 수 없습니다.

해결 방법:

  1. 플랜에 AI 챗봇 도구가 포함되어 있는지 확인합니다.
  2. 역할에 챗봇 설정 권한이 있는지 확인합니다.
  3. 접근 권한을 변경한 후 페이지를 새로 고칩니다.

주제 제안이 비어 보임​

보이는 현상: 음성 사이드바에 추천 주제가 표시되지 않습니다.

해결 방법:

  1. 음성 흐름을 계속 사용합니다.
  2. 관련 챗봇 문서가 아직 Processing 상태인지 확인합니다.
  3. 게이트웨이가 chat microservice에 접근할 수 있는지 확인합니다.
  4. 목록이 계속 오래된 상태라면 캐시된 주제 설정을 검토합니다.

비품 요청이 제출되지 않음​

보이는 현상: 어시스턴트가 비품 요청을 반복하지만 요청이 제출되지 않습니다.

해결 방법:

  1. 어시스턴트의 확인 질문에 명확하게 답합니다.
  2. 대화 주제가 바뀌었다면 비품 요청을 다시 말합니다.
  3. 확인 프롬프트가 만료되었다면 새 음성 세션을 시작합니다.
  4. 확인한 요청도 제출되지 않으면 지원팀에 문의합니다.

어시스턴트가 추가 요청 세부 정보를 요구함​

보이는 현상: 어시스턴트가 누락된 정보를 요청하거나 이용 가능한 서비스를 제안합니다.

해결 방법:

이는 하우스키핑 요청을 아직 검증할 수 없을 때 예상되는 동작입니다. 요청된 세부 정보를 제공한 다음 전체 요청을 확인합니다.

체크인 전 객실 번호가 음성으로 안내됨​

보이는 현상: 투숙객이 체크인하기 전에 어시스턴트가 객실 번호를 말합니다.

해결 방법:

  1. 음성 세션을 종료합니다.
  2. 투숙객의 예약 및 통화 세부 정보를 기록합니다.
  3. 즉시 지원팀에 문의해 검토를 요청합니다.

계속 해결되지 않나요?​

다음과 같은 경우 success@vouch-technologies.com으로 문의하세요.

  • ❌ 재시도 후에도 저장 실패가 계속됨
  • ❌ 음성 응답이 저장한 프롬프트를 무시함
  • ❌ 게이트웨이 설정을 조정해도 음성 답변이 계속 시간 초과됨
  • ❌ 문제가 30분 넘게 지속됨

함께 전달하면 좋은 정보:

  • Voice Setup 페이지 스크린샷
  • 저장하려던 정확한 텍스트
  • 현재 사용 중인 타임아웃 값
  • 문제가 시작된 시간