1. 모델의 기대를 데이터 계약으로 전환하기
검증기를 선택하기 전에 프로그램이 기대하는 객체부터 시작하세요. 표 형식 입력이라면 열 이름, 타입, 단위를 명시하세요. 이미지라면 크기, 채널, 방향 처리 방식을 명시하세요. 텍스트라면 인코딩, 필수 필드, 빈 입력에 대한 정책을 정의하세요. 데이터는 읽을 수 있지만 연산에 적합하지 않을 수 있습니다.
세 가지 결정을 구분하세요: 거부, 그대로 수용, 문서화된 규칙에 따라 변환. 문자열을 숫자로 변환하거나, 결측값을 대체하거나, 입력을 잘라내는 것은 처리되는 내용을 바꿉니다. 이러한 작업은 도구가 기본 타입을 선택하기 때문에 발생해서는 안 됩니다.
이 가이드의 예시는 교육용이며 실행되지 않습니다. 식별자와 −100에서 100 사이의 세 가지 숫자 값을 포함하는 객체를 다룹니다. 이 범위는 계약을 설명하기 위해 임의로 만든 것으로, 물리적 단위나 Kernodeck 데이터 세트와의 연관성은 없습니다. 실제 프로젝트의 규칙으로 대체해야 합니다.
표의 모든 열을 보려면 스크롤하세요.| 수준 | 규칙 | 식별 가능한 실패 |
|---|---|---|
| 스키마 | 정확히 id와 values | 필드 누락 또는 예상치 못한 필드. |
| 타입 | id는 문자열, values는 숫자 리스트 | 숫자가 텍스트, 불리언 또는 결측값으로 표현됨. |
| 형상 | 객체당 세 개의 값 | 벡터가 너무 짧거나 너무 김. |
| 값 | [−100, 100] 범위 내의 유한한 숫자 | NaN, 무한대 또는 교육용 범위를 벗어난 값. |
| 코퍼스 | 고유 식별자 | 두 객체가 같은 식별자를 가짐. |
2. 변환 전에 읽기 검증하기
포맷과 그 방언을 고정하세요. CSV라면 구분자, 인코딩, 헤더 존재 여부를 문서화하세요. Python 표준 CSV 리더는 일반적으로 문자열을 반환하며, 해당 열이 정수라고 판단하지 않습니다. 0012와 같은 식별자는 변환으로 12가 되면 의미를 잃을 수 있습니다. 따라서 식별자는 의도된 타입으로 유지하세요.
비즈니스 객체를 생성하기 전에 필드 수와 열 이름을 검증하세요. 예상치 못한 구분자로 어긋난 행은 일부 값이 여전히 변환 가능하다는 이유로 통과해서는 안 됩니다. 바이너리 파일이나 이미지의 경우에도 실제 읽기를 수행하세요. 올바른 확장자가 디코딩 가능한 내용을 보장하지는 않습니다.
디코딩된 JSON이 곧 검증된 계약은 아닙니다. Python 모듈은 기본적으로 일부 비유한 값과 객체 내 중복된 이름을 허용합니다. 여러분의 형식이 이를 금지한다면 디코딩 단계에서 거부하도록 설정한 뒤 스키마 규칙을 적용하세요. 또한 전체 파일을 메모리에 로드하기 전에 적절한 크기 제한을 정의하세요.
3. 규칙 유형별로 오류를 분리하기
각각의 잘못된 항목이 중요한 규칙 하나만 위반하도록 작은 집합을 구성하세요. 그러면 검사가 무엇을 탐지하는지 알 수 있습니다. 유일한 잘못된 예시가 잘못된 식별자, 잘못된 크기, 무한대 값을 모두 겸하고 있다면, 그 거부가 세 가지 규칙이 모두 작동한다는 것을 입증하지는 못합니다.
표에서 표기법은 이미 읽어들인 교육용 객체를 나타냅니다. 무한대는 비유한 숫자 값이지, 채택해야 할 JSON 문법이 아닙니다. 판정은 추론에 의해 예상된 것이며 실행된 프로그램의 출력이 아닙니다. a를 가진 두 번째 객체는 유일성을 검증하기 위해 유효한 a 객체 다음에 테스트합니다.
계약이 진화할 때 이 사례들을 계약과 함께 보관하세요. 숫자 문자열을 허용하기로 결정했다면 명시적인 변환 단계를 만들고 그 결정의 기록을 남기세요. 코퍼스의 첫 번째 거부를 없애기 위해 검사를 조용히 수정하지 마세요.
표의 모든 열을 보려면 스크롤하세요.| 식별자 및 값 | 예상 판정 | 적용된 규칙 |
|---|---|---|
| a · [1, 2, 3] | 허용 | 유효한 기준. |
| b · ["4", 5, 6] | 거부: 타입 | 이 계약에서 문자열은 숫자가 아닙니다. |
| c · [7, 8] | 거부: 형태 | 세 개 대신 두 개의 값. |
| d · [0, 무한대, 1] | 거부: 값 | 비유한 값은 계산에 들어갈 수 없습니다. |
| a · [4, 5, 6], 첫 번째 a 이후 | 거부: 중복 | 코퍼스에 대한 유일성. |
4. 명시적인 검증기와 활용 가능한 메시지 유지하기
다음 발췌는 디코딩 이후 객체에 대한 검사를 보여줍니다. 첫 번째 실패 규칙에서 멈추며, 전체 파일이나 가능한 모든 형식을 다루지 않습니다. seen 컨테이너는 코퍼스 순회에 속합니다. 매 줄마다 이를 다시 만들면 중복 검사가 무의미해집니다.
유용한 메시지에는 규칙, 논리 파일, 객체의 위치가 포함됩니다. 그 내용 전체를 그대로 옮겨 적지 마세요. 여러 오류를 수집할 때는 유지되는 세부 정보를 제한하되 카운터는 완전하게 유지하세요. 수 기가바이트짜리 보고서도 첫 번째 원인을 찾는 데에는 도움이 되지 않습니다.
NumPy 배열에서는 요소별 유한성 검사가 타입 및 형태 검사를 보완할 수 있습니다. 그러나 비즈니스 범위를 대체하지는 않습니다. 유한한 숫자도 여전히 음수 길이나 잘못된 단위로 표현된 값일 수 있습니다.
import math
def valider_objet(item, seen):
if type(item) is not dict or set(item) != {"id", "values"}:
raise ValueError("SCHEMA")
identifiant = item["id"]
if type(identifiant) is not str or not identifiant.strip():
raise ValueError("IDENTIFIANT")
if identifiant in seen:
raise ValueError("DOUBLON")
values = item["values"]
if type(values) is not list or len(values) != 3:
raise ValueError("FORME")
for value in values:
if type(value) not in (int, float):
raise ValueError("TYPE")
if not (-100 <= value <= 100) or not math.isfinite(value):
raise ValueError("VALEUR")
seen.add(identifiant)
return item5. 샘플에서 전체 코퍼스로 나아가기
짧은 샘플은 리더와 계약을 빠르게 수정할 수 있게 해줍니다. 일반적인 사례와 경계를 선택하세요: 빈 입력, 최대 크기, 특이한 문자, 첫 번째와 마지막 파티션. 처음 몇 줄만 선택하면 더 뒤의 파일이나 희귀 범주에 있는 이상을 놓칠 수 있습니다.
전체 검증은 관련된 모든 항목을 순회하며 전역 규칙을 적용합니다. 대용량의 경우 파일을 점진적으로 처리하고 그 정체성을 기록하세요. 모든 식별자를 메모리에 담은 집합은 작은 예시에는 적합하지만 너무 비용이 커질 수 있습니다. 그럴 때는 검사를 포기하지 않으면서 볼륨에 맞는 유일성 전략을 선택하세요.
보고서는 그 범위를 명시해야 합니다. 즉, 파일럿 검증용 샘플인지, 특정 파티션 전체인지, 정의된 코퍼스 전체인지를 밝혀야 합니다. 읽은 항목, 승인한 항목, 거부한 항목의 개수와 적용한 규칙을 유지하세요. 이후 파일이 변경되면 이전 보고서가 새로운 입력을 자동으로 검증하지는 않습니다.
6. 거부된 데이터를 어떻게 처리할지 결정하기
오류가 계산의 의미를 무효화할 때는 작업을 중단하세요. 필수 열 누락, 호환되지 않는 단위, 식별자 매칭 실패 등이 그 예입니다. 작업에서 개별 항목의 제외를 허용한다면, 실행 전에 그 정책을 정의하고, 거부 항목을 보존하며, 실제로 승인된 범위를 기준으로 결과를 계산하세요.
제외는 수정이 아닙니다. 결측값을 대체하거나 입력을 정규화한다면, 식별 가능한 새 버전을 생성하고 다시 검증하세요. 변환과 그 파라미터를 실험과 함께 보관하세요. 그렇지 않으면 같은 이름의 두 실험이 서로 다른 데이터를 사용할 수 있습니다.
GPU에 넣기 전에 실제로 구성된 배치를 다시 점검하세요. 차원 순서, 수치 타입, 존재하는 경우의 마스크, 그리고 타깃과의 대응 관계를 확인하세요. 파일 검증은 변환보다 먼저 이루어지며, 이후 파이프라인이 그 속성을 유지한다는 것을 증명하지는 않습니다. 대표적인 케이스 하나로 이 마지막 경계를 확인할 수 있습니다.
7. 이해할 수 있는 실행 승인 산출하기
기대하는 결과물은 네 가지 질문에 답하는 짧은 보고서입니다. 즉, 어떤 입력인지, 어떤 규칙인지, 어떤 범위인지, 어떤 결정인지입니다. 유효 상태는 정확한 코퍼스 식별자를 가리켜야 합니다. 부분 상태는 무엇이 아직 검증되어야 하는지 명시해야 합니다. 거부는 해당 객체의 내용을 불필요하게 유포하지 않고도 그 객체를 추적할 수 있게 해야 합니다.
검증기 자체에 대한 점검도 추가하세요. 올바른 케이스는 통과하고, 각 잘못된 케이스는 올바른 이유로 거부되며, 카운터가 일치하는지 확인하세요. 그런 다음 애플리케이션에서 작은 구간을 확인하세요. 이 이중 점검은 데이터 적합성을 모델 품질이나 GPU 가용성과 혼동하는 것을 방지합니다.
규정을 준수하는 입력이라도 편향되어 있거나, 라벨이 잘못되었거나, 연구 질문에 부적합할 수 있습니다. 이 가이드는 구조적 적합성과 명시적 규칙을 다루며, 대표성이나 사용 권리를 보증하지는 않습니다. 이러한 결정은 장시간 처리 전에 문서를 보완합니다.