모든 모드가 동일한 I/O 계약을 공유한다. 모드 변경 시 호출부만 갈아끼우면 된다.
6.1 입력 포맷
인입 (Ingest)
| 형식 | 파서 | 비고 |
|---|---|---|
| 자체 구조 추출 파서 | 텍스트·표·이미지 추출 | |
| DOCX, XLSX | 자체 구조 추출 파서 | 오피스 변환 의존성 필요 |
| HWP, HWPX | 자체 파서 | OLE2 / ZIP-XML 기반 |
| CSV | 자체 파서 | UTF-8 / CP949 자동 감지, 500행 단위 청킹 |
| 외부 드라이브 | Google Drive 등 | 사용자 동의 토글 1회 연결 |
| 웹 자료 | 4단계 폴백 크롤링 | 가벼운 페이지는 가벼운 도구로, 막히는 페이지만 비용 큰 도구로 |
| 외부 운영 DB | MES / ERP / LIMS 커넥터 | B2B 라인 |
| Obsidian vault | 마크다운 양방향 동기화 | — |
파일 검증 — 사전 검증 단계에서 빈 파일 / 200MB 초과 / 포맷 불일치 / 손상 PDF / 암호 PDF / 인코딩 감지 실패 등을 차단한다.
검색 (Search) — 2.4 retriever 파라미터 참조.
6.2 출력 JSON 스키마 — retriever
본 절은 response_format="text" (기본) 의 응답 구조이다. response_format="json" 호출 시 content 필드 대신 entities / relationships / chunks / references 4섹션이 dict 로 분리되어 반환된다 (호스트 UI 가 섹션별 렌더링을 직접 제어하는 경우 권장).
{
"content": "# Knowledge Graph Data (Entity):\\n...\\n# Document Chunks:\\n...\\n# Reference Document List:\\n...",
"metadata": {
"references": [
{
"reference_id": "1",
"file_path": "document.pdf",
"page": 12
}
]
},
"score": [0.95, 0.87, 0.82],
"latency": 6.50
}응답 본문 구성
| 섹션 | 설명 |
|---|---|
| Knowledge Graph Data (Entity) | 관련 엔티티 (entity_id, type, description) |
| Knowledge Graph Data (Relationship) | 엔티티 간 관계 |
| Document Chunks | 관련 텍스트 청크. [reference_id] 인라인 시테이션으로 출처 참조 |
| Reference Document List | 출처 문서 목록 |
| 필드 | 의미 |
|---|---|
content | 검색 결과 본문 (엔티티·관계·청크·출처 목록을 마크다운 섹션으로 합성) |
metadata.references[] | 참조 문서 목록 (reference_id, file_path, page) — 호스트 측 원문 뷰어 점프에 사용 |
score[] | 청크 단위 재정렬 점수 — mode="deep" 호출 시 채워짐 |
latency | 검색 단계 지연 (초) |
6.3 근거·출처 활용
- 호스트 앱에서
metadata.references[].reference_id와 본문[1][2]인라인 시테이션을 매핑하여 근거 카드 UI를 만들 수 있다 metadata.references[].file_path와page는 도입사 원문 뷰어로 점프하는 딥링크 소스로 사용한다score[]가 비어있는 경우 청크 재정렬이 적용되지 않은 상태이며,mode="deep"으로 호출하면 청크별 재정렬 점수가 채워진다
6.4 데모 시연 스키마 ↔ 정식 응답 스키마 매핑 (참고)
별도 동봉된 모바일 데모는 시연 UI용 단축 스키마를 사용한다. 데모 코드와 정식 명세를 동시에 보는 경우의 키 매핑은 다음과 같다.
| 데모 단축 스키마 | 정식 응답 스키마 (6.2) | 비고 |
|---|---|---|
text | content (Knowledge Graph Data • Document Chunks 등 섹션을 합성한 마크다운) | 데모는 단일 문자열, 정식은 섹션 단위 마크다운 |
cites[] (인덱스 배열) | metadata.references[] (객체 배열) | 본문 [1][2] 인라인 인덱스는 양쪽 동일. 정식은 객체로 별도 노출 |
cites[].docId | metadata.references[].reference_id • metadata.references[].file_path | 데모는 짧은 ID. 정식은 논리 ID와 파일 경로를 분리해 노출 |
cites[].loc | metadata.references[].page | 페이지 단위 동일. 셀 좌표는 향후 확장 |
cites[].confidence (0~100) | score[] (청크 단위 0.0~1.0 재정렬 점수, mode="deep" 호출 시 채움) | 단위·위치 다름 — 데모는 시테이션별, 정식은 청크 배열 |
| (없음) | latency (검색 단계 지연, 초) | 정식 응답만 노출 |
데모 스키마는 시연 UI 단순화 목적이며, 운영 통합 시에는 6.2 정식 응답 스키마를 단일 기준으로 사용한다.