Files

hskwon aca1767eb9 초기 커밋: 5130 레거시 시스템

- URL 하드코딩 → .env APP_URL 기반 동적 URL로 변경
- DB 연결 하드코딩 → .env 기반으로 변경
- MySQL strict mode DATE 오류 수정

2025-12-10 20:14:31 +09:00

10 KiB

Raw Blame History

Sam AI 개발 문서

프로젝트 개요

Sam AI는 Google Gemini Live API를 활용한 실시간 음성 AI 어시스턴트입니다. React (CDN)와 PHP를 사용하여 구현되었으며, 사용자의 음성 명령으로 대시보드 네비게이션과 파일 검색 기능을 제공합니다.

기술 스택

Frontend: React 18 (CDN), Tailwind CSS (CDN), Babel (브라우저 변환)
Backend: PHP 7.3+
AI SDK: Google GenAI SDK (@google/genai@^1.31.0)
API: Gemini Live API (gemini-2.5-flash-native-audio-preview-09-2025)
오디오: Web Audio API, ScriptProcessorNode

설치 과정

1. 파일 구조

ai_sam/
├── index.php              # 메인 애플리케이션 파일
├── api/
│   └── get_api_key.php   # API 키 조회 엔드포인트
├── API_KEY_GUIDE.md       # API 키 발급 가이드
└── dev.md                 # 개발 문서 (본 파일)

2. API 키 설정

필요한 API 키

Gemini Live API를 사용하기 위해서는 Google AI Studio에서 발급받은 Gemini API 키가 필요합니다.

⚠️ 중요:

Vertex AI API 키가 아닙니다
서비스 계정 OAuth 토큰이 아닙니다
Google AI Studio의 일반 Gemini API 키입니다

API 키 발급 방법

방법 1: Google AI Studio (권장)

https://makersuite.google.com/app/apikey 접속
Google 계정으로 로그인 (Codebridge-Chatbot 프로젝트 계정)
"Create API Key" 버튼 클릭
프로젝트 선택: Codebridge-Chatbot
생성된 API 키 복사

방법 2: Google Cloud Console

https://console.cloud.google.com/ 접속
프로젝트 선택: Codebridge-Chatbot
"API 및 서비스" > "라이브러리"
"Generative Language API" 검색 후 "사용 설정"
"API 및 서비스" > "자격 증명"
"자격 증명 만들기" > "API 키"
생성된 API 키 복사

API 키 저장

생성된 API 키를 apikey/gemini_api_key.txt 파일에 저장합니다.

# 파일 위치: apikey/gemini_api_key.txt
# 파일 내용: API 키만 저장 (설명 텍스트 제외)
AIzaSyAbCdEfGhIjKlMnOpQrStUvWxYz1234567

프로젝트 확인

ai_sam/api/get_api_key.php는 Codebridge-Chatbot 프로젝트의 서비스 계정(apikey/google_service_account.json)을 확인하여 프로젝트 일치 여부를 검증합니다.

// 프로젝트 ID 확인
if ($serviceAccount['project_id'] !== 'codebridge-chatbot') {
    // 오류 반환
}

3. 의존성

모든 의존성은 CDN을 통해 로드됩니다:

React & ReactDOM: https://unpkg.com/react@18/umd/react.development.js
Babel: https://unpkg.com/@babel/standalone/babel.min.js
Tailwind CSS: https://cdn.tailwindcss.com
Google GenAI SDK: https://aistudiocdn.com/@google/genai@^1.31.0 (ES Module)

4. 서버 요구사항

PHP 7.3 이상
openssl 확장 (서비스 계정 인증용, 선택사항)
HTTPS 또는 localhost (마이크 접근 권한 필요)

개발 과정에서 발생한 이슈 및 해결

이슈 1: WebSocket이 즉시 종료되는 문제

증상: "Call Sam" 버튼을 클릭하면 연결이 시작되자마자 즉시 종료됨

원인 분석:

WebSocket 연결 상태 추적 부족
세션 객체 관리 미흡
오디오 스트림 정리 로직 부재

해결 방법:

연결 상태 추적 추가

this.isConnected = false;
this.session = null;

안전한 데이터 전송

if (this.session && this.isConnected) {
    try {
        this.session.sendRealtimeInput({ media: pcmBlob });
    } catch (sendError) {
        // WebSocket이 닫힌 경우 처리
    }
}

리소스 정리 개선
- cleanup() 메서드 추가
- 미디어 스트림 트랙 중지
- ScriptProcessor 연결 해제
- AudioContext 종료
- 세션 종료

이슈 2: 디버그 로깅 시스템 구축

목적: 연결 과정의 각 단계를 추적하여 문제점 파악

구현 내용:

LiveManager 클래스에 디버그 로깅 추가

this.debugLog = [];
this.log = (msg, data = null) => {
    const timestamp = new Date().toISOString();
    const logEntry = { timestamp, msg, data };
    this.debugLog.push(logEntry);
    console.log(`[Sam AI Debug ${timestamp}]`, msg, data || '');
};

주요 디버그 포인트
- API 키 확인
- Google GenAI SDK 로드 상태
- AudioContext 생성
- WebSocket 연결 (시도, 성공, 실패, 종료)
- 미디어 스트림 (마이크 접근 권한)
- 세션 관리
콘솔 출력
- 연결 성공/실패/종료 시 전체 디버그 로그 출력
- 각 단계별 상세 정보 표시

이슈 3: API 키 종류 혼동

문제: Vertex AI API 키와 Gemini API 키의 차이점 불명확

해결:

Google AI Studio에서 발급받은 일반 Gemini API 키 사용
API_KEY_GUIDE.md 문서 작성
get_api_key.php에서 프로젝트 검증 로직 추가

이슈 4: ScriptProcessorNode Deprecation 경고

경고: ScriptProcessorNode는 deprecated되었으며 AudioWorkletNode 사용 권장

현재 상태:

기능은 정상 동작
향후 AudioWorkletNode로 마이그레이션 필요

참고: https://bit.ly/audio-worklet

주요 컴포넌트

LiveManager 클래스

Gemini Live API와의 연결을 관리하는 핵심 클래스입니다.

주요 메서드:

initAI(): Google GenAI SDK 초기화
connect(): WebSocket 연결 시작
handleOpen(): 연결 성공 시 미디어 스트림 시작
handleMessage(): 서버 메시지 처리 (오디오, 도구 호출)
cleanup(): 리소스 정리
disconnect(): 연결 종료

상태 관리:

isConnected: 연결 상태 플래그
session: WebSocket 세션 객체
inputAudioContext: 입력 오디오 컨텍스트 (16kHz)
outputAudioContext: 출력 오디오 컨텍스트 (24kHz)
mediaStream: 마이크 스트림
scriptProcessor: 오디오 처리 노드

App 컴포넌트

메인 React 컴포넌트로 UI와 상태를 관리합니다.

주요 기능:

메뉴 네비게이션
파일 검색
Sam AI 연결 관리
오디오 시각화

도구 (Tools)

AI가 사용할 수 있는 기능들:

navigateToPage: 대시보드 메뉴 네비게이션
searchDocuments: 파일 검색

사용 방법

1. 기본 사용

브라우저에서 ai_sam/index.php 접속
"Call Sam" 버튼 클릭
마이크 접근 권한 허용
음성으로 명령 (예: "Settings 화면으로 이동해줘")

2. 디버그 모드

브라우저 개발자 도구 열기 (F12)
Console 탭 선택
"Call Sam" 버튼 클릭
콘솔에 출력되는 디버그 로그 확인

3. 예시 명령어

"Show me the finance dashboard"
"Find the Q3 report from October"
"Settings 화면으로 이동해줘"
"Find the financial report"

파일 구조 상세

index.php

메인 애플리케이션 파일로 다음을 포함합니다:

HTML 구조
React 컴포넌트 (Sidebar, FileList, Visualizer, App)
LiveManager 클래스
오디오 유틸리티 함수
상수 정의 (MOCK_FILES, MOCK_MENU, SYSTEM_INSTRUCTION)

api/get_api_key.php

API 키를 안전하게 조회하는 PHP 엔드포인트:

서비스 계정 프로젝트 검증
API 키 파일 읽기
플레이스홀더 텍스트 필터링
JSON 응답 반환

보안 고려사항

API 키 보호
- API 키는 서버 측에서만 관리
- 클라이언트에 직접 노출되지 않음
- get_api_key.php를 통해서만 전달
프로젝트 검증
- Codebridge-Chatbot 프로젝트만 허용
- 서비스 계정 정보로 검증
HTTPS 권장
- 마이크 접근 권한은 HTTPS 또는 localhost에서만 가능
- 프로덕션 환경에서는 반드시 HTTPS 사용

성능 최적화

오디오 처리
- ScriptProcessorNode 사용 (향후 AudioWorkletNode로 마이그레이션 예정)
- 16kHz 샘플레이트로 입력 최적화
- 24kHz 샘플레이트로 출력 최적화
리소스 관리
- 연결 종료 시 모든 리소스 정리
- 메모리 누수 방지
에러 처리
- 모든 비동기 작업에 try-catch 적용
- 사용자 친화적 에러 메시지

향후 개선 사항

AudioWorkletNode 마이그레이션
- ScriptProcessorNode 대신 AudioWorkletNode 사용
- 더 나은 성능과 안정성
에러 복구 메커니즘
- 자동 재연결 기능
- 네트워크 오류 처리 개선
사용자 경험 개선
- 연결 상태 시각적 표시 개선
- 오디오 레벨 표시 개선
- 더 많은 도구 추가

참고 자료

변경 이력

2025-01-XX (초기 개발)

Sam AI 기본 구조 구현
React (CDN) 기반 UI 구성
Gemini Live API 통합
실시간 음성 대화 기능 구현
도구 시스템 (navigateToPage, searchDocuments) 구현
디버그 로깅 시스템 구축
WebSocket 연결 안정화
API 키 관리 시스템 구축
Codebridge-Chatbot 프로젝트 연동

문제 해결 체크리스트

연결이 안 될 때 확인 사항:

API 키가 올바르게 설정되었는가? (apikey/gemini_api_key.txt)
API 키 형식이 올바른가? (약 39자, AIzaSy로 시작)
Google Cloud Console에서 "Generative Language API"가 활성화되었는가?
Codebridge-Chatbot 프로젝트에서 API 키가 생성되었는가?
브라우저 콘솔에 에러 메시지가 있는가?
마이크 접근 권한이 허용되었는가?
HTTPS 또는 localhost에서 실행 중인가?
Google GenAI SDK가 정상적으로 로드되었는가?

개발자 노트

모든 디버그 로그는 브라우저 콘솔에서 확인 가능
연결 과정의 각 단계는 타임스탬프와 함께 로깅됨
에러 발생 시 전체 디버그 로그가 자동으로 출력됨
API 키는 절대 클라이언트 코드에 하드코딩하지 않음

10 KiB Raw Blame History