오디오 입력 전처리¶

이 페이지는 --audio 또는 API content part로 multimodal chat과 generation에 전달하는 오디오를 설명합니다. Whisper/Kokoro OpenAI 오디오 API와는 별도 경로입니다.

공통 입력 계약¶

CLI 파일과 서버가 해석한 바이트는 같은 엄격한 RIFF/WAVE decoder를 거칩니다. PCM16 또는 float32 WAV를 허용하고 비어 있거나 잘못되었거나 유한하지 않거나 예산을 넘는 입력을 거부합니다. 채널을 평균해 mono로 만들고 sample을 [-1, 1] 범위의 유한 f32 값으로 제한합니다. Clip 순서와 1부터 시작하는 placeholder 번호는 유지됩니다.

체크포인트 정책은 config.json과 processor_config.json 또는 preprocessor_config.json에서 파생합니다. 여기에는 목표 sample rate, duration/sample 제한, feature frame shape, channel/dtype 요구사항, clip 수, aggregate encoded-byte 한도, host-memory 예산이 포함됩니다. 잘못된 정책 metadata는 모델 시작을 실패시키며, 잘못된 요청은 조용히 text-only 요청으로 바뀌지 않고 실패합니다.

검증된 모델군¶

모델군	처리 정책	기본 요청 한도
Phi-4 Multimodal	Mono float32, 공개 SpeechLib integer-ratio resampler, 번호가 붙은 placeholder	최대 16개 clip, 합계 30분·28,800,000 normalized sample, 256 MiB encoded input
Gemma 3n	16 kHz mono float32, deterministic linear resampling, clip당 soft token 188개	최대 16개 clip, 합계 30초·480,000 normalized sample, 64 MiB encoded input

Phi 정책은 reference processor의 특이한 integer-ratio 동작을 generic linear resampler로 대체하지 않고 의도적으로 유지합니다. 다른 audio-capable 모델군은 공통 acquisition/admission 경계를 사용하면서 자체 전처리기를 가질 수 있습니다.

서버 입력 획득과 제한¶

모델별 처리에 앞서 서버 입력 획득 단계는 clip 16개, clip당·요청당 encoded audio 500 MiB라는 절대 상한을 적용합니다. URL Content-Length와 base64 크기 사전 검사는 큰 메모리를 할당하기 전에 명백히 큰 입력을 거부합니다. 그 뒤 로드한 모델의 더 엄격한 encoded byte, duration, sample, frame, clip, retained result, working memory, prepared result 예산을 요청 전체 합계에 적용합니다.

Image/audio URL 및 file access는 sandbox되지 않음

서버는 client가 제공한 http://·https:// image/audio URL을 대신 fetch하고 file:// 또는 bare local path를 읽으므로, API key는 caller를 인증할 뿐 server의 network/filesystem access를 제한하지 않습니다. Payload/model 예산이 적용되고, 목적지에 대해서는 두 정책이 걸립니다. 공인 주소가 아닌 곳으로 resolve되는 원격 URL은 MLXCEL_ALLOW_PRIVATE_MEDIA_URLS=1이 아니면 거부하고, 로컬 파일은 설정한 --media-path 루트 아래에서만 읽습니다. hostname allowlist나 HTTPS-only switch는 여전히 없고 --allowed-media-domains라는 옵션도 존재하지 않으므로, multimodal endpoint는 신뢰할 수 있는 client에만 노출하거나 reverse proxy, egress firewall, container/OS sandbox로 destination policy를 강제하십시오. Local video path에는 별도의 fail-closed MLXCEL_VIDEO_DIR_ALLOWLIST가 적용됩니다. 미디어 입력을 참조하십시오.

취소와 메모리 회계¶

Decode, resampling, CPU feature extraction 동안 취소를 확인합니다. Encoded input과 host working memory는 수락 시점부터 결과를 소비·취소·폐기할 때까지 하나의 RAII guard가 예약하므로 실패한 요청이 공유 예산을 누출하지 않습니다. 요청이 모델 실행에 진입한 뒤의 취소는 cooperative 방식이며 이미 진행 중인 device operation을 즉시 멈추지 못할 수 있습니다.

Metrics를 켜면 서버는 audio admission, byte, duration, frame, cancellation, 단계별 latency counter를 노출합니다. 이를 통해 acquisition 거부, preprocessing pressure, model execution latency를 구분할 수 있습니다.

CLI 예제¶

# Phi-4 Multimodal 오디오 질문
mlxcel generate -m ./models/phi-4-multimodal \
  --audio ./meeting.wav \
  -p "Summarize the discussion." -n 200

# Gemma 3n 오디오 입력
mlxcel run ./models/gemma-3n-e4b-it \
  --audio ./clip.wav \
  -p "What do you hear?"

표준 PCM16 또는 float32 WAV를 사용하십시오. 압축 형식은 mlxcel을 실행하기 전에 변환하십시오. 예: ffmpeg -i input.mp3 -ac 1 output.wav.