dspy.Audio
dspy.Audio
dspy.Audio는 DSPy의 오디오 입력 타입입니다. 데이터 URI 문자열, 원시 bytes(with audio_format=), numpy 계열 배열, {"data", "audio_format"} 딕셔너리, 또는 다른 Audio를 값으로 받을 수 있습니다.
출처: 문서
본문
dspy.Audio(*args, **data)
- Bases:
Type
DSPy의 오디오 입력 타입입니다.
인메모리 값에서만 생성합니다: 데이터 URI 문자열, 원시 bytes(with audio_format=), numpy 계열 배열, {"data", "audio_format"} 딕셔너리, 또는 다른 Audio. 원시 base64는 Audio(data=..., audio_format=...)로 전달합니다. 생성과 어댑터 파싱은 절대 파일시스템이나 네트워크에 접근하지 않습니다. 로컬 파일은 from_path, 원격 리소스는 from_url, 배열 데이터는 from_array를 사용하세요.
def __init__(self, *args, **data):
if len(args) > 1:
raise TypeError(f"Audio expected at most 1 positional argument, received {len(args)}")
if args:
if "data" in data:
raise TypeError("Audio received data as both a positional and keyword argument")
value = args[0]
sampling_rate = data.pop("sampling_rate", None)
audio_format = data.pop("audio_format", None)
if audio_format is not None and _carries_own_format(value):
raise TypeError(
"Audio received audio_format alongside an input that already carries its format; provide only one"
)
if sampling_rate is not None and not hasattr(value, "shape"):
raise TypeError("Audio received sampling_rate for a non-array input; it only applies to array data")
normalized = encode_audio(value, sampling_rate=sampling_rate or 16000, format=audio_format or "wav")
normalized.update(data)
data = normalized
super().__init__(**data)
소스 코드는 dspy/adapters/types/audio.py에 있습니다.
Methods
from_array(array, sampling_rate, format='wav') -> Audio (classmethod)
numpy 계열 배열을 처리해 base64로 인코딩합니다. 인코딩에 sampling rate와 오디오 형식을 사용합니다. soundfile이 필요하며, 없으면 ImportError를 발생시킵니다. sf.write로 PCM_16 서브타입 wav를 만든 뒤 base64로 인코딩합니다.
@classmethod
def from_array(cls, array: Any, sampling_rate: int, format: str = "wav") -> "Audio":
"""
Process numpy-like array and encode it as base64. Uses sampling rate and audio format for encoding.
"""
if not SF_AVAILABLE:
raise ImportError("soundfile is required to process audio arrays.")
byte_buffer = io.BytesIO()
sf.write(
byte_buffer,
array,
sampling_rate,
format=format.upper(),
subtype="PCM_16",
)
encoded_data = base64.b64encode(byte_buffer.getvalue()).decode("utf-8")
return cls(data=encoded_data, audio_format=format)
from_path(file_path: str) -> Audio (classmethod)
로컬 오디오 파일을 읽어 base64로 인코딩합니다. 파일이 없으면 ValueError("File not found")를, 오디오 MIME 타입이 아니면 ValueError를 발생시킵니다. MIME 타입에서 오디오 형식을 추출합니다.
from_url(url, verify=True, timeout=30.0) -> Audio (classmethod)
URL에서 오디오 파일을 다운로드해 base64로 인코딩합니다.
보안: 이 메서드는 명시적이고 호출자가 시작한 fetch를 수행하며, HTTP(S) 스킴을 요구하는 것 외에 SSRF 보호를 적용하지 않습니다.
requests.get처럼 private·loopback·cloud-metadata 호스트에 도달하고 그쪽으로 리다이렉트를 따라갑니다.url이 신뢰할 수 없는 입력에서 비롯된 경우 이 메서드를 호출하기 전에 호출자가 호스트를 allowlist에 대해 검증해야 합니다.
from_file(file_path: str) -> Audio (classmethod)
from_path의 deprecated 별칭입니다. Audio.from_file은 deprecated이며 3.4에서 제거될 예정이니 Audio.from_path를 사용하세요.
validate_input(values) -> Any (classmethod)
Audio 입력을 검증합니다. 딕셔너리에 'data'와 'audio_format' 키가 있어야 합니다.
format() -> list[dict[str, Any]]
오디오를 DSPy에 맞게 포맷합니다. {"type": "input_audio", "input_audio": {"data": ..., "format": ...}} 형태의 리스트를 반환합니다.
표준 상속 메서드
adapt_to_native_lm_feature(...), extract_custom_type_from_annotation(annotation), description(), serialize_model(), parse_lm_response(...), parse_stream_chunk(...), is_streamable() 등은 모든 커스텀 타입이 공유하는 base_type.py의 표준 메서드입니다. adapt_to_native_lm_feature는 LM과 설정이 네이티브 도구 호출·네이티브 추론 같은 관련 네이티브 LM 기능을 지원할 때 시그니처와 lm_kwargs를 그 기능에 맞게 적응시킵니다. extract_custom_type_from_annotation은 중첩된 annotation에서 모든 커스텀 타입을 추출합니다(예: list[dict[str, Tool]]에서 Tool 감지).