> 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.5/basic-tutorials/guides/data/ai-drive/ingestion-method.md).
# 적재 방식
### 개요
AI 드라이브에 올린 문서를 **어떤 방법으로 적재할지** 정하는 설정입니다. v1.9.5 이전에는 전처리기(문서 전처리 > 전처리기)만 고를 수 있었지만, v1.9.5부터는 **파이프라인(문서 전처리 > 파이프라인)** 도 같은 목록에서 고를 수 있습니다. 두 가지를 한 목록에 묶으면서 항목 이름이 **「전처리기」에서 「적재 방식」으로** 바뀌었습니다.
적재 방식은 **드라이브 단위로 한 번만** 정합니다. 파일을 올릴 때마다 고르는 값이 아니며, 바꾸려면 드라이브 기본 정보에서 수정합니다.
진입 경로는 다음과 같습니다.
| 역할 | 경로 |
| -------------- | ------------------------------------------------- |
| 드라이브 생성 시 지정 | 데이터 > AI 드라이브 > \[드라이브 생성] > 2단계 > 「적재 방식」 |
| 지정값 확인·변경 | 데이터 > AI 드라이브 > 드라이브 내부 > 우측 패널 > 기본 정보 > 「적재 방식」 |
| 드라이브별 확인 | 데이터 > AI 드라이브 > 목록 > 「적재 방식」 컬럼 |
| 전처리기·파이프라인 등록 | 문서 전처리 > 전처리기 / 문서 전처리 > 파이프라인 |
| 파이프라인 실행 상황 확인 | 문서 전처리 > 파이프라인 실행 현황 |
| 항목 | 내용 |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------- |
| 버전 | v1.9.5 |
| 영역 | 크로스 (admin-front AI 드라이브 · admin-api 적재 경로) |
| 상태 | 완료 |
| 관련 이슈 | #20929(상위) · #21280(기획) · #22069 · #22070 · #22071 · #22072 · #22073(BE) · #22074 · #22075 · #22076(FE) · #22355(삭제 전파) · #13295(이식 기준) |
| 최종 확인 | 2026-10-13 · 기준: `admin-front/src/views/data/ai-drive/` |
### 주요 개념
| 개념 | 설명 |
| ----- | ------------------------------------------------------------------------------------------- |
| 적재 방식 | 드라이브에 올린 문서를 적재할 때 사용할 전처리 수단입니다. 전처리기 또는 파이프라인 중 하나를 고릅니다. |
| 전처리기 | 문서 전처리 > 전처리기에 등록한 단일 전처리 모듈입니다. 기존 AI 드라이브가 쓰던 방식입니다. |
| 파이프라인 | 문서 전처리 > 파이프라인에 등록한 여러 단계로 구성된 적재 흐름입니다. v1.9.5부터 AI 드라이브에서도 선택할 수 있습니다. |
| 종류 배지 | 목록·기본 정보·활동 내역에서 항목 이름 옆에 붙는 `전처리기` · `파이프라인` 표시입니다. 이름만으로는 둘을 구분할 수 없어 배지로 구분합니다. |
| 파라미터 | 선택한 적재 방식이 가진 기본값(`default_params`)으로 채워지는 입력란입니다. Chunk Size · Chunk Overlap 등이 여기에 들어갑니다. |
### 드라이브 생성 시 적재 방식 선택
AI 드라이브 생성 2단계의 **「적재 방식」** 항목에서 고릅니다. 필수 항목입니다.
목록에는 **전처리기가 먼저, 그 다음 파이프라인이** 순서대로 표시되며, 항목마다 이름 옆에 `전처리기` 또는 `파이프라인` 배지가 붙습니다. 항목을 고르면 그 항목의 설명과 지원 확장자가 함께 표시됩니다.
선택을 바꾸면 **파라미터 영역이 선택한 항목의 기본값으로 통째 교체**됩니다. 기본값이 없는 항목을 고르면 파라미터 영역 자체가 보이지 않습니다. 이 규칙은 전처리기·파이프라인이 같습니다.
| 상황 | 화면 |
| ------------------ | ------------------------------------------------- |
| 선택하지 않고 저장 | `적재 방식을 선택해 주세요` |
| 전처리기·파이프라인이 하나도 없음 | `등록된 전처리기·파이프라인이 없습니다. 문서 전처리 메뉴에서 등록 후 이용해 주세요.` |
| 목록을 불러오지 못함 | `적재 방식 목록을 불러오지 못했습니다. 잠시 후 다시 시도해 주세요.` |
> 적재 방식은 AI 드라이브에서 새로 만들 수 없습니다. 등록은 **문서 전처리 > 전처리기** 또는 **문서 전처리 > 파이프라인** 메뉴에서만 가능하므로, 빈 상태에서도 생성 유도 버튼은 제공하지 않습니다.
### 지정값 확인과 변경
드라이브 내부 우측 패널의 **기본 정보 > 「적재 방식」** 에서 현재 값을 확인합니다. 값은 `항목 이름 + 종류 배지` 형태로 표시됩니다.
수정 모드로 바꾸면 생성 때와 같은 병합 목록에서 다른 적재 방식을 고를 수 있습니다. 적재 방식을 바꾸면 **이미 올려 둔 파일은 새 적재 방식으로 다시 적재해야** 하므로, 기존 파일이 `재적재 대상` 상태로 전환됩니다.
변경 내역은 드라이브 **활동 내역**에 기록됩니다. 전처리기에서 파이프라인으로 바꾼 경우에도 **「적재 방식」 한 줄**로 변경 전 → 변경 후가 표시되며, 각 값에 종류 배지가 함께 붙습니다.
### 드라이브 목록의 「적재 방식」 컬럼
AI 드라이브 목록에 **「적재 방식」** 컬럼이 있습니다. 한 셀이 두 줄로 구성됩니다.
| 줄 | 내용 |
| -- | ------------------------- |
| 1행 | 적재 방식 이름 (값이 없으면 `-`) |
| 2행 | 종류 배지 — `전처리기` 또는 `파이프라인` |
이름 칸에는 파이프라인을 쓰는 드라이브도 파이프라인 이름이 그대로 표시되므로, **종류는 배지로만 구분**됩니다. 컬럼 정렬도 지원합니다.
### 삭제된 적재 방식
드라이브가 쓰던 전처리기·파이프라인이 삭제되면 이름 옆에 **「삭제됨」** 배지가 붙습니다. 목록 컬럼과 기본 정보 양쪽에 표시되며, 종류 배지와는 별개로 평가되므로 종류를 알 수 없는 경우에도 삭제 여부는 그대로 보입니다.
삭제된 적재 방식을 쓰는 드라이브는 **업로드·재적재가 막힙니다.** 아래 문구가 표시되면 기본 정보에서 적재 방식을 다른 항목으로 바꾼 뒤 다시 시도합니다.
> 삭제된 적재 방식이라 적재할 수 없습니다. 적재 방식을 다시 선택한 뒤 시도해 주세요.
반대로, **AI 드라이브가 사용 중인 파이프라인은 삭제되지 않습니다.** 문서 전처리 > 파이프라인에서 삭제를 시도하면 사용 중인 드라이브를 알려 주며 막힙니다.
> \[파이프라인: {id}]가 \[AI 드라이브: {드라이브 ID}] 에서 사용 중입니다.
### 적재 상태 확인과 재적재
파일의 적재 상태는 드라이브 내부 파일 목록의 상태 배지로 확인합니다. 상태는 5종입니다.
| 상태 | 의미 | 클릭 동작 |
| ------ | ------------------------ | ----- |
| 대기 중 | 적재 대기열에 있음 | 중단 |
| 실행 중 | 적재 진행 중 | 중단 |
| 완료됨 | 적재 완료 | 없음 |
| 오류 발생 | 적재 실패 (오류 메시지는 툴팁) | 재적재 |
| 재적재 대상 | 설정 변경·덮어쓰기 등으로 다시 적재해야 함 | 재적재 |
적재가 실패하면 파일 상세에 `적재에 실패했습니다. 상태 버튼으로 재시작할 수 있습니다.` 가 표시됩니다. 상태 배지를 누르면 `선택한 파일을 재적재하시겠습니까?` 확인 후 재적재가 시작되고, `재적재가 시작되었습니다` 토스트가 표시됩니다.
파이프라인으로 적재한 경우 단계별 실행 상황과 소요 시간은 **문서 전처리 > 파이프라인 실행 현황**에서 확인합니다. AI 드라이브 화면은 파일 단위 상태만 보여 줍니다.
| 작업 | 가능한 사용자 |
| ------------------ | --------------------- |
| 드라이브 생성 시 적재 방식 지정 | AI 드라이브 쓰기 권한이 있는 사용자 |
| 적재 방식 변경 | 해당 드라이브 쓰기 권한이 있는 사용자 |
| 전처리기·파이프라인 등록·삭제 | 문서 전처리 메뉴 권한이 있는 관리자 |
### 오류·예외 처리
| 코드 | 발생 상황 | 표시 문구 |
| ---------- | ---------------------------- | --------------------------------------------------------------------------------------- |
| `03020057` | 삭제된 적재 방식으로 적재 시도 | 삭제된 적재 방식이라 적재할 수 없습니다. 적재 방식을 다시 선택한 뒤 시도해 주세요. |
| `03044005` | 드라이브 설정에 적재 방식·임베딩 서빙이 비어 있음 | 드라이브 설정에 적재 방식 또는 임베딩 서빙이 비어 있어 재적재할 수 없습니다. |
| `03044014` | 파이프라인 적재가 아닌 건에 파이프라인 재시작 시도 | 파이프라인 적재가 아니어서 재시작할 수 없습니다. |
| `03020043` | 파이프라인으로 적재된 문서가 아님 | 파이프라인으로 적재된 문서가 아니어서 재시작할 수 없습니다. |
| `03020045` | 파이프라인 적재 건에 전처리기 재시작 시도 | 파이프라인으로 적재된 문서입니다. 파이프라인 재시작을 사용해 주세요. 전처리기 재시작은 지원하지 않습니다. |
| `02110006` | 사용 중인 파이프라인 삭제 시도 | \[파이프라인: {{pipeline\_id}}]가 \[AI 드라이브: {{drive\_ids}}] 에서 사용 중입니다. |
| `02110001` | 선택한 파이프라인을 찾을 수 없음 | \[파이프라인: {{pipeline\_id}}] 을/를 찾을 수 없습니다. 삭제되었거나 접근 권한이 없는지 확인해 주세요. |
| `03020041` | Temporal 워크플로우 시작 실패 | Temporal 워크플로우를 시작하지 못했습니다. Temporal 서버 연결 상태와 파이프라인의 큐 이름·워크플로우 타입(워커 등록 여부)을 확인해 주세요. |
### 사용자 시나리오
#### 여러 단계를 거쳐 문서를 적재하고 싶은 경우
문서 전처리 > 파이프라인에 적재 흐름을 먼저 등록한 뒤, AI 드라이브를 만들 때 「적재 방식」에서 그 파이프라인을 고릅니다. 목록에서 전처리기 다음에 표시되며 `파이프라인` 배지로 구분됩니다.
#### 기존 드라이브를 파이프라인 방식으로 바꾸고 싶은 경우
드라이브 내부 우측 패널의 기본 정보에서 적재 방식을 파이프라인으로 바꿉니다. 이미 올라가 있던 파일은 `재적재 대상`이 되므로, 상태 배지를 눌러 재적재합니다.
#### 목록에서 어떤 드라이브가 파이프라인을 쓰는지 보고 싶은 경우
AI 드라이브 목록의 「적재 방식」 컬럼 2행 배지로 구분합니다. 이름만으로는 알 수 없습니다.
#### 업로드가 막히고 「삭제된 적재 방식」 안내가 뜨는 경우
쓰던 전처리기·파이프라인이 삭제된 상태입니다. 기본 정보에서 다른 적재 방식을 고른 뒤 다시 업로드합니다. 기존 파일은 재적재가 필요합니다.
#### 파이프라인을 지우려는데 삭제가 안 되는 경우
그 파이프라인을 쓰는 AI 드라이브가 있습니다. 안내에 표시된 드라이브의 적재 방식을 먼저 바꾼 뒤 삭제합니다.
***
## 임시 코드 검수 메모: 리스크 및 보완 필요 사항
> v1.9.5 시점의 열린 항목입니다. 사용자 안내가 아니라 후속 작업 확인용입니다.
* **AI 드라이브 전용 「파이프라인 진행률·재시작」 UI 없음** — 기획(#21280)에는 "파이프라인 적재에 진행률 조회·재시작 제공"으로 정리되어 있으나, `admin-front/src/views/data/ai-drive/` 에는 해당 UI가 없습니다. 현재는 파일 상태 배지의 **재적재**로 처리되고, 단계별 진행 상황은 문서 전처리 > 파이프라인 실행 현황에서 봅니다. 본 매뉴얼은 구현 기준으로 기술했습니다.
* **Chunk Size·Overlap 유지 규칙 차이** — 기획 메모에는 "파이프라인 선택 시에도 Chunk Size·Overlap 입력란과 값 유지(벡터 DB와 유일하게 다른 지점)"로 되어 있으나, 구현은 **선택 항목의 `default_params` 로 통째 교체**이며 전처리기·파이프라인이 같은 규칙입니다. 기본값이 없으면 영역이 사라집니다.
* **종류 배지는 BE 응답 의존** — 응답에 종류 구분값(`ingestion_kind`·`pipeline_id`)이 없으면 배지를 생략합니다. 구버전 응답이 섞이면 같은 화면에서 배지가 있는 행과 없는 행이 공존할 수 있습니다.
* **삭제 차단 적용 전 데이터** — 삭제 차단(#22355) 적용 이전에 생긴, 이미 삭제된 적재 방식을 참조하는 드라이브가 운영망에 남아 있을 수 있습니다. 적재 방식을 교체하기 전까지 업로드·재적재가 막히므로 배포 전 정리와 관리 그룹 사전 안내가 필요합니다.
* **미캡처 화면 3종** — 빈 상태(등록된 전처리기·파이프라인 0건) · 「삭제됨」 배지 · 활동 내역의 적재 방식 변경 전/후는 개발망에 해당 데이터가 없어 캡처하지 못했습니다. 본문 설명은 소스 기준으로 작성했으며, 데이터가 생기면 `screenshots/03_empty-state.png` · `06_deleted-badge.png` · `08_activity-change.png` 로 추가하면 됩니다.
* **자동 적재는 범위 밖** — 자동 적재(폴더 소스)의 파이프라인 지원은 후속 과제(#22095)로, 이번 매뉴얼에 포함하지 않았습니다.
### Changelog
* v1.9.5 (2026-10-13): 최초 작성. 전처리기·파이프라인 병합 선택(「적재 방식」), 종류 배지, 빈 상태·조회 실패 안내, 적재 방식 변경 시 재적재 전환과 활동 기록, 목록 2줄 셀, 삭제된 적재 방식 차단, 적재 상태 5종과 재적재. #20929 · #21280 · #22069\~#22076 · #22355
---
# 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.5/basic-tutorials/guides/data/ai-drive/ingestion-method.md?ask=&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.
