---
tags: [workflow, rag, companyx, upload, indexing]
type: workflow
last_updated: 2026-04-06
---

# RAG 업로드·인덱싱 파이프라인

## 목적
- 외부 또는 내부 문서를 `skill-rag-file`에 업로드해 검색 가능한 상태로 만든다.
- Company X 문서를 검색 경로에 넣기 위한 전처리·저장 절차를 고정한다.

## 상위 원칙
- [RAG Workflow Index](./README.md)
- [project-artifacts-ssot.md](../../../../0_VALUE/20_Governance/project-artifacts-ssot.md)
- [test-principles.md](../../../../0_VALUE/20_Governance/test-principles.md)

## 코드 SSOT
- `skill-rag-file` 서비스 (업로드·인덱싱·검색 담당)
- `rb8001/app/pipelines/langgraph_document.py` (문서 파이프라인에서 업로드·재인덱싱 호출)
- `rb8001/app/router/slack_handler.py` (Slack 파일 업로드 경로)
- `rb8001/app/services/naverworks_file_processor.py` (네이버웍스 첨부 업로드 경로)

## 입력
- `team_id`
- `file_url` 또는 업로드 파일 본문
- `file_name`
- `metadata`

## 출력
- 업로드 결과 (document_id)
- 인덱싱 결과 (청크 수, 임베딩 상태)
- 저장된 문서의 메타데이터
- 실패 시 실패 원인과 재시도 가능 여부

## 처리 순서
1. 요청 페이로드를 정규화한다.
2. 원본 문서를 `$SKILL_RAG_FILE_URL/api/upload`로 전달한다.
3. 텍스트 추출을 수행한다. OCR 대상(이미지 PDF 등)은 OCR 폴백 경로로 처리한다.
4. 청킹한다 (기준: 1,000자 chunk, 200자 overlap).
5. 임베딩한다 (Gemini Embedding 2, 768d).
6. DB 저장 시 `tsvector` 컬럼이 트리거로 자동 생성된다 (`simple` 설정).
7. 저장 결과를 그대로 반환한다.

## 재인덱싱
- `$SKILL_RAG_FILE_URL/api/reindex` 엔드포인트를 통해 기존 문서 재인덱싱 가능.
- `langgraph_document.py` 파이프라인에서 업로드 후 필요 시 재인덱싱을 호출한다.
- 재인덱싱 후 `$SKILL_RAG_FILE_URL/api/text/{document_id}`로 텍스트 추출 결과를 검증한다.

## 업로드 경로별 진입점

| 경로 | 코드 | 설명 |
|------|------|------|
| Slack 파일 첨부 | `slack_handler.py` → `$SKILL_RAG_FILE_URL/api/upload` | Slack에서 파일 다운로드 후 skill-rag-file로 전송 |
| 네이버웍스 메일 첨부 | `naverworks_file_processor.py` → `$SKILL_RAG_FILE_URL/api/upload` | 메일 첨부 다운로드 후 업로드 |
| IR Deck 업로드 | `ir_deck.py` → `slack_handler.upload_files_to_rag()` | IR Deck 평가를 위한 업로드 |
| 배치 인덱싱 | `skill-rag-file/scripts/` | 대량 문서 일괄 인덱싱 |

## 환경변수
- `SKILL_RAG_FILE_URL` — skill-rag-file 서비스 베이스 URL (필수).

## 실패 분기
- 파일 누락이면 업로드 전에 실패한다.
- 텍스트 추출이 실패하면 인덱싱하지 않는다.
- 임베딩 또는 저장이 실패하면 성공처럼 반환하지 않는다.
- 같은 파일 재업로드 시 멱등성 규칙을 유지해야 한다.

## 현재 기준
- RAG 인덱싱은 `skill-rag-file`이 담당한다.
- Company X 문서는 `team_id`(`79441171-3951-4870-beb8-916d07fe8be5`) 경계로 분리한다.
- 검색 가능한 상태가 되기 전까지는 Grounding 파이프라인에 연결하지 않는다.
- 청킹 기준: 1,000자 chunk, 200자 overlap.
- 임베딩: Gemini Embedding 2, 768차원, HNSW cosine 인덱스.
- `tsvector` 컬럼은 INSERT/UPDATE 트리거로 자동 생성된다 (`simple` 설정, GIN 인덱스).

## 검증 기준
- 업로드 직후 검색 API로 최소 1건 이상 적중하는지 확인한다.
- 저장된 문서명이 원본 파일명과 정합한지 확인한다.
- 대용량 문서도 실패 없이 처리되는지 확인한다.

## 관련 문서
- [RAG 검색·Grounding 요청](./rag_search_grounding_request.md)
- [임베딩 브리지](./skill_embedding_bridge.md)
- [Company X Grounding 파이프라인](./companyx_grounding_pipeline.md)