> 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.2/admin-management/settings/resource/pipeline.md).
# 파이프라인 관리
**파이프라인**(Pipeline)은 문서 적재를 파싱 → 전처리 → 임베딩 → VectorDB 저장의 여러 단계로 나누어 실행하는 적재기입니다. 각 단계의 진행 상황을 실시간으로 확인할 수 있고, 중간 단계에서 실패한 경우 실패한 지점부터 다시 이어서 실행할 수 있습니다.
좌측 네비게이션의 **문서 전처리 > 파이프라인** 메뉴에서 진입합니다.
## 주요 개념
| 개념 | 설명 |
| -------- | -------------------------------------------------------------------- |
| 파이프라인 | 다단계 적재를 오케스트레이션하는 적재기입니다. 별도의 배포 과정 없이 메타 정보만 등록하면 워크플로우가 실행을 담당합니다. |
| 큐 이름 | 파이프라인이 사용할 작업 큐의 이름입니다. 워커가 이 큐를 확인해 워크플로우를 실행합니다. |
| 워크플로우 타입 | 실행할 워크플로우의 종류를 지정하는 이름입니다. |
| 진척도 | 워커가 단계마다 기록하는 진행 정보로, 목록·상세 화면에서 "3/4"와 같은 형태로 표시됩니다. |
### 전처리기와의 차이
| 특성 | 전처리기 | 파이프라인 |
| ----- | --------------------------- | -------------------- |
| 정의 | 문서 전처리 Python 코드(부착·지능형·변환) | 다단계 적재 워크플로우 오케스트레이션 |
| 배포 | 컨테이너 배포 필요 | 배포 없이 메타 정보만 등록 |
| 상태 추적 | 컨테이너 상태 배지 | 단계별 진척도 |
| 재시작 | 처음부터 재적재 | 중간 재개 또는 전체 재실행 선택 |
## 목록 화면
**문서 전처리 > 파이프라인** 화면에서 등록된 파이프라인 목록을 확인합니다. 전처리기 목록과 화면 구성은 비슷하지만, 배포·연결 상태·카탈로그 항목이 없고 **큐 이름**과 **워크플로우 타입** 컬럼이 표시됩니다.
파이프라인 목록 화면
* **목록 컬럼:** ID, 이름, 확장자, 큐 이름, 워크플로우 타입
* **검색:** 검색 조건을 선택해 원하는 파이프라인을 빠르게 찾을 수 있습니다.
* **생성:** 생성 권한이 있는 경우에만 `[생성]` 버튼이 활성화됩니다.
## 파이프라인 생성
목록 화면의 `[생성]` 버튼을 눌러 생성 다이얼로그를 엽니다.
파이프라인 생성 다이얼로그
| 입력 항목 | 필수 | 설명 |
| -------- | -- | --------------------------------------------------- |
| 이름 | 필수 | 파이프라인의 이름입니다. |
| 설명 | | 파이프라인에 대한 상세 설명입니다. |
| 확장자 | | 이 파이프라인이 처리할 파일 형식입니다. 예를 들어 "pdf, docx"와 같이 입력합니다. |
| 큐 이름 | 필수 | 워커가 확인할 작업 큐의 이름입니다. |
| 워크플로우 타입 | 필수 | 실행할 워크플로우의 종류입니다. |
| 관리 그룹 | 필수 | 파이프라인을 관리할 그룹입니다. |
저장하면 목록이 갱신되고, 이후 문서 업로드 시 이 파이프라인을 선택할 수 있습니다.
### 큐 이름·워크플로우 타입 작성 규칙
**큐 이름**과 **워크플로우 타입**은 저장 시 아래 규칙으로 검증됩니다. 규칙에 맞지 않으면 저장되지 않으니 입력값을 확인해 주세요.
* 영문·숫자로 시작하며, 이후에는 영문·숫자와 마침표(`.`), 밑줄(`_`), 하이픈(`-`)만 사용할 수 있습니다.
* 최대 128자까지 입력할 수 있습니다.
* 공백과 슬래시(`/`)는 사용할 수 없습니다.
* `temporal-sys`, `__temporal`, `/_sys` 로 시작하는 이름은 시스템 예약어이므로 사용할 수 없습니다.
## 문서 업로드 및 진척도 추적
파이프라인은 VectorDB에 문서를 업로드할 때 사용됩니다.
1. VectorDB 상세 화면에서 문서를 업로드하면서 사용할 **파이프라인**을 선택합니다.
2. 업로드된 문서가 등록되고, 적재 상태가 **대기**로 표시됩니다.
3. 각 문서에 대해 워크플로우가 시작되면 상태가 **실행 중**으로 전환됩니다.
4. 워커가 큐를 확인해 파싱 → 전처리 → 임베딩 → VectorDB 저장을 순서대로 수행하며, 단계가 바뀔 때마다 진행 정보를 기록합니다.
5. 화면은 이 정보를 주기적으로 조회해 "1/4 파싱 중"에서 "4/4"와 같이 진척도를 갱신하고, 모든 단계가 끝나면 완료 배지로 전환됩니다.
### 실패한 문서 다시 실행하기
적재가 실패한 문서는 두 가지 방식으로 다시 실행할 수 있습니다.
| 방식 | 동작 |
| ------ | ----------------------------------------------------------------------------------- |
| 중간 재개 | 이미 완료된 단계의 중간 산출물을 재사용하고, 실패한 지점부터 이어서 실행합니다. 재개 지점을 찾지 못하는 경우에는 전체 재실행으로 자동 전환됩니다. |
| 전체 재실행 | 진행 중이던 실행을 종료하고 파싱 단계부터 처음부터 다시 실행합니다. 중간 산출물은 재사용하지 않습니다. |
시간이 오래 지나 이력이 만료된 문서는 중간 재개가 불가능할 수 있으며, 이 경우 전체 재실행을 사용해 주세요.
## 오류 상황과 대처
| 증상 | 대처 방법 |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ |
| 문서 업로드 후 곧바로 적재가 실패하고 오류 메시지가 표시됩니다. | 파이프라인에 입력한 큐 이름·워크플로우 타입이 실제 워커 설정과 일치하는지 확인해 주세요. 값이 올바르다면 워크플로우 서버가 정상 동작 중인지 관리자에게 확인이 필요합니다. |
| 적재 상태만 표시되고 진척도가 비어 있습니다. | 진척 정보를 조회할 수 없는 상태입니다. 적재 자체는 진행 중일 수 있으며, 연결이 복구되면 진척도 표시가 자동으로 재개됩니다. |
| 진척도가 계속 표시되지 않습니다. | 워커가 단계별 진행 정보를 기록하지 않으면 진척도가 표시되지 않습니다. 워크플로우 구현 담당자에게 확인해 주세요. |
| 파이프라인으로 적재한 문서를 전처리기 방식으로 재시작하면 차단됩니다. | 파이프라인으로 적재한 문서는 중간 재개 또는 전체 재실행을 사용해 주세요. |
| 생성 버튼이 비활성화되어 있습니다. | 파이프라인 생성 권한이 없는 계정입니다. 관리 그룹 담당자에게 권한을 요청해 주세요. |
## 사용자 시나리오 — 파이프라인 생성 후 문서 적재
1. **문서 전처리 > 파이프라인** 화면에서 `[생성]`을 누릅니다.
2. 이름, 설명, 확장자, 큐 이름, 워크플로우 타입, 관리 그룹을 입력합니다. 큐 이름과 워크플로우 타입은 작성 규칙에 맞게 입력해야 합니다.
3. 저장하면 목록에 새 파이프라인이 추가됩니다.
4. VectorDB 상세 화면에서 문서를 업로드할 때 방금 만든 파이프라인을 선택합니다.
5. 적재가 시작되면 상태가 **실행 중**으로 바뀌고, 진척도가 "1/4 파싱 중"에서 "4/4"까지 순차적으로 갱신됩니다.
6. 실패한 문서가 있다면 중간 재개 또는 전체 재실행으로 다시 적재합니다.
## 참고
* 전처리기의 등록·배포·관리와 전처리기 카탈로그 이용 방법은 [전처리기 관리](/default/v1.9.2/admin-management/settings/resource/preprocessor.md) 문서를 참고하세요.
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://genos-docs.gitbook.io/default/v1.9.2/admin-management/settings/resource/pipeline.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.