> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.4/basic-tutorials/guides/workflow-quality.md).

# 워크플로우 품질 평가

워크플로우 품질 평가는 워크플로우 상세 화면의 **「품질 평가」 탭**에서 그 워크플로우를 워크플로우형 리더보드(골든셋 문항과 평가지표 세트)에 연결해 두고, 지표별 합격 기준과 비교 기준선을 정해 두는 기능입니다. 연결한 뒤에는 배포 직후·지정한 실행 주기·모델이나 프롬프트가 바뀐 시점에 골든셋 평가가 자동으로 돌고, 관리자가 「지금 평가 실행」으로 즉시 돌릴 수도 있습니다.

채점이 끝나면 지표별 점수를 임계값·기준선과 대조해 **합격 / 품질저하 / 측정무효 / 기준없음**으로 판정합니다. 품질저하나 측정무효가 나오면 시스템 관리자에게 「품질 저하」 알림이 발송되고, 이후 실행이 합격으로 돌아오면 그 알림이 자동으로 「해결됨」 처리됩니다. 판정 근거는 탭 하단의 최근 실행 이력과, 행을 클릭하면 열리는 「실행 상세」의 기준별 판정 및 지표별 문항 집계에서 확인합니다.

### 주요 개념

| 개념        | 설명                                                                   |
| --------- | -------------------------------------------------------------------- |
| 리더보드      | 평가지표 세트입니다. 품질 평가에 연결할 수 있는 것은 **워크플로우형 리더보드**뿐입니다.                  |
| 골든셋       | 채점에 쓰는 질문·정답 문항 묶음입니다. 리더보드가 아니라 **지표마다 붙은 데이터셋 버전**에서 옵니다.          |
| 합격 기준     | 「어느 지표를 · 어떻게 비교해서 · 어느 값과 견줄지」를 정한 한 줄입니다. 지표 하나당 기준 하나만 만들 수 있습니다. |
| 기준선       | 「기준선 대비 차이/비율」로 비교할 때 상대가 되는 과거 실행입니다.                               |
| 실행(run)   | 한 번의 평가 시도입니다. 진행 상태와 판정을 각각 갖습니다.                                   |
| 판정        | 그 실행의 결론입니다. 합격 / 품질저하 / 측정무효 / 기준없음 / 미판정.                          |
| 측정무효      | 채점 자체를 신뢰할 수 없어 합격·불합격을 매기지 않은 상태입니다.                                |
| 트리거       | 실행을 일으킨 계기입니다. 수동 / 정기 / 배포 / 모델 변경.                                 |
| 재알림 최소 간격 | 같은 정책에서 품질 저하 알림이 다시 나가기까지 최소한 기다리는 시간(초)입니다.                        |

### 시작하기 전에

연결하기 전에 [리더보드](/default/v1.9.4/basic-tutorials/guides/leaderboard.md) 쪽에서 끝나 있어야 하는 것이 셋 있습니다.

1. **리더보드가 워크플로우형이어야 합니다.** LLM 리더보드는 연결 드롭다운에 아예 나오지 않습니다.
2. **리더보드에 활성** [**평가지표**](/default/v1.9.4/basic-tutorials/guides/metric.md)**가 1개 이상 있어야 합니다.** 0개면 기준을 만들 수 없을 뿐 아니라, 실행 자체가 `[품질] 리더보드에 활성 지표가 없어 평가할 수 없습니다.` 로 거부됩니다.
3. **지표마다 데이터셋(골든셋)이 붙어 있어야 합니다.** 비어 있으면 판정이 「측정무효 · 골든셋 문항 없음」으로 떨어집니다.

### 진입 경로

좌측 메뉴 **에이전트 › 워크플로우**에서 워크플로우를 열면 나오는 상세 페이지의 **「품질 평가」** 탭입니다. `?tab=Quality` 로 바로 열 수도 있습니다.

평가 대상 리비전은 「현재 배포 리비전 → 없으면 가장 최근 리비전 → 그래도 없으면 없음」 순으로 정해집니다.

> **첫 진입 시 탭 본문이 잠깐 완전히 비어 보입니다.** 정책을 조회하는 동안 로딩 표시 없이 아무것도 그리지 않기 때문입니다. 잠시 기다리면 화면이 나타납니다.

저장하지 않은 변경이 있는 상태에서 다른 탭으로 옮기거나 새로고침하면 이탈 확인 창이 뜹니다. 탭 이동 시 문구는 「편집한 내용이 사라집니다.」입니다.

### 리더보드 연결

품질 평가 정책이 없으면 빈 상태 화면이 뜹니다.

> **연결된 품질 평가가 없습니다** 리더보드를 연결하면 배포할 때마다 골든셋 평가가 자동으로 돌고, 점수가 기준 아래로 떨어지면 알림이 옵니다.

드롭다운(「리더보드 선택」)에서 워크플로우형 리더보드를 고르고 \*\*「품질 평가 연결」\*\*을 누르면 정책이 생성되고 「품질 평가를 연결했습니다.」 토스트가 뜹니다.

연결 직후 기본값은 다음과 같습니다.

| 설정                 | 기본값       |
| ------------------ | --------- |
| 합격 기준              | 없음        |
| 기준선                | 마지막 합격 실행 |
| 배포 후 자동 평가         | **켜짐**    |
| 수동 실행 허용           | **켜짐**    |
| 모델·프롬프트 변경 시 자동 평가 | 꺼짐        |
| 실행 주기              | 사용 안 함    |
| 임계 미달 시 알림         | **켜짐**    |
| 재알림 최소 간격          | 3600초     |

> ⚠️ **연결 해제 후 다시 연결하면 이전 설정은 복원되지 않습니다.** 같은 리더보드로 재연결해도 과거 합격 기준·트리거·재알림 간격은 위 기본값으로 전부 덮입니다. 지난 실행 이력과 판정 기록은 리더보드에 그대로 남습니다.

#### 불러오기에 실패했을 때

정책 조회가 실패하면 연결 화면 대신 빨간 배너 「품질 평가 설정을 불러오지 못했습니다.」와 **「다시 시도」** 버튼만 나옵니다. 조회 실패를 '미연결'로 오인해 연결 버튼을 누르면 살아 있는 기준·트리거가 전체 교체 저장으로 지워지기 때문에, 일부러 연결 화면을 띄우지 않습니다.

> ⚠️ **권한이 없어도 「연결된 품질 평가가 없습니다」로 보입니다.** 화면은 워크플로우 기준으로 정책을 조회하고 서버는 *내가 읽을 수 있는* 정책만 돌려줍니다. 리더보드 읽기 권한이 없으면 정책이 있어도 빈 상태로 보이며, 여기서 다른 리더보드를 연결하면 별개 정책이 하나 더 생깁니다. 연결이 이미 있는데 빈 화면이 뜨면 리더보드 권한을 먼저 확인하세요.

### 합격 기준 설정

**「합격 기준」** 섹션에서 \*\*「기준 추가」\*\*로 한 줄씩 만듭니다. 한 줄은 왼쪽부터 다음 순서입니다.

**지표 선택 → 비교 방식 → 연산자 → 임계값 → (방향 안내) → 삭제**

* **지표 선택** — 이미 다른 줄이 쓰는 지표는 목록에서 빠집니다(지표당 기준 1개).
* **방향 안내** — 「높을수록 좋음」/「낮을수록 좋음」이 읽기 전용으로 표시됩니다. 이는 참고 표시일 뿐이며, **실제 판정 방향은 관리자가 고른 연산자만으로 결정됩니다.**
* 새 줄의 기본값은 비교 방식 「절대값」, 연산자 「이상 (≥)」, 임계값 0.8 입니다.

지표가 0개면 「기준 추가」가 비활성되고 경고 배너와 **「리더보드 열기」** 버튼이 나옵니다. 기준이 0건이면 안내 배너가 뜹니다.

> 기준이 없으면 합격·불합격 판정과 품질 저하 알림이 생기지 않습니다. 다만 **측정 자체가 깨지면 「측정무효」 알림은 나갈 수 있습니다.**

#### 비교 방식

| 화면 표기     | 실제 계산                                               | 기준선 필요            |
| --------- | --------------------------------------------------- | ----------------- |
| 절대값       | 이번 실행의 지표 점수를 임계값과 비교                               | 아니오               |
| 기준선 대비 차이 | (이번 점수 − 기준선 점수)를 임계값과 비교                           | 예                 |
| 기준선 대비 비율 | (이번 점수 − 기준선 점수) ÷ \|기준선 점수\| 를 임계값과 비교 (0.05 = 5%) | 예. 기준선이 0이면 판정 불가 |

#### 연산자

| 화면 표기  | 통과 조건     |
| ------ | --------- |
| 이상 (≥) | 계산값 ≥ 임계값 |
| 초과 (>) | 계산값 > 임계값 |
| 이하 (≤) | 계산값 ≤ 임계값 |
| 미만 (<) | 계산값 < 임계값 |

#### 기준선

| 화면 표기     | 기준선으로 뽑히는 실행                                    |
| --------- | ----------------------------------------------- |
| 마지막 합격 실행 | 같은 리더보드·워크플로우에서 판정이 「합격」 또는 「기준없음」인 가장 최근 완료 실행 |
| 마지막 실행    | 같은 리더보드·워크플로우에서 「측정무효」가 아닌 가장 최근 완료 실행          |

> 채점 단계(검색/생성)는 기준에서 고르지 않습니다. 지표에 설정된 단계가 자동으로 쓰이며, 화면에서는 지표 드롭다운 항목 옆과 실행 상세의 지표명 뒤 괄호로만 보입니다.

### 자동 실행 조건

| 설정                 | 동작                                              |
| ------------------ | ----------------------------------------------- |
| 배포 후 자동 평가         | 워크플로우를 배포하면 평가를 예약하고, 파드 롤아웃이 끝난 뒤 채점을 시작합니다.   |
| 수동 실행 허용           | 꺼 두면 「지금 평가 실행」 버튼이 비활성됩니다.                     |
| 모델·프롬프트 변경 시 자동 평가 | 배포된 리비전의 스텝 정의를 해시한 '지문'이 직전 실행과 달라지면 자동 실행합니다. |
| 실행 주기              | crontab 식으로 주기 실행합니다.                           |

#### 실행 주기

오른쪽 끝 스위치로 사용 여부를 켜고 끕니다. 꺼져 있으면 내부 입력이 모두 비활성입니다. 켜면 행 아래에 실제 저장될 식이 `cron: 0 2 * * *` 형태로 미리 보입니다.

| 프리셋   | 추가 입력             | 저장되는 cron    |
| ----- | ----------------- | ------------ |
| 매시간   | 없음                | `0 * * * *`  |
| 매일    | 시각(HH:MM)         | `분 시 * * *`  |
| 매주    | 요일 + 시각(HH:MM)    | `분 시 * * 요일` |
| 직접 입력 | cron 텍스트(최대 128자) | 입력한 문자열 그대로  |

저장된 cron 이 없으면 기본은 「매일 02:00」입니다.

> **5분보다 짧은 주기는 의미가 없습니다.** `*/1 * * * *` 를 넣어도 정책 단위 5분 선점 창에 걸려 5분에 한 번만 실제로 발사됩니다. 프리셋의 최소 단위가 「매시간」인 이유이기도 합니다.

#### 모델·프롬프트 변경 감지

리비전 번호가 아니라 **스텝 정의 전체를 SHA-256 해시한 '지문'** 으로 판단합니다. 그래서 워크플로우 안의 모델 교체나 프롬프트 수정이 잡힙니다. 서버가 15초마다 확인합니다.

> **이 스위치를 켜고 저장하면 대개 15초 안에 평가가 한 번 돕니다.** 해당 범위에 실행 이력이 하나도 없으면 비교할 지문이 없어 즉시 1회 실행하기 때문입니다. 「아무것도 안 했는데 평가가 돌았다」고 느끼는 지점입니다.

#### 자동 실행이 조용히 건너뛰어지는 경우

정기·모델변경 트리거는 아래 상황에서 **실행 행조차 만들지 않고** 넘어갑니다. 화면에 흔적이 남지 않습니다.

* 현재 배포된 리비전을 구할 수 없을 때
* 같은 워크플로우에 아직 끝나지 않은 실행(대기·진행·판정 중)이 있을 때
* 직전 자동 발사로부터 5분이 지나지 않았을 때

배포 트리거는 같은 리비전으로 최근 10분 안에 만들어진 실행이 있으면 예약을 건너뜁니다.

### 알림 설정

| 설정           | 동작                                                             |
| ------------ | -------------------------------------------------------------- |
| 임계 미달 시 알림   | 끄면 품질 저하·측정무효 알림이 나가지 않습니다.                                    |
| 재알림 최소 간격(초) | 기본 3600. 이 시간 안에는 같은 정책에서 알림이 다시 나가지 않습니다. 0이면 억제 없이 매번 발송됩니다. |

알림 스위치가 꺼져 있으면 간격 입력은 비활성됩니다. 간격 칸을 비운 채 저장하면 3600으로 저장됩니다.

### 저장

이 화면의 모든 변경은 **맨 아래 고정된 저장 바의 「저장」 버튼 한 번**으로만 서버에 반영됩니다. 값을 바꾸고 다른 곳을 눌러도 저장되지 않습니다.

변경이 있으면 왼쪽에 「저장하지 않은 변경이 있습니다.」가 뜨고 버튼이 활성됩니다. 저장에 성공하면 정책을 다시 불러와 이 표시가 자동으로 풀립니다.

저장 시 검사는 아래 순서로 진행되며, 하나라도 걸리면 저장하지 않고 오류 토스트를 띄웁니다.

| 순서 | 조건                      | 토스트 문구                                             |
| -- | ----------------------- | -------------------------------------------------- |
| 1  | 지표를 고르지 않은 기준이 있음       | 지표를 선택하지 않은 기준이 있습니다.                              |
| 2  | 임계값이 비었거나 숫자가 아님        | 임계값을 입력하지 않은 기준이 있습니다.                             |
| 3  | 실행 주기를 켰는데 cron 이 비어 있음 | 주기 실행을 켰으면 실행 주기를 입력해야 합니다.                        |
| 4  | cron 이 공백 구분 5개 필드가 아님  | crontab 식은 공백으로 구분된 5개 필드여야 합니다. (예: 0 2 \* \* \*) |
| 5  | 재알림 간격이 정수가 아니거나 음수     | 재알림 최소 간격은 0 이상의 정수여야 합니다.                         |

1·2번은 「합격 기준」 섹션으로 화면이 스크롤됩니다. 저장에 성공하면 「저장했습니다.」가 뜹니다.

### 지금 평가 실행

상단 \*\*「지금 평가 실행」\*\*은 현재 워크플로우와 대상 리비전으로 즉시 평가를 요청하고 「평가를 시작했습니다.」 토스트를 띄웁니다.

아래 중 하나라도 해당하면 버튼이 비활성입니다.

* 리더보드 미연결
* 요청 진행 중
* 「수동 실행 허용」이 꺼짐
* **저장하지 않은 변경이 있음** — 실행은 *저장된* 기준으로 채점되므로, 편집 중에는 먼저 저장해야 합니다.

> **채점은 리비전이 아니라 「현재 배포된 워크플로우」를 호출합니다.** 실행 이력의 「리비전」 열은 기록용 라벨이고, 실제로는 배포 컨테이너에 골든셋 질문을 하나씩 보냅니다. 그래서 아직 배포되지 않은 최신 리비전으로 실행해도 점수는 현재 떠 있는 배포본의 것입니다. 이 호출에는 크레딧이 과금되지 않습니다.

### 실행 이력

탭 하단 표에 **최근 10건**이 최신순으로 보입니다. 페이지 이동 막대는 없습니다. 비어 있으면 「데이터가 없습니다.」가 표시됩니다.

| 컬럼   | 표시 내용                                                          |
| ---- | -------------------------------------------------------------- |
| 판정   | 합격(초록) / 품질저하(빨강) / 측정무효(주황) / 기준없음(회색) / 미판정(회색)              |
| 트리거  | 수동 / 정기 / 배포 / 모델 변경                                           |
| 리비전  | 평가 대상 워크플로우 리비전 ID                                             |
| 진행   | `Queued` `Running` `Comparing` `Completed` `Error` (영문 원문 그대로) |
| 비고   | 측정무효 사유를 한글로 쉼표 연결. 없으면 `-`                                    |
| 실행일시 | 실행 등록 일시                                                       |

#### 판정

| 화면 표기 | 의미                               |
| ----- | -------------------------------- |
| 합격    | 모든 합격 기준을 통과했습니다.                |
| 품질저하  | 합격 기준 중 하나 이상이 미달했습니다.           |
| 측정무효  | 측정을 신뢰할 수 없어 합격·불합격을 매기지 않았습니다.  |
| 기준없음  | 기준이 없거나, 기준선이 없어 모든 기준을 건너뛰었습니다. |
| 미판정   | 아직 판정 전입니다(대기·진행 중).             |

#### 진행 상태

| 값         | 의미                                                           |
| --------- | ------------------------------------------------------------ |
| Queued    | 배포 후 자동 평가가 파드 롤아웃 완료를 기다리는 중입니다. 최대 900초.                   |
| Running   | 채점 중입니다. 최대 4시간 30분.                                         |
| Comparing | 채점이 끝나 판정을 계산하는 중입니다.                                        |
| Completed | 채점·판정이 끝났습니다.                                                |
| Error     | 판정 없이 회수됐습니다(시간 초과·리비전 변경·발사 실패 등). 판정은 항상 「측정무효」가 함께 기록됩니다. |

> 수동·정기·모델변경 실행은 생성 즉시 `Running` 이 됩니다. `Queued` 로 대기하는 것은 **배포 트리거뿐**입니다.

#### 측정무효 사유

| 화면 문구              | 언제 붙는가                           |
| ------------------ | -------------------------------- |
| 골든셋 문항 없음          | 채점 결과가 전무하거나 골든셋 문항 수가 0입니다.     |
| 채점 중단              | 실제 채점한 문항 수가 전체 문항 수와 다릅니다.      |
| 채점된 문항 부족          | 정상 채점된 문항이 전체의 90% 미만입니다.        |
| 지표 점수 없음           | 어떤 지표의 점수가 나오지 않았습니다.            |
| 기준선과 지표 버전 불일치     | 기준선 실행과 이번 실행의 평가지표 버전이 다릅니다.    |
| 기준선이 0 이라 비율 비교 불가 | 「기준선 대비 비율」 기준인데 기준선 점수가 0입니다.   |
| 대상 리비전 변경          | 배포 후 자동 평가 대기 중에 다른 리비전이 배포됐습니다. |
| 배포 준비 대기 초과        | 롤아웃 완료를 900초 동안 확인하지 못했습니다.      |
| 채점 시간 초과           | 채점이 4시간 30분을 넘겼습니다.              |
| 채점 요청 실패           | 채점 작업 발사가 실패했습니다.                |
| 평가 데이터 유실          | 실행에 연결된 평가 데이터가 사라졌습니다.          |

> 측정무효 검사 대상은 **합격 기준이 가리키는 지표들**입니다. 다만 기준이 0건이면 필터가 걸리지 않아 **리더보드의 모든 지표**가 검사 대상이 됩니다.

### 실행 상세

실행 이력의 행을 클릭하면 「실행 상세」 팝업이 열립니다. 부제에 실행 번호와 UID가 표시됩니다.

#### 기준별 판정

| 컬럼    | 내용                                        |
| ----- | ----------------------------------------- |
| 지표    | 기준이 감시하는 지표 이름(판정 시점 스냅샷)                 |
| 기준    | `비교 방식 · 연산자 임계값` (예: `절대값 · 이상 (≥) 0.8`) |
| 관측값   | 이번 실행의 지표 점수(소수 4자리)                      |
| 기준선 값 | 기준선 실행의 점수(소수 4자리). 절대값 비교거나 기준선이 없으면 `-` |
| 판정    | 통과(초록) / 미달(빨강) / 판정 불가(주황)               |

#### 지표별 문항 집계

| 컬럼       | 내용                                  |
| -------- | ----------------------------------- |
| 지표       | 지표 이름 + 단계 괄호 표기 (검색) / (생성)        |
| 문항       | 채점 시도한 문항 수                         |
| 채점       | 정상 채점된 문항 수                         |
| 대상 호출 실패 | 워크플로우가 응답하지 못한 문항 수. 0보다 크면 빨간 글자   |
| 지표 오류    | 지표 코드 실행 중 오류가 난 문항 수. 0보다 크면 빨간 글자 |
| 평균 / 최저  | 정상 채점된 문항의 평균·최저 점수(소수 4자리)         |

**「대상 호출 실패」나 「지표 오류」가 0보다 크면 임계값 문제가 아니라 채점 자체가 깨진 것**이므로, 경고 배너가 함께 표시됩니다.

문항 점수가 한 건도 적재되지 않으면 「문항 점수가 적재되지 않았습니다…」 경고만 뜨고, 채점과 판정은 그대로 진행됩니다. 판정은 지표 평균만으로 계산됩니다.

### 품질 저하 알림과 해결

#### 언제 발송되나

판정이 \*\*「품질저하」 또는 「측정무효」\*\*로 확정되면 발송됩니다. 정책이 없거나 「임계 미달 시 알림」이 꺼져 있으면 발송하지 않습니다.

제목은 항상 \*\*「품질 저하」\*\*이고 본문은 다음 형식입니다.

```
'<리더보드명>' 품질 저하가 감지되었습니다. <지표명> = 0.7412 (기준 gte 0.8)
```

미달 기준이 둘 이상이면 뒤에 `외 N건`이 붙습니다. 본문의 연산자는 화면 라벨(`이상 (≥)`)이 아니라 원시 코드(`gte` `gt` `lte` `lt`)로 나옵니다.

측정무효인 경우는 이 형식입니다.

```
'<리더보드명>' 품질 평가 결과를 신뢰할 수 없습니다. 사유: 채점된 문항 부족
```

#### 누가 받나

리더보드 등록자 개인이 아니라 **시스템 관리자**에게 갑니다. `dashboard_system` 에 READ\_WRITE 권한이 있는 활성 사용자 전원과 전역 최고관리자가 대상이며, 알림함에 「중요」로 분류됩니다.

알림함에서 이 알림을 클릭하면 품질 평가 탭이 아니라 **워크플로우 리더보드 상세**로 이동합니다.

#### 재알림

「재알림 최소 간격(초)」 안에는 같은 정책에서 알림이 다시 나가지 않습니다. 억제된 실행도 판정 자체는 이력에 그대로 남습니다. 발송이 실패하면 선점했던 시각을 되돌려, 일시 장애 1건 때문에 이후 내내 침묵하지 않습니다.

#### 자동 해결

다음 실행의 판정이 \*\*「합격」 또는 「기준없음」\*\*으로 끝나면 회복으로 보고, 같은 리더보드·워크플로우에서 열려 있는 품질 저하 알림을 닫습니다. 알림함의 칩이 \*\*「해결됨」\*\*으로 바뀝니다.

**기준을 완화하면 닫히지 않습니다**

합격이더라도 **직전 품질저하 실행 때보다 합격 기준이 느슨해졌다면** 알림을 닫지 않습니다. 점수가 올라간 것이 아니라 감시 기준만 내린 것이기 때문입니다. 기준이 그대로이거나 더 엄격해진 상태에서 합격하면 닫습니다.

'느슨해졌다'의 판정 규칙은 다음과 같습니다.

| 상황                          | 판정                 |
| --------------------------- | ------------------ |
| 통과 방향이 위(≥, >)인데 임계값이 내려감   | 완화                 |
| 통과 방향이 아래(≤, <)인데 임계값이 올라감  | 완화                 |
| 임계값이 같고 등호가 붙은 쪽(≥, ≤)으로 바뀜 | 완화                 |
| 감시하던 지표의 기준이 삭제됨            | 완화                 |
| 비교 방식이 바뀌었거나 통과 방향이 뒤집힘     | 견줄 수 없으므로 안전측으로 완화 |
| 기준이 새로 추가됨                  | 완화 아님(감시가 늘어남)     |
| 기준선이 없어 이번에 견줘지지 못한 기준      | 재보지 못한 것이므로 완화로 계산 |

> 그래서 **알림 → 해결을 확인하려면 두 실행 사이에 기준을 수정하면 안 됩니다.** 기준을 먼저 확정해 저장하고, 그 다음 대상만 바꿔 두 번 실행하세요.

재알림 간격은 알림을 닫든 닫지 않든 **합격 판정이 나오면 즉시 해제**됩니다. 다음 저하가 발생했을 때 바로 알릴 수 있어야 하기 때문입니다.

### 전체 이력 보기

상단 \*\*「리더보드에서 평가 기록 보기」\*\*는 워크플로우 리더보드 상세를 새 탭으로 엽니다. 기본 선택은 「기본 정보」 탭이므로 **「평가 목록」 탭으로 옮겨야** 전체 이력이 보입니다. 그 표에는 지표별 점수와 함께 「품질 판정」 컬럼이 있어 트리거 배지와 판정 배지를 같이 보여줍니다. 품질 평가를 거치지 않은 평가는 `-` 로 나옵니다.

### 권한

탭 노출 자체에는 별도 권한 조건이 없지만, 서버는 리소스 권한을 확인합니다.

| 작업                    | 필요 권한                                |
| --------------------- | ------------------------------------ |
| 설정·실행 이력·실행 상세 조회     | 리더보드 **읽기**                          |
| 지금 평가 실행              | 리더보드 **읽기**                          |
| 품질 평가 연결 · 저장 · 연결 해제 | 리더보드 **쓰기** + (저장 시) 대상 워크플로우 **쓰기** |

저장에 워크플로우 쓰기 권한까지 요구하는 이유는, 배포 훅이 워크플로우 기준으로 트리거를 발사하기 때문에 남의 워크플로우에 트리거를 심지 못하게 막기 위해서입니다.

### 오류·예외 처리

| 발생 상황                     | 화면 문구                                          |
| ------------------------- | ---------------------------------------------- |
| 실행 시 대상 리더보드가 없거나 비활성     | \[품질] 리더보드를 찾을 수 없습니다. (id=…)                  |
| 품질 평가 기능이 꺼진 사이트에서 실행 요청  | \[품질] 품질 평가 기능이 비활성화되어 있습니다.                   |
| 「수동 실행 허용」이 꺼진 상태에서 실행 요청 | \[품질] 이 리더보드는 수동 실행이 허용되지 않습니다.                |
| 같은 범위에 진행 중인 실행이 있음       | \[품질] 이미 진행 중인 평가가 있습니다. (실행 id=…)             |
| 기준이 가리키는 지표가 리더보드에 없음     | \[품질] 기준 N번의 지표가 이 리더보드에 없습니다. (metric\_id=…)  |
| 연결된 리더보드가 워크플로우형이 아님      | \[품질] 워크플로우 평가에는 워크플로우 리더보드가 필요합니다.            |
| 리더보드에 활성 지표가 하나도 없음       | \[품질] 리더보드에 활성 지표가 없어 평가할 수 없습니다. (id=…)       |
| 실행 상세 조회 시 실행 행이 없음       | \[품질] 실행을 찾을 수 없습니다. (id=…)                    |
| 임계값이 숫자가 아님               | \[품질] 기준 N번의 임계값이 숫자가 아닙니다.                    |
| 기준에 대상 지표가 없음             | \[품질] 기준 N번에 대상 지표가 지정되지 않았습니다.                |
| 한 지표에 기준이 둘 이상            | \[품질] 기준 N번의 지표에 이미 기준이 있습니다. 지표당 기준은 하나입니다.   |
| 해제할 활성 정책이 없음             | \[품질] 해제할 품질 평가 연결이 없습니다.                      |
| 리비전이 하나도 없는 워크플로우에서 실행    | \[평가지표] LLM 리비전과 워크플로우 리비전 중 정확히 하나를 지정해야 합니다. |

품질 평가 기능이 사이트 전역에서 꺼져 있으면 「지금 평가 실행」이 거부되고 배포·모델변경 트리거가 전혀 돌지 않으며 크론도 등록되지 않습니다. 다만 **연결·저장·해제 조작 자체는 그대로 성공**하므로, 설정은 되는데 아무것도 돌지 않는 상태가 됩니다.

### 사용자 시나리오

#### 배포할 때마다 품질을 자동 점검하고 싶다

워크플로우 상세 → 「품질 평가」 탭 → 리더보드 선택 후 「품질 평가 연결」. 「기준 추가」로 핵심 지표 하나에 `절대값 · 이상 (≥) 0.8` 을 걸고 「저장」. 이후 배포할 때마다 롤아웃이 끝나면 평가가 자동으로 돌고, 0.8 미만이면 「품질 저하」 알림이 관리자에게 갑니다.

#### 매일 새벽에 정기 점검을 돌리고 싶다

「실행 주기」 스위치를 켜고 프리셋 「매일」, 시각 `02:00` 을 지정한 뒤 「저장」. 행 아래 미리보기가 `cron: 0 2 * * *` 인지 확인합니다.

#### 알림이 왔는데 원인을 알고 싶다

실행 이력에서 판정이 「품질저하」인 행을 클릭합니다. 「기준별 판정」에서 어느 지표가 얼마로 미달했는지, 「지표별 문항 집계」에서 「대상 호출 실패」·「지표 오류」가 있는지 봅니다. 이 두 값이 0보다 크면 임계값 문제가 아니라 채점이 깨진 것입니다.

#### 개선 후 알림을 「해결됨」으로 닫고 싶다

**기준은 건드리지 않고** 워크플로우를 개선해 다시 배포하거나 「지금 평가 실행」을 누릅니다. 판정이 「합격」으로 나오면 열려 있던 알림이 자동으로 「해결됨」이 됩니다. 임계값을 낮춰서 합격시키면 완화로 간주되어 알림이 닫히지 않습니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://genos-docs.gitbook.io/default/v1.9.4/basic-tutorials/guides/workflow-quality.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.