JSONL이란? AI 데이터와 요청을 한 줄씩 저장하는 파일 형식

TL;DR

JSONL(JSON Lines)은 한 줄마다 독립된 JSON 값을 하나씩 기록하는 텍스트 파일 형식입니다. 여러 AI 요청이나 학습 예시를 줄 단위로 읽고 처리하기 쉬워 배치 API, 파인튜닝 데이터, 대규모 데이터셋에 자주 쓰입니다. 확장자만 바꾼다고 JSONL이 되는 것은 아니며, 각 줄이 올바른 JSON인지와 서비스별 필수 필드를 따로 확인해야 합니다.

핵심 3줄 요약

• 핵심 1
  한 줄이 한 레코드입니다. 각 줄은 다른 줄과 분리된 완전한 JSON 값이어야 합니다.
• 핵심 2
  대량 AI 작업에 잘 맞습니다. 줄 단위로 요청·학습 예시·결과를 읽고 오류 위치를 찾기 쉽습니다.
• 핵심 3
  파일 형식과 데이터 규칙은 다릅니다. JSONL 구조가 맞아도 OpenAI, Gemini, 데이터셋 도구가 요구하는 필드가 빠지면 처리되지 않습니다.

이 글에서 다룰 내용

JSONL을 한 문장으로 정의하면 무엇인가요?

JSONL(JSON Lines)은 줄마다 하나의 유효한 JSON 값을 기록해 여러 레코드를 순서대로 저장하는 UTF-8 텍스트 형식입니다.

JSON Lines 문서는 이 형식의 기본 조건을 세 가지로 설명합니다. 파일은 UTF-8을 쓰고, 각 줄은 독립적으로 유효한 JSON 값이어야 하며, 값 뒤에는 줄바꿈 문자를 둡니다. 보통 확장자는 .jsonl을 사용합니다.

JSONL은 거대한 JSON 배열 하나를 만드는 방식과 다릅니다. 파일 전체를 한꺼번에 읽지 않아도 첫 줄, 둘째 줄처럼 필요한 레코드를 순서대로 처리합니다. 그래서 요청이나 학습 예시가 많은 AI 작업에서 자주 등장합니다.

한 줄 정리: JSONL은 JSON 문법으로 쓴 레코드를 줄바꿈으로 구분한 파일입니다.

쉬운 예시로 이해해 볼까요?

감자나라ai님이 고객 문의 두 건을 AI로 분류한다고 가정해 보겠습니다. JSONL 파일은 아래처럼 한 줄에 문의 한 건을 담습니다.

• 1번째 줄: {"id":"q-001","text":"배송이 늦어요","label":"배송"}
• 2번째 줄: {"id":"q-002","text":"환불하고 싶어요","label":"환불"}

첫 줄의 여는 중괄호부터 닫는 중괄호까지가 하나의 JSON 객체입니다. 둘째 줄도 완전히 독립된 JSON 객체입니다. 두 객체를 감싸는 바깥 대괄호도 없고, 줄 사이에 쉼표도 넣지 않습니다.

레코드가 10만 건이어도 원리는 같습니다. 프로그램은 한 줄을 읽고 처리한 뒤 다음 줄로 넘어갑니다. 특정 줄의 문법이 잘못됐다면 어느 레코드에서 문제가 생겼는지 찾기도 쉽습니다.

쉬운 예시: JSONL은 서류철 전체를 하나의 봉투에 넣는 방식보다, 한 줄마다 번호가 붙은 신청서를 차례로 쌓는 방식에 가깝습니다.

왜 AI를 사용할 때 JSONL이 중요한가요?

대량 요청을 한 파일로 전달합니다

OpenAI Batch API는 입력 요청 파일에 JSONL 형식을 요구합니다. 각 줄에는 요청을 구분할 고유한 custom_id, HTTP 메서드, API 경로와 요청 본문이 들어갑니다. 결과도 요청 식별자와 연결해 확인합니다.

Gemini Batch API도 큰 요청 묶음에는 JSONL 입력 파일을 안내합니다. 각 줄에는 사용자가 정한 키와 완전한 GenerateContentRequest 객체가 들어갑니다. 출력 파일 역시 줄마다 응답이나 상태 객체를 담는 JSONL 형식입니다.

서비스마다 줄 안의 필드 이름과 구조는 다릅니다. JSONL이라는 공통 그릇을 쓰더라도 OpenAI용 요청 한 줄을 Gemini에 그대로 넣을 수는 없습니다.

파인튜닝 예시를 레코드 단위로 저장합니다

OpenAI Files 문서는 파인튜닝 입력에 .jsonl 파일을 사용한다고 안내합니다. 한 줄은 보통 하나의 학습 예시를 담지만, 구체적인 메시지 필드와 역할 구조는 선택한 파인튜닝 방식에 맞아야 합니다.

JSONL을 알면 파인튜닝 문서에서 말하는 한 줄당 예시, 학습 파일 검증, 오류가 난 줄 같은 표현을 이해하기 쉬워집니다. 다만 JSONL은 학습 방법이 아닙니다. 데이터를 담는 파일 형식일 뿐입니다.

큰 데이터셋을 줄 단위로 다루기 편합니다

Hugging Face Datasets 문서는 JSON 파일을 불러올 때 여러 JSON 객체를 두고 각 줄을 데이터 한 행으로 만드는 형식을 효율적인 방식으로 소개합니다. 전체 파일을 하나의 거대한 배열로 만들지 않아도 레코드를 순서대로 읽을 수 있기 때문입니다.

로그, 평가 결과, 생성 기록처럼 데이터가 계속 추가되는 작업에도 잘 맞습니다. 새 레코드를 끝에 한 줄씩 붙일 수 있고, 여러 파일을 나누거나 압축하기도 쉽습니다.

핵심 인사이트: JSONL의 장점은 AI가 더 똑똑해지는 데 있지 않습니다. 많은 요청과 예시를 레코드 단위로 저장하고 전달하기 쉬워지는 데 있습니다.

JSONL 파일은 어떻게 생겼나요?

한 줄에는 완전한 JSON 값 하나를 넣습니다

한 객체를 여러 줄로 보기 좋게 들여쓰면 일반 JSON으로는 유효할 수 있지만 JSONL에서는 한 레코드가 여러 줄로 갈라집니다. JSONL 파일에서는 한 레코드를 한 줄에 끝내는 편이 안전합니다.

문자열은 큰따옴표로 감싸고, 객체의 키도 큰따옴표를 써야 합니다. 문자열 안의 줄바꿈은 실제 줄바꿈을 넣기보다 JSON 이스케이프 규칙에 맞춰 표현해야 합니다.

줄 사이에 쉼표를 넣지 않습니다

일반 JSON 배열은 객체 사이에 쉼표가 필요합니다. JSONL은 줄바꿈이 레코드 경계이므로 줄 끝에 쉼표를 붙이지 않습니다. 파일 전체를 대괄호로 감싸지도 않습니다.

빈 줄을 두지 않습니다

JSON Lines 문서 기준으로 각 줄은 유효한 JSON 값이어야 합니다. 빈 줄은 JSON 값이 아니므로 데이터 사이에 장식용 빈 줄을 넣지 않는 것이 좋습니다.

실전 팁: 파일을 눈으로 볼 때는 줄 번호를 표시하는 편집기를 쓰세요. 검증 오류가 난 줄을 바로 찾기 쉽습니다.

JSONL과 헷갈리는 용어는 무엇이 다른가요?

일반 JSON과 JSONL의 차이

일반 JSON 문서는 파일 전체에 하나의 최상위 값을 둡니다. 여러 객체를 담으려면 보통 하나의 배열 안에 넣고 객체 사이에 쉼표를 씁니다.

JSONL은 각 줄이 별도의 최상위 JSON 값입니다. 바깥 배열과 객체 사이 쉼표가 없습니다. 일반 JSON 파서가 JSONL 파일 전체를 하나의 JSON 문서로 읽으려 하면 오류가 날 수 있습니다.

CSV와 JSONL의 차이

CSV는 행과 열이 단순한 표 형태일 때 사람이 열어 보기 쉽고 스프레드시트와 잘 맞습니다. JSONL은 배열이나 중첩 객체처럼 구조가 복잡한 레코드를 담는 데 유리합니다. 숫자, 문자열, 참·거짓, null 같은 JSON 자료형도 명확히 표현합니다.

한 형식이 언제나 낫지는 않습니다. 단순한 연락처 표라면 CSV가 편하고, 대화 메시지 배열이나 도구 호출 정보가 들어간 AI 학습 예시라면 JSONL이 자연스럽습니다.

JSON Schema와 JSONL의 차이

JSON Schema는 JSON 데이터에 어떤 필드가 있어야 하는지, 자료형과 허용값은 무엇인지 검사하는 규칙입니다. JSONL은 여러 JSON 레코드를 줄 단위로 저장하는 방식입니다.

둘은 함께 씁니다. 파일은 JSONL로 저장하고, 각 줄의 객체가 정해진 JSON Schema를 따르는지 검사합니다.

NDJSON과 JSONL의 차이

NDJSON은 Newline-Delimited JSON의 줄임말입니다. 실무에서는 JSONL과 거의 같은 뜻으로 쓰이지만 도구가 요구하는 확장자나 MIME 유형은 다를 수 있습니다. 문서에 .jsonl을 요구하면 임의로 .ndjson으로 바꾸지 말고 서비스 안내를 따르는 편이 안전합니다.

배치 처리와 JSONL의 차이

배치 처리는 여러 작업을 모아 비동기로 처리하는 실행 방식입니다. JSONL은 그 작업들을 파일에 담는 형식입니다. 배치 API가 JSONL을 사용할 수 있지만 모든 배치 시스템이 반드시 JSONL만 쓰는 것은 아닙니다.

비교 정리: JSON은 한 문서의 구조, JSONL은 줄 단위 레코드 저장, CSV는 표 형태 데이터, JSON Schema는 구조 검증 규칙, 배치 처리는 작업 실행 방식입니다.

실전에서는 어디에 쓰이나요?

AI 배치 API 요청 파일

수천 건의 요약, 분류, 임베딩 생성이나 이미지 생성 요청을 비동기로 처리할 때 씁니다. 요청마다 식별자를 넣어 결과 파일의 각 줄을 원래 작업과 연결합니다.

파인튜닝 학습·검증 데이터

대화 예시, 분류 예시, 선호도 데이터 등을 한 줄에 하나씩 저장합니다. 학습 파일과 검증 파일이 같은 예시를 중복해서 담지 않는지, 역할과 필드가 서비스 문서에 맞는지 확인해야 합니다.

평가와 실험 결과

프롬프트, 모델 응답, 정답, 점수, 실행 시간과 오류를 한 레코드로 묶어 저장합니다. 줄 단위라서 실패한 레코드만 다시 고르거나 여러 파일을 합치기 편합니다.

머신러닝 데이터셋

텍스트, 라벨, 메타데이터와 중첩된 속성을 함께 담을 때 씁니다. 이미지나 오디오 원본을 JSONL 안에 직접 넣기보다 파일 경로, URL, 라벨과 설명을 레코드로 기록하는 경우도 많습니다.

실전 팁: JSONL을 만들기 전에 한 줄의 샘플 객체부터 검증하세요. 샘플이 통과한 뒤 같은 구조로 전체 레코드를 생성하면 대량 오류를 줄일 수 있습니다.

JSONL 파일을 만들 때 어떤 순서로 확인하나요?

1. 사용할 서비스의 예시를 그대로 확인합니다

확장자만 .jsonl이면 된다고 생각하지 마세요. OpenAI Batch API와 Gemini Batch API는 줄 안에 요구하는 키가 다릅니다. 파인튜닝도 모델과 방식에 따라 메시지 구조가 달라집니다.

2. 레코드 식별자를 넣습니다

배치 요청이나 평가 데이터라면 각 줄을 구분할 고유 ID를 둡니다. 결과 순서가 바뀌거나 일부 요청만 실패해도 입력과 결과를 다시 연결합니다.

3. 한 줄씩 JSON 문법을 검사합니다

큰따옴표 누락, 마지막 쉼표, 닫는 중괄호 누락, 실제 줄바꿈이 들어간 문자열을 찾습니다. 파일 전체가 아니라 각 줄을 독립된 JSON 값으로 파싱해야 합니다.

4. UTF-8과 줄바꿈을 확인합니다

한국어가 들어간 파일은 UTF-8로 저장합니다. 파일 앞에 BOM을 붙이지 않고, 레코드 사이에는 정상적인 줄바꿈이 하나씩 있는지 봅니다.

5. 작은 파일로 먼저 시험합니다

두세 줄짜리 파일을 업로드해 구조와 권한, 결과 연결 방식을 확인한 뒤 전체 파일을 처리합니다. 형식 오류를 늦게 발견하면 대량 작업을 다시 만들어야 합니다.

한 줄 정리: JSON 문법 검사와 서비스별 스키마 검사는 별개입니다. 두 검사를 모두 통과해야 실제 AI 작업에 쓸 수 있습니다.

사용할 때 무엇을 주의해야 하나요?

첫째, 파일 이름만 바꾸지 않습니다. 일반 JSON 배열 파일의 확장자를 .jsonl로 바꿔도 내부 구조는 그대로입니다. 배열을 각 줄의 독립된 객체로 변환해야 합니다.

둘째, 비밀정보를 넣지 않습니다. API 키, 비밀번호, 개인정보나 내부 문서 원문이 레코드에 섞이지 않았는지 확인합니다. 배치와 학습 파일은 업로드 뒤 보관·삭제 정책도 함께 봐야 합니다.

셋째, 한 줄의 크기를 지나치게 키우지 않습니다. 긴 문서나 바이너리 데이터를 한 레코드에 그대로 넣으면 편집과 오류 확인이 어려워집니다. 서비스의 파일 크기와 요청 크기 제한을 먼저 확인하세요.

넷째, 출력 순서만 믿지 않습니다. 배치 시스템은 결과를 입력 순서대로 돌려주지 않을 수 있습니다. 서비스가 제공하는 요청 ID나 사용자 지정 키로 연결하는 편이 안전합니다.

다섯째, 압축과 확장자 규칙을 확인합니다. JSON Lines 문서는 스트림 압축에 잘 맞는 형식이라고 설명하지만 모든 AI 서비스가 .jsonl.gz 업로드를 받는 것은 아닙니다. 서비스가 허용한 파일 유형을 따르세요.

주의: JSONL은 데이터가 정확하거나 안전하다는 보증이 아닙니다. 문법이 맞아도 라벨 오류, 중복, 개인정보, 잘못된 지시문은 그대로 남습니다.

자주 묻는 질문

Q1. JSONL은 JSON과 완전히 다른 언어인가요?

아닙니다. 각 줄은 JSON 문법을 그대로 씁니다. 차이는 여러 JSON 값을 하나의 파일에 넣을 때 바깥 배열 대신 줄바꿈으로 구분한다는 점입니다.

Q2. 확장자는 .json과 .jsonl 중 무엇을 써야 하나요?

사용할 도구와 서비스 문서를 따르세요. 한 줄에 한 레코드를 넣는 파일이라면 보통 .jsonl을 씁니다. 일부 도구는 .json 파일 안의 줄 단위 객체도 읽지만 이름만 보고 형식을 판단하는 시스템도 있습니다.

Q3. 한 줄을 보기 좋게 여러 줄로 들여써도 되나요?

권장하지 않습니다. JSONL에서는 줄바꿈이 레코드 경계입니다. 한 레코드는 한 줄에 두고, 사람이 보기 편한 출력은 별도의 JSON 뷰어나 포매터로 확인하는 편이 안전합니다.

Q4. 빈 줄이나 주석을 넣어도 되나요?

빈 줄은 유효한 JSON 값이 아니며 표준 JSON에는 주석 문법도 없습니다. 설명이 필요하면 각 레코드 안에 허용된 설명 필드를 두되, 사용하는 서비스가 그 필드를 받는지 먼저 확인하세요.

Q5. JSONL 파일이면 OpenAI와 Gemini에 똑같이 쓸 수 있나요?

아닙니다. 두 서비스 모두 JSONL을 쓸 수 있지만 각 줄에 요구하는 필드와 요청 구조가 다릅니다. 같은 파일 형식과 같은 API 스키마는 별개의 문제입니다.

출처

마무리

JSONL은 한 줄마다 독립된 JSON 값을 기록하는 파일 형식입니다. AI 배치 요청, 파인튜닝 예시, 평가 결과와 대규모 데이터셋처럼 레코드가 많은 작업에서 특히 자주 만납니다.

초보자라면 세 가지만 기억하면 충분합니다. 한 줄에 한 레코드를 넣고, UTF-8로 저장하며, 사용할 서비스가 요구하는 필드를 따로 확인하세요. JSONL 형식을 이해하면 AI 문서에서 입력 파일, 레코드, 줄별 오류와 결과 식별자를 훨씬 쉽게 읽을 수 있습니다.