체크섬 manifest로 잡는 깨진 다운로드

2026년 7월 1일 | 개발 깨알 상식_Tips

---

다운로드 완료 신호와 파일 무결성 검증 신호를 분리해 두면, 깨진 파일이 다음 파이프라인으로 넘어가는 일을 줄일 수 있다.

다운로드 성공과 파일 정상은 다르다

모델 가중치나 대용량 데이터 압축 파일을 받을 때 제일 찜찜한 순간은 파일이 분명히 있는데 다음 단계에서 이상하게 깨질 때다. 압축 해제 중간에 CRC 오류가 나기도 하고, JSONL 마지막 줄이 잘려 파서가 멈추기도 한다. 더 귀찮은 경우는 파일 크기가 그럴듯해서 한참 뒤 학습이나 평가 단계에서야 원인을 찾는 경우다.

나는 이런 파일을 받을 때 다운로드 명령이 0으로 끝났다는 사실과 받은 바이트가 기대한 파일과 같다는 사실을 따로 본다. 전자는 네트워크 작업의 종료 신호이고, 후자는 산출물의 무결성 신호다. 둘을 합쳐 버리면 실패 위치가 흐려진다. 로그에는 “download complete”가 남았는데 실제로는 프록시가 HTML 에러 페이지를 저장했거나, 중간 재시도에서 일부만 덮어쓴 파일일 수도 있다.

manifest 한 줄이 주는 기준

가장 단순한 기준은 SHA-256 체크섬이다. 원본을 제공하는 쪽에서 checksum 파일을 같이 주면 그대로 쓰고, 내가 만든 내부 산출물이라면 생성 직후 manifest를 같이 남긴다. 중요한 건 해시값만 복사해 두는 게 아니라, 해시와 파일명을 같은 줄에 묶어 두는 것이다. 그래야 나중에 파일 이름을 바꿨거나 잘못된 디렉터리에서 검사한 문제까지 같이 잡힌다.

sha256sum model.bin > SHA256SUMS
sha256sum -c SHA256SUMS --strict

이 두 줄은 특별한 도구가 아니다. 그래도 효과는 꽤 크다. `sha256sum -c`가 `OK`를 내면 적어도 지금 디렉터리의 해당 파일은 manifest가 적은 바이트와 맞다. 반대로 `FAILED`가 뜨면 압축 해제, 변환, 학습으로 넘어가지 말고 다시 받는 쪽부터 봐야 한다. 여기서 바로 다음 단계로 밀어붙이면 깨진 입력을 정상 데이터처럼 다루게 된다.

실패를 분리해서 읽는 순서

체크섬 실패가 났을 때도 나는 바로 “서버 파일이 잘못됐다”로 가지 않는다. 먼저 파일 크기와 수정 시각을 본다. 그다음 manifest가 어느 버전에서 온 것인지 확인한다. release asset은 새로 받았는데 checksum 파일은 예전 release에서 복사한 경우도 있고, 압축을 푼 뒤 내부 파일에 대해 검사해야 하는 값을 바깥 archive에 대고 확인하는 경우도 있다.

또 하나 조심하는 건 partial file이다. 이어받기나 재시도 옵션을 쓰다 보면 `model.bin.tmp`, `model.bin.part` 같은 파일이 남는다. 이 파일을 최종 이름으로 바꾸는 순간부터 뒤쪽 파이프라인은 그것을 정상 입력으로 본다. 그래서 나는 임시 파일 이름으로 받은 뒤 checksum을 통과한 파일만 최종 이름으로 옮기는 편이다. 이 흐름은 작은 파일보다, 여러 시간 걸려 받은 모델 파일에서 특히 값어치가 있다.

sha256sum -c SHA256SUMS --strict --quiet
# 실패하면 압축 해제와 후속 변환을 시작하지 않는다.

한 가지 더 두는 규칙은 검증 위치를 고정하는 것이다. 작업 디렉터리가 바뀐 상태에서 checksum 파일만 상대 경로로 들고 오면 엉뚱한 파일을 검사하거나, 아예 파일을 못 찾아 실패한다. 그래서 manifest 안의 파일명은 실제 배포 단위와 같은 디렉터리 기준으로 두고, 자동화에서는 먼저 그 디렉터리로 이동한 뒤 검사한다. 사소해 보이지만 이 기준이 없으면 실패 로그가 “파일 없음”인지 “해시 불일치”인지 섞여 읽힌다.

내가 남기는 최소 로그

자동화 로그에는 너무 많은 정보를 넣지 않아도 된다. 대신 네 가지는 남기는 편이 좋다. 파일명, byte count, checksum 결과, manifest 출처다. 이 네 가지가 있으면 다음에 같은 실패를 봤을 때 “다운로드가 끊겼나, 파일이 바뀌었나, 검증 기준이 틀렸나”를 빠르게 나눌 수 있다. 특히 동료나 코딩 에이전트에게 넘길 때는 원본 파일 전체보다 이 짧은 검증 로그가 더 도움이 된다.

반대로 체크섬을 만능 안전장치처럼 보면 곤란하다. checksum은 파일이 기대한 바이트와 같은지만 말해 준다. 그 파일이 의미적으로 맞는 데이터인지, 스키마가 맞는지, 안전한 archive 경로인지까지 보장하지는 않는다. 그래서 체크섬은 후속 검증을 시작해도 되는 입구 조건에 가깝다. 압축 파일이면 목록과 경로를 보고, JSONL이면 레코드 경계를 보고, 모델 파일이면 로더가 읽는 최소 smoke test까지 이어 가야 한다.

그래도 이 작은 manifest가 있으면 막연한 불안이 줄어든다. 파일이 존재한다는 신호와 파일이 맞다는 신호를 분리해 두면, 깨진 다운로드가 다음 단계의 이상한 버그처럼 위장하는 일을 꽤 줄일 수 있다. 나는 대용량 파일을 다루는 작업일수록 이 검증을 귀찮은 절차가 아니라, 다음 시간을 아끼는 짧은 문턱으로 보는 편이다.