지난달에 저는 파일 이름 때문에 약 두 시간의 업로드 작업을 날렸습니다. 거부된 파일도, 손상된 zip 파일도 아닙니다. 바로 파일 이름 때문이었습니다. Adobe Stock과 Vecteezy용 벡터 40개로 구성된 팩을 준비했고, 한 오후에 배치 처리를 두 번 실행했는데, 제 파일명 체계가 추적기(tracker)에게 무엇이 이미 완료되었는지 알려줄 방법이 없었기 때문에 중복 파일을 올렸습니다. 그날 저는 파일 이름을 장식처럼 취급하는 것을 멈추고 데이터를 다루는 것으로 여기기 시작했습니다.
제가 배운 점을 여기에 정리했으니, 이 글을 읽으면서 두 시간을 아끼세요.
파일명은 단순한 파일 이름이 아니다
두 플랫폼 모두에서 파일명 필드는 사람들이 생각하는 것보다 더 많은 역할을 합니다. Adobe Stock용 CSV를 만들 때, 스크립트는 각 행을 디스크의 파일에 일치시켜야 합니다. Adobe의 업로드 CSV 형식은 5개 열이며, 첫 번째 열이 파일 이름입니다. 이 문자열이 업로드한 파일과 정확하게 일치하지 않으면, 메타데이터 행은 아무것에도 연결되지 않습니다. 에셋은 제목 없이 그 자리에 있게 되고, 제목 없는 에셋은 검토 과정에서 거부되며, 여러분은 며칠 후에야 알게 됩니다.
Vecteezy의 CSV는 4개 열이며 동일한 논리가 적용됩니다. 파일명은 CSV와 실제 업로드 간의 조인 키(join key)입니다. 이것을 잘못하면 전체 행이 쓸모없어집니다.
따라서 제 파이프라인의 첫 번째 규칙은 다음과 같습니다: 파일명은 안정적이고, 고유하며, 제가 생성하는 모든 플랫폼 CSV에서 동일해야 합니다. 에셋당 하나의 표준 이름(canonical name)을 한 번만 생성하고 절대 수동으로 수정해서는 안 됩니다.
좋은 파일명이 포함해야 할 내용
제 체계는 간단합니다: pack-name_asset-number.svg이며, 모두 소문자이고 공백이 없습니다. 두 가지 이유가 있습니다.
첫째, make_metadata.py에는 제목 파일을 제공하지 않을 경우 파일명을 가져와 제목 케이스(title-cases)로 변환하여 제목으로 사용하는 폴백(fallback) 기능이 있습니다. 이것은 첫 번째 시도에는 괜찮지만,
둘째로, 에셋 번호(asset number)가 upload_tracker.py가 키(key)로 삼는 값입니다. 제가 upload_tracker.py done "botanical-set_012.svg"를 실행하면, 원장(ledger)에는 정확히 그 문자열이 기록됩니다. 만약 패키지를 재생성하고 파일 이름이 아주 조금이라도 변경되면, 트래커는 그것들을 새로운 에셋으로 간주하여 재실행 시 이중 게시(double-posts)가 발생합니다. 이중 게시되는 것은 제가 아는 가장 빠르게 계정을 플래그(flagged) 당하게 만드는 방법이므로, 이것은 미관상의 문제가 아닙니다.
헤더는 관대하지 않으니 직접 입력하는 것을 멈추세요
제가 업로드하는 세 개의 채널 모두 잘못된 CSV 헤더를 즉시 거부합니다. Adobe는 정확히 5개 열의 헤더를 원하고, Vecteezy는 정확히 4개 열의 헤더를 원하며, Dreamstime은 15개의 열을 원합니다. 부분 점수도 없고, 어떤 열이 문제인지 알려주는 유용한 오류 메시지도 없습니다.
예전에는 세 개의 템플릿 스프레드시트를 가지고 다녔습니다. 하지만 실수로 헤더 행의 셀 하나를 편집하여 업로드 사이클을 날린 적이 있습니다. 이제 make_metadata.py는 플랫폼이 요구하는 헤더만 작성하고 그 외에는 아무것도 하지 않습니다. 저는 다시는 헤더를 손으로 건드리지 않습니다.
작업 흐름은 플랫폼당 하나의 명령어입니다:
python make_metadata.py ./output --platform adobe --out metadata.csv --ext .jpg
python make_metadata.py ./output --platform vecteezy --out vecteezy.csv --ext .jpg
같은 폴더, 같은 파일, 세 개의 CSV 파일에 각각 에셋당 하나의 표준화된 파일 이름이 들어갑니다. 파일 이름 필드는 이 모든 것에서 일치해야 하는 유일한 것이므로, 바로 이것이 직접 입력되는 것이 아니라 생성되어야만 하는 이유입니다.
폴더 레이아웃이 파일 이름을 정직하게 유지합니다
패키지 목록은 고정된 구조가 없으면 잡동사니 서랍(junk drawer)으로 변해버립니다. 제 것은 다음과 같습니다:
project/
assets/ 원시 출력물, 에셋당 하나의 파일
output/ 제출 준비 완료 파일 + metadata.csv
...
에셋은 최종본이 될 때까지 assets/를 벗어나지 않습니다. 이름 변경은 오직 한 번만 발생하며, 파일이 assets/에서 output/으로 이동할 때입니다. 그 이후로는 이름이 고정됩니다. 만약 에셋을 수정해야 한다면, 트래커가 동기화 상태를 유지하도록 다시 이름 변경 단계를 거쳐야 합니다. 이 습관 하나로 제가 겪었던 모든 중복 및 오리진(orphaned-metadata) 문제를 제거할 수 있었습니다.
제가 초기에 저질렀고 반복하지 않을 실수: '정리'한다고 해서 research/ 폴더를 삭제하지 마세요. 그 노트와 로그가 다음 팩의 원자재입니다. 디스크 공간이 연구를 다시 하는 것보다 싸습니다.
저렴한 하드웨어에서 실행하는 것에 대한 참고 사항
이 모든 것이 큰 기계를 필요로 하지 않습니다. 전체 파이프라인, 즉 완성된 제품 39개와 약 856 MB의 출력은 GPU가 없는 vCPU 1개, RAM 2 GB 서버에서 실행되었습니다. 작동하게 만드는 습관들은 다음과 같습니다: 한 번에 하나의 프로세스만 처리하고, 코어 하나에서 이미지 작업을 절대 병렬화하지 않으며, 각 에셋 후에 gc.collect()를 호출하고, 추측하는 대신 resource.getrusage(RUSAGE_SELF).ru_maxrss로 최대 RSS를 측정합니다. 특히 메타데이터 작업의 경우 거의 아무것도 필요하지 않습니다. make_metadata.py와 upload_tracker.py는 파이썬 표준 라이브러리만으로 실행되며, 설치가 전혀 필요 없습니다.
이것이 된 도구
위에 언급된 모든 것은 파이프라인 스타터 키트에 포함되어 있습니다: 제가 실제로 사용하는 네 가지 스크립트를 포함하며, 여기에는 정확한 Adobe, Vecteezy, Dreamstime 헤더를 가진 make_metadata.py와 재실행 시 중복 게시를 막아주는 upload_tracker.py가 포함됩니다. 이 도구는 그 39개 제품을 패키징하는 데 사용된 것과 동일하며, 임대할 수 있는 가장 작은 서버에서도 잘 작동합니다.
파이프라인 스타터 키트 받기
디지털 제품을 제작하시나요? 디지털 제품 판매자를 위한 무료 가이드 및 키트.