AI API 키 설정 — 명함 OCR · 미팅 요약 · AI 명령
워크허브의 AI 기능 (CRM 명함 자동 인식, 미팅 트랜스크립트 요약, AI 슬래시 명령 등) 을 사용하려면 본인 기관의 Google Gemini API 키 를 등록해야 합니다.
왜 본인 키인가: 워크허브가 운영자(시스템관리자) 키 한 개로 전 기관에 공급하면 비용 분배·쿼터 통제가 안 됩니다. 각 기관이 본인 Google AI Studio 계정으로 키를 발급해 등록하면, 그 기관 사용량은 그 기관 청구서로 가서 비용 투명성이 보장됩니다.
1. 지원 AI 제공자
현재 Google Gemini 만 지원합니다.
| 모델 | 용도 권장 | 무료 한도 |
|---|---|---|
| gemini-2.5-flash (기본) | 일반 텍스트 요약 / 명함 OCR / AI 명령 | 15 RPM · 100만 TPM · 일 1500 요청 |
| gemini-2.5-pro | 고품질 분석 (긴 회의록·복잡 문서) | 5 RPM · 250K TPM · 일 100 요청 |
| gemini-2.0-flash | 안정 버전 (구버전 호환) | 동일 |
| gemini-2.0-flash-lite | 저비용 (경량 작업) | 더 큰 한도 |
대부분 운영에서는 gemini-2.5-flash 면 충분합니다.
2. 사전 준비 — Google AI Studio 에서 키 발급
2.1 Google 계정 준비
- 본인 Workspace 계정 또는 일반 Gmail 계정 모두 가능
- 결제 정보 등록은 무료 한도 안에서는 불필요 — 일 1500 요청까지 무료
2.2 API 키 생성
- https://aistudio.google.com/apikey 접속
- 로그인 (위 계정)
- "Create API key" 클릭
- 프로젝트 선택 (없으면 "Create API key in new project")
- 생성된 키
AIza...형태 — 즉시 복사 (이후 다시 노출 안됨)
보안 주의:
- 키를 메일/메신저로 전달하지 말 것 — 누출 시 누군가 본인 쿼터를 소진할 수 있음
- 워크허브에 입력한 후엔 화면에
AIzaS****...***식으로 마스킹돼 표시됩니다- 누출이 의심되면 https://aistudio.google.com/apikey 에서 즉시 폐기
2.3 (선택) 키 사용 제한
Google Cloud Console → 본인 프로젝트 → API 및 서비스 → 사용자 인증 정보 → 그 API 키 클릭:
- HTTP 리퍼러 제한: 안 함 (워크허브 백엔드가 호출하므로 IP 제한 추천 X)
- API 제한: "Generative Language API" 만 허용 — 권장
3. 워크허브에 등록
3.1 화면 이동
좌측 사이드바 AI 설정 또는 /app/ai-settings 직접 접속.
권한: 본인이 기관관리자(
org_admin) 또는 시스템관리자(system_admin) 인 경우에만 진입 가능. 일반 사용자에게 키 등록 화면 노출하지 않습니다 (혹여 누가 본인 사적 키를 등록해 기관 전체가 의존하는 사태 방지).
3.2 등록
┌─────────────────────────────────────────────────────────────┐
│ AI 설정 │
│ ──────────────────────────────────────────────────────────── │
│ 등록된 키 (0) │
│ │
│ ╔═══════ Google Gemini ═══════════════════════════════════╗ │
│ ║ 모델: [gemini-2.5-flash ▼] ║ │
│ ║ 키: [AIza_______________________________] 👁 ║ │
│ ║ ║ │
│ ║ [+ 등록] 가이드: https://aistudio.google.com/apikey ║ │
│ ╚══════════════════════════════════════════════════════════╝ │
└─────────────────────────────────────────────────────────────┘- 모델 선택 — 기본
gemini-2.5-flash권장 - API 키 붙여넣기 — 입력 후 👁 토글로 가렸다 폈다 가능
- [등록] 클릭
3.3 자동 검증
등록 시 백엔드가 즉시 Gemini API 에 짧은 호출을 보내 키 유효성을 검사:
- ✅ valid — "API 키가 정상적으로 등록되었습니다" → 키 카드에
AIzaS****...***,created_at,is_active=true - ❌ invalid — "키가 거부됨 (잘못된 키 또는 API 미활성)" → 등록 실패. 다시 확인.
3.4 무료 쿼터 현황 카드
등록 후 화면 상단에 "무료 쿼터 현황" 카드가 활성. [쿼터 확인] 클릭 시:
┌─────────────────────────────────────────────────────────────┐
│ 무료 쿼터 현황 [쿼터 확인] │
│ ──────────────────────────────────────────────────────────── │
│ 🟢 사용 가능 gemini-2.5-flash │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ 요청 한도 │ │ 토큰 한도 │ │
│ │ 1,432 / 1,500 │ │ 952K / 1M │ │
│ └──────────────────┘ └──────────────────┘ │
│ 55초 후 리셋 │
└─────────────────────────────────────────────────────────────┘- 🟢 사용 가능 / 🔴 쿼터 초과 / ⚪ 미확인
- 분당 RPM 한도와 일 한도 둘 다 표시
- 일 한도 초과 시 다음 날 자정(태평양 시각) 리셋
4. AI 기능이 어디서 사용되나
키 등록 후 즉시 다음 기능들이 활성화됩니다:
| 기능 | 위치 | 호출 패턴 |
|---|---|---|
| CRM 명함 OCR (Gemini Vision) | 고객관리 → 명함 → [OCR 처리] | 1 명함당 1회 (이미지 분석) |
| CRM 명함 텍스트 파싱 | 고객관리 → 명함 → [텍스트 붙여넣기] | 1 텍스트당 1회 |
| CRM 미팅 트랜스크립트 요약 | 고객관리 → 미팅 → 트랜스크립트 ingest | 1 트랜스크립트당 1~2회 (요약+태스크 추출) |
| 고객사 매칭 제안 (CRM-M8) | 명함 확정 시 자동 | 신규 명함 확정 시 1회 |
| AI 슬래시 명령 | 메시지/채팅에서 /ai ... | 명령당 1회 |
| 메일 자동 분류 (사용자 선택) | Claude MCP 스킬 호출 시 | 별도 — Claude 측 API 사용 |
호출량 추정
| 시나리오 | 일 호출 추정 |
|---|---|
| 직원 30명 / 명함 평균 5장/일 | 약 150 |
| 미팅 10건/일 (트랜스크립트 ingest) | 약 30 |
| AI 슬래시 명령 평균 사용 | 약 50~100 |
| 합계 | 약 200~280 (무료 1500 한도 안에서 충분) |
→ 직원 100명 규모도 무료 한도 안에서 운영 가능. 대기업/대량 사용은 결제 등록 권장.
5. 키 관리 (기관관리자)
키 비활성화 / 삭제
화면의 키 카드 우측:
- [🗑 삭제] → 즉시 삭제. AI 기능이 화면에서 자동 비활성.
- 사용량이 의심되면 삭제 → AI Studio 에서 새 키 발급 → 재등록
키 회전 (정기 교체 권장)
보안 베스트 프랙티스 — 분기별 1회:
- AI Studio 에서 새 키 생성
- 워크허브에서 새 키 등록
- 새 키 유효 확인 후 기존 키 삭제 (워크허브 + AI Studio 양쪽)
여러 모델 동시 사용
워크허브는 한 번에 한 모델만 활성. 다른 모델로 바꾸려면:
- 기존 키 삭제
- 다른 모델 선택 + 새 키 (또는 같은 키) 등록
6. FAQ
Q. 무료 한도를 초과하면 어떻게 되나요?
- 분당 (RPM) 초과 → 잠시 (1분) 후 자동 복구
- 일 한도 초과 → 다음 날 자정 (태평양 시각, 한국 17시) 까지 AI 기능 일시 중단
- 사용자에게는 "AI 일시 사용 불가 — 내일 다시 시도" 안내
Q. 결제 등록하면 한도가 어떻게 되나요?
Google AI Studio 결제 등록 후:
- gemini-2.5-flash: 1000 RPM · 4M TPM (무료의 60배+)
- 비용: 1M 입력 토큰당 $0.075 / 1M 출력 토큰당 $0.30 (2026년 6월 기준)
- 일 1500 한도 → 무제한 (사용량만큼 청구)
Q. 시스템관리자가 운영하는 워크허브 자체 키 같은 건 없나요?
없습니다 — 각 기관이 본인 키를 등록해야 합니다 (비용·쿼터 분리 원칙). 시스템 관점에서는 무료 한도 안에서는 사용자 부담 없이 시작할 수 있습니다.
Q. CRM/메일을 안 쓰는데 AI 키를 등록해야 하나요?
아니요. AI 기능을 안 쓰면 키 미등록 상태로 운영 가능. 단:
- CRM 명함 OCR 기능 자체가 비활성됨 — 명함 수동 입력만 가능
- 미팅 자동 요약 안됨 — 사용자가 직접 작성
- AI 슬래시 명령 안됨
Q. 키를 등록했는데 명함 OCR 이 동작 안 합니다.
체크:
- AI 설정 화면에서 키 카드의
is_active가 true 인지 - 무료 쿼터 현황 클릭 — 일 한도 초과 여부
- 모델이
gemini-2.5-flash등 vision 지원 모델인지 (lite 변종은 vision 미지원)
Q. 다른 AI 제공자 (OpenAI, Anthropic) 는 지원 안 하나요?
현재는 미지원. Gemini 만 지원하는 이유:
- 무료 한도가 후함 (1500 req/day) → 워크허브 도입 즉시 운영 가능
- Vision (명함 OCR) 이 무료 한도에 포함
- 모델 응답 품질이 OCR/요약 작업에 적합
향후 OpenAI/Anthropic 지원 검토 — 별도 이슈로 등록 가능.
Q. Claude 측에서 호출하는 AI (메일 트리아지 스킬 등) 도 이 키를 쓰나요?
아니요. Claude 가 호출하는 AI 는 Claude 자체의 모델 입니다. 본인이 Claude Desktop/Code 에서 사용하는 API/구독으로 직접 결제. 워크허브 측 Gemini 키와 무관.
7. 트러블슈팅
"AI 설정에서 Gemini API 키를 등록해주세요"
CRM 명함 OCR 등을 시도했는데 이 메시지가 뜨면 → 위 3.2 단계로 등록.
"키 유효성 검사 실패: API key not valid"
원인:
- 키 복사 시 공백/줄바꿈 포함
- AI Studio 에서 키를 삭제한 상태 (이미 폐기)
- Google Cloud 프로젝트에서 Generative Language API 가 비활성
해결: 새 키 발급 + 재등록.
"RESOURCE_EXHAUSTED" 또는 429 에러
일·분 한도 초과. 무료 쿼터 현황 카드에서 리셋 시각 확인. 즉시 필요하면:
- 결제 등록으로 한도 확장 (Google AI Studio)
- 또는 임시로 본인 다른 Google 계정 키로 교체
8. 보안 / 개인정보
- API 키는 DB 저장 시 AES-GCM 암호화 — 시스템관리자도 평문 조회 불가
- 화면 응답에는 마스킹된 hint (
AIzaS****...***) 만 포함 — 평문 절대 회신 안됨 - 키 호출 시 워크허브 백엔드 → Gemini API 직접 (사용자 브라우저 거치지 않음)
- 호출 로그는 audit table 에 기록 (호출 시각·기능·org_id만 — 키 자체나 응답 내용은 비저장)
- 의심되는 사용량 발견 시 본인이 AI Studio 에서 즉시 폐기 → 워크허브 키도 자동 무효화
9. 운영자 (시스템관리자) 참고
기관관리자가 본인 키를 등록할 수 있게 하기 위해 운영자는 시스템 차원의 환경변수가 필요합니다:
| 환경변수 | 목적 | 미설정 시 |
|---|---|---|
AI_KEY_ENC_KEY 또는 통합 키 | API 키 AES-GCM 마스터 | AI 설정 화면 등록 자체가 안됨 |
운영자 자체가 별도로 Gemini 키를 보유할 필요 없음 (기관 단위 등록 원칙).
관련 가이드
- AI 명령어 (사용자 가이드) — AI 슬래시 명령 사용법 (
/ai,/요약,/번역등) - CRM 모듈 (관리자) — 명함 OCR · 미팅 요약이 이 키를 사용
- Gmail 모듈 (관리자) — 메일 모듈 활성화 / OAuth scope
- Claude / MCP 클라이언트 연결 (사용자 가이드) — Claude 측 자동화 (별개 AI)