본문으로 건너뛰기

AI Usage — 비용·호출 대시보드

이 문서는 운영자/관리자가 GenD의 LLM 호출 비용과 사용량을 점검할 때 사용합니다. 어떤 워크스페이스가 얼마나 쓰고 있는지, 실패율은 높지 않은지, 비용이 폭등한 use case는 무엇인지 한 화면에서 확인할 수 있습니다.

무엇을 할 수 있나요​

GenD가 외부 LLM(GenON 등)을 호출하면 호출 1건마다 토큰 수, 비용(USD), 응답 지연, 성공/실패 여부가 자동으로 기록됩니다. ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 사용량 화면에서 이 데이터를 use case별, 워크스페이스별, 프로바이더별로 집계해 볼 수 있고, 최근 100건의 개별 호출 로그도 바로 확인할 수 있습니다.

AI Usage 대시보드

그림: ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 사용량 — 3 KPI 카드, 집계 표, Recent calls 로그.

누가 사용할 수 있나요​

사용자 유형접근 가능 여부보이는 데이터
admin realm role 보유자O전 워크스페이스
워크스페이스 멤버 (/tenants/{slug} Keycloak group)X (본 화면)자기 워크스페이스 한정 화면은 별도 (/workspace/{slug}/usage)
그 외X (403)—

이 화면(/admin/llm-usage)은 전사 비용 가시성이 필요한 운영자 전용입니다. 워크스페이스 사용자에게 노출하려면 사용자에게 admin realm role을 부여하거나, 워크스페이스 단위 화면(별도 문서)을 안내하세요.

접근 권한 부여 절차​

운영자에게 권한을 줄 때:

  1. Keycloak Console 접속 → gend realm 선택
  2. Users → 해당 사용자 검색 → Role mapping 탭
  3. Assign role → admin realm role 체크 → Assign 클릭
  4. 사용자가 다시 로그인하면 /admin/llm-usage 메뉴가 노출됩니다.

화면 둘러보기​

상단부터 순서대로 다음 영역으로 구성돼 있습니다.

KPI 카드 (상단 3개)​

카드의미보는 법
Total calls선택 기간 총 호출 수트렌드 비교용. 평소 대비 급증/급감 확인
Total cost같은 기간 총 비용 (USD)월 예산 대비 잔여 확인
Failed rate실패 호출 ÷ 총 호출 비율0.5% 이상이면 원인 점검 권장

셀렉터 (상단 우측)​

  • Group by — use_case / workspace / provider 중 선택. 어떤 축으로 비용을 쪼개볼지 결정합니다.
  • Period — 7d / 30d / 90d 토글. 기본값은 30일입니다.
  • ↻ Refresh — 캐시 무시하고 즉시 재집계. 방금 한 호출까지 반영하고 싶을 때 사용하세요.

집계 표 (Buckets)​

Group by 키별로 한 줄씩 표시되며 비용 내림차순으로 정렬됩니다.

컬럼설명
Group keyuse case 이름 / 워크스페이스 슬러그 / 프로바이더 이름
Calls호출 건수
Prompt tk입력 토큰 합계
Completion tk출력 토큰 합계
Cost비용 합계 (USD)
Avg lat평균 응답 지연 (ms)
Failed실패 건수

Recent calls (하단)​

최근 100건의 개별 호출 로그입니다. 시간, use case, model, 토큰, 비용, 지연, 상태 컬럼이 보이며, status = failed 행을 빠르게 식별할 수 있습니다.

단계별 사용법​

시나리오 1 — 이번 달 비용이 얼마나 나왔는지 확인​

  1. 사이드바 하단 ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 사용량 클릭
  2. 상단 셀렉터에서 30d 클릭
  3. Total cost 카드의 USD 값을 확인하세요

시나리오 2 — 어느 워크스페이스가 비용을 많이 쓰는지 확인​

  1. 상단 Group by 셀렉터를 workspace 로 변경
  2. 표 첫 줄(비용 내림차순 정렬)이 가장 많이 쓰는 워크스페이스입니다
  3. 해당 워크스페이스 슬러그를 메모하고, 필요하면 워크스페이스 쿼터(별도 문서)에서 한도를 조정하세요

시나리오 3 — 실패가 늘었을 때 원인 찾기​

  1. Failed rate 카드가 평소보다 높으면 클릭(또는 표를 status 열로 정렬)
  2. 화면 하단 Recent calls 표에서 status = failed 행 확인
  3. 같은 model/use_case가 반복 실패하면 해당 프로바이더 healthcheck(별도 문서)에서 endpoint·key 상태를 점검하세요

API 직접 호출 (선택)​

UI 대신 스크립트로 데이터를 끌어가야 할 때:

# 30일 use_case 집계
curl -H "Authorization: Bearer $ADMIN_JWT" \
  "https://gend.genon.ai/api/v1/llm-usage/summary?group_by=use_case&days=30"

# 특정 워크스페이스 최근 7일 호출 로그 100건
curl -H "Authorization: Bearer $ADMIN_JWT" \
  "https://gend.genon.ai/api/v1/llm-usage/log?workspace_slug=finance-invest&days=7&limit=100"
MethodPath설명
GET/api/v1/llm-usage/summary집계 (group_by=use_case/workspace/provider)
GET/api/v1/llm-usage/log호출 단위 로그 (drill-down)

두 endpoint 모두 admin 권한 필요. 일반 사용자 JWT로 호출하면 403.

자주 묻는 질문 / 문제 해결​

Q. 비용 값이 0으로만 나옵니다. A. 프로바이더 등록 시 cost_per_1m_input / cost_per_1m_output 단가를 채우지 않은 경우입니다. ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 제공자 에서 해당 프로바이더를 편집하여 단가를 입력하세요.

Q. 호출은 분명 했는데 표에 안 보입니다. A. (1) 기간(7d/30d/90d) 셀렉터를 더 넓혀보세요. (2) 호출 직후 1~2초 내에는 집계 반영이 늦을 수 있으니 Refresh 버튼을 누르세요. (3) 그래도 없으면 API 측 호출 사이트가 emit_call_log 헬퍼를 호출하지 않는 경로일 수 있습니다 — 운영팀에 문의하세요.

Q. workspace_id가 NULL인 행은 무엇인가요? A. 워크스페이스 컨텍스트 없이 실행된 시스템/배경 호출입니다 (예: 헬스체크, 스케줄러). 정상이며, group_by=workspace 시 (NULL/global) 버킷으로 묶입니다.

Q. provider_id가 NULL이고 (env_fallback)으로 표시됩니다. A. DB에 등록된 프로바이더가 아니라 환경변수 fallback으로 호출된 건입니다. 운영 환경에서는 가급적 프로바이더를 등록해 비용 추적이 누락되지 않도록 하세요.

Q. 메뉴가 안 보입니다. A. 위 접근 권한 부여 절차에 따라 admin realm role이 부여돼 있는지 확인하세요. 부여 후 재로그인이 필요합니다.

Q. 화면을 새로 띄워도 데이터가 갱신되지 않습니다. A. 브라우저 캐시 가능성이 큽니다. Shift+새로고침 후에도 같으면, /api/v1/llm-usage/summary 응답을 curl로 직접 확인해 보세요.

참고​