한 장의 그림으로 이해하기

그림 크게 보기 ↗ (새 탭)
모델·API · 판정 관망
그림을 글로 풀면
배치 완료와 문서 완료 나누기
문서별 성공 여부와 저장 여부를 따로 대조합니다.
- 대상
- 야간 문서 처리를 만드는 개발자
- 무엇이 바뀜
- 배치 결과에는 개별 오류가 포함될 수 있습니다.
- 왜 중요한가
- 전체 재전송은 중복 작업을 만들 수 있습니다.
- 지금 할 일
- 입력 ID와 결과 ID를 대조합니다.
- 한계·미확인
- API 실행 없이 구성한 복구 설계 예시입니다.
- 확인일
- 2026-09-16
작업 하나에 완료 상태 하나만 두면 생기는 문제
Gemini Batch API는 즉시 응답이 필요하지 않은 여러 요청을 비동기로 처리합니다. 공식 문서는 작업 결과 안에서 개별 요청 오류를 확인하도록 안내합니다. 따라서 상위 작업이 종료됐다는 사실만으로 모든 문서를 후속 업무에 넘기는 구조는 피해야 합니다. 작업 상태와 문서별 결과 상태를 별도 칸에 기록하는 것이 이 글의 설계 출발점입니다.
가상의 문서 100개를 세 단계로 대조하기
다음은 실제 처리 결과가 아닌 설계 연습입니다. 문서 100개에 내부 ID를 부여하고 제출 목록을 먼저 고정합니다. 결과를 받은 뒤 성공 96개, 오류 3개, 결과를 찾지 못한 1개로 나뉘었다고 가정합니다. 마지막 1개를 오류와 합쳐 바로 재전송하지 말고 결과 파일을 끝까지 읽었는지, 같은 ID가 두 번 나왔는지부터 확인합니다. 정상 결과라도 저장이 실패하면 후속 업무에는 미완료로 남겨야 합니다.
재시도 범위를 좁히는 제출 장부
공식 문서상 배치 생성 요청을 두 번 보내면 별도 작업 두 개가 만들어집니다. 네트워크 응답이 끊겼을 때 생성 요청부터 반복하는 복구는 이 특성을 고려해야 합니다. AINOW가 제안하는 장부에는 입력 묶음의 내부 키, 공급자 작업 ID, 제출 시각, 결과 확인 시각을 둡니다. 생성 성공 여부가 불명확하면 기존 작업을 먼저 조회하고, 확인된 실패 항목만 새로운 묶음으로 분리합니다.
통과 기준은 답변 수보다 저장된 문서 수
연습을 마칠 때는 제출 ID 전체가 성공 저장, 확인된 실패, 조사 대기 중 하나에 정확히 한 번 들어가는지 확인합니다. 성공 저장된 문서는 동일한 결과를 다시 읽어도 중복 등록되지 않게 내부 키로 보호합니다. 이 제안은 공급자의 처리 시간을 보장하지 않습니다. 업무 마감까지 결과가 오지 않을 때 담당자에게 넘길 목록과 다음 실행에서 이어갈 범위도 함께 정해야 합니다.
참고 원문: Gemini Batch API 공식 문서 · 원문 게시일 미확인 · 확인일 2026-09-16
AI 작성·자동 검증: 공식 자료와의 대조 및 게시 구조 검사. 사람의 개별 검수와 제품 실행 시험은 수행하지 않았습니다. 그림은 신규 생성한 개념 일러스트입니다.
이 글의 검증 카드
- 자료 버전
- 공식 웹 문서 2026-09-16 확인; 실행 미검증
- 확인일
- 2026-09-16
- 검증 상태
- 개발자 주장
- 한계·주의
- API 실행 없이 구성한 복구 설계 예시입니다.
함께 더 정확하게
질문·오류 제보
그림에서 이해되지 않는 부분이나 달라진 내용을 알려 주세요. 관리자가 확인하고 승인한 글만 공개됩니다.
개발에서는 이메일 인증 가입 또는 관리자 발급 계정으로 참여할 수 있습니다. 계정·이용 문의
아직 계정이 없으신가요? 회원가입
공개된 질문·제보
아직 공개된 질문·제보가 없습니다. 궁금한 부분을 먼저 남겨 주세요.