DOCS/workflow/03_rag/rag_upload_indexing_pipeline.md

tags: [workflow, rag, companyx, upload, indexing]

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

목적

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

상위 원칙

• RAG Workflow Index
• project-artifacts-ssot.md
• test-principles.md

입력

• team_id
• file_url 또는 업로드 파일 본문
• file_name
• metadata

출력

• 업로드 결과
• 인덱싱 결과
• 저장된 문서의 메타데이터
• 실패 시 실패 원인과 재시도 가능 여부

처리 순서

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

실패 분기

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

현재 기준

• 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 인덱스).
• 배치 인덱싱 스크립트: skill-rag-file/scripts/reindex_companyx_latest_200.py (200개 기준).

검증 기준

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

관련 문서

• RAG 검색·Grounding 요청
• 임베딩 브리지
• Company X Grounding 파이프라인