> 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.6/basic-tutorials/guides/data/dataset/auto-generation.md).

# 데이터셋 자동 생성

**데이터 > 데이터셋 > \[데이터셋 생성]** 의 데이터 소스에서 **「근거 문서로 자동 생성」** 을 고르면, AI 드라이브에 적재해 둔 약관·법령 같은 조항 문서를 읽어 평가용 질문·정답 데이터셋을 자동으로 만듭니다. 조항마다 에이전트 워크플로우를 한 번씩 호출해 질문·정답을 받고, 만들어진 항목에는 근거 문서와 근거 조항이 자동으로 연결됩니다.

근거가 조항 단위로 기록되므로, 나중에 문서를 개정해 다시 올리면 **바뀐 조항의 항목만** 검증필요로 표시됩니다. 이후 처리는 [데이터셋 근거 재검증](/default/v1.9.6/basic-tutorials/guides/data/dataset/revalidation.md)을 참고하세요.

<figure><img src="https://3853761281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAP3EtxIDdFGAeKwwGTl%2Fuploads%2Fgit-blob-2ea59abb02fc50eb87349b77e3c42bd385dc1276%2Fdatasetgen_01_create_modal_steps.png?alt=media" alt="데이터셋 생성 4단계"><figcaption><p>데이터셋 생성 4단계</p></figcaption></figure>

> 지원 문서는 **텍스트가 있는 PDF**뿐입니다.

## 준비물

| 준비물                   | 조건                                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 지능형 전처리기로 적재한 AI 드라이브 | 전처리기 타입을 **「지능형 전처리기」** 로 등록하고, 드라이브 적재 방식으로 그 전처리기를 고릅니다. 파라미터는 `max_chars`(청크 최대 글자 수, 기본 2000·최소 200) 하나만 씁니다. |
| 배포된 에이전트 워크플로우        | 조항 본문을 받아 **질문·정답 JSON 배열**로 답하는 워크플로우를 배포해 둡니다. 형식은 아래 [생성 워크플로우 규격](#생성-워크플로우-규격) 참고.                           |

## 주요 개념

| 개념           | 설명                                                                    |
| ------------ | --------------------------------------------------------------------- |
| 지능형 전처리기     | 문서를 조항 단위 청크로 나눠 적재하는 전처리기입니다.                                        |
| 조항(청크)       | 문서를 나눈 한 덩어리입니다. 자동 생성은 조항 하나마다 워크플로우를 한 번 호출합니다.                     |
| `article_no` | 조항 라벨입니다. 문서 안에서 유일하고 개정 전후에 같은 값이어야 하며, **재검증에서 조항을 짝짓는 기준**으로 쓰입니다. |
| `sort_key`   | 문자열로 정렬하면 문서 순서가 되는 키입니다. 생성 순서와 문서뷰 정렬에 쓰입니다.                        |
| 정답 없음        | 워크플로우가 `[]`로 답해 만들 내용이 없던 조항입니다. 조항당 1행으로 데이터셋에 들어갑니다.                |

> **이름이 비슷해 헷갈리기 쉽습니다.** 「적재용 전처리기」와 자동 생성에 필요한 **「지능형 전처리기」** 는 다른 타입입니다. 드라이브가 자동 생성에 쓸 수 있는지는 **연결된 전처리기의 타입이 「지능형 전처리기」인지**로만 판단합니다.

## 전체 흐름

1. **지능형 전처리기 등록·배포** — 문서 전처리 > 전처리기 > 전처리기 생성에서 타입을 「지능형 전처리기」로 고르면 기본 코드가 채워집니다. 그대로 배포하거나 고쳐 씁니다.
2. **AI 드라이브 생성** — 데이터 > AI 드라이브 > 드라이브 생성에서 적재 방식으로 1의 전처리기를 고릅니다.
3. **근거 문서 업로드와 적재** — PDF를 올리고 상태가 「완료」가 될 때까지 기다립니다. 이때 문서가 조항 단위 청크로 저장됩니다.
4. **생성 워크플로우 준비·배포** — 조항 본문을 받아 질문·정답 JSON 배열을 돌려주는 워크플로우를 배포합니다.
5. **데이터셋 자동 생성** — 데이터 > 데이터셋 > \[데이터셋 생성]에서 데이터 소스를 「근거 문서로 자동 생성」으로 고르고 진행합니다.
6. **결과 확인** — 리비전 상세에서 항목마다 근거 문서·조항이 연결된 것을 확인합니다. 재검증 상태는 「검증 완료」로 시작합니다.

## 데이터셋 자동 생성하기

생성 모달은 **기본 정보 → 근거 문서 → 생성 옵션 → 생성** 4단계입니다.

### 1단계 · 기본 정보

제목·상세 설명·관리 그룹·데이터셋 형식(LLM / VLM / Embedding / Reranking)·유형(Train / Evaluation)을 입력합니다. **학습용(Train) 데이터셋은 자동 생성을 지원하지 않습니다.**

### 2단계 · 근거 문서

데이터 소스를 **「근거 문서로 자동 생성」** 으로 고릅니다.

<figure><img src="https://3853761281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAP3EtxIDdFGAeKwwGTl%2Fuploads%2Fgit-blob-86b7d133b38bc91f53db885f58ac0331fda35e4a%2Fdatasetgen_02_data_source_auto.png?alt=media" alt="데이터 소스 선택과 근거 문서 지정"><figcaption><p>데이터 소스 선택과 근거 문서 지정</p></figcaption></figure>

1. **데이터 소스** — `근거 문서로 자동 생성` · `파일 직접 업로드` · `AI 드라이브 파일 선택` 중 하나를 고릅니다.
2. **안내** — 「지능형 전처리기를 연결한 드라이브만 선택할 수 있으며, 근거는 조항 단위로 기록됩니다. 미적용 드라이브 문서는 「파일 직접 업로드」로 데이터셋을 만든 뒤 근거를 지정해 주세요.」
3. **근거 문서 드라이브** — 자동 생성에 쓸 AI 드라이브를 고릅니다.
4. **근거 문서 파일** — 드라이브 안의 PDF를 고릅니다(여러 건 가능).
5. **선택된 문서** — 파일 경로·버전·**조항 수**가 표시됩니다. 이 조항 수가 워크플로우 호출 횟수가 됩니다.

드라이브 선택기는 그룹 드라이브 · 내 드라이브 · 공유받은 문서함 세 탭으로 나뉘고, 고를 수 없는 드라이브는 흐리게 표시되며 뒤에 사유가 붙습니다.

<figure><img src="https://3853761281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAP3EtxIDdFGAeKwwGTl%2Fuploads%2Fgit-blob-cbef66ba835011150e1f8e927e057fa6816724dc%2Fdatasetgen_03_evidence_drive_picker.png?alt=media" alt="근거 문서 드라이브 선택기"><figcaption><p>근거 문서 드라이브 선택기</p></figcaption></figure>

1. **탭** — 그룹 드라이브 · 내 드라이브 · 공유받은 문서함
2. **선택 불가** — 「— 지능형 전처리기 미적용」처럼 사유가 붙고 고를 수 없습니다
3. **선택 가능** — 지능형 전처리기를 연결한 드라이브

### 3단계 · 생성 옵션

<figure><img src="https://3853761281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAP3EtxIDdFGAeKwwGTl%2Fuploads%2Fgit-blob-eb4a9e9b1564284d7f0580659060c76638ba2a67%2Fdatasetgen_04_generation_options.png?alt=media" alt="생성 옵션"><figcaption><p>생성 옵션</p></figcaption></figure>

1. **에이전트 워크플로우** — 배포된 워크플로우만 목록에 나옵니다(「배포된 워크플로우만 제공되며, 프롬프트와 평가 기준은 워크플로우에서 정합니다.」).
2. **조항당 생성 건수** — 1\~20. 조항마다 이 수만큼 질문을 만듭니다.
3. **예상 건수 안내** — 「조항마다 질문을 만듭니다. 조항당 1\~20건. 지금 설정이면 조항 9개 × 3건 = 27건(호출 9회)입니다.」처럼 호출 횟수를 미리 보여 줍니다.
4. **\[생성 시작]** — 누르면 작업이 시작되고 4단계로 넘어갑니다.

### 4단계 · 생성

진행 상황은 화면 우측 하단 위젯(「데이터셋 생성 중」)과 데이터셋 목록의 **재검증 상태** 열(`생성 중` · `생성 중단` 배지)에서 볼 수 있습니다. 생성이 끝나야 리비전을 열 수 있습니다.

## 결과물

* 질문·정답 파일 하나가 첫 리비전으로 등록됩니다. 열은 `chunk_id` · `question` · `answer`입니다.
* 항목마다 근거 문서와 조항이 연결되고, 재검증 상태는 **「검증 완료」** 로 시작합니다.
* 정답 없음 조항도 조항당 1행으로 들어갑니다(질문 칸에 조항 이름, 정답 칸은 공란). 평가에 쓰지 않을 행은 재검증 상태를 「평가 제외」로 둡니다.
* 데이터셋 암호화가 켜진 환경에서는 파일 값이 저장 시 암호화됩니다.

### 문서를 개정하면

근거 문서의 새 버전을 올리면 재적재가 끝난 뒤 `article_no`로 이전·새 조항을 짝지어 본문을 비교합니다. 공백·줄바꿈 차이는 변경으로 보지 않습니다.

| 비교 결과                      | 항목 상태                       |
| -------------------------- | --------------------------- |
| 본문이 같음                     | 그대로 유지. 근거가 새 버전 조항으로 옮겨집니다 |
| 본문이 다름(개정 이력 표시만 바뀐 경우 포함) | 검증필요 · 버전 변경                |
| 같은 `article_no`가 없음        | 검증필요 · 조항 삭제                |

이후 처리는 [데이터셋 근거 재검증](/default/v1.9.6/basic-tutorials/guides/data/dataset/revalidation.md)을 참고하세요.

## 생성 워크플로우 규격

워크플로우를 직접 만드는 개발자를 위한 내용입니다.

### 목록에 나오는 조건

* **배포된** 워크플로우여야 합니다.
* 생성하는 사용자에게 워크플로우 **읽기 권한**(정책·공유)이 있어야 합니다. 만든 사람이라도 권한이 없으면 보이지 않습니다.
* 태그는 필요 없습니다. 다만 관리자가 서버 설정으로 생성용 태그를 지정해 둔 환경에서는, 배포 리비전에 그 태그가 붙은 워크플로우만 목록에 나옵니다. 기본값은 제한이 없습니다.
* 호출은 플랫폼 내부 호출이라 워크플로우에 인증 키가 걸려 있어도 그대로 쓸 수 있고, **크레딧 차감에서 제외**됩니다.

### 입력 — 워크플로우가 받는 요청

조항마다 워크플로우를 한 번씩 실행합니다. 여러 조항을 동시에 호출하므로 조항이 끝나는 순서는 문서 순서와 다를 수 있습니다. 조항 본문은 복호화된 평문으로 들어갑니다. Flowise 설정에 따라 `overrideConfig.vars`가 노드까지 전달되지 않을 수 있어 생성 개수·문서·조항 정보를 `question` 문자열에도 함께 넣습니다. **프롬프트는 `question`을 기준으로 읽도록** 구성하세요.

```json
{
  "question": "[생성 개수] 3\n[문서] 특허법_개정테스트.pdf\n[조항] 제2조(정의)\n\n[본문]\n제2조(정의) 이 법에서 사용하는 용어의 뜻은 다음과 같다. …",
  "overrideConfig": {
    "vars": {
      "article_no": "제2조",
      "sub_title": "제2조(정의)",
      "sort_key": "001.002.000.000",
      "per_clause": "3",
      "document_name": "특허법_개정테스트.pdf"
    }
  }
}
```

### 출력 — 답변 형식

워크플로우는 최종 답변(텍스트)을 **질문·정답 객체의 JSON 배열**로 돌려줘야 합니다. 만들 내용이 없으면 `[]`로 답해야 합니다.

```json
[
  {"question": "특허법에서 '발명'은 어떻게 정의되나요?", "answer": "자연법칙을 이용한 기술적 사상의 창작으로서 고도한 것을 말합니다."},
  {"question": "'특허발명'은 무엇을 뜻하나요?", "answer": "특허를 받은 발명을 말합니다."}
]
```

| 읽는 규칙 | 내용                                                                                               |
| ----- | ------------------------------------------------------------------------------------------------ |
| 찾는 위치 | 답변 텍스트 안의 첫 JSON 배열을 씁니다                                                                         |
| 허용 형태 | 배열 그대로, ` ```json ` 코드 블록, `{"items": [...]}`, `{"data": [...]}`, 단일 `{"question", "answer"}` 객체 |
| 항목 조건 | `question`·`answer`가 비어 있지 않은 문자열. 다른 키는 무시합니다                                                   |
| 개수    | 앞에서부터 최대 \[생성 개수]개만 저장합니다. 더 적게 줘도 됩니다                                                           |
| 추론 모델 | `<think>…</think>` 구간은 지우고 읽습니다                                                                  |
| 중복    | 같은 조항 안에서 질문이 같으면 앞의 것만 남깁니다(공백 차이 무시)                                                           |

### 응답별 처리

| 워크플로우 응답                                     | 조항 결과                    | 데이터셋                          |
| -------------------------------------------- | ------------------------ | ----------------------------- |
| 유효 항목 1개 이상                                  | 생성                       | 항목마다 1행                       |
| `[]` (빈 배열)                                  | 정답 없음                    | 조항당 1행. 질문 칸에 조항 이름, 정답 칸은 공란 |
| 배열 없음 · 유효 항목 없음 · 오류 응답 · 응답 시간 초과(기본 300초) | 호출 실패                    | 저장하지 않음. \[이어서 생성] 때 다시 호출    |
| 호출 실패 연속 5회                                  | 작업 중단 — 「워크플로우 응답 시간 초과」 | —                             |
| 접근 권한 오류                                     | 작업 중단 — 「워크플로우 접근 권한 없음」 | —                             |

> 목차나 삭제 조항처럼 **만들 내용이 없으면 반드시 `[]`를 돌려주세요.** 사과 문장이나 빈 답변은 호출 실패로 처리되어 같은 조항을 다시 호출하고, 연속되면 작업이 중단됩니다.

### 구성 예시

가장 단순한 형태는 **채팅 입력 → LLM 체인(프롬프트 + 채팅 모델) → 출력**입니다. 본문이 요청에 이미 들어 있으므로 도구 호출이나 검색은 필요 없습니다.

```
너는 약관·법령 조항으로 평가용 질문·정답을 만드는 출제자다.
입력의 [생성 개수], [조항], [본문]을 읽는다.

규칙
- [본문]에 근거가 있는 내용으로만 질문과 정답을 만든다. 본문에 없는 사실을 추측하지 않는다.
- 질문은 사용자가 실제로 물을 법한 자연스러운 문장으로, 조항 번호를 몰라도 이해되게 쓴다.
- 정답은 본문 표현을 살려 1~3문장으로 쓴다.
- [생성 개수]만큼 만들되 서로 다른 내용을 묻는다. 만들 내용이 부족하면 더 적게 만든다.
- 목차, 삭제된 조항처럼 만들 내용이 없으면 [] 만 출력한다.

출력
JSON 배열만 출력한다. 설명 문장, 코드 블록 표시를 붙이지 않는다.
[{"question": "...", "answer": "..."}]
```

* 모델 출력 길이 제한은 \[생성 개수] × 항목 길이가 들어가도록 넉넉히 잡으세요. 중간에 잘리면 배열을 읽지 못해 호출 실패가 됩니다.
* 조항 하나의 처리 시간이 300초를 넘지 않게 하세요.

## 지능형 전처리기가 저장하는 형태

기본 코드가 문서를 어떻게 나누고 청크 하나에 어떤 속성을 담는지 정리했습니다. 커스텀 전처리기를 만들 때 기준이 됩니다.

### 나누는 규칙

1. **조항 우선** — `제N조`·`제N조의M`으로 시작하는 줄을 조항 제목으로 보고 다음 조항 전까지를 한 청크로 묶습니다. `[25] … 특별약관` 같은 약관 블록과 `<별표 1>` 블록은 제목 행 기준으로 따로 묶습니다.
2. 조항 제목이 2개 미만이면 `1. 제목` 형태의 번호 대단원으로 나눕니다.
3. 둘 다 없으면 페이지 단위로 나눕니다.

* 첫 조항 앞부분은 **서문**(`preamble`), 점선·쪽번호가 이어지는 목차 영역은 **목차**(`toc`)가 됩니다. 머리글·바닥글은 제거합니다.
* 청크가 `max_chars`를 넘으면 항(①②) → 호(1.) → 줄 경계 순으로 자릅니다. 잘린 뒷조각에는 조항 제목을 맨 앞에 다시 붙입니다.
* 부칙·특별약관처럼 조 번호가 다시 1부터 시작하면 `부칙 제1조`처럼 묶음 이름을 앞에 붙입니다. 그래도 같은 라벨이 겹치면 `제1조 (2)`처럼 순번을 붙여 문서 안에서 유일하게 만듭니다.

### 청크 속성

| 속성                                               | 내용                                    | 쓰는 곳                           |
| ------------------------------------------------ | ------------------------------------- | ------------------------------ |
| `text`                                           | 청크 본문. 분할 조각은 조항 제목 + 본문              | 생성 입력, 재검증 비교, 검색              |
| `article_no`                                     | 조항 라벨. 모든 청크에 채웁니다                    | 근거 칩 표시, **재검증 짝짓기 기준**        |
| `sub_title`                                      | 조항은 `제5조(채무조정 신청)`, 그 외는 원래 제목 행      | 생성 입력의 \[조항] 라벨, 정답 없음 행의 질문 칸 |
| `article_title`                                  | 조항 제목. 없으면 본문 앞 20자                   | 문서뷰 조항 표시                      |
| `chunk_unit`                                     | 청크 종류(아래 표)                           | 생성 대상 제외 판단                    |
| `sort_key`                                       | `구분.조.의.분할` 3자리씩, 예 `002.005.000.000` | 생성 순서, 문서뷰 정렬                  |
| `prev_sort_key` · `next_sort_key`                | 문서 순서상 앞뒤 청크의 `sort_key`              | 문서뷰 앞뒤 이동                      |
| `i_page` · `e_page`                              | 시작·끝 페이지                              | 근거 문서뷰 페이지 이동                  |
| `i_chunk_on_doc` · `n_chunk_of_doc`              | 문서 안 청크 순번·전체 수                       | 보조 정렬                          |
| `i_chunk_on_page` · `n_chunk_of_page` · `n_page` | 페이지 안 순번·페이지당 수·전체 페이지 수              | 문서뷰                            |
| `n_char` · `n_word` · `n_line`                   | 글자·단어·줄 수                             | 통계                             |
| `chunk_bboxes`                                   | 줄별 위치(페이지·좌표) JSON 문자열                | 문서뷰 하이라이트                      |
| `title` · `reg_date` · `media_files`             | 문서 제목, 처리 시각, 첨부 미디어(`"[]"`)          | 공통 메타                          |

문서 식별 속성과 암호화 여부는 적재 과정에서 플랫폼이 덧붙입니다. 암호화를 쓰는 환경에서는 `text`가 암호문으로 저장되고, 생성·재검증 시 플랫폼이 복호화합니다.

### `chunk_unit`과 `article_no` 값

| `chunk_unit` | 뜻                     | `article_no` 예            | 자동 생성  |
| ------------ | --------------------- | ------------------------- | ------ |
| `article`    | 조항                    | `제5조`, `제52조의2`, `부칙 제1조` | 대상     |
| `clause`     | 약관·특약 블록              | `[25]`                    | 대상     |
| `appendix`   | 별표                    | `별표 1`                    | 대상     |
| `section`    | 번호 대단원                | `1.`                      | 대상     |
| `page`       | 페이지 단위(조항·대단원이 없는 문서) | `3페이지`                    | 대상     |
| `text`       | 목차 뒤 조항 밖 본문          | `본문`                      | 대상     |
| `preamble`   | 서문(첫 조항 앞)            | `서문`                      | **제외** |
| `toc`        | 목차                    | `목차`                      | **제외** |

제외할 종류는 서버 설정으로 바꿀 수 있습니다(기본: 목차·서문).

### `sort_key` 읽는 법

`002.005.001.002`는 **구분 2**, **제5조의1**, **두 번째 분할 조각**입니다. 구분은 편·장·관 제목이나 부칙처럼 조 번호가 다시 시작될 때 1씩 오릅니다. 분할하지 않은 청크의 마지막 자리는 `000`입니다. 키는 문서 안에서 유일하고, 문자열로 정렬하면 문서 순서가 됩니다.

## 커스텀 전처리기 만들기

문서 형식이 달라 나누는 규칙을 바꿔야 할 때 기본 코드를 고쳐 씁니다. 나누는 방법은 자유지만 아래 저장 규칙은 지켜야 자동 생성·재검증이 동작합니다.

### 필수 규칙

| 규칙                                                                                  | 지키지 않으면                                      |
| ----------------------------------------------------------------------------------- | -------------------------------------------- |
| 전처리기 타입을 **「지능형 전처리기」** 로 등록하고, 드라이브 적재 방식으로 그 전처리기를 고른다                            | 문서를 근거로 고를 수 없고, 재검증이 문서 단위로만 동작한다           |
| 청크마다 `text`를 채운다                                                                    | 빈 본문이 워크플로우에 전달된다                            |
| 모든 청크에 `article_no`를 채우고 **문서 안에서 조항마다 유일**하게 만든다. 한 조항을 여러 청크로 나눴다면 조각끼리는 같은 값을 쓴다 | 근거 칩이 비고, 재검증에서 조항을 짝짓지 못해 「조항 삭제」로 판정된다     |
| `article_no`를 **개정 전후에 같은 조항이면 같은 값**으로 만든다(예: 항상 `제5조`)                            | 문서를 다시 올릴 때마다 모든 항목이 「검증필요」가 된다              |
| `sort_key`를 문서 안에서 유일하게, **문자열 정렬 = 문서 순서**가 되도록 자릿수를 고정해 채운다                       | 생성 순서와 문서뷰 조항 순서가 뒤섞이고, 문서뷰에 조항 정보가 표시되지 않는다 |
| 목차·서문처럼 질문을 만들 필요가 없는 청크는 `chunk_unit`을 `toc` 또는 `preamble`로 둔다                     | 목차까지 조항으로 세어 호출 수가 늘고 정답 없음이 많아진다            |

### 권장 규칙

| 규칙                                                | 효과                                       |
| ------------------------------------------------- | ---------------------------------------- |
| `sub_title`에 사람이 읽는 조항 이름(`제5조(채무조정 신청)`)         | 워크플로우가 조항을 알아보기 쉽고, 정답 없음 행의 질문 칸이 읽기 좋다 |
| `i_page`, `chunk_bboxes`                          | 근거 문서뷰에서 해당 페이지·위치로 이동한다                 |
| `article_title`, `prev_sort_key`, `next_sort_key` | 문서뷰에서 조항 제목과 앞뒤 조항 이동이 동작한다              |
| `i_chunk_on_doc`                                  | `sort_key`가 같을 때 보조 정렬 기준이 된다            |
| `text`를 직접 암호화하거나 문서 식별·암호화 여부 속성을 넣지 **않는다**     | 적재 과정에서 플랫폼이 환경 설정에 따라 처리한다              |

**수동 스키마 드라이브**를 쓴다면 `article_no`·`sub_title`·`article_title`·`chunk_unit`·`sort_key`·`prev_sort_key`·`next_sort_key`를 text 속성으로 스키마에 포함해 두세요. `chunk_unit`은 생성 대상 조항 수를 셀 때 값 비교 필터로 쓰입니다.

### 코드 골격

전처리기는 `__call__(request, file_path, **kwargs)`에서 청크 목록을 돌려줍니다. `kwargs`에는 드라이브·전처리기 파라미터(예: `max_chars`)가 들어옵니다. 기본 코드의 `compose_vectors`만 바꾸고 반환 형태는 그대로 두는 것이 가장 안전합니다.

```python
# segments: [(article_no, sub_title, unit, body_text, (구분, 조, 의), page), ...] — 나누는 방법은 자유
def to_vectors(segments, title):
    keys = ["%03d.%03d.%03d.000" % key for *_, key, _ in segments]
    out = []
    for i, (no, sub_title, unit, body, key, page) in enumerate(segments):
        out.append(GenOSVectorMeta.model_validate({
            "text": body,
            "article_no": no,              # 문서 안 유일, 개정 전후 동일
            "sub_title": sub_title,        # 예: 제5조(채무조정 신청)
            "chunk_unit": unit,            # 목차·서문은 toc / preamble
            "sort_key": keys[i],           # 문자열 정렬 = 문서 순서
            "prev_sort_key": keys[i - 1] if i else None,
            "next_sort_key": keys[i + 1] if i + 1 < len(keys) else None,
            "i_page": page,
            "i_chunk_on_doc": i,
            "n_chunk_of_doc": len(segments),
            "title": title,
        }))
    return out
```

### 배포 전 확인

* 테스트 PDF를 적재하고 문서뷰에서 조항 라벨·순서가 맞는지 봅니다.
* 같은 문서의 개정본(조항 하나만 수정)을 다시 올려, 수정한 조항의 항목만 「검증필요」가 되는지 봅니다.
* 데이터셋 생성 화면의 조항 수가 목차·서문을 뺀 수와 맞는지 봅니다.

## 오류·예외 처리

### 근거 문서를 고를 수 없음

| 화면 안내                                 | 해결                                   |
| ------------------------------------- | ------------------------------------ |
| 지능형 전처리기 미적용 드라이브의 문서입니다              | 드라이브 적재 방식을 지능형 전처리기로 바꾸고 재적재합니다     |
| 적재가 끝나지 않은 문서입니다                      | 파일 상태가 「완료」가 될 때까지 기다리거나, 오류면 재적재합니다 |
| 열람 권한이 없는 문서입니다                       | 드라이브 공유·권한을 받습니다                     |
| 파일이 아닌 항목입니다                          | 폴더 대신 파일을 고릅니다                       |
| 선택한 문서에 생성할 조항이 없습니다. 다른 문서를 선택해 주세요. | 목차·서문만 있는 문서입니다. 다른 문서를 고릅니다         |
| 학습용 데이터셋은 근거 문서 자동 생성을 지원하지 않습니다      | 유형을 Evaluation으로 만듭니다                |

### 적재가 실패함

| 상황                                       | 해결                                                      |
| ---------------------------------------- | ------------------------------------------------------- |
| PDF가 아닌 파일                               | 지능형 전처리기는 **PDF만** 지원합니다                                |
| 「PDF에서 텍스트를 추출하지 못했습니다. 스캔본은 지원하지 않습니다.」 | 스캔 이미지만 있는 PDF입니다. 텍스트가 있는 PDF를 씁니다                     |
| 적재 방식을 바꾼 뒤 결과가 그대로                      | 드라이브 적재 방식을 바꾸면 기존 파일이 「재적재 대상」이 됩니다. 재적재해야 새 설정이 반영됩니다 |

### 워크플로우 목록이 비어 있음

배포 상태 → 워크플로우 읽기 권한 → 관리자가 지정한 생성용 태그 조건 순으로 확인합니다.

### 작업이 중단됨

생성된 항목은 저장되어 있습니다. 원인을 해결한 뒤 **\[이어서 생성]** 을 누르면 남은 조항과 호출에 실패한 조항만 다시 처리합니다.

| 중단 사유                          | 뜻                                         |
| ------------------------------ | ----------------------------------------- |
| 워크플로우 응답 시간 초과                 | 호출 실패가 연속 5회. 워크플로우 오류·응답 형식·처리 시간을 점검합니다 |
| 워크플로우 접근 권한 없음                 | 워크플로우 권한이 회수됐습니다                          |
| 생성 진행 멈춤                       | 2분 동안 진행이 없었습니다(서버 재시작 등)                 |
| 작업 준비 시간 초과                    | 생성 작업이 5분 안에 시작되지 못했습니다                   |
| 생성 작업 오류                       | 생성 작업이 예기치 않게 끝났습니다                       |
| 데이터셋 쓰기 권한 없음 · 근거 문서 읽기 권한 없음 | 관리 그룹·문서 권한을 확인합니다                        |

### 정답 없음이 너무 많음

워크플로우가 어떤 경우에 `[]`를 돌려주는지 프롬프트를 점검합니다. 목차·서문이 섞여 들어온다면 전처리기의 `chunk_unit` 값을 확인합니다.

## 사용 시나리오

### 약관 하나로 평가 데이터셋을 처음 만드는 담당자

지능형 전처리기를 배포하고 그 전처리기로 AI 드라이브를 만든 뒤 약관 PDF를 올립니다. 적재가 「완료」가 되면 데이터셋 생성에서 「근거 문서로 자동 생성」을 고르고, 드라이브·파일을 지정합니다. 조항 수가 120개로 표시되고 조항당 3건으로 두면 「조항 120개 × 3건 = 360건(호출 120회)」로 안내됩니다. 워크플로우를 고르고 \[생성 시작]을 누른 뒤, 우측 하단 위젯으로 진행을 지켜봅니다.

### 생성이 중단된 경우

목록에 「생성 중단」 배지가 뜨면 중단 사유를 확인합니다. 워크플로우 응답 형식 문제였다면 프롬프트를 고쳐 다시 배포한 뒤 \[이어서 생성]을 누릅니다. 이미 만들어진 항목은 그대로 두고 남은 조항만 처리합니다.

### 문서 형식이 달라 조항이 제대로 안 나뉘는 경우

기본 코드의 분할 규칙으로는 조항이 잡히지 않는 문서입니다. 커스텀 전처리기에서 나누는 방법을 바꾸되, `article_no`·`sort_key`·`chunk_unit` 규칙은 그대로 지킵니다. 테스트 PDF를 적재해 문서뷰에서 조항 라벨·순서를 확인하고, 개정본을 올려 수정한 조항의 항목만 검증필요가 되는지 확인합니다.


---

# 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.6/basic-tutorials/guides/data/dataset/auto-generation.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.