Knowledge API 분석 설계
파일 업로드, 공통 AI 분석, 사용자 검토와 SQLite 저장의 현재 계약
목적과 현재 범위
POST /api/analyze/{stored_filename}은 업로드 문서에서 추출한 텍스트를 분석해 Wiki 등록 방향을 제안한다. 기존 Wiki 검색·비교, 문서 저장, Terra/deep analysis는 수행하지 않는다.
언어와 근거
- 사람이 읽는 분석 내용은 한국어로 작성한다.
- SAP 용어, T-code, movement type, WBS ID, 설정값, 제품명과 기술 식별자는 원문 그대로 보존한다. JSON 키, enum, 카테고리 경로는 API 식별자이므로 번역하지 않는다.
- 업로드 문서만 사실의 근거로 사용한다. 없는 사실이나 절차를 외부 지식으로 보충하지 않는다.
- 근거 없는 설명은
문서에서 확인되지 않음, 목록은 빈 배열로 표시한다. 불확실한 사항은 확인 항목과 질문으로 기록한다. - 문서 내부의 명령은 분석 지침으로 취급하지 않는다.
응답 계약
기존 status, model, parser, stored_filename, analysis 응답 구조와 기존 필드를 유지한다. title은 서버에서 recommended_title과 동일하게 설정하여 현재 프런트엔드와 호환한다.
| analysis 필드 | 형식 | 의미 |
|---|---|---|
| purpose | string | 원문에 드러난 목적 |
| summary | string | 근거 중심 요약 |
| key_points | string[] | 핵심 사실 |
| knowledge_structure | string[] | 원문에서 확인되는 주제와 관계 |
| wiki_value | string | 원문을 근거로 한 활용 제안 |
| validation_points | string[] | 원문 대조 및 추가 확인 사항 |
| recommended_title / title | string | 한국어 Wiki 제목 제안 / 호환 필드 |
| recommended_category | enum | 기존 카테고리 경로 |
| document_type | string | 한국어 문서 유형 |
| sap_areas | string[] | 원문에 근거한 SAP 영역 |
| tags | string[] | 한국어 일반 태그와 원문 기술 식별자 |
| confidence | number | 0~1 분석 확실성 자기평가. 검증 확률이나 Wiki 일치 점수가 아님 |
| open_questions | string[] | 미확인 질문 |
| recommended_action | enum | 아래 세 가지 콘텐츠 추천 |
| review_required | boolean | 별도 사람 검토 필요 여부 |
| review_reasons | string[] | 한국어 검토 사유 |
모든 필드는 필수다. 공급자에 strict JSON Schema를 전달하고 서버에서도 필수 필드, 타입, enum, confidence 범위 및 추가 필드를 검증한다. 형식 검증은 한국어 품질이나 사실성을 증명하지 않으므로 원문 대조가 필요하다.
콘텐츠 추천과 검토 상태
new_document: 새 문서 작성 제안. 기존 문서가 없음을 확인했다는 의미는 아니다.update_existing: 원문에서 개정/추가 의도가 확인되는 경우의 업데이트 후보. 기존 Wiki의 존재나 일치를 확정하지 않는다. 서버는 항상review_required=true와 Wiki 비교 필요 사유를 보장한다.reference_only: 참고 자료로 보관 제안.
needs_review는 새 API 추천 값에서 제거한다. 어떤 추천에도 검토가 필요할 수 있다. 사유가 있으면 서버가 검토 상태를 true로 보정하고, 검토가 필요한데 사유가 비어 있으면 일반 검토 사유를 추가한다. 프런트엔드는 이전 응답의 needs_review도 한국어로 표시한다.
설정과 검증
ANALYSIS_MODEL 환경변수를 유지하며 기본값은 기존 gpt-5.6-luna다. OPENAI_API_KEY는 환경변수로 제공한다. 추가 분석 단계는 없다.
백엔드 디렉터리에서 python -m unittest discover -s tests -v로 계약과 API 흐름을 검증한다. 저장소 루트에서 npm run typecheck, npm run build를 실행한다. 모의 모델 응답 테스트는 실제 모델의 언어 준수, 식별자 보존, 사실성을 보장하지 않는다. 실제 문서로 별도 확인해야 한다.
자료 검토 화면과 콘텐츠 유형
업로드 → 분석 중 → 자료 검토의 모달 흐름을 유지한다. 검토 화면은 AI 원본 분석, 사용자 검토본, 검토 메타데이터로 구성한다. AI 원본 안에는 기본 정보, 문서 목적, 핵심 지식, Wiki 활용 제안, 검증 및 미결 사항을 표시한다. 지식 구조와 핵심 사항은 공백 차이만 있는 동일 항목을 중복 표시하지 않는다. 기술 식별자는 보존하며 태그는 최대 8개의 줄바꿈 가능한 칩으로 표시한다.
공통 분석 응답과 사용자의 ReviewDraft는 분리한다. 콘텐츠 유형의 기본값은 knowledge이며 검토 저장 시 SQLite에 영속화한다. 유형을 바꿔도 분석 내용은 재구성되지 않으며 추가 API 호출은 없다.
| 콘텐츠 유형 | 표시 | 향후 재구성 대상 |
|---|---|---|
knowledge | 지식 | 지식 전용 메타데이터 및 템플릿 스키마 |
meeting | 회의록 | 회의록 전용 메타데이터 및 템플릿 스키마 |
deliverable | 산출물 | 산출물 전용 메타데이터 및 템플릿 스키마 |
향후 흐름은 Original Source → AI Common Analysis → User Reviewed Common Content → Content Type Confirmation → Second AI Restructuring → Structured Knowledge → Wiki Markdown이다. 각 스키마의 상세 필드는 아직 확정하지 않았다. 재구성 결과는 원본 공통 분석과 별도로 관리하고, 재구성 후 유형이 변경되면 기존 결과를 무효화하는 처리가 필요하다. 현재 재구성 상태는 not_started만 사용한다.
최종 분류, 선택적 SAP 모듈, 최종 문서명, 처리 방식, 원본 보관 여부는 수정할 수 있다. 경로는 기본적으로 docs/분류/선택적 모듈/문서명.md 형식의 제안이며 사용자가 대상 경로 메타데이터를 편집할 수 있다. 저장된 경로는 다시 열 때 그대로 복원한다. 실제 경로 검증이나 파일 생성은 수행하지 않는다. 검토 대기 또는 검토 완료를 선택해 메타데이터 저장 버튼으로 저장한다. 저장 중 중복 제출을 막고 성공/오류 메시지를 표시한다. 모달을 다시 열면 source_id로 저장된 검토 값을 불러온다. 저장은 Wiki 파일 생성이 아니다.
SQLite 메타데이터 저장
Python 표준 sqlite3를 사용한다. KNOWLEDGE_DB_PATH의 기본값은 /app/data/knowledge.db이며 저장소 밖의 절대 경로를 사용한다. 최초 접근 시 디렉터리와 sources 테이블을 생성한다. SQL 값은 매개변수로 전달하며 연결마다 트랜잭션을 커밋하고 닫는다. 파일 바이너리와 OpenAI API 키는 DB에 저장하지 않는다.
스키마
| 필드 | SQLite 형식 / 기본값 | 의미 |
|---|---|---|
| source_id | TEXT PRIMARY KEY | 파일명과 독립적으로 생성한 UUID |
| original_filename | TEXT NOT NULL | 원본 파일명 |
| stored_filename | TEXT NOT NULL UNIQUE | /app/uploads 내부 파일명, 업로드당 유일 |
| file_extension | TEXT NOT NULL | 점을 포함한 소문자 확장자 |
| file_size_bytes | INTEGER NOT NULL | 원본 크기, 0 이상 |
| content_type | TEXT NOT NULL, knowledge | knowledge / meeting / deliverable |
| uploaded_at | TEXT NOT NULL | 최초 업로드 완료 시각 |
| analyzed_at | TEXT, NULL | 최초 성공한 분석 시각 |
| registered_at | TEXT, NULL | 최초 성공한 검토 저장 시각, 이후 유지 |
| updated_at | TEXT NOT NULL | 생성 또는 마지막 분석/검토 저장 시각 |
| recommended_title | TEXT, NULL | AI 추천 제목 |
| final_title | TEXT, NULL | 사용자 확인 제목 |
| recommended_category | TEXT, NULL | AI 추천 분류 원문 |
| domain / category / module | TEXT, NULL | 사용자 선택 계층 분류 |
| recommended_action | TEXT, NULL | AI 추천 처리 방식 |
| selected_action | TEXT, NULL | new_document / update_existing / reference_only |
| review_required | INTEGER NOT NULL, 1 | AI 검토 필요 여부, 0/1 |
| review_status | TEXT NOT NULL, review_pending | review_pending / reviewed |
| keep_original | INTEGER NOT NULL, 1 | 원본 보관 의사, 0/1 |
| target_wiki_path | TEXT, NULL | 향후 Wiki 대상 경로 메타데이터 |
| analysis_json | TEXT, NULL | 정규화·검증한 최초 AI 공통 분석 JSON (불변) |
| review_content_json | TEXT, NULL | 사용자 편집 공통 검토본 JSON; 미래 구조화 지식과 별개 |
시간은 모두 서버가 UTC ISO 8601 (Z)로 저장한다. 프런트엔드는 사용자의 현지 시간대로 표시한다. 등록 예정 브라우저 시계는 제거했다. 이전 백엔드와의 호환용 업로드/분석 임시 시각은 서버 시각이 없을 때만 표시하며 DB로 보내지 않는다.
생명주기와 API
논리적 흐름은 uploaded → analyzed → review_pending → reviewed다. review_status는 업로드부터 review_pending이며 분석 성공 후에도 유지된다. analyzed는 분석 API 성공 이벤트이고, 별도 DB 상태 enum은 아니다. source 읽기 응답의 status는 분석/검토 저장 전 uploaded, 이후 review_status다. 검토 대기 상태로도 저장할 수 있다.
POST /api/upload: 파일과 메타데이터를 저장하고 기존 응답에source_id,uploaded_at,updated_at을 추가한다. 기존 업로드 응답의content_type은 파일 MIME 유형이며, source 읽기 응답의content_type은 검토 콘텐츠 유형이다.POST /api/analyze/{stored_filename}: 동일 업로드 행을 갱신한다. 전체 분석, 추천 필드, 검토 필요 여부와 분석/수정 시각을 저장하고 응답에source_id,analyzed_at,updated_at을 추가한다. 이미 분석이 있으면 최초 저장된 분석을 반환하고 모델을 다시 호출하지 않는다 (model,parser는 null). 저장 계층도analysis_json IS NULL조건으로 최초 결과 덮어쓰기를 방지한다. 사용자 검토 값과 모든 날짜는 유지한다.GET /api/sources/{source_id}: 파일 메타데이터, UTC 날짜, 추천 및 검토 값, status를 반환한다.analysis_json은 파싱된analysis객체로 반환하며 미분석이면 null이다. boolean은 JSON boolean으로 반환한다.POST /api/sources/{source_id}/review:content_type,final_title,domain,category,module,selected_action,keep_original,target_wiki_path,review_status를 모두 받는다. 빈 분류 값은 초안 저장을 위해 허용한다. enum/타입 오류나 추가 필드는 422, 없는 source는 404다. 최초 저장 시 등록 시각을 설정하고 매번 수정 시각을 갱신한다. 반환 형식은 source 읽기와 같다.
기존에 메타데이터 없이 저장한 파일은 자동으로 스캔하거나 이관하지 않는다. 해당 파일 분석 요청은 404로 다시 업로드하도록 안내한다. uploads-test는 읽거나 처리하지 않는다.
원본, 분석, 검토, Wiki 문서의 구분
- 원본 파일:
/app/uploads에 저장한 바이너리.keep_original=false도 현재는 보관 의사 기록일 뿐 파일을 삭제하지 않는다. - 분석: 원본에서 AI가 제시한 구조화 정보와 추천. DB의
analysis_json으로 보존한다. - 검토 메타데이터: 사용자가 확인한 제목, 분류, 처리 방식과 보관 의사. AI 추천과 별도 필드에 저장한다.
- 향후 Wiki 문서: 아직 생성하지 않는다. 대상 경로는 메타데이터일 뿐 파일 시스템 쓰기에 사용하지 않는다. 실제 생성 단계에서 경로 검증이 필요하다.
메타데이터 저장 성공 문구는 검토 메타데이터가 저장되었습니다. Wiki 문서는 아직 생성되지 않았습니다.다.
Docker / OCI 영속 볼륨
Dockerfile은 /app/data를 준비하고 VOLUME으로 선언한다. 운영 재배포에서도 같은 DB를 사용하려면 OCI 호스트의 지속 디렉터리를 명시적으로 bind mount해야 한다. 저장소 밖의 OCI compose 파일은 수정하지 않았다. 다음은 사용할 호스트 경로를 /srv/subchi-wiki/knowledge-data로 정한 구체적 설정 예시이며 기존 OCI 경로를 확인한 사실은 아니다.
services:
knowledge-api:
environment:
KNOWLEDGE_DB_PATH: /app/data/knowledge.db
volumes:
- /srv/subchi-wiki/knowledge-data:/app/data
# 기존 /app/uploads 볼륨 매핑도 그대로 유지
호스트 디렉터리를 생성하고 컨테이너 실행 사용자에게 쓰기 권한을 부여한다. DB 파일 하나가 아닌 /app/data 디렉터리 전체를 마운트한다. /app/uploads 영속 볼륨은 원본 파일용이고 /app/data는 메타데이터용이므로 둘 다 유지해야 한다. 백업은 서비스 정지 후 복사하거나 SQLite 백업 기능을 사용한다. 개발 환경 예: KNOWLEDGE_DB_PATH=/tmp/subchi-wiki-data/knowledge.db (운영 영속 경로로 사용하지 않음).
검증과 다음 단계
백엔드 테스트는 임시 디렉터리의 실제 SQLite와 모의 OpenAI/Docling을 사용하며 업로드, 재분석, 검토 재저장, 새 연결에서 읽기, enum 검증, 오류 처리를 검증한다. 실행에는 런타임 의존성과 테스트용 httpx가 필요하다. 실제 모델 호출과 Docling 변환은 별도 운영 검증 대상이다.
다음 단계는 콘텐츠 유형별 스키마 및 두 번째 AI 재구성, 검증된 경로로 Wiki 문서 생성, 기존 Wiki 검색/비교 등이다. 현재 Wiki 생성, Git commit/push, Terra/deep analysis, 유형별 재구성, embeddings/vector DB는 구현하지 않는다.
자료 관리 관리
상단 내비게이션의 자료 관리 링크에서 /knowledge 화면으로 이동한다. 이 목록은 최초 검토 저장 여부와 관계없이 DB에 기록된 모든 업로드 자료를 포함한다. 미분석 자료에는 미분석을 표시한다.
GET /api/sources: 요약 객체 배열을 반환한다. 본문 분석, 저장 파일명, 바이너리는 목록에 포함하지 않는다.q: 원본 파일명, 최종 제목, 추천 제목의 부분 문자열 검색. SQLitelower기준으로 영문 대소문자를 구분하지 않으며%,_, 따옴표는 일반 문자로 처리한다.content_type:knowledge,meeting,deliverable중 하나.review_status:review_pending,reviewed중 하나. 위 두 enum의 잘못된 값은 422다.domain: 저장된 도메인과 정확히 일치하는 값. 조건은 모두 AND로 결합하며 생략하면 해당 조건을 적용하지 않는다.- 정렬은
updated_at DESC, source_id ASC다. 현재 페이지네이션 없이 전체 검색 결과를 반환한다.
화면에서 검색어, 콘텐츠 유형, 검토 상태, 도메인을 조합하고 초기화할 수 있다. 검색 입력은 250ms 지연하며 조건 변경 시 이전 요청을 취소한다. 로딩, 빈 목록, 검색 결과 없음, 오류 및 재시도를 표시한다. 날짜는 브라우저의 현지 시간대로 표시한다.
자료 제목을 선택하면 ID로 상세 정보를 조회하고 기존 자료 검토 폼을 사용한다. 저장된 사용자 검토 값을 복원하며, 미분석 자료에도 메타데이터 입력을 허용한다. 저장 성공 시 서버가 반환한 등록·수정 시각을 표시한다. 목록으로 돌아오면 현재 검색 조건으로 다시 조회하므로 수정 결과가 필터와 맞지 않으면 목록에서 제외될 수 있다. 상세 조회 실패 시 재시도할 수 있으며 검토 정보 로딩 실패 중에는 저장을 막는다. 편집 중 목록으로 이동하면 저장하지 않은 입력은 유지되지 않는다.
목록·필터·검색·재조회 테스트는 services/knowledge-api/tests/test_storage.py에 포함한다. 기존 테스트와 함께 별도로 준비한 Python 런타임에서 다음과 같이 실행할 수 있다. 테스트는 임시 디렉터리에 SQLite와 업로드를 만들고 OpenAI/Docling을 모의 처리한다. 운영 DB와 uploads-test는 사용하지 않는다.
cd services/knowledge-api
PYTHONDONTWRITEBYTECODE=1 /tmp/wiki-management-venv/bin/python -m unittest discover -s tests -v
위 경로는 이번 개발 검증용으로 준비한 런타임이며 운영 경로가 아니다. 필요한 테스트 의존성은 fastapi, python-multipart, openai, pydantic>=2,<3, httpx다. 실제 Docling 변환·모델 호출·운영 프록시 연결과 브라우저 상호작용은 이 모의 API 테스트의 검증 범위 밖이다.
프런트엔드 검토 모델 테스트는 Node.js 22.18 이상(이번 검증은 24.21.0)에서 node --test tests/knowledge-review.test.mjs로 실행한다. 저장한 사용자 값이 AI 제안보다 우선 복원되는지, 빈 값과 false가 유지되는지, 다른 도메인의 경로에 SAP 분류가 섞이지 않는지 검증한다. Node의 모듈 형식 자동 감지 경고는 테스트 실패가 아니며 이를 없애기 위해 프로젝트 모듈 설정을 변경하지 않는다.
사용자 검토본 계층과 전용 API
다음 다섯 계층을 분리한다.
- Original Source: 원본 업로드 파일. 기존 영속 볼륨을 유지한다.
- AI Common Analysis: 최초 AI 결과인
analysis_json. 사용자 편집과 메타데이터 저장으로 변경하지 않는다. - User Reviewed Content:
review_content_json에 저장하는 편집 가능한 공통 검토본. 구조화 지식이라고 부르지 않는다. - Future Structured Knowledge: 콘텐츠 유형 확정 후 두 번째 AI가 생성할 유형별 결과. 아직 미구현이며 검토본과 별도 저장 계층이 필요하다.
- Future Wiki Markdown: 향후 발행 가능한 Wiki 산출물. 아직 생성·발행하지 않는다.
GET /api/sources/{source_id}는 analysis와 review_content를 별도 객체로 반환한다. 검토본이 없으면 review_content: null이며 서버에서 두 객체를 병합하지 않는다. GET /api/sources는 둘 다 포함하지 않는 기존 경량 목록 계약을 유지한다.
POST /api/sources/{source_id}/content-review 요청은 다음 필드를 모두 받는다.
- 문자열:
purpose,summary,wiki_value - 문자열 배열:
key_points,knowledge_structure,validation_points,review_reasons,open_questions,tags(최대 8개)
빈 문자열과 빈 배열은 허용한다. 누락·잘못된 타입·추가 필드·태그 초과는 422, 존재하지 않는 ID는 404다. 저장 SQL은 review_content_json과 updated_at만 갱신한다. 응답은 source_id, review_content, updated_at, analyzed_at, registered_at이다. 메타데이터 API /review와 독립적이며 review_status나 최초 메타데이터 저장 시각은 자동 변경하지 않는다.
기존 DB는 연결 시 BEGIN IMMEDIATE로 마이그레이션을 직렬화하고 PRAGMA table_info(sources)를 확인한다. 열이 없을 때만 ALTER TABLE sources ADD COLUMN review_content_json TEXT를 실행한다. 테이블·DB 재생성, 행 삭제, 원본 파일 이동은 없다. 기존 행은 NULL로 유지된다. 운영 배포 전 기존 영속 볼륨 매핑과 백업을 확인해야 한다.
자료 검토 UX와 홈페이지 정보 구조
상세 화면은 접을 수 있는 AI 원본 분석, 편집 가능한 사용자 검토본, 기존 검토 메타데이터로 구분한다. AI 원본은 읽기 전용이며 “AI가 최초 분석한 결과이며 사용자 수정본과 별도로 보존됩니다.”를 표시한다. 검토본에는 “최종 Wiki 작성 전에 사용자가 내용을 검토하고 수정하는 영역입니다.”를 표시한다.
저장된 검토본이 있으면 빈 값까지 그대로 복원한다. 없으면 AI 분석의 복사본을 에디터 초깃값으로 사용하되 자동 저장하지 않는다. 목록은 항목별 편집·추가·삭제를 지원하며 순서, 중복, 식별자, 입력 문자열을 보존한다. 저장 시 빈 목록 행만 제외한다. 태그는 개별 입력으로 최대 8개를 추가할 수 있다. 기존 데이터가 8개를 초과하면 자동 삭제하지 않고 정리를 요청한다.
검토 내용 저장 성공 후 상세를 다시 조회하고 서버 수정 시각과 목록을 갱신한다. 저장 성공 문구는 “검토 내용이 저장되었습니다. AI 원본 분석은 변경되지 않았습니다. Wiki 문서는 아직 생성되지 않았습니다.”다. 재조회에 실패하면 저장 완료와 재조회 실패를 구분해서 표시한다. 검토 완료는 Wiki 문서 생성 완료를 의미하지 않습니다.
홈은 Wiki 정체성·소개 → Wiki 둘러보기 → SAP / Projects / Development / Notes 카테고리 → 바로가기 순서다. 가짜 최근 자료를 표시하지 않는다. 자료 수집은 상단의 작은 + 자료 추가 링크로 기존 업로드 모달을 열고, 자료 관리는 일반 내비게이션으로 /knowledge에 연결한다. 업로드·분석 자료를 발행된 Wiki 지식으로 표시하지 않는다. 전체 테마 교체나 UI 프레임워크 추가는 없다.
배포 시 변경된 FastAPI 서비스 knowledge-api와 Docusaurus 프런트엔드 서비스를 재빌드해야 한다. 이 저장소에는 OCI Compose가 없어 프런트엔드의 실제 서비스 키는 확인할 수 없다. Nginx Proxy Manager 설정 변경은 이 구현에 포함되지 않는다. 배포는 수행하지 않았다.
2026-09-24 자료 저장소와 지식 저장소 분리
이 절이 앞의 초기 milestone 설명 중 업로드→자동 AI 분석, + 자료 추가, 구조화 지식 전체 미구현 설명을 대체한다. 앞 절은 당시 계약과 설계 이력으로 보존한다. 기존 공통 분석·검토 API는 유지하며 자동 Wiki Markdown 발행은 여전히 미구현이다.
현재 흐름과 의미
자료 저장소는 Original File → 원본 보존 → Extracted Content → 최소 분류 → Repository Ready → 선택적 AI 분석 → 선택적 사용자 검토다. 실제로 추출이 성공하면 즉시 ready이며 분류가 실패해도 이 상태는 유지된다. 문서와 산출물을 보관하는 데 AI 호출은 필요하지 않다.
지식 저장소는 Manual/GPT/Meeting/Work Note → 직접 저장 또는 선택적 AI 보완 → 사용자 검토 → Knowledge Entry → 향후 Wiki 발행이다. AI 보완을 요청하면 원문을 먼저 지식 초안으로 저장한 뒤 별도 결과를 저장한다. GPT가 준비한 내용은 다시 AI를 거치지 않아도 된다. 지식은 파일 없이 생성할 수 있다.
- repository READY ≠ AI analyzed
- AI analyzed ≠ user reviewed
- user reviewed ≠ Wiki published
- 자료 검토 저장과 지식 entry 저장은 별개이며 원본 파일은 그대로 보존한다.
자료 데이터와 additive migration
sources의 기존 열·행·분석·검토는 유지한다. 연결 시 기존 마이그레이션 잠금 안에서 열 존재 여부를 검사해 다음 열만 추가한다. 테이블 재생성이나 데이터 삭제는 없다.
| 필드 | 의미 / 기본값 |
|---|---|
| ingestion_status | uploaded / extracting / ready / failed, 기본 uploaded |
| classification_status | pending / classifying / classified / failed / skipped, 기본 pending |
| analysis_status | not_requested / analyzing / analyzed / failed, 기본 not_requested |
| extracted_text, parser, extracted_at | 재사용 가능한 추출 본문과 파서·완료 시각 |
| classification_json | 규칙 기반 최소 분류 제안과 방법·주의사항 |
| tags_json | 자료 메타데이터 태그, 기본 빈 배열 |
| processing_error, classification_error, analysis_error | 내부 예외·비밀값을 노출하지 않는 오류 안내 |
| processing_attempts | 최초 처리 포함 요청 횟수 |
| processing_started_at, processing_finished_at, classified_at, analysis_started_at | 독립 처리의 시각 |
기존 행에 분석이 있으면 API는 analysis_status=analyzed로 해석한다. 기존 행의 추출 여부를 추측하지 않으며 본문이 없으면 자료 관리에서 처리 재시도한다. 기존 status 필드는 하위 호환용으로 남고 새 UI는 세 독립 상태를 사용한다. 분석 원본과 검토본은 각각 analysis_json, review_content_json을 유지한다. 최초 분석을 다시 요청해도 저장된 결과를 반환하며 모델을 다시 호출하지 않는다.
BackgroundTasks와 재시도
업로드는 원본 파일과 메타데이터를 저장하고 작업을 예약한 뒤 응답한다. 응답은 기존 200/파일명/source_id 계약을 유지한다. 추출·분류는 FastAPI BackgroundTasks의 동기 작업으로 응답 이후 진행한다. 업로드마다 깊은 AI 분석을 수행하지 않는다. SQLite 조건부 UPDATE가 중복 예약을 막고 프로세스 내 잠금으로 Docling 작업을 직렬화한다.
이 구현은 기존 Docker CMD의 단일 Uvicorn 프로세스 전제다. 영속 큐가 아니므로 재시작 후 자동 재개하지 않는다. 시작 시 unfinished 처리와 analyzing 상태를 실패로 표시하여 사용자가 재시도하게 한다. 추출 본문이 이미 있으면 보존하고 재분류만 수행한다. 작업 상태·시각은 DB에 남아 브라우저를 닫아도 조회할 수 있다. 자료 목록은 진행 중 작업이 있으면 5초마다 재조회한다. 상세는 편집 내용 보호를 위해 자동으로 폼을 교체하지 않고 새로고침을 제공한다.
프로세스가 살아 있으나 파서가 멈춘 경우 강제 취소/시간 제한 기능은 없다. 여러 worker/인스턴스로 확장하기 전에는 DB lease·작업 소유권·복구 정책을 별도 설계해야 한다. 브로커·Redis·Celery는 추가하지 않았다. 명시적 AI 분석/텍스트 보완은 동기 요청이며 추가 시간이 걸릴 수 있다. AI 분석 상태는 자료에 저장된다. 텍스트 보완 실패는 기존 저장 내용을 바꾸지 않으며 다시 요청할 수 있다.
최소 분류
AI를 사용하지 않는 rules_v1이다. 파일명과 추출 본문의 앞 12,000자에서 명시적인 SAP 및 MM/CO/PP/FI/SD/PS/AA 식별자를 확인한다. 한 모듈만 확인되면 모듈 제안, 여러 모듈이면 태그만 제안한다. 미확정 domain/category/module은 빈 값으로 남긴다. document_type은 일반 자료, 제목은 원본 파일명이다. SAP 식별자만 있는 다른 문맥도 있으므로 사용자가 확인해야 하는 제안으로 표시한다. 긴 해석, 의사결정 분석, 교차 문서 추론은 하지 않는다. 모델 설정이나 추가 비밀값이 필요 없다.
분류 실패는 추출 성공을 취소하지 않는다. 재분류는 저장된 검토 메타데이터와 사용자가 저장한 태그를 덮어쓰지 않는다. 자료 유형·도메인·분류·모듈·태그는 기존 검토 폼에서 수정한다.
자료 API와 화면
| API | 동작 |
|---|---|
POST /api/upload | 파일 저장 + background 추출/분류 예약. 한 요청당 파일 하나; UI의 복수 선택은 순차 요청 |
GET /api/sources | 기존 필터 + category/module/tag/ingestion_status/classification_status/analysis_status |
GET /api/sources/{source_id} | 원본 메타데이터, 추출 본문, 분류, AI 원본과 검토본 |
POST /api/sources/{source_id}/retry | 202 예약, 이미 처리 중이면 409. 추출 본문 재사용 |
GET /api/sources/{source_id}/original | attachment로 원본 다운로드 |
GET /api/parse/{stored_filename} | 저장된 추출이 있으면 재사용, 없으면 기존 직접 파싱 호환 동작 |
POST /api/analyze/{stored_filename} | 명시적 공통 AI 분석. 추출 미완료는 409; 저장된 분석은 그대로 반환 |
POST /api/sources/{source_id}/review | 기존 메타데이터 계약 + 선택적 tags (최대 8개); 미전송 시 기존 태그 유지 |
POST /api/sources/{source_id}/content-review | 기존 계약 그대로. AI 원본 수정 금지 |
목록 q는 파일명·제목·저장된 추출 본문을 문자 검색한다. 태그는 정확 일치, 조건은 AND다. 목록 응답에는 본문·analysis·review_content·분류 JSON을 넣지 않는다. 페이지네이션/FTS는 아직 없으며 현재 소규모 자료를 위한 SQLite 검색이다. 원본 파일을 매 검색 때 다시 열지 않는다.
/knowledge는 반응형 자료 카드 목록과 제한된 파일 업로드를 제공한다. 상세는 원본 자료 / 추출 내용 / 분류 정보 / AI 분석 / 사용자 검토 / 지식으로 만들기로 구분한다. /?add-source=1은 /knowledge?upload=1로 클라이언트 이동한다. /knowledge?source=ID는 재열기 가능한 상세 URL이다. 기존 Wiki·홈·SAP·개발·인프라·검색·tools URL은 유지한다.
지식 모델과 미래 trusted-client API
별도 knowledge_entries 테이블을 CREATE TABLE IF NOT EXISTS로 추가한다. sources를 텍스트 입력용으로 재사용하지 않는다.
- entry_id, title, content: 지식 ID·제목·편집 가능한 현재 본문
- original_text: 최초 저장한 원문. 업데이트 API에 노출하지 않아 사용자 편집·AI 보완으로 변경되지 않는다.
- knowledge_type: knowledge / meeting / work_note / gpt_summary / decision / other
- origin_type: manual / gpt / meeting / work_note / repository_source
- source_id: 자료 기반 지식의 출처 참조. 자료 기반일 때 필수이며 존재 여부 확인; 다른 origin에는 허용하지 않는다.
- domain/category/module/tags_json: 지식의 자체 분류
- refinement_json: 최초 AI 보완 결과. 원문·편집 본문과 별도 보존, 반복 요청은 재사용
- review_status: review_pending / reviewed; created_at, updated_at
| API | 계약 |
|---|---|
POST /api/knowledge-entries | title/content 필수, knowledge_type/origin_type 및 source_id, domain/category/module/tags. 201 반환 |
GET /api/knowledge-entries | 본문 없는 지식 목록 |
GET /api/knowledge-entries/{entry_id} | 최초 원문·현재 본문·AI 제안·출처·검토 상태 |
PUT /api/knowledge-entries/{entry_id} | title/content 필수, domain/category/module/tags/review_status 갱신. origin/type/source/original/refinement는 변경 불가 |
POST /api/knowledge-entries/{entry_id}/refine | 기존 OpenAI client/config와 공통 분석 계약으로 original_text를 분석. 결과 별도 저장 |
제목은 1500자, 본문은 1500,000자이며 공백뿐인 입력은 거절한다. 원문 공백과 기술 식별자는 그대로 보존한다. 태그는 최대 8개다. 잘못된 타입·추가 필드·출처 조합은 422, 없는 ID는 404다. PUT은 부분 PATCH가 아니라 편집 필드 전체 저장 계약이다. 현재 동시 편집은 마지막 저장 우선이다.
/knowledge-add에서 유형·제목·본문·분류·태그를 입력하고 AI 없이 저장한다. AI 보완을 원하면 원문 저장 후 제안이 표시된다. 제안을 필요한 만큼 복사하여 본문에 반영하고 검토 상태를 저장한다. /knowledge-entries에서 저장한 지식을 재열고 편집한다. 자료 기반 생성은 저장된 사용자 검토본을 우선 초깃값으로 사용하고 없으면 추출 본문을 사용한다. 원본 source_id를 유지하며 사용자가 저장하기 전 자동 생성하지 않는다.
향후 ChatGPT 등 신뢰된 클라이언트는 위 POST/PUT 계약을 그대로 사용할 수 있다. 예: { "title": "업무 정리", "content": "사용자가 확인한 내용", "knowledge_type": "gpt_summary", "origin_type": "gpt", "tags": [] }. 이번에는 외부 connector/plugin이나 인증 변경을 구현하지 않는다. 현재의 인증/프록시 경계를 그대로 따른다.
미래 검색·교차 영역 synthesis (미구현)
자료 저장소의 원본 근거 + 지식 저장소의 검토 지식 → 관련 자료 검색 → 관련 구절 선택 → 근거와 추론 구분 → 교차 영역 reasoning → 새 지식 초안을 향후 목표로 둔다. MM의 결정 근거, CO의 합의, PP의 후속 행동을 묶는 질문은 현재 키워드 검색으로 해결된 것으로 표시하지 않는다.
매 질의마다 모든 원본을 다시 파싱하지 않는다. 오늘 저장한 extracted_text·분류·메타데이터·AI 분석·검토본·entry 출처를 재사용한다. 향후 검색 단계가 관련 자료의 부분 집합과 근거 구절을 선택한 뒤에만 추론한다. 구절의 안정적인 위치/버전 참조, 출처 연결, 근거/추론 표시, 새 결과의 사용자 검토가 후속 설계 대상이다. 벡터 DB·임베딩·RAG·agentic synthesis는 이번에 구현하지 않았다.
제한과 실제 환경 검증
텍스트/Markdown/CSV는 직접 파싱, 기존 문서 형식은 Docling을 유지한다. PNG/JPG는 기존 업로드 허용을 유지하지만 현재 파싱 미지원이므로 원본은 보존되고 추출 실패가 표시된다. 빈 추출 결과도 실패로 표시한다. 파일 크기 제한/페이지네이션/작업 취소/분석 버전 이력은 미구현이다.
실제 Docling의 PDF/Word/Excel 처리, 실제 OpenAI 품질·비용·timeout, 운영 프록시·인증·볼륨·재시작은 별도 비운영 환경에서 확인해야 한다. 이번 로컬 검증은 임시 SQLite와 모의 외부 서비스만 사용한다. 운영 DB·업로드는 변경하지 않았고 커밋·푸시·OCI 배포도 수행하지 않았다.
2026-09-24 AI 검색 Phase 1: 색인·검색·근거 기반 추론
이 절은 앞의 미래 검색·교차 영역 synthesis (미구현) 중 백엔드 색인/검색/추론 상태를 갱신한다. 기존 계층과 API는 유지한다. /search의 공개 Wiki 카탈로그 검색, 자료 목록 검색, 자료 AI 분석은 각각 그대로 동작한다. 이번에는 최종 검색 UI, AI 결과의 지식 저장 UI, 발행, 배포를 구현하지 않았다.
- 일반 검색 != AI 검색: 일반 검색은 관련 구절과 출처를 반환하고 AI 검색은 선택한 근거를 비교하여 설명한다.
- AI 분석 != AI 검색: 최초 자료 분석은 한 자료의 별도 저장 결과다. AI 검색은 여러 자료/지식의 선택된 구절을 일회성으로 사용한다.
- AI 검색 != Wiki 발행: 추론 결과는 ephemeral이며 knowledge entry나 Markdown으로 자동 저장하지 않는다.
flowchart TD
A[자료 저장소] --> B[저장된 extracted content / analysis / review]
K[지식 저장소] --> L[original / curated content / refinement]
B --> C[계층별 searchable chunks + SQLite FTS5]
L --> C
Q[질문] --> P[규칙 기반 query interpretation]
P --> R[metadata filter + retrieval + ranking]
C --> R
R --> E[중복 참조 보존 + evidence bundle + 예산]
E --> AI[근거 한정 AI reasoning]
AI --> O[답변 + provenance + 부족/충돌 표시]
실제 조사와 호환성
storage.py의 sources/knowledge_entries DDL·additive migration, processing.py의 추출/분류, main의 분석/보완 호출, 기존 tests와 화면을 기준으로 구현했다. 운영 SQLite 파일/OCI 스키마를 열어 확인한 것은 아니다. 임시 SQLite에서 기존 구형 테이블의 migration과 legacy uploaded/pending/analyzed 조합을 검증한다.
기존 자료가 추출 본문 없이 analysis/review만 가지고 있어도 해당 계층과 메타데이터를 색인한다. 추출 유무는 extraction_available로 표시한다. 원본 바이너리를 bootstrap/검색에서 다시 파싱하지 않는다. original_text/content, analysis_json/review_content_json을 병합하거나 덮어쓰지 않는다.
Additive schema와 상태
기존 migration의 BEGIN IMMEDIATE 안에 다음을 추가한다. sources/knowledge_entries에 새 열을 요구하지 않으며 기존 행은 색인을 만들기 전에도 읽을 수 있다.
| 객체 | 역할 |
|---|---|
search_objects | object_type/object_id 복합 키, revision/indexed_revision, pending/indexed/failed/stale, 현재 generation, 청킹 설정 signature, 추출 유무, 생성/수정/색인 시각, 안전한 error_code |
search_chunks | generation별 불변 구절과 provenance. 같은 객체/계층/section/order/generation은 유일 |
search_chunks_fts | 가능할 때 생성하는 FTS5 unicode61: chunk_id, title, text, search_metadata |
| 네 개의 source/entry INSERT/UPDATE triggers | 검색 대상 열이 변경될 때만 revision 증가와 pending/stale 기록 |
chunk에는 unique chunk_id, object_type (repository_source/knowledge_entry), object_id, source_id/knowledge_entry_id, origin_layer, title/text, chunk_order, section과 문자 offsets, domain/category/module/tags, knowledge_type/origin_type, source_date/date_kind, source_updated_at, content_hash, created_at/updated_at/indexed_at을 보존한다. section은 JSON 필드·배열 항목 또는 body/metadata다. offsets는 해당 section 문자열의 Python 문자 인덱스이며 PDF 페이지 번호가 아니다.
자료 계층은 metadata, extracted_text, analysis, review_content; 지식 계층은 metadata, knowledge_original, knowledge_content, knowledge_refinement다. 구조화 JSON은 알려진 콘텐츠 필드만 색인한다. 내부 처리 오류, 업로드 저장 경로, API 키 등은 검색 대상으로 복사하지 않는다.
기존 chunk나 FTS 행도 삭제하지 않는다. 현재 generation + indexed revision만 검색하여 중복 활성 구절을 방지한다. 과거 generation의 보관 용량과 BM25 통계 영향은 제한 사항이다. 향후 보관/정리 정책은 별도 승인·설계 대상이다.
청킹과 증분 갱신
기본 1,800자로 문단 경계 → 문장/줄 경계 → 공백 순으로 분할하며 원문의 부분 문자열과 offset/hash를 보존한다. 공백 없는 긴 식별자는 강제로 자르지 않는다. 전체 근거 예산을 넘는 구절은 제외하고 경고한다. 구조화 결과는 필드/목록 항목별로 분리한다.
source 생성·추출 저장·분류 메타데이터 변경·최초 분석·검토본·검토 메타데이터 저장과 entry 생성·수정·refinement 저장 후 해당 객체만 동기 색인한다. 원본 저장 transaction이 먼저 commit된다. indexing 실패는 원본 저장을 취소하지 않는다. 처리 상태만 바뀐 경우는 검색 revision을 바꾸지 않는다. 직접 SQL 콘텐츠 변경은 trigger가 stale로 표시하며 다음 명시 bootstrap에서 복구한다.
색인 build는 transaction/savepoint 안에서 수행한다. 성공하면 generation 포인터를 교체하고 실패하면 부분 chunk/FTS 삽입을 rollback하고 index_build_failed를 기록한다. 연결 자체 실패는 이미 저장된 pending/stale 상태를 남기고 비밀값 없는 일반 로그만 남긴다. 중단/실패/설정 변경은 bootstrap으로 복구한다. 검색은 stale/failed/설정 불일치 구절을 제외하고 불완전한 색인임을 반환한다.
관리용 bootstrap/reindex
자동 전체 startup rebuild는 없다. HTTP 관리 endpoint도 노출하지 않는다. 배포 후 기존 영속 DB가 올바르게 연결된 API 런타임에서 명시 실행한다. 아래 명령은 절차이며 이 개발 실행에서 운영 DB에는 실행하지 않았다.
# services/knowledge-api 또는 API 컨테이너 /app에서, 기존 KNOWLEDGE_DB_PATH 사용
python -m search_index
# 특정 객체만 재시도
python -m search_index --object-type repository_source --object-id SOURCE_ID
python -m search_index --object-type knowledge_entry --object-id ENTRY_ID
# 이미 최신인 객체도 새 generation을 추가하는 명시적 재색인
python -m search_index --force --object-type repository_source --object-id SOURCE_ID
100개 ID 단위로 열거한다. 기본 실행은 최신 indexed 객체를 skip하고 missing/pending/stale/failed/청킹 signature 불일치를 처리한다. 소스·지식 본문은 수정하지 않는다. 반복 실행에 활성 chunk 중복은 없다. indexed/skipped/failures를 JSON으로 반환하고 실패가 있으면 exit 1이다. 존재하지 않는 명시 ID도 failures에 포함한다. 전체 목록의 단일시점 스냅샷은 아니므로 동시에 들어오는 새 자료는 다음 실행에서도 확인할 수 있다.
일반 검색 서비스와 최소 API
retrieval.retrieve(SearchRequest)는 HTTP와 분리되어 있다. POST /api/search/retrieve는 다음 JSON을 받는다.
{
"query": "MM에서는 왜 이 방식으로 결정했고 CO는 어떤 조건으로 합의했어?",
"scope": "both",
"domain": "SAP",
"limit": 20
}
선택 필터는 domain/category/module 정확 일치, object_type, scope (both/repository/knowledge), source_type (knowledge/meeting/deliverable, 자료의 content_type), knowledge_type이다. source_type과 knowledge_type은 각각 해당 객체에만 적용되며 서로 모순된 필터는 빈 결과다. 자유 분류 문자열은 기존 데이터와 동일하게 취급하고 enum/추가 필드/빈 질의/범위 밖 limit는 422로 거절한다.
질의 해석은 한국어 조사가 붙은 MM/CO/PP 등 모듈, 주제어, 결정/이유·합의/조건·영향/결과·변경 의도를 추출한다. ISO 날짜 언급은 계획에 남기되 자동으로 업로드 날짜 필터로 바꾸지 않는다. 질문에 포함된 모듈은 검색 확장/다양성 단서이며 강제 AND 필터가 아니다. 사용자 module 필터만 정확 제약이다. AI 질의 해석 호출은 없다.
FTS5는 title/text/tags 및 분류 metadata를 검색한다. MATCH 토큰은 인용·이스케이프한 prefix 검색이며 SQL 값은 모두 parameterized다. 후보 안에서 BM25, 실제 구절/주제 일치, 의도 개념, 계층 가중치를 결합한다. 검토본 > 편집 지식 > 공통 AI 분석 > 추출 원문 > 메타데이터를 선호하되 낮은 계층도 유지한다. 최초 지식 원문과 refinement도 독립 근거다. 계층 선호는 진실성 인증이 아니다.
후보 LIMIT 이전에 객체별 순위를 교차 배치하고, 여러 모듈 질의에는 후보 슬롯을 나누어 다양성을 확보한다. 기본 검색이 비면 결정/합의 등 intent 개념으로 확장하며 주제 관련성 확인 경고를 반환한다. 정확한 공백 정규화 중복은 우선 계층 하나를 선택하고 다른 chunk provenance를 duplicate_references에 남긴다. 대소문자·숫자·부정 표현 차이는 병합하지 않는다. 단어 집합이 매우 비슷한 구절은 점수를 낮추지만 제거하지 않는다.
FTS5 미지원은 SQLite 부분 문자열 fallback을 사용한다. FTS 조회 오류도 동일 fallback과 경고로 처리한다. fallback까지 실패하면 안전한 503이다. FTS 없이도 메타데이터 필터·다양성·예산은 유지되지만 전체 문자 검색의 성능/한국어 형태소 처리는 제한적이다. 현재 SQL은 SQLite 3.35 이상(CTE materialization/window support)을 전제로 하며 배포 런타임에서 확인해야 한다.
Evidence bundle과 예산
응답은 query_plan, evidence, evidence_quality, warnings, index_status, retrieval_mode, evidence_chars, candidate_count, source_count다. 각 evidence에는 E1 같은 요청 내 ID, chunk ID/hash와 위치, 객체/원본 참조, title/domain/category/module/tags, origin_layer, passage, 저장 시각과 date_kind, rank/검색 점수, navigation_ref, duplicate_references, 추출 유무가 있다. 검색 점수는 확률/확신도가 아니다. navigation_ref는 /knowledge?source=ID 또는 /knowledge-add?entry=ID이며 임의 서버 경로를 노출하지 않는다.
모든 설정은 search_config.py에 집중되어 있고 SEARCH_ + 대문자 필드명 환경변수로 덮어쓸 수 있다.
| 설정 | 기본값 |
|---|---|
| CHUNK_CHARS | 1800 |
| MAX_CANDIDATES | 160 |
| MAX_CHUNKS_PER_SOURCE | 4 |
| MAX_EVIDENCE_CHUNKS | 20 |
| MAX_EVIDENCE_CHARS | 30000 |
| MAX_SOURCES | 10 |
| MAX_QUERY_CHARS | 2000 |
| MAX_QUERY_TERMS | 24 |
| MAX_CONTEXT_CHARS | 60000 |
| MODEL_TIMEOUT_SECONDS | 90 |
| MAX_OUTPUT_TOKENS | 6000 |
문자 예산은 tokenizer의 정확한 token 수가 아니다. 최대 전체 context는 질문·계획·근거의 JSON 크기도 검사한다. request limit는 1~100이며 서버 근거 제한이 우선한다. 출처 수 제한은 선택된 주 evidence 객체 기준이고 duplicate_references는 병합 전 provenance를 추가 보존한다. 과대 context는 모델 호출 전 거절하며 임의로 잘라 사실을 변경하지 않는다.
AI reasoning 계약
reasoning.reason(question, plan, bundle)는 이미 구성된 bundle만 받는다. DB, 파일, 원본 파서, 다른 검색 서비스를 호출하지 않는다. POST /api/search/reason은 동일 SearchRequest로 retrieval 후 reason을 호출하고 {answer, retrieval, persisted:false}를 반환한다. 일반 검색 오류와 AI 오류를 구분하며 AI 설정 없음 503, timeout 504, 모델 실패/잘못된 응답 502, 예산 초과 422를 반환한다. 근거가 없거나 제목/메타데이터뿐이면 모델 호출 없이 insufficient 결과를 반환한다.
기존 OpenAI SDK Responses API와 OPENAI_API_KEY, ANALYSIS_MODEL(기존 기본값 gpt-5.6-luna)을 재사용한다. timeout 90초, 자동 retry 0, 출력 한도, strict JSON Schema를 설정하고 store=false로 요청한다. 기존 한 자료 분석의 설정·결과는 바꾸지 않는다. 질문·구절은 지시가 아닌 데이터로 전달하며 tools/file access를 주지 않는다. prompt/chain-of-thought를 API 결과나 DB에 저장하지 않는다.
| 결과 | 계약 |
|---|---|
| summary | 근거 붙은 findings/relationships를 요약 |
| findings | statement, evidence_ids, type |
| relationships | finding 필드 + from_module/to_module, decision/rationale/agreement/condition/dependency/outcome/change |
| type | confirmed / inferred / conflicting / unknown |
| unresolved_issues | 누락 근거·추가 확인 사항 |
| evidence_references | 유효한 실제 인용 ID 집합 |
| evidence_quality | strong / partial / insufficient / conflicting |
| warnings | retrieval 및 reasoning 주의사항 |
서버는 실제 bundle에 없는 인용 ID, 근거 없는 confirmed/inferred, 양쪽 구절이 없는 conflicting을 거절한다. AI 계층만 근거로 한 confirmed는 inferred로 낮춘다. 충돌 finding은 전체 품질을 conflicting으로 만든다. 근거 부족, 누락, 해석, 단일 독립 출처는 strong으로 부풀리지 않는다. 자료와 그 자료에서 만든 지식은 같은 독립 출처로 센다. 초기 retrieval quality는 부분 근거 또는 부족만 표시하고 의미적 직접 지지는 reasoning에서 평가한다.
검토/원문 계층의 진술도 실제 사건의 독립 검증은 아니다. 모델은 사건 시각이 명시된 구절만으로 선후를 설명해야 한다. uploaded_at/created_at/source_updated_at는 저장 시각이지 결정일이 아니다. early A/later B를 모두 보이고 변경 이유가 없으면 없다고 말해야 한다. PP 근거 누락은 warning과 unresolved_issues에 남긴다. JSON/인용 검증만으로 의미적 진실성이나 모델의 모든 규칙 준수를 보장하지는 않는다.
제한과 다음 frontend/API 단계
한국어 형태소 분석·동의어·semantic retrieval/embeddings는 없다. 규칙 해석, prefix/문자 검색 및 제한된 후보는 관련 근거를 놓칠 수 있다. 최대 예산으로 모든 충돌을 발견한다는 보장은 없다. 사건 날짜 전용 구조, PDF page mapping, 고급 reranker, 색인 worker/lease, 증분 색인 비동기 큐, 세밀한 인증/권한·rate limit는 후속 설계다. 현재 신규 API는 기존 API와 같은 인증/프록시 경계에 있다. bootstrap은 관리 CLI로만 실행한다.
다음 단계는 일반 검색/AI 검색 탭, 필터와 로딩/오류/취소 UX, 근거 구절·계층·출처/날짜 설명, fact/inference/conflict 표시, 누락/색인 경고 표시, 명시적 검토 후 “지식으로 저장” 계약·UI다. 먼저 비운영의 실제 한국어 MM/CO/PP 문서로 검색 재현율과 추론 품질을 평가하고 사용자 검토 기준을 정한다. API versioning·인증·요청 제한도 노출 범위에 맞게 확정한다.
이 변경을 운영에 적용할 때는 knowledge-api 서비스 재빌드가 필요하다. 변경된 Wiki 설계 문서를 공개하려면 Docusaurus 프런트엔드 빌드도 필요하다. 실제 OCI frontend 서비스 키/Compose는 확인하지 않았다. Nginx Proxy Manager 변경 필요성을 가정하지 않으며 이번에는 OCI 배포·Docker rebuild·commit/push를 수행하지 않는다.
AI Search Phase 1.5: retrieval 품질 보완
2026-09-27. 기존 SQLite/FTS5/API/identity/provenance를 유지하고 stopword, relevance cutoff, coverage 확장만 추가했다. schema/index signature 변경이나 migration은 필요 없다. /search UI 및 upload/extraction/classification/analysis 저장 흐름은 변경하지 않는다.
Stopword와 QueryPlan
원본 SearchRequest.query와 reasoning 질문은 그대로 유지한다. 검색 terms에만 한국어 일반 질문 표현과 영어 관사·전치사를 제거한다. 정확한 stopword 검사 후 제한된 한국어 조사 제거를 적용한다. 각각 같은 coverage 표현은 원문에서 감지하고 검색 term에서는 제외한다. 토큰 내부 -, /, .를 보존하고 module 추출 때문에 토큰을 분해하지 않아 FI-AA/GR/IR/Go/No-Go/WBS/PO/CIP/CJ30/CJ88/101/313 및 한 자리 숫자를 유지한다. 기존 최대 term 수 제한은 적용된다. 형태소 분석기나 새 dependency는 없다.
QueryPlan에 기본값 focused인 coverage_mode를 additive로 추가했다. focused / broad_object / cross_object 중 하나이며 coverage일 때 intents에도 coverage를 추가한다. 전체·각각·all·whole 등의 표현과 작업/목록/요약 표현이 함께 있어야 확장한다. 복수 module이나 여러 문서 표현이면 cross_object다. full outer join 같은 표현은 coverage가 아니다.
Relevance cutoff
기존 점수식(term 일치 3점 + 본문 일치 2점 + intent/계층/BM25 보정)을 유지한다. max(min_relevance_score, top_score * relative_score_ratio) 이상만 dedup/evidence 선택에 전달한다. limit를 채우려고 탈락한 후보를 추가하지 않는다. 모두 절대 기준 미달이면 최상위 1개를 남길 수 있지만 insufficient와 weak_top_match warning을 사용하고 coverage는 확장하지 않는다. 문자 예산을 넘는 passage까지 강제로 보존하지 않는다.
58/51/6/4 점수 fixture에서는 58/51만 유지하며, 단일 5점 결과는 보존한다. Q1 합성 fixture의 최상위 점수는 43.0으로 Storage만 겹치는 투자 문서는 제외됐다. 운영 corpus에서 측정한 값은 아니다. source_count는 최종 주 evidence 객체 수, index_status는 기존 전체 색인 상태, candidate_count는 확장 전 lexical 후보 수다.
Object expansion과 예산
cutoff 통과 후보에서 object를 선정한다. broad_object에서 최상위 점수가 다음 객체의 2배 이상이면 한 객체를 선택하며, 불명확하면 제한된 객체에 분배한다. cross_object는 요청 module 다양성을 우선한다. 선택한 객체 전체에 단일 parameterized SQL을 실행하여 현재 generation/필터/색인 호환성을 검사하고 authoritative layer의 chunk를 순차 조회한다. Python 전체 chunk scan이나 source 본문 load는 없다. 기존 object/generation index를 사용하며 SQL window 비용은 선정된 object 크기에 영향을 받는다.
- Repository: extracted_text → review_content → analysis → metadata.
- Knowledge: knowledge_content → knowledge_original → knowledge_refinement → metadata.
- 확장 pool의 정확한 공백 정규화 중복은 병합하고 duplicate_references를 보존한다. refinement가 원문보다 우선하지 않는다.
- object별 round-robin으로 근거를 먼저 분배하고 응답은 object identity/chunk_order 순서로 정렬한다. 확장 passage의 retrieval_score는 object 식별에 사용된 최고 후보 점수를 상속하며 passage 자체의 lexical 점수는 아니다.
- request.limit, max_chunks_per_source, max_sources, max_evidence_chunks, max_evidence_chars를 유지한다. reasoning과 공유하는 payload serializer로 질문·계획·근거·warning JSON context 예산도 검사한다.
- layer 일부가 예산으로 제외되면 coverage_truncated_by_budget, 객체 범위가 제한되면 coverage_object_scope_limited, context 때문에 제외되면 evidence_context_budget_reached를 표시한다. retrieval quality는 기존 partial/insufficient만 사용한다.
설정 및 한계
모두 search_config.py에서 관리하며 환경변수 생략 시 안전한 기본값을 적용한다. 이 retrieval 설정 변경만으로는 재색인이 필요하지 않다.
| 환경변수 | 기본값 | 의미 |
|---|---|---|
| SEARCH_MIN_RELEVANCE_SCORE | 3.0 | 절대 최소 점수 |
| SEARCH_RELATIVE_SCORE_RATIO | 0.2 | 최상위 대비 최소 비율, 0~1 |
| SEARCH_COVERAGE_OBJECT_LIMIT | 3 | 확장 object 상한, max_sources도 적용 |
기존 예산(source당 4 chunk, 전체 20 chunk, passage 30,000자, context 60,000자)을 유지한다. 37 Activity fixture는 3 chunk에 들어가 전체를 포함했지만 긴 실제 문서는 완전한 coverage를 보장하지 않는다. 별도 neighbor 설정 없이 authoritative layer의 순차 prefix를 확장한다. lexical 후보에 없는 객체는 찾을 수 없고, “이 문서”만으로 문서 identity를 알 수 없어 제목/식별자/필터 단서가 필요하다. focused에서도 제목 일치로 여러 chunk가 반환될 수 있다. 규칙/한국어 조사 처리에는 오탐·누락이 있으며 semantic search/embedding은 도입하지 않았다.
신규 16개와 기존 54개, 총 backend 70개 테스트 및 Q1~Q3 합성 fixture 검증은 검증 기록을 참조한다. 운영 corpus/실제 모델/대규모 성능은 미검증이며 production DB 접근·OCI 배포는 수행하지 않았다.
Phase 2 UI는 coverage_mode, evidence_quality, warnings, source_count, index_status 및 evidence title/origin_layer/passage/navigation_ref/duplicate_references를 활용한다. 사용자에게 부분 근거·모듈 근거 부족·색인 갱신 필요를 알리고 low_relevance_candidates_dropped는 상세 진단으로 둔다. confirmed/inferred/unknown과 evidence_id 연결은 기존 reasoning 계약을 따른다.