한울연구소는 가상 조직이다. 책에 등장하는 교육비 금액, 시행일, 사용자, 티켓과 문서 문장은 학습을 위해 작성한 값이며 실제 기관의 규정이 아니다. 예제 수치를 다른 조직의 업무 판단에 적용하지 않는다.
정책과 저장 구조
fixtures/policies/edu-v1.txt와 edu-v2.txt는 개정 전후를 비교하는 UTF-8 텍스트다. 개념 설명의 필드는 저장소 구현에서 다음처럼 나뉜다.
| 개념 | 구현 위치 |
|---|---|
| 문서 식별자 | 조직과 문서 ID의 조합 |
| 개정 | Revision.id |
| 적용 구간 | valid_from, 선택적인 valid_until |
| 본문 | 정규화한 텍스트와 청크의 시작·끝 위치 |
| 읽기 권한 | 별도의 ACL과 현재 요청 주체 |
| 갱신 순서 | 문서 전체 스냅샷의 증가하는 순번 |
개념 설명의 audience를 문자열 하나로 모델에게 읽히는 것과, DB의 권한 행을 검사하는 것은 다르다. 구현은 실제 읽기 권한을 서버가 집행한다. 파일 이름만 바꾸는 것으로 개정이나 권한 갱신이 완료되지 않는다.
청크 위치는 정규화한 텍스트 기준이다. 원본 파일의 바이트 위치나 PDF 좌표로 직접 해석하지 않는다. 이미지 OCR을 넣을 때는 페이지·좌표·검토 상태를 추가로 관리해야 하며 기존 문자 오프셋만으로 원본 위치를 복원할 수 없다.
질문 집합과 실험 기록
초기 Q01–Q20은 요구사항을 드러내기 위한 시나리오다. 검색 실험의 E 계열, RAG 생성의 R01–R04, 파인튜닝 표본의 T·D·E 계열은 각 스크립트의 별도 식별 체계다. 이름이 같거나 비슷하다고 서로 같은 표본으로 조인하지 않는다. 결과 파일과 데이터셋 이름을 함께 키로 사용한다.
experiments의 JSON에는 실제 실행과 가상 제어 실험이 함께 있다. 각 파일의 본문·범위 표시를 확인한다. 대역 모델이나 수동 벡터가 포함된 실험을 실제 가중치의 성능 기록으로 해석하지 않는다. 원본 생성 결과를 보존한 파일은 모두 가상 자료의 실험이며 운영 로그의 기본 형식이 아니다.
학습 표본은 fixtures/tuning-samples.jsonl이다. 각 행은 id, split, family, question, evidence, target을 갖는다. 아홉 행은 데이터 계약을 연습하기 위한 공개 표본이다. 충분한 학습 데이터도, 독립적인 비공개 시험 집합도 아니다.
이미지와 음성
media_demo.py는 문서 이미지와 음성 파일을 로컬에서 생성한다. 이미지의 글자는 운영체제 폰트로 그리며 외부 스캔 문서를 사용하지 않는다. 질문 음성은 macOS의 Yuna 음성으로 합성한다. 개인의 실제 목소리·초상·비공개 자료는 포함하지 않는다.
생성된 바이너리 매체는 기본 Git 추적 대상에서 제외한다. 독자가 실행해 같은 가상 내용을 만들 수 있도록 스크립트와 텍스트 결과를 제공한다. 폰트·운영체제 음성 파일 자체를 저장소에 재배포하지 않는다. 다른 환경에서 만든 음성이 달라지면 그 파일의 해시와 합성 설정을 함께 기록한다.
OCR 한국어 가중치와 Whisper 가중치는 외부 프로젝트의 별도 사용 조건을 따른다. 다운로드한 가중치를 본 저장소의 코드 라이선스가 자동으로 포괄하지 않는다. 사용·재배포 전에 해당 고정 리비전의 조건을 확인한다. Tesseract 한국어 학습 데이터 저장소, Whisper 모델 카드
운영 자료로 교체할 때
자료를 교체하기 전 수집 권한, 조직·문서 식별자, 개정·시행 구간, 파생 자료와 삭제 경로를 정한다. 기존 예제의 가상 사용자에게 운영 자료 권한을 그대로 부여하지 않는다. 텍스트를 익명화했다고 판단할 때도 직책·사건·날짜 조합으로 개인을 알아볼 수 있는지 검토한다.
정답 작성자는 실제 문서에서 답을 확인하고, 질문 시점에 적용되는 규정을 기록한다. 문서의 오류와 모델의 오류를 구분할 수 있어야 한다. 평가에 사용한 문서가 학습이나 프롬프트 선택에 이미 들어갔다면 그 이력을 남긴다.
프로젝트의 가상 자료는 안전한 출발점을 제공한다. 실제 조직의 문서를 넣는 순간 인증·보관·삭제·진단·외부 전송의 요건이 달라지므로 그 변화도 설계의 일부로 취급한다.