> For the complete documentation index, see [llms.txt](https://docs.smply.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smply.one/ai/gemini-dashboard.md).

# Gemini 연동 및 대시보드

## Gemini 연동 및 대시보드

조직의 Gemini 사용 현황을 한 화면에서 분석합니다. Gemini는 서로 다른 두 개의 연동으로 나뉩니다. \*\*`Gemini Code Assist`\*\*는 코드 어시스턴트 사용량과 생산성(활성 사용자·코드 제안 승인·토큰)을 보여주고, \*\*`Gemini Enterprise`\*\*는 Google Workspace의 Gemini Enterprise 라이선스가 누구에게 할당됐는지를 보여줍니다. 두 연동은 서로 독립적이며, 각각 GCP 프로젝트를 등록했을 때 해당 대시보드가 채워집니다.

{% hint style="info" %}
**두 연동은 별개입니다** **`Gemini Code Assist`**(코드 어시스턴트 사용량)와 **`Gemini Enterprise`**(라이선스 할당 현황)는 등록 방법·필요한 정보·대시보드가 모두 다릅니다. 사용하려는 대상에 맞는 섹션을 따라가세요.
{% endhint %}

***

### 1. Gemini Code Assist 연동하기

Gemini Code Assist 연동은 **`설정`** > **`연동 관리`** 목록에는 카드로 노출되지 않습니다. 대시보드(`/ai/gemini`) 또는 연동 설정 화면(`/settings/integration/gemini`)에서 직접 진입합니다.

{% hint style="info" %}
**필요한 준비물**

* Gemini Code Assist가 활성화된 **GCP 프로젝트** 1개 이상
* 해당 GCP 프로젝트에 심플리 서비스 계정을 추가할 수 있는 권한
  {% endhint %}

**단계 1: 서비스 계정 추가**

1. 연동 설정 화면 상단의 **서비스 계정** 카드에 표시된 이메일을 확인합니다.
2. **`이메일 복사`** 버튼으로 서비스 계정 이메일을 복사합니다 (`smply-gcp-sa@smply-prod.iam.gserviceaccount.com`).
3. 복사한 서비스 계정을 연동하려는 GCP 프로젝트에 추가합니다.

**단계 2: GCP 프로젝트 등록**

1. **GCP 프로젝트** 카드의 `GCP 프로젝트 ID` 입력란에 프로젝트 ID를 입력합니다 (placeholder: `my-gcp-project-123`).
2. **`프로젝트 추가`** 버튼을 누릅니다.
3. 추가된 프로젝트는 아래 목록에 나타나며, 상태가 **`인증됨`** / **`대기 중`** / **`인증 실패`** 중 하나로 표시됩니다.

**프로젝트 상태**

| 상태          | 의미                                                                 |
| ----------- | ------------------------------------------------------------------ |
| **`인증됨`**   | 서비스 계정이 프로젝트에 정상 접근해 데이터를 수집할 수 있는 상태입니다.                          |
| **`대기 중`**  | 등록은 됐지만 아직 접근 권한 확인이 끝나지 않은 상태입니다. **`연결 확인`** 버튼으로 다시 시도할 수 있습니다. |
| **`인증 실패`** | 서비스 계정이 프로젝트에 접근하지 못한 상태입니다. IAM 권한을 확인한 뒤 \*\*`연결 확인`\*\*을 누르세요.  |

{% hint style="warning" %}
**IAM 권한이 없으면 인증에 실패합니다** 서비스 계정에 프로젝트 접근 권한이 없으면 *"IAM 권한이 없습니다. 서비스 계정에 프로젝트 접근 권한을 부여해주세요."* 안내가 표시됩니다. GCP에서 서비스 계정에 권한을 부여한 뒤 다시 연결을 확인하세요.
{% endhint %}

**연동 후 관리**

* 연동된 뒤에는 화면 우측 상단의 **`대시보드 보기`** 버튼으로 사용량 대시보드(`/ai/gemini`)로 이동합니다.
* 연동을 끊으려면 \*\*`연동 해제`\*\*를 누릅니다. 확인 안내: *"연동 해제 후에는 관련 데이터 동기화가 중단됩니다."*

***

### 2. Gemini Enterprise 연동하기

Gemini Enterprise 연동은 **`설정`** > \*\*`연동 관리`\*\*의 **AI 도구** 섹션에 **`Gemini Enterprise`** 카드로 노출됩니다. 카드를 누르면 연동 상세 화면(`/settings/integration/gemini-enterprise`)으로 이동합니다.

{% hint style="info" %}
**필요한 준비물**

* Gemini Enterprise 라이선스를 사용하는 **GCP 프로젝트 ID**
* 해당 프로젝트의 **청구 계정 ID** (형식: `XXXXXX-XXXXXX-XXXXXX`)
* GCP 프로젝트에 심플리 서비스 계정을 추가하고 IAM 역할을 부여할 수 있는 권한
  {% endhint %}

{% hint style="warning" %}
**이 연동은 v1alpha API를 사용합니다** 연동 화면 상단에 *"이 연동은 Google Workspace Licenses API v1alpha를 사용합니다. 일부 기능이 변경될 수 있습니다."* 안내가 표시됩니다. Google 측 API가 정식 버전이 아니므로 동작이 바뀔 수 있습니다.
{% endhint %}

**단계 1: 서비스 계정과 IAM 역할 부여**

1. 연동 상세 화면의 **서비스 계정 설정** 카드에서 서비스 계정과 IAM 역할을 확인합니다.
2. 서비스 계정(`smply-gemini-service@smply-prod.iam.gserviceaccount.com`)을 GCP 프로젝트에 추가합니다.
3. 해당 서비스 계정에 IAM 역할 \*\*`roles/cloudquota.viewer`\*\*를 부여합니다.

**단계 2: 프로젝트 추가**

1. **프로젝트 추가** 카드의 `GCP 프로젝트 ID` 입력란에 프로젝트 ID를 입력합니다 (placeholder: `my-project-123`).
2. `청구 계정 ID` 입력란에 청구 계정 ID를 입력합니다 (placeholder: `XXXXXX-XXXXXX-XXXXXX`).
3. **`추가하기`** 버튼을 누릅니다. 두 값이 모두 입력돼야 버튼이 활성화됩니다.
4. 추가된 프로젝트는 아래 목록에 상태 뱃지와 함께 표시됩니다.

**프로젝트 상태**

| 상태            | 의미                                                                           |
| ------------- | ---------------------------------------------------------------------------- |
| **`정상`**      | 서비스 계정이 라이선스 데이터를 정상 수집하는 상태입니다.                                             |
| **`권한 오류`**   | 서비스 계정에 권한이 없어 데이터를 가져오지 못한 상태입니다. IAM 역할(`roles/cloudquota.viewer`)을 확인하세요. |
| **`데이터 없음`**  | 접근은 되지만 아직 수집된 라이선스 데이터가 없는 상태입니다.                                           |
| **`프로젝트 없음`** | 입력한 GCP 프로젝트를 찾을 수 없는 상태입니다. 프로젝트 ID를 확인하세요.                                 |

**연동 후 관리**

* 화면 상단의 **`대시보드`** 버튼으로 라이선스 현황 대시보드(`/ai/gemini-enterprise`)로 이동합니다.
* **`연동 목록`** 버튼으로 연동 관리 목록으로 돌아갑니다.
* 개별 프로젝트는 목록의 **`제거`** 버튼으로 연동을 끊을 수 있습니다.

***

### 3. 대시보드 접근

| 대시보드                     | 진입 경로                                                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------- |
| **`Gemini Code Assist`** | 사이드바 **`AI`** 메뉴 > **`AI 메인 페이지`**(`/ai`)의 Gemini Code Assist 카드 **`열기`** 버튼, 또는 연동 설정의 **`대시보드 보기`** 버튼 |
| **`Gemini Enterprise`**  | 연동 상세 화면의 **`대시보드`** 버튼 (`/ai/gemini-enterprise`)                                                        |

{% hint style="info" %}
**사이드바 AI 하위 메뉴에서도 진입할 수 있습니다** 사이드바의 **`AI`** 하위 메뉴에 Anthropic·OpenAI와 함께 **`Gemini`**(`/ai/gemini`) 항목이 있습니다. Gemini Code Assist 대시보드는 이 메뉴나 **AI 메인 페이지**(`/ai`)의 카드, 또는 연동 설정 화면의 버튼으로 진입할 수 있습니다.
{% endhint %}

**헤더 — `연동 설정` 버튼**

대시보드 헤더 우측의 **`연동 설정`** 버튼을 누르면 해당 연동의 설정 화면으로 이동해 프로젝트를 추가·제거할 수 있습니다.

{% hint style="info" %}
**아직 연동되지 않았을 때** 프로젝트가 하나도 등록되지 않은 경우 빈 화면이 표시됩니다.

* Gemini Code Assist: *"Gemini Code Assist가 연결되지 않았습니다. 연동 설정에서 GCP 프로젝트 ID를 등록해주세요."* — **`연동 관리로 이동하기`** 버튼 제공.
* Gemini Enterprise: *"Gemini Enterprise가 연결되지 않았습니다. 연동 설정에서 GCP 프로젝트를 추가해주세요."* — **`연동 설정으로 이동하기`** 버튼 제공.
  {% endhint %}

<figure><img src="/files/WYfwduF02DRxMKHlLnbA" alt="/ai/gemini 빈 상태(미연동) 화면"><figcaption></figcaption></figure>

***

### 4. Gemini Code Assist 대시보드

Gemini Code Assist 대시보드는 위에서부터 프로젝트 선택 → KPI 카드 → 사용량 추이 차트 → 사용량 상세 표 순으로 이어집니다.

**프로젝트 선택**

연동된 GCP 프로젝트가 여러 개이면 상단의 **`프로젝트 선택`** 드롭다운으로 한 프로젝트의 데이터만 골라 볼 수 있습니다.

**KPI 카드 (4장)**

| 카드             | 의미                                                           |
| -------------- | ------------------------------------------------------------ |
| **28일 활성 사용자** | 최근 28일 동안 Gemini Code Assist를 사용한 사용자 수. 어제 대비 증감을 함께 표시합니다. |
| **제안 승인률**     | 코드 제안 중 실제로 승인된 비율(승인 ÷ 제안).                                 |
| **승인된 코드 라인**  | 사용자가 승인해 반영한 코드 라인 수. 어제 대비 증감을 함께 표시합니다.                    |
| **채팅 활동**      | Gemini 채팅 대화 건수. 어제 대비 증감을 함께 표시합니다.                         |

**사용량 추이**

일자별 코드 제안 건수를 면적 차트로 표시합니다. 마우스를 올리면 해당일의 제안 건수와 토큰 사용량을 함께 보여줍니다. 데이터가 2일 이상 있을 때만 차트가 나타납니다.

**사용량 상세**

날짜·프로젝트 단위로 사용량을 집계한 표입니다. 검색·정렬이 가능하며 기본 정렬은 날짜 내림차순입니다.

| 컬럼         | 설명              |
| ---------- | --------------- |
| **날짜**     | 집계 기준 일자        |
| **프로젝트**   | GCP 프로젝트 ID     |
| **사용자**    | 해당일 일일 활성 사용자 수 |
| **제안**     | 코드 제안 건수        |
| **승인**     | 승인된 코드 제안 건수    |
| **코드 라인**  | 승인된 코드 라인 수     |
| **대화**     | 채팅 대화 건수        |
| **API 호출** | API 호출 건수       |
| **토큰**     | 입력·출력·캐시 토큰 합계  |

{% hint style="info" %}
**데이터가 비어 있으면 동기화를 기다려 주세요** Gemini Code Assist 대시보드의 KPI·차트·표는 GCP에서 수집한 실제 사용량 데이터로 채워집니다. 연동 직후나 자동 동기화 전에는 데이터가 비어 보일 수 있으며, 동기화가 완료되면 반영됩니다. (자동 동기화 일정은 아래 *"동기화"* 항목을 참고하세요.)
{% endhint %}

<figure><img src="/files/A2FLqr95oE0YqEOOkODx" alt="/ai/gemini Code Assist 대시보드 — KPI 카드·사용량 추이 차트·사용량 상세 표"><figcaption></figcaption></figure>

***

### 5. Gemini Enterprise 대시보드

Gemini Enterprise 대시보드는 위에서부터 청구 계정 선택 → KPI 카드 → 유저별 라이선스 표 순으로 이어집니다.

**청구 계정 선택**

연동된 청구 계정이 2개 이상이면 상단의 **`청구 계정 선택`** 드롭다운으로 한 청구 계정의 데이터만 골라 볼 수 있습니다. 기본값은 \*\*`전체 청구 계정`\*\*입니다.

**KPI 카드 (3장)**

| 카드           | 의미                         |
| ------------ | -------------------------- |
| **청구 계정**    | 연동된 청구 계정 수                |
| **마지막 동기화**  | 가장 최근 데이터가 수집된 날짜          |
| **할당된 라이선스** | 라이선스가 실제로 할당된(`할당됨`) 사용자 수 |

**유저별 라이선스**

사용자 단위로 라이선스 할당 상태를 보여주는 표입니다. 검색·정렬이 가능하며 기본 정렬은 이메일 오름차순입니다.

| 컬럼           | 설명                   |
| ------------ | -------------------- |
| **이메일**      | 사용자 이메일              |
| **이름**       | 사용자 이름               |
| **할당 상태**    | 라이선스 할당 상태 (아래 표 참조) |
| **청구 계정 ID** | 해당 라이선스의 청구 계정       |
| **마지막 로그인**  | 사용자의 마지막 로그인 시각      |

**할당 상태 값**

| 값                | 의미                  |
| ---------------- | ------------------- |
| **할당됨**          | 라이선스가 사용자에게 할당된 상태  |
| **라이선스 없음**      | 라이선스가 할당되지 않은 상태    |
| **로그인 시도 (미할당)** | 라이선스 없이 로그인을 시도한 상태 |
| **차단됨**          | 사용이 차단된 상태          |
| **알 수 없음**       | 상태를 확인할 수 없는 상태     |

{% hint style="info" %}
**첫 동기화 전에는 표가 비어 있습니다** 라이선스 데이터가 아직 없을 때는 \*"라이선스 데이터가 없습니다 — 첫 동기화 후 유저별 라이선스 현황이 표시됩니다."\*가 표시됩니다. 첫 동기화가 끝나면 채워집니다.
{% endhint %}

***

### 6. 동기화 방식

* **자동 동기화**: 두 연동 모두 매일 **한국시간 오전 5시** 배치로 실행되도록 예약돼 있습니다.
  * `Gemini Code Assist`: 프로젝트별 사용량(활성 사용자·코드 제안·토큰)을 수집합니다.
  * `Gemini Enterprise`: 청구 계정별 유저 라이선스 할당 현황을 수집합니다.
* **수동 동기화**: 두 대시보드 모두 화면에 **수동 새로고침 버튼이 노출되지 않습니다**. 데이터는 자동 동기화 배치로만 갱신됩니다.

{% hint style="warning" %}
**자동 동기화 스케줄은 순차 활성화 중입니다** 두 동기화 배치(매일 오전 5시 KST 예약)는 현재 일시 정지(paused) 상태로 설정돼 있어, 환경에 따라 자동 수집이 아직 동작하지 않을 수 있습니다. 데이터가 채워지지 않으면 채널톡으로 알려주세요.
{% endhint %}

***

### 7. 권한 안내

{% hint style="info" %}
**Basic 플랜은 AI 메뉴 자체가 숨겨집니다** Basic 플랜에서는 사이드바에 AI 메뉴가 표시되지 않습니다.
{% endhint %}

| 작업                     | 필요 권한                       |
| ---------------------- | --------------------------- |
| 대시보드 조회                | 로그인된 워크스페이스 세션 (Basic 외 플랜) |
| 연동 설정(`설정 > 연동 관리`) 접근 | **관리자(Admin)** 역할           |

***

### 8. 문제 해결

#### Q: 프로젝트를 추가했는데 상태가 "인증 실패" 또는 "권한 오류"로 떠요

**원인**: 심플리 서비스 계정이 GCP 프로젝트에 접근할 권한이 없을 때입니다.

**해결 방법**:

1. 연동 설정 화면에 표시된 서비스 계정이 해당 GCP 프로젝트에 추가돼 있는지 확인합니다.
   * Gemini Code Assist: `smply-gcp-sa@smply-prod.iam.gserviceaccount.com`
   * Gemini Enterprise: `smply-gemini-service@smply-prod.iam.gserviceaccount.com`
2. Gemini Enterprise는 서비스 계정에 IAM 역할 \*\*`roles/cloudquota.viewer`\*\*가 부여돼 있어야 합니다.
3. 권한을 부여한 뒤 Code Assist는 \*\*`연결 확인`\*\*을 다시 누릅니다.

#### Q: 대시보드가 "연결되지 않았습니다"라고 떠요

해당 연동에 GCP 프로젝트가 아직 등록되지 않은 경우입니다. 빈 화면의 **`연동 관리로 이동하기`**(Code Assist) 또는 **`연동 설정으로 이동하기`**(Enterprise) 버튼으로 프로젝트를 먼저 등록하세요.

#### Q: 연동은 됐는데 대시보드에 데이터가 없어요

**원인**:

* 자동 동기화 배치가 아직 실행되지 않았거나, 스케줄이 일시 정지 상태일 수 있습니다.
* 해당 기간에 실제 사용·할당 데이터가 없었을 수 있습니다.

**해결 방법**: 두 대시보드에는 수동 새로고침 버튼이 없으므로 자동 동기화(한국시간 오전 5시) 이후 다시 확인하세요. 계속 비어 있으면 채널톡으로 알려주세요.

#### Q: Gemini Code Assist와 Gemini Enterprise는 뭐가 다른가요

\*\*`Gemini Code Assist`\*\*는 코드 어시스턴트의 사용량·생산성(활성 사용자·코드 제안 승인·토큰)을 보여주고, \*\*`Gemini Enterprise`\*\*는 Google Workspace의 Gemini Enterprise 라이선스가 누구에게 할당됐는지를 보여줍니다. 두 연동은 등록 방법(필요한 ID·IAM 역할)과 대시보드가 모두 다릅니다.

#### Q: "v1alpha API" 경고는 무슨 의미인가요

Gemini Enterprise 연동은 Google Workspace Licenses API의 정식 출시 전(v1alpha) 버전을 사용합니다. Google 측 API가 변경되면 일부 동작이 바뀔 수 있다는 안내입니다.

#### Q: 이 외의 문제

채널톡으로 문의해 주세요.