업로드한 문서를 읽어 AI 에이전트가 검색할 수 있는 시스템 만들기

## 브랜치 이름 규칙을 정하고 API·워커·공통 코드 나누기 코드를 변경하기 전에 책임 범위를 드러내어, 각 동작이 해당 동작을 테스트하고 유지관리할 수 있는 계층에 머물도록 하세요. ### 추적 가능한 브랜치 사용하기 - 브랜치 이름은 `type/user/description pattern` 형식으로 지정하세요. - `type`은 소문자로 유지하고 `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `perf`, `ci`, `build`, `revert`처럼 인정된 변경 분류를 선택하세요. - `user`에는 작업을 책임지는 사람을 사용하세요. 일반적인 에이전트나 도구 이름으로 절대 대체하지 마세요. - `description`은 짧은 소문자 케밥 표기법으로 작성하세요. ### 실행 시점의 책임 분리하기 - 동기식 API 처리, 비동기 문서 작업, 공유 모델과 서비스, 배포 관련 사항을 서로 다른 패키지에 유지하세요. - 엔드포인트 오케스트레이션, 비즈니스 규칙, 영속화, 파싱, 정보 검색, 범용 유틸리티를 책임 범위가 명시된 모듈에 배치하고, 독립적으로 배포되는 SDK는 별도 제품으로 취급하세요. - 동작이 여러 패키지에 걸치면 먼저 공유 계약을 정의하고, 각 책임 주체의 구현을 테스트하세요. ## 업로드된 파일을 형식에 맞는 파서로 보내기 단계별 파이프라인을 사용하여 모든 문서가 업로드부터 인용 가능한 정보 검색 증거까지 눈에 보이는 경로를 따르도록 하세요. 1. 업로드를 수락하고, 작업을 생성하며, 소스 객체를 영속화한 뒤 비동기 처리를 대기열에 넣으세요. 2. 문서를 한 번만 프로파일링하고, 파일 형식과 구조적 증거에 따라 파서로 라우팅하세요. 3. 파서 출력을 하나의 타입 기반 테이블형 계약으로 변환하세요. 4. 행을 타입 기반 청크 레코드로 변환하세요. 5. 정보 검색 전에 문서, 섹션, 청크, 그래프 상태를 반영하세요. ### 파서 라우팅을 명시적으로 유지하기 - 모든 형식에 하나의 타입 기반 파서 진입점을 사용하고, 작업 범위 내의 산출물 경로를 반환하세요. - PDF, DOCX, PPTX, 스프레드시트, Markdown, 텍스트, 이미지, 원시 조각 입력을 형식별 전략으로 라우팅하고, 이전 사무용 파일 형식은 최신 파서에 전달하기 전에 변환하세요. - PDF에서는 개방형 의미 분류와 아틀라스, 스캔 문서, 슬라이드, 일반 문서처럼 라우팅에만 쓰는 분류를 구분하세요. - 대용량 문서는 진입점에서 구조 분석을 한 번만 실행하고, 그 결과인 샤드 계획을 후속 단계로 전달하세요. - 파싱 후 참조되지 않은 이미지를 제거하고 결정론적 이미지 압축을 적용하세요. ## 제목 계층을 찾고 변환 중 표와 이미지 보존하기 사용 가능한 가장 강력한 증거로 구조를 판단하고, 변환 중에도 표, 이미지, 제목 간 관계를 유지하세요. ### 증거의 우선순위에 따라 제목 정하기 1. 포함된 목차가 있으면 이를 정답 기준으로 사용하세요. 2. 명시적 번호 지정 패턴과 언어별 장 마커를 일치시키세요. 3. 해결되지 않은 제목 후보에만 LLM 계층 모델을 사용하세요. 4. 레이아웃 정보가 풍부한 PDF에서는 글꼴 기하 정보를 제한된 수의 제목 단계로 군집화하세요. ### 형식별 동작 보존하기 - 문단, 표, 이미지, 목차 영역을 포함한 DOCX 본문 요소를 소스 순서대로 순회하세요. - 새 제목이 상위 단계로 돌아갈 때 하위 항목을 닫는 제목 스택을 유지하세요. - 정확한 `rowspan`과 `colspan`을 사용해 표를 HTML로 변환하고, 지각 해시로 이미지 중복을 제거하세요. - 표준 PDF는 추출 및 Markdown 파싱 경로로 라우팅하고, 아틀라스형 문서나 대용량 문서는 각각의 전용 경로로 라우팅하세요. - 요약, 계층 인식, 이미지 설명, OCR, 거친 분류에는 서로 다른 모델 구성 키를 사용하세요. ## 청크, 탐색 정보, 매니페스트를 정해진 형식으로 저장하기 영속화된 코퍼스를 권위 있는 정본으로 취급하고, 중간 DataFrame은 일시적인 구현 세부 사항으로 간주하세요. ### 코퍼스와 문서 상태 저장하기 - 수집·적재된 문서별 디렉터리와 나란히 코퍼스 전체의 그래프 메타데이터와 정보 검색 적중 통계를 보관하세요. - 순서가 있는 청크, 계층형 탐색, 파싱 메타데이터, 전체 제목 트리, 보관된 소스 자산, 추출된 이미지와 표, 진단 출력을 영속화하세요. - 핵심 청크 타입은 정확히 세 가지만 사용하세요. `text`, `image`, `table`입니다. - 모든 청크에 결정론적 `chunk_id`, 타입 기반 콘텐츠, 계층 경로를 부여하고, 길이, 요약, 페이지 번호, 토큰, 키워드, 파일 경로, 청크 간 참조에 관한 메타데이터를 추가하세요. ### 참조와 탐색 보존하기 - 인라인 관계는 `connect_to` 항목으로 나타내고, 그 안에 `target`, `relation`, `ref`, 문자 오프셋인 `position`을 포함하세요. - 인라인 자산에는 `embeds`를 사용하고, 인라인이 아닌 연결에는 `related`를 사용하세요. - `doc_nav.json`을 요약, 청크 수, 하위 요소, 이미지 또는 표 리소스를 포함하는 섹션 트리로 구축하세요. - `manifest.json`을 구축하고, 소스 메타데이터, 통계, 중첩된 `HIERARCHY`를 포함하세요. - 임시 파서 행을 타입 기반 청크 페이로드로 변환한 뒤 `chunks.json`에 기록하세요. ## 데이터베이스 레코드, 검색 색인, 그래프 연결을 함께 반영하기 관계형 레코드, 검색 채널, 그래프 에지가 같은 청크 집합을 나타내도록 하나의 일관된 리비전을 반영하세요. ### 관계형 데이터의 책임 범위 유지하기 - 문서 수준에서 문서 식별 정보, 소유자, 네임스페이스, 상태, 활성 리비전, 소스 파일 이름을 저장하세요. - 상위 링크, 경로, 제목, 단계, 요약, 정렬 순서를 리비전을 인식하는 섹션 트리에 저장하세요. - 각 청크의 콘텐츠 해시, 청크 타입, 검색 가능 텍스트, 소스 경로, 자산 경로, 메타데이터, 정렬 순서를 저장하세요. - 그래프 노드의 범위를 문서 내부로 한정하고, 그래프 에지가 대칭적 관련성을 나타낼 때는 무방향으로 유지하세요. ### 고정된 순서로 반영하기 1. 결정론적 콘텐츠 해시를 기준으로 문서 간 청크 중복을 제거하세요. 2. 청크 경로에서 상위 섹션을 위에서 아래 순서로 구축하세요. 3. 모든 청크에 콘텐츠, 경로, 원시 용어 검색 채널을 각각 생성하세요. 4. 공유 키워드가 최소 3개이고 점수가 0.8 이상일 때만 문서 그래프 노드와 키워드 중첩 에지를 생성하세요. 콘텐츠 검색에는 토큰화된 콘텐츠와 요약을, 경로 검색에는 토큰화된 파일 이름과 섹션 경로를, 부분 문자열 검색에는 원시 콘텐츠와 경로를 사용하세요. ## 기존 순위 검색과 예산 상한이 있는 에이전트 검색 모두 제공하기 요청 구성, 어휘 검색, 하이드레이션, 그래프 접근, 적중 통계, 워크플로 실행, 탐색, 증거 렌더링을 책임 범위별로 분리하세요. ### 두 가지 정보 검색 모드 보존하기 - 기존 모드에서는 경로, 콘텐츠, 용어 채널을 역수 순위 융합으로 결합하세요. - 기본 채널 가중치는 `path=1.0`, `content=2.0`, `term=1.5`로 하고, `score = weight / (k + rank + 1)` 및 `k=60`을 사용하세요. - 에이전트형 모드에서는 플래너가 복잡한 쿼리를 정보 검색 단계의 DAG로 분해하게 하되, 정보 검색 내부에서 답변 합성 단계를 계획하지 마세요. - 전체 DAG에 하나의 토큰 예산을 강제하세요. 예산을 소진하면 안전하게 중단하고 그때까지 수집한 최선의 증거를 반환하세요. - 발견, 제약된 너비 우선 섹션 탐색, 증거 렌더링을 서로 다른 단계로 실행하세요. - `evidence_text`를 기본 응답으로 제공하고, 사용 중단 예정인 `answer_text`는 빈 호환 필드로만 유지하세요. ### 의도에 따라 하이드레이션하고 순위 매기기 - 열지 않은 섹션은 제목과 요약으로 구성된 개요로 렌더링하고, 선택한 말단에 대해서만 원시 `text`, `image`, `table` 청크를 하이드레이션하세요. - 연결된 자산을 네이티브 방식으로 해석하고, 취약한 문자열 치환 자리표시자를 사용하지 않은 채 인라인으로 포함하세요. - 에이전트 결과는 먼저 `agent_score`, 다음으로 `discovery_score`를 기준으로 순위를 매기고, `agent_score=0`인 행은 대체 집합으로 낮추세요. - 조립 전에 제외 대상 문서와 제외 대상 섹션을 걸러내고, 허용된 청크 타입만 남기세요. - `document_id`, `chunk_id`, `source_file_name`, `section_path`를 포함하는 인용 정보를 첨부하세요. ## 청크 ID를 안정적으로 유지하고 성공한 결과만 캐시하기 최적화로 정보 검색의 의미가 바뀌지 않도록 단축 경로, 식별자, 변경 순서, 텔레메트리를 명시하세요. ### 결과를 재현 가능하게 유지하기 - 이미지와 표 참조를 제외하고 텍스트 콘텐츠만의 안정적인 해시에서 청크 ID를 도출하여, 업로드 간 동일 콘텐츠의 중복을 제거하세요. - 먼저 DOM 변경을 계획한 다음 인덱스 이동을 피하도록 역순으로 적용하세요. - 캐시된 메타데이터를 재사용하면서 문서 안의 동일 이미지를 지각 해시로 중복 제거하세요. - 서로 다른 위치에 반복되는 이미지에는 결정론적이면서 고유한 ID를 부여하고, 인접한 텍스트 컨텍스트를 찾을 때 바이너리 식별자를 지나서 계속 탐색하세요. ### 단축 경로와 캐시에 상한 설정하기 - `total_chunks <= top_k`이면 명시적인 소규모 코퍼스 경로를 통해 모든 청크를 직접 반환하세요. - 사용자, 네임스페이스, 쿼리, `top_k`, 필터를 키로 캐시하고, 실행 전에 캐시 버전을 확인하며, 성공한 뒤에만 기록하세요. - 소스 콘텐츠를 변경하지 않고 순위 향상에 사용할 청크별 및 문서별 적중을 기록하세요. - 에이전트 작업, 입력, 출력, 지연 시간, 토큰 사용량에 관해 추가만 가능한 실행 및 단계 레코드를 유지하세요. ## LLM API의 특이점에 대응하고 완료 보고 전에 로컬에서 확인하기 오류를 계속 진단할 수 있도록 모델 제약과 로컬 검증 명령을 명시하세요. ### 모델 통합 강화하기 - `json`이라는 단어를 DeepSeek의 `json_object` 모드를 요청할 때 포함하세요. - 스트리밍 중에는 `delta.content`가 `None`이 아닐 때만 이어 붙이세요. - 각 토큰의 속도 제한 안에서 API 토큰을 순환시키고, 대기 시간을 적용하며, 다음으로 사용 가능한 토큰을 사용해 그 자리에서 재시도하세요. - 정보 검색은 증거만 제공하도록 유지하세요. 후속 에이전트가 증거의 충분성을 판단하고 정보 검색 서비스 외부에서 답변을 합성합니다. ### 시스템을 로컬에서 검증하기 - 버전이 고정된 워크스페이스에서 설치하고, 환경 템플릿을 로컬로 복사한 뒤 필요한 데이터베이스, 캐시, 객체 스토리지, API, 작업자 서비스를 시작하세요. - 파서, 프로파일러, 계층, 에이전트형 처리에 집중한 엔드투엔드 디버그 명령을 제공한 다음, API, 작업자, 공유 패키지 전반에서 린트, 안전한 자동 수정, 타입 검사를 실행하세요. - 상위 수준의 파이프라인 오류를 진단하기 전에 로컬 API 문서와 기반 서비스 엔드포인트를 확인하세요. - 영향을 받는 파서, 반영 경로, 정보 검색 모드, 품질 검사에서 직접적인 결과를 얻기 전에는 완료를 보고하지 마세요.