API를 사용하여 이미지, 오디오 또는 기타 문서를 업로드하는 데 어려움을 겪어본 적이 있다면 일반 텍스트를 보내는 것만큼 간단하지 않다는 것을 알 것입니다. HTTP 요청을 이용한 파일 업로드 이는 AI 서비스를 다루는 모든 개발자에게 필수적인 기반입니다. 클라우드 저장소 티켓팅 시스템 같은 것도 마찬가지지만, 내부 작동 방식을 이해하지 못하면 답답한 서버 오류를 겪을 가능성이 매우 높습니다.
모든 것이 원활하게 작동하려면 바이너리 데이터가 기존 텍스트 형식과 잘 호환되지 않는다는 점을 이해하는 것이 중요합니다. 바로 이러한 이유로 표준이 존재하는 것입니다. 멀티 파트 / 양식 데이터이 솔루션은 다양한 유형의 콘텐츠를 단일 제출물로 패키징하도록 설계되어 서버가 텍스트 필드가 끝나는 위치와 파일의 바이트 스트림이 시작되는 위치를 정확히 알 수 있도록 합니다.
multipart/form-data는 정확히 무엇이며 어떻게 작동합니까?
기본적으로 텍스트와 바이너리 파일을 혼합하여 폼 데이터를 제출할 수 있도록 하는 콘텐츠 유형입니다. application/x-www-form-urlencoded일반 텍스트 필드의 표준인 멀티파트 형식은 요청 본문을 다음과 같이 나눕니다. 독립된 부품.
이 모든 과정의 비밀은 바로 '무엇'이라고 불리는 것'에 있습니다. 경계이것은 경계 역할을 하는 고유하고 임의적인 문자열입니다. 서버는 이 식별자를 사용하여 각 데이터 블록을 구분합니다. 헤더를 구성하려고 하면 오류가 발생할 수 있습니다. Content-Type 이 경계를 포함하지 않고 수동으로 구문 분석하면 서버가 멈추고 400 오류를 반환합니다. 서버가 정보를 구문 분석하는 방법을 알 수 없기 때문입니다.
코딩 방법 비교
JSON을 Base64로 인코딩할지, 아니면 멀티파트 인코딩을 사용할지 고민하는 경우가 많습니다. 멀티파트 인코딩이 일반적으로 더 나은 선택인 이유를 알아보겠습니다.
- application/x-www-form-urlencoded: 단순한 키-값 쌍에만 작동합니다. URL 이스케이핑이 필요하기 때문에 바이너리 파일을 업로드하는 것은 사실상 불가능합니다. 극도로 비효율적.
- application/json con Base64: 가능은 하지만, 그에 따른 비용이 발생합니다. 파일을 Base64로 변환하면 파일 크기가 약 [누락된 값]만큼 증가합니다. 33%이로 인해 대역폭 사용량이 증가하고 서버의 CPU 부하가 높아집니다.
- multipart/form-data: 파일 전송을 위한 기본 옵션입니다. 이 기능을 사용하면 파일을 보낼 수 있습니다. 바이너리 데이터를 직접 복잡한 인코딩 없이 가장 빠르고 가벼운 방식입니다.
Curl을 사용한 실제 구현
Curl은 API 및 그 매개변수를 테스트하는 데 사용되는 스위스산 도구입니다. -F 멀티파트 요청을 실행하는 가장 빠른 방법입니다. -FCurl은 복잡한 작업을 대신 해줍니다. POST 메서드를 설정하고 Content-Type을 구성합니다. 고유한 경계를 생성합니다 자동적으로
텍스트 필드를 제출하려면 다음을 사용하세요. -F "clave=valor"로컬 파일을 업로드하려면 '@' 기호를 사용해야 합니다. -F "campo=@/ruta/al/archivo.jpg". 당신도 할 수 있습니다 MIME 유형을 지정합니다. API 요구 사항이 매우 높은 경우 수동으로 추가합니다. ;type=image/jpeg 파일 경로의 끝부분에 있습니다.
다양한 언어로 작성된 코드 예제
환경에 따라 구현 방식은 다르지만 논리는 동일합니다. 라이브러리에서 이미 콘텐츠 헤더를 처리하는 경우, 굳이 강제로 헤더를 추가하지 마세요.
Requests 라이브러리를 사용한 Python
파이썬에서 라이브러리 requests 이렇게 하면 아주 간단합니다. 텍스트 데이터용 딕셔너리 하나와 파일용 딕셔너리 하나를 정의하기만 하면 됩니다. 파일은 파일 이름과 바이너리 읽기 모드로 열린 객체를 포함하는 튜플로 전달해야 합니다.rb)와 MIME 콘텐츠 유형.
여기서 중요한 점은 매개변수를 전달할 때입니다. data y files 동시에 서점은 경계를 자동으로 구성합니다서버에 요청이 손상된 형태로 도착하는 것을 방지합니다.
자바스크립트와 Node.js
브라우저에서는 객체를 사용합니다. FormData우리는 단순히 필드를 추가합니다 append() 그리고 우리는 그 객체를 전달합니다. body 기능의 fetch. 그것은 매우 중요하다 Content-Type을 수동으로 설정하지 마십시오.이렇게 하면 브라우저가 기본적으로 생성하는 경계가 삭제되어 로드가 실패합니다.
Node.js에서도 상황은 비슷하지만, 보통 모듈을 사용합니다. form-data y axios이 경우에는 전화를 걸어야 합니다. form.getHeaders() 요청에 올바른 제목을 포함시키십시오.
실제 사례: Sora 2부터 Google Drive까지
각 서비스는 이 표준을 약간씩 다른 방식으로 구현합니다. 예를 들어, API는 다음과 같습니다. 소라 2 처리 오류를 방지하려면 업로드된 이미지의 해상도가 비디오 크기 매개변수와 정확히 일치해야 합니다.
반면에 API는 Google 드라이브 세 가지 업로드 레벨을 제공합니다. 단일 업로드는 메타데이터가 없는 작은 파일을 위한 것입니다. 멀티파트 업로드를 사용하면 여러 파일을 동시에 전송할 수 있습니다. JSON 형식의 메타데이터 및 파일 단일 요청으로 처리합니다(RFC 2387 준수). 대용량 파일의 경우 Google은 다음을 권장합니다. 재개 가능한 요금어떻게와 비슷하게 압축 파일 전송이를 통해 연결이 끊어지더라도 처음부터 다시 시작할 필요 없이 업로드를 복구할 수 있습니다.
오류 관리 및 최적화
413 오류(페이로드 크기가 너무 큼)가 발생하는 경우, 파일 크기가 서버에 설정된 제한(예: Nginx의 기본값인 1MB)을 초과했음을 의미합니다. 이 문제를 해결하려면 다음을 수행할 수 있습니다. 파일을 압축하다 또는 분할 업로드를 구현하십시오.
또 다른 일반적인 문제는 경계값이 누락되었을 때 발생하는 오류 400입니다. 경계값은 반드시 고유한 문자열이어야 한다는 점을 항상 기억하십시오. 신체에 나타나지 않습니다 서버 파서가 혼동하지 않도록 메시지의 일부를 생략하십시오. 이러한 오류를 디버깅하려면 다음을 사용하십시오. curl -v 이는 요청이 컴퓨터를 떠나기 전에 정확히 어떤 구조로 되어 있는지 확인할 수 있기 때문에 최선의 선택입니다.
궁극적으로 이 프로토콜을 사용하여 바이너리 데이터 전송을 숙달하면 복잡한 AI 및 스토리지 서비스를 효율적으로 통합할 수 있습니다. 핵심은... 올바른 도구를 사용하십시오 FormData나 Requests 라이브러리와 같은 라이브러리는 항상 경계 관리를 HTTP 클라이언트에 위임하여 API와의 통신이 원활하고 구문 분석 오류 없이 이루어지도록 합니다.
