From 9fdbee5f0f4bdf323d0b28de3b5745d426d47922 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Mon, 2 Mar 2026 14:48:42 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20[google-cloud]=20AI=20=ED=99=9C?= =?UTF-8?q?=EC=9A=A9=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=ED=8E=98=EC=9D=B4?= =?UTF-8?q?=EC=A7=80=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AiGuideController 생성 (HX-Redirect 패턴) - STT, Speaker Diarization, 회의록, 음성녹음, Gemini, GCS, AI Config 정보 페이지 - Google Cloud 메뉴 하위에 라우트 등록 --- .../GoogleCloud/AiGuideController.php | 20 + .../google-cloud/ai-guide/index.blade.php | 733 ++++++++++++++++++ routes/web.php | 4 + 3 files changed, 757 insertions(+) create mode 100644 app/Http/Controllers/GoogleCloud/AiGuideController.php create mode 100644 resources/views/google-cloud/ai-guide/index.blade.php diff --git a/app/Http/Controllers/GoogleCloud/AiGuideController.php b/app/Http/Controllers/GoogleCloud/AiGuideController.php new file mode 100644 index 00000000..5521c86b --- /dev/null +++ b/app/Http/Controllers/GoogleCloud/AiGuideController.php @@ -0,0 +1,20 @@ +header('HX-Request')) { + return response('', 200)->header('HX-Redirect', route('google-cloud.ai-guide.index')); + } + + return view('google-cloud.ai-guide.index'); + } +} diff --git a/resources/views/google-cloud/ai-guide/index.blade.php b/resources/views/google-cloud/ai-guide/index.blade.php new file mode 100644 index 00000000..beabf671 --- /dev/null +++ b/resources/views/google-cloud/ai-guide/index.blade.php @@ -0,0 +1,733 @@ +@extends('layouts.app') + +@section('title', 'Google Cloud AI 활용 가이드') + +@push('styles') + +@endpush + +@section('content') +
+ + {{-- 페이지 헤더 --}} +
+
+

Google Cloud AI 활용 가이드

+

SAM에서 활용 중인 Google Cloud AI 서비스 총정리 | @codebridge-x.com

+
+
+ CodeBridgeX | 2026.03 +
+
+ + {{-- ─── 핵심 요약 4카드 ─── --}} +
+
+
+ + 음성 인식 +
+
Speech-to-Text
+
V1 + V2 Chirp 2 자동 폴백
+
+
+
+ + AI 분석 +
+
Gemini 2.0 Flash
+
재무 분석, 회의 요약, 명함 OCR
+
+
+
+ + 클라우드 저장 +
+
Cloud Storage
+
음성/파일 백업, 서명 URL
+
+
+
+ + 설정 관리 +
+
AI Config
+
다중 Provider, 토큰/비용 추적
+
+
+ + {{-- ─── Section 1: SAM AI 아키텍처 개요 ─── --}} +
+
+

SAM AI 아키텍처 개요

+

Google Cloud 기반 AI 서비스 통합 구조

+
+
+ {{-- 아키텍처 다이어그램 --}} +
+ 
+    ┌─────────────────────────────────────────────────────────────────────┐
+    │                        SAM 관리자 (MNG)                            │
+    │                                                                    │
+    │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐             │
+    │  │ 회의록    │ │ 음성녹음  │ │ 상담메모  │ │ 재무분석  │             │
+    │  │ 시스템    │ │ 분석     │ │ STT 입력  │ │ AI리포트  │             │
+    │  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘             │
+    │       │            │            │            │                     │
+    │  ┌────▼────────────▼────────────▼────────────▼─────┐              │
+    │  │           GoogleCloudService                     │              │
+    │  │  ┌─────────────┐  ┌───────────────┐             │              │
+    │  │  │ STT V2      │  │ STT V1        │             │              │
+    │  │  │ (Chirp 2)   │  │ (latest_long) │  ← 자동폴백 │              │
+    │  │  └──────┬──────┘  └───────┬───────┘             │              │
+    │  │         └────────┬────────┘                      │              │
+    │  │    ┌─────────────┼──────────────┐                │              │
+    │  │    │ Speaker     │ GCS Upload   │                │              │
+    │  │    │ Diarization │ /Download    │                │              │
+    │  │    └─────────────┴──────────────┘                │              │
+    │  └──────────────────────────────────────────────────┘              │
+    │                          │                                         │
+    └──────────────────────────┼─────────────────────────────────────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │  Google Cloud APIs   │
+                    │                     │
+                    │  Speech-to-Text     │
+                    │  Cloud Storage      │
+                    │  Vertex AI (Gemini) │
+                    └─────────────────────┘
+
+ + {{-- 서비스 매핑 테이블 --}} +
SAM 서비스 ↔ Google Cloud API 매핑
+ + + + + + + + + + + + @php + $services = [ + ['sam' => '회의록 자동 생성', 'api' => 'Speech-to-Text', 'model' => 'Chirp 2 / latest_long', 'status' => '운영중', 'file' => 'MeetingMinuteService'], + ['sam' => '음성 녹음 분석', 'api' => 'Speech-to-Text', 'model' => 'Chirp 2 + Gemini', 'status' => '운영중', 'file' => 'AiVoiceRecordingService'], + ['sam' => '상담 메모 음성 입력', 'api' => 'Speech-to-Text', 'model' => 'V1 latest_long', 'status' => '운영중', 'file' => 'GoogleCloudService'], + ['sam' => '재무 AI 리포트', 'api' => 'Vertex AI (Gemini)', 'model' => 'gemini-2.0-flash', 'status' => '운영중', 'file' => 'AiReportService (API)'], + ['sam' => '명함 OCR', 'api' => 'Gemini API', 'model' => 'gemini-2.0-flash', 'status' => '운영중', 'file' => 'GeminiService'], + ['sam' => '오디오 백업/저장', 'api' => 'Cloud Storage', 'model' => 'Standard Class', 'status' => '운영중', 'file' => 'GoogleCloudStorageService'], + ['sam' => 'AI 설정 관리', 'api' => '—', 'model' => '다중 Provider', 'status' => '운영중', 'file' => 'AiConfig (Model)'], + ['sam' => '토큰/비용 추적', 'api' => '—', 'model' => 'USD/KRW 환산', 'status' => '운영중', 'file' => 'AiTokenHelper'], + ]; + @endphp + @foreach($services as $svc) + + + + + + + + @endforeach + +
SAM 서비스Google Cloud API모델/엔진상태소스 파일
{{ $svc['sam'] }}{{ $svc['api'] }}{{ $svc['model'] }} + {{ $svc['status'] }} + {{ $svc['file'] }}
+
+
+ + {{-- ─── Section 2: Speech-to-Text (음성 인식) ─── --}} +
+
+
+
+ +
+
+

Speech-to-Text — 음성 인식

+

V2 Chirp 2 → V1 latest_long 자동 폴백 전략

+
+
+
+
+ {{-- V2 vs V1 비교 --}} +
+
+
+ V2 (Primary) + Chirp 2 모델 +
+
+
▶ Chirp 2 — Google 최신 음성 인식 모델
+
▶ Batch Recognize API (비동기 처리)
+
▶ Speaker Diarization (화자 분리) 내장
+
▶ Speech Adaptation — phrase hints 지원
+
▶ 자동 구두점, 단어별 타임스탬프
+
+
메서드: speechToTextV2()
+
+ +
+
+ V1 (Fallback) + latest_long 모델 +
+
+
▶ latest_long — 안정적인 기본 모델
+
▶ LongRunningRecognize API (비동기)
+
▶ Speaker Diarization (2~6명)
+
▶ WEBM_OPUS, 48kHz, 2ch 인코딩
+
▶ V2 실패 시 자동 폴백으로 안정성 확보
+
+
메서드: speechToTextWithDiarization()
+
+
+ + {{-- 자동 폴백 플로우 --}} +
자동 폴백 흐름 (speechToTextWithDiarizationAuto)
+
+ @php + $sttFlow = [ + ['num' => 1, 'title' => 'GCS 업로드', 'desc' => '오디오 → gs://', 'color' => '#ea4335'], + ['num' => 2, 'title' => 'V2 Chirp 2', 'desc' => '최신 모델 시도', 'color' => '#4285f4'], + ['num' => 3, 'title' => '성공?', 'desc' => '결과 확인', 'color' => '#fbbc04'], + ['num' => 4, 'title' => 'V1 폴백', 'desc' => '실패 시 V1', 'color' => '#34a853'], + ['num' => 5, 'title' => '파싱', 'desc' => '화자별 세그먼트', 'color' => '#4285f4'], + ]; + @endphp + @foreach($sttFlow as $step) +
+
{{ $step['num'] }}
+
{{ $step['title'] }}
+
{{ $step['desc'] }}
+
+ @endforeach +
+ + {{-- Speaker Diarization 설명 --}} +
+
+ + Speaker Diarization — 화자 분리 +
+

회의 녹음에서 각 발화자를 자동 식별합니다. 최소 2명~최대 6명까지 지원하며, 결과는 [화자 1] 텍스트 형태의 세그먼트로 반환됩니다. SentencePiece 토크나이저 결과를 자연어로 재결합하는 후처리가 포함됩니다.

+
+
+
+ + {{-- ─── Section 3: 회의록 자동 생성 시스템 ─── --}} +
+
+
+
+ +
+
+

회의록 자동 생성 시스템

+

MeetingMinuteService — 녹음 → STT → Gemini 요약

+
+
+
+
+ {{-- 처리 플로우 --}} +
+ @php + $meetingFlow = [ + ['num' => 1, 'title' => '녹음', 'desc' => '브라우저 WebRTC', 'color' => '#ea4335'], + ['num' => 2, 'title' => 'GCS 업로드', 'desc' => '오디오 백업', 'color' => '#fbbc04'], + ['num' => 3, 'title' => 'STT 변환', 'desc' => '화자 분리 포함', 'color' => '#4285f4'], + ['num' => 4, 'title' => 'Gemini 요약', 'desc' => 'AI 자동 요약', 'color' => '#34a853'], + ['num' => 5, 'title' => '회의록 저장', 'desc' => 'DB 기록', 'color' => '#9334e9'], + ]; + @endphp + @foreach($meetingFlow as $step) +
+
{{ $step['num'] }}
+
{{ $step['title'] }}
+
{{ $step['desc'] }}
+
+ @endforeach +
+ + {{-- 기능 카드 --}} +
+
+
핵심 기능
+
+
✓ 브라우저 내 실시간 녹음 (WebM/Opus)
+
✓ 화자별 발화 자동 분리 (2~6명)
+
✓ Gemini AI 회의 내용 자동 요약
+
✓ 회의록 검색/필터/페이지네이션
+
✓ 화자 이름 수동 편집 기능
+
+
+
+
데이터 구조
+
+
meeting_minutes 회의 메타 정보
+
meeting_minute_segments 화자별 세그먼트
+
상태: draft → recording → processing → completed
+
GCS URI로 원본 오디오 보관
+
full_transcript + ai_summary 저장
+
+
+
+
사용되는 API
+
+
STT Speech-to-Text V2
+
AI Gemini 2.0 Flash
+
GCS Cloud Storage
+
인증: Service Account (OAuth 2.0)
+
+
+
+
+
+ + {{-- ─── Section 4: 음성 녹음 분석 ─── --}} +
+
+
+
+ +
+
+

음성 녹음 분석

+

AiVoiceRecordingService — 녹음 → STT → Gemini 분석

+
+
+
+
+
+
+
처리 파이프라인
+
+ @php + $pipeline = [ + ['step' => '1. 오디오 수신', 'desc' => 'Base64 인코딩된 WebM/Opus 오디오를 수신', 'icon' => '🔊'], + ['step' => '2. GCS 업로드', 'desc' => 'Google Cloud Storage에 원본 백업 (gs://bucket/recordings/...)', 'icon' => '☁'], + ['step' => '3. STT 변환', 'desc' => 'V2 Chirp 2 → V1 자동 폴백으로 텍스트 변환', 'icon' => '💬'], + ['step' => '4. Gemini 분석', 'desc' => 'AI가 음성 내용을 분석/요약하여 인사이트 생성', 'icon' => '🤖'], + ['step' => '5. 결과 저장', 'desc' => 'transcript_text + analysis_text를 DB에 저장', 'icon' => '💾'], + ]; + @endphp + @foreach($pipeline as $p) +
+ {{ $p['icon'] }} +
+
{{ $p['step'] }}
+
{{ $p['desc'] }}
+
+
+ @endforeach +
+
+ +
+
인터뷰 템플릿 기능
+
+

음성 녹음 시 인터뷰 템플릿을 선택하면, Gemini가 해당 템플릿의 질문 항목에 맞춰 음성 내용을 구조화된 분석 결과로 변환합니다.

+
+
데이터 모델
+ + + + + + + + + + + + + + + + + + + +
테이블ai_voice_recordings
상태값pending → processing → completed / failed
저장 항목GCS URI, 원본 텍스트, 분석 결과, 소요 시간
파일 보관생성일로부터 7일 (file_expiry_date)
+
+
+
+
+ + {{-- ─── Section 5: Gemini AI 활용 ─── --}} +
+
+
+
+ +
+
+

Gemini AI 활용

+

Vertex AI — 재무 분석 리포트, 회의 요약, 명함 OCR

+
+
+
+
+
+ {{-- 재무 분석 --}} +
+
+ 운영중 + AI 재무 분석 리포트 +
+

테넌트의 비즈니스 데이터(지출, 매출, 매입, 입출금, 카드/계좌, 미수금)를 자동 수집하여 일간/주간/월간 분석 리포트를 생성합니다.

+
+
서비스: AiReportService (API 프로젝트)
+
모델: gemini-2.0-flash (Vertex AI)
+
분석 영역: 지출, 매출, 매입, 입출금, 카드/계좌, 미수금
+
API: POST /v1/reports/ai/generate
+
+
+ + {{-- 회의 요약 --}} +
+
+ 운영중 + 회의 내용 AI 요약 +
+

STT로 변환된 회의 전문을 Gemini에 전달하여 핵심 내용, 결정 사항, 후속 조치 항목을 자동으로 요약합니다.

+
+
서비스: MeetingMinuteService (MNG)
+
모델: gemini-2.0-flash
+
입력: 화자별 세그먼트 전체 텍스트
+
출력: ai_summary 필드에 저장
+
+
+ + {{-- 명함 OCR --}} +
+
+ 운영중 + 명함 OCR +
+

명함 이미지를 Gemini Vision에 전달하여 이름, 직함, 회사, 전화번호, 이메일 등을 자동 추출합니다.

+
+
서비스: GeminiService (MNG)
+
메서드: extractBusinessCard()
+
입력: 명함 이미지 파일
+
출력: 구조화된 연락처 정보 JSON
+
+
+
+ + {{-- 토큰 사용량 추적 --}} +
+
+ + 토큰 사용량 & 비용 추적 (AiTokenHelper) +
+
+
+

모든 Gemini API 호출 시 토큰 사용량과 비용을 자동으로 기록합니다.

+
+
테이블: ai_token_usages
+
기록 항목: provider, model, menu, input/output tokens
+
비용 계산: ai_pricing_configs 테이블의 단가 참조
+
+
+
+
비용 계산 흐름
+
AiTokenHelper::record( + provider: 'gemini', + model: 'gemini-2.0-flash', + menu: 'meeting-minutes', + inputTokens: 1520, + outputTokens: 350, + costUsd: 0.00012 +);
+
+
+
+
+
+ + {{-- ─── Section 6: Cloud Storage (GCS) ─── --}} +
+
+
+
+ +
+
+

Cloud Storage (GCS)

+

GoogleCloudStorageService — 파일 업로드, 다운로드, 서명 URL

+
+
+
+
+
+ {{-- 용도별 정리 --}} +
+
SAM에서의 GCS 활용
+ + + + + + + + + + + + + + + + + + + + + + + + + +
용도저장 경로설명
회의록 녹음meetings/{tenant}/{id}/WebM 오디오 원본
음성 녹음recordings/{tenant}/분석용 음성 파일
상담 음성consultations/{tenant}/10MB 이상 자동 백업
+
+ + {{-- 서비스 메서드 --}} +
+
주요 메서드 (2개 서비스)
+
+
+
GoogleCloudService (MNG)
+
+
uploadToStorage() 로컬 → GCS
+
uploadBase64Audio() Base64 → GCS
+
downloadFromStorage() GCS → 스트림
+
deleteFromStorage() GCS 파일 삭제
+
+
+
+
GoogleCloudStorageService (MNG)
+
+
upload() 파일 업로드 (URI 반환)
+
getSignedUrl() 서명 다운로드 URL (60분)
+
delete() 파일 삭제
+
isAvailable() 사용 가능 여부
+
+
+
+
+
+ + {{-- 설정 우선순위 --}} +
+
GCS 설정 우선순위
+
1. DB 설정 (ai_configs 테이블의 활성화된 gcs provider) + ↓ 없으면 +2. 환경변수 (.env: GCS_BUCKET_NAME, GCS_SERVICE_ACCOUNT_PATH) + ↓ 없으면 +3. 레거시 파일 (/sales/apikey/gcs_config.txt, google_service_account.json)
+
+
+
+ + {{-- ─── Section 7: AI 설정 관리 시스템 ─── --}} +
+
+
+
+ +
+
+

AI 설정 관리 시스템

+

AiConfig — 다중 Provider 관리, 연결 테스트, 토글 활성화

+
+
+
+
+ {{-- Provider 테이블 --}} +
지원 Provider
+
+ @php + $providers = [ + ['name' => 'Gemini', 'provider' => 'gemini', 'model' => 'gemini-2.0-flash', 'use' => '명함 OCR, 회의 요약, 음성 분석', 'color' => 'blue', 'auth' => 'Vertex AI / API Key'], + ['name' => 'Claude', 'provider' => 'claude', 'model' => 'claude-sonnet-4-20250514', 'use' => 'AI 재무 분석 (예비)', 'color' => 'purple', 'auth' => 'API Key'], + ['name' => 'OpenAI', 'provider' => 'openai', 'model' => 'gpt-4o', 'use' => '범용 AI (예비)', 'color' => 'green', 'auth' => 'API Key'], + ['name' => 'GCS', 'provider' => 'gcs', 'model' => '—', 'use' => '음성 녹음 백업, 파일 저장', 'color' => 'cyan', 'auth' => 'Service Account'], + ]; + @endphp + @foreach($providers as $prov) +
+
+ {{ $prov['name'] }} + {{ $prov['provider'] }} +
+
+
모델: {{ $prov['model'] }}
+
용도: {{ $prov['use'] }}
+
인증: {{ $prov['auth'] }}
+
+
+ @endforeach +
+ + {{-- DB 구조 --}} +
데이터베이스 구조
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
테이블설명주요 컬럼
ai_configsProvider별 설정name, provider, api_key, model, is_active, options(JSON)
ai_token_usages토큰 사용량 추적provider, model, menu, input/output_tokens, cost_usd, cost_krw
ai_pricing_configs모델별 단가 설정provider, model, input_price_per_1m, output_price_per_1m
ai_reportsAI 분석 리포트report_type(daily/weekly/monthly), content, status
ai_voice_recordings음성 녹음gcs_uri, transcript_text, analysis_text, duration_seconds
+ + {{-- 관리 UI 안내 --}} +
+ AI 설정 관리 페이지: 시스템 관리 > AI 설정 (/system/ai-config) — Provider별 추가/수정/삭제, 활성화 토글, 연결 테스트 가능 +
+
+
+ + {{-- ─── Section 8: 관련 소스 파일 정리 ─── --}} +
+
+

관련 소스 파일 & 문서

+

SAM Google Cloud AI 관련 전체 파일 매핑

+
+
+
+ {{-- 서비스 파일 --}} +
+
+ 서비스 (MNG) +
+
+ @php + $mngFiles = [ + ['file' => 'app/Services/GoogleCloudService.php', 'desc' => 'STT V1/V2, Speaker Diarization, GCS 업로드/다운로드'], + ['file' => 'app/Services/GoogleCloudStorageService.php', 'desc' => 'GCS 전용 서비스 (서명 URL, 설정 우선순위)'], + ['file' => 'app/Services/MeetingMinuteService.php', 'desc' => '회의록 생성/수정/삭제, STT+Gemini 파이프라인'], + ['file' => 'app/Services/AiVoiceRecordingService.php', 'desc' => '음성 녹음 처리, 인터뷰 템플릿 분석'], + ['file' => 'app/Services/GeminiService.php', 'desc' => 'Gemini API 호출 (명함 OCR 등)'], + ['file' => 'app/Helpers/AiTokenHelper.php', 'desc' => '토큰 사용량 기록, 비용 계산 (USD/KRW)'], + ]; + @endphp + @foreach($mngFiles as $f) +
+
{{ $f['file'] }}
+
{{ $f['desc'] }}
+
+ @endforeach +
+
+ + {{-- 모델 & API 파일 --}} +
+
+ 모델 & API +
+
+ @php + $modelFiles = [ + ['file' => 'app/Models/System/AiConfig.php', 'desc' => 'AI 설정 모델 (Provider별 활성 조회)'], + ['file' => 'app/Models/Juil/MeetingMinute.php', 'desc' => '회의록 모델 (상태 관리, 관계)'], + ['file' => 'app/Models/AiVoiceRecording.php', 'desc' => '음성 녹음 모델 (파일 만료, 상태)'], + ]; + $apiFiles = [ + ['file' => 'api/app/Services/AiReportService.php', 'desc' => '재무 분석 리포트 생성 (Gemini Vertex AI)'], + ['file' => 'config/gcs.php', 'desc' => 'GCS 환경변수 설정 매핑'], + ['file' => 'config/services.php', 'desc' => 'Google Cloud 서비스 설정 (credentials, bucket)'], + ]; + @endphp + @foreach($modelFiles as $f) +
+
{{ $f['file'] }}
+
{{ $f['desc'] }}
+
+ @endforeach + @foreach($apiFiles as $f) +
+
{{ $f['file'] }}
+
{{ $f['desc'] }}
+
+ @endforeach + +
+ 문서 +
+
+
docs/guides/ai-config-settings.md
+
AI 및 스토리지 설정 기술문서
+
+
+
docs/features/ai/README.md
+
AI 분석 리포트 기능 명세
+
+
+
+
+ + {{-- 한 줄 요약 --}} +
+
+ Google Cloud AI — SAM의 핵심 자동화 엔진 +
+

Speech-to-Text + Gemini + Cloud Storage = 음성/문서/분석 완전 자동화

+

(주)코드브릿지엑스 | @codebridge-x.com

+
+
+
+ +
+@endsection diff --git a/routes/web.php b/routes/web.php index 6ac0efd6..7482cc27 100644 --- a/routes/web.php +++ b/routes/web.php @@ -38,6 +38,7 @@ use App\Http\Controllers\ClaudeCode\UsagePlanController as ClaudeCodeUsagePlanController; use App\Http\Controllers\GoogleCloud\WorkspacePolicyController as GoogleCloudWorkspacePolicyController; use App\Http\Controllers\GoogleCloud\WorkspacePricingController as GoogleCloudWorkspacePricingController; +use App\Http\Controllers\GoogleCloud\AiGuideController as GoogleCloudAiGuideController; use App\Http\Controllers\GoogleCloud\CloudApiPricingController as GoogleCloudCloudApiPricingController; use App\Http\Controllers\Lab\StrategyController; use App\Http\Controllers\MenuController; @@ -757,6 +758,9 @@ ->name('cloud-api-pricing.index'); Route::get('/cloud-api-pricing/download', [GoogleCloudCloudApiPricingController::class, 'download']) ->name('cloud-api-pricing.download'); + + Route::get('/ai-guide', [GoogleCloudAiGuideController::class, 'index']) + ->name('ai-guide.index'); }); /*