동기화 규칙과 한계 | Geo-MLOps 매뉴얼

판정표

한 번의 동기화는 원격 매니페스트를 읽어 파일마다 아래처럼 판정합니다. 화면의 미리보기와 실제 동기화가 같은 판정 함수를 쓰므로, 미리보기에서 본 것이 그대로 일어납니다.

판정	조건	동작
신규	매니페스트에 있고, 이 데이터셋에 그 `file_id` 로 받은 파일이 없음	내려받는다
변경	`file_id` 는 같고 `sha256` 이 다름	다시 받아 같은 행을 교체한다(파일 id 유지)
유지	`file_id` 와 `sha256` 이 같음	아무것도 안 한다
삭제	동기화로 받은 파일인데 매니페스트에서 사라짐	저장소 객체와 행을 지운다
충돌	파일 이름이 직접 올린 파일과 겹침 / 정리한 이름이 비거나 매니페스트 안에서 겹침	건너뛰고 경고를 남긴다

모든 쓰기는 "원격 file_id 에서 온 파일" 에만 합니다. 직접 올린 파일은 판정 대상이 아닙니다.
체크섬은 저장소가 실제로 기록한 바이트로 계산해 매니페스트와 비교합니다. 전송 중 잘린 파일이 정상 파일로 통과하지 않습니다. 맞지 않으면 그 파일만 버리고 경고를 남깁니다.
원격의 파일별 meta 와 원래 파일 이름은 플랫폼 파일의 meta.source 에 보관됩니다.

전송 순서

어노테이션 파일은 마지막에 받습니다. 어노테이션 검증은 데이터셋에 이미 있는 이미지와 짝을 맞춰 보는데, 매니페스트 순서(0001.json < 0001.png)대로 받으면 짝이 0% 로 나오기 때문입니다. 실행 끝에 어노테이션을 한 번 더 검증해, 이미지가 나중 실행에 들어온 경우까지 맞춥니다.

실행 제어

상황	동작
같은 데이터셋에서 동기화가 도는 중에 또 시작	`409` (`a sync is already running for this dataset`)
취소	지금 받는 파일이 끝나면 멈춥니다. 받다 만 파일은 반영되지 않고, 이미 받은 파일은 다음 동기화가 체크섬으로 이어받습니다
소스가 비활성	연결은 유지되고 새 동기화만 막힙니다
동기화 중 파일 업로드	거절됩니다. 동기화가 끝난 뒤 올리세요
여러 데이터셋 동시 동기화	서버 전체에서 기본 2개까지(`GEO_MLOPS_DATASET_SYNC_MAX_CONCURRENCY`). 나머지는 기다립니다

API 로 동기화를 시작하면 202 와 실행 행이 바로 돌아옵니다. 진행은 실행 목록을 다시 읽어 봅니다.

curl -b cookies.txt -H "X-Tenant: DEMO" -X POST \
  "http://localhost:10000/api/v1/datasets/<데이터셋 id>/syncs"
# 도는 중에 한 번 더 부르면:
# {"error_id":"…","code":"conflict","message":"a sync is already running for this dataset","detail":null}

서버 설정

환경 변수	기본값	설명
`GEO_MLOPS_DATASET_SYNC_MAX_CONCURRENCY`	`2`	동시에 동기화하는 데이터셋 수
`GEO_MLOPS_DATASET_SYNC_HTTP_TIMEOUT`	`30`	원격 호출 한 번의 시간 제한(초). 파일 전체가 아니라 읽기 단위에 걸립니다
`GEO_MLOPS_DATASET_MAX_UPLOAD_BYTES`	2 GiB	파일 하나의 상한(업로드와 같은 값)

지금 없는 것

없는 것	대신
예약·주기 동기화	수동 버튼 또는 외부 스케줄러에서 API 호출
`updated_at` 을 보고 동기화 자체를 건너뛰기	매번 매니페스트를 읽고 `sha256` 으로 비교합니다(바뀐 게 없으면 받는 파일 0)
`Range` 이어받기	실패한 파일은 다음 동기화에서 통째로 다시 받습니다
플랫폼 → DataOps 역방향 업로드(Push)	없음. 이 연동은 Pull 전용입니다
어노테이션 형식·클래스 표 해석	매니페스트의 `annotation_format` · `classes` 는 기록만 합니다. 라벨은 받은 어노테이션 파일(COCO · LabelMe · VOC)을 검증기가 직접 읽습니다

판정표#

전송 순서#

실행 제어#

서버 설정#

지금 없는 것#

판정표

전송 순서

실행 제어

서버 설정

지금 없는 것