LLM 스팬에 이미지와 오디오를 첨부하여 음성 에이전트 및 이미지 처리 에이전트의 문제를 해결하세요. 모델이 수신한 이미지를 검사하고, 트레이스 보기에서 다른 스팬 데이터와 함께 입력 및 출력 오디오를 직접 재생할 수 있습니다. 로그나 별도의 스토리지에서 상호 작용을 재구성할 필요가 없습니다. 음성 대화의 경우 각 턴의 대본을 오디오와 함께 볼 수 있습니다.
미디어는 LLM 스팬 내의 개별 메시지에 속합니다. 자동 계측은 지원되는 라이브러리에서 미디어를 캡처합니다. 다른 라이브러리의 경우 수동 계측을 사용하여 미디어를 첨부합니다. OpenTelemetry 스팬의 경우 OpenTelemetry 계측을 참조하세요.
요구 사항
다음 Datadog SDK 버전은 메시지에 미디어 첨부를 지원합니다. 자동 캡처에 대해서는 통합별 요구 사항을 참조하세요.
Nova 2 Sonic 및 ElevenLabs에는 ddtrace 4.17 이상이 필요합니다. Nova 2 Sonic에는 Python 3.12+ 및 aws-sdk-bedrock-runtime 0.11.0+도 필요하며, ElevenLabs에는 elevenlabs 2.70.0+가 필요합니다.
스트리밍된 채팅 완료(stream=True)의 오디오는 캡처되지 않습니다.
통합
캡처된 미디어
Datadog SDK 버전
OpenAI 채팅 완료
입력 input_audio 콘텐츠 및 출력 오디오(모델의 오디오 대본 포함)
v6: >= 6.7.0; v5: >= 5.118.0
OpenAI 에이전트
OpenAI 채팅 완료 형식을 통한 입력 및 출력 오디오
v6: >= 6.7.0; v5: >= 5.118.0
OpenAI Realtime API
턴별 입력 및 출력 오디오, 대본, 토큰 사용량 및 도구 호출
v6: >= 6.17.0; v5: >= 5.128.0
Amazon Nova 2 Sonic(@aws-sdk/client-bedrock-runtime)
턴별 입력 및 출력 오디오, 대본, 토큰 사용량 및 도구 호출
v6: >= 6.22.0; v5: >= 5.133.0
ElevenLabs Agents(WebSocket)
대화 입력 및 출력 오디오, 대본 및 클라이언트 도구 호출
출시 예정
스트리밍된 채팅 완료의 오디오는 캡처되지 않습니다.
자동 계측으로 캡처된 음성 대화 재생 및 턴 대본.
통합은 원격 URL이나 파일 ID로 참조되는 이미지를 가져오지 않습니다. 애플리케이션이 base64 데이터로 인라인 전송하는 이미지만 캡처합니다. 통합이 미디어를 캡처할 수 없는 경우 메시지에 [image] 또는 [audio]와 같은 텍스트 마커를 기록합니다.
mime_type과 인라인 바이트가 포함된 blob 파트는 이미지 또는 오디오 파트가 됩니다. modality가 생략되면 Datadog은 MIME 유형에서 이를 추론합니다.
base64 이미지 데이터 URI를 포함하는 uri 파트(예: data:image/png;base64,...)는 이미지 파트가 됩니다.
base64 바이트로 인라인 처리된 미디어만 렌더링됩니다. 원격 URL은 텍스트 참조로 기록되며 실제로 가져오지는 않습니다. 오디오 재생을 위해서는 오디오를 blob 파트로 전송하세요. 규칙은 인라인 base64 데이터에 대해 blob을 지정하므로 오디오와 이미지 모두에 blob을 사용하는 것이 좋습니다.
importbase64fromddtrace.llmobsimportLLMObsfromddtrace.llmobs.decoratorsimportllm@llm(model_name="gpt-4o",model_provider="openai")defdescribe_image(image_bytes):resp=...# multimodal (vision) LLM callLLMObs.annotate(input_data=[{"role":"user","content":"What is in this image?","image_parts":[{"mime_type":"image/png","content":base64.b64encode(image_bytes).decode("utf-8")}],}],output_data=[{"role":"assistant","content":"The image shows a golden retriever puppy."}],)returnresp
오디오 및 대본 첨부
importbase64fromddtrace.llmobsimportLLMObsfromddtrace.llmobs.decoratorsimportllm@llm(model_name="gpt-realtime",model_provider="openai")defvoice_turn(user_audio_bytes):resp=...# multimodal (audio) LLM callLLMObs.annotate(input_data=[{"role":"user","content":"Hey, how are you?",# transcript of the input audio"audio_parts":[{"mime_type":"audio/wav","content":base64.b64encode(user_audio_bytes).decode("utf-8")}],}],output_data=[{"role":"assistant","content":"Hey! I'm doing great, thanks for asking. How about you?","audio_parts":[{"mime_type":"audio/wav","content":base64.b64encode(resp.audio_bytes).decode("utf-8")}],}],)returnresp
미디어 파트에 mime_type 또는 content가 누락되면 주석 처리에 실패합니다.
Node.js는 camelCase 필드 이름인 imageParts 및 audioParts를 사용하며, 각 파트에 mimeType이 포함됩니다.
이미지 첨부
functiondescribeImage(imageBytes){constresp=...// multimodal (vision) LLM call
llmobs.annotate({inputData:[{role:'user',content:'What is in this image?',imageParts:[{mimeType:'image/png',content:imageBytes.toString('base64')}]}],outputData:[{role:'assistant',content:'The image shows a golden retriever puppy.'}]})returnresp}describeImage=llmobs.wrap({kind:'llm',modelName:'gpt-4o',modelProvider:'openai'},describeImage)
오디오 및 대본 첨부
functionvoiceTurn(userAudioBytes){constresp=...// multimodal (audio) LLM call
llmobs.annotate({inputData:[{role:'user',content:'Hey, how are you?',// transcript of the input audio
audioParts:[{mimeType:'audio/wav',content:userAudioBytes.toString('base64')}]}],outputData:[{role:'assistant',content:"Hey! I'm doing great, thanks for asking. How about you?",audioParts:[{mimeType:'audio/wav',content:resp.audioBuffer.toString('base64')}]}]})returnresp}voiceTurn=llmobs.wrap({kind:'llm',modelName:'gpt-audio',modelProvider:'openai'},voiceTurn)
mimeType 또는 content가 누락된 미디어 파트는 삭제됩니다. 메시지의 나머지 부분은 여전히 기록됩니다.
스팬 API 엔드포인트로 보내는 메시지 객체에 audio_parts 및 image_parts를 제출하세요. 필드 이름은 Python SDK와 일치합니다.
{"role":"user","content":"What is in this image?","image_parts":[{"mime_type":"image/png","content":"iVBORw0KGgoAAAANSUhEUgAA..."}]}
Trace Explorer에서 트레이스를 열고 LLM 스팬을 선택하세요. 스팬의 메시지에 첨부된 미디어는 해당 메시지 내부에 렌더링됩니다.
이미지는 썸네일로 표시됩니다. 썸네일을 선택하면 전체 크기 이미지가 열립니다. 메시지당 최대 12개의 이미지가 렌더링됩니다.
오디오는 플레이어로 표시되며 메시지 텍스트가 그 옆에 표시됩니다. 음성 대화의 경우 해당 텍스트는 턴 대본입니다. 플레이어를 선택하여 오디오를 로드하고 재생하세요.
지원되는 형식
MIME 유형이 image/png, image/jpeg, image/webp 또는 image/gif 중 하나이고 선언된 MIME 유형이 인코딩된 바이트와 일치할 때 이미지가 렌더링됩니다. SVG 이미지는 렌더링되지 않습니다. 트레이스 보기는 아웃바운드 요청을 수행하지 않으므로 원격 URL로 참조된 이미지는 가져오는 대신 텍스트로 표시됩니다.
오디오는 브라우저의 기본 오디오 플레이어를 통해 재생됩니다. 지원되는 컨테이너에는 audio/wav, audio/mpeg, audio/ogg 및 audio/webm이 포함됩니다. pcm16, g711_ulaw 및 g711_alaw와 같은 원시 형식은 재생되지 않습니다. 원시 오디오를 첨부하기 전에 WAV로 변환하세요. OpenAI Realtime API, Nova 2 Sonic 및 ElevenLabs용 자동 통합은 지원되는 원시 오디오를 WAV로 변환합니다.
제한 및 동작
스팬 이벤트 크기. 스팬 이벤트는 5MB로 제한됩니다. 스팬이 제한을 초과하면 입력 및 출력이 자리 표시자로 대체되고 dropped_io가 스팬의 collection_errors 속성에 추가됩니다. 스팬 자체는 유지됩니다.
파트별 크기. Python의 자동 계측은 단일 인라인 미디어 파트를 4MiB로 제한합니다. 제한을 초과하면 통합 기능이 [audio] 또는 [image omitted: too large]와 같은 텍스트 마커를 기록하고 주변 메시지 텍스트와 모델 응답을 보존합니다.
Sensitive Data Scanner. 미디어 콘텐츠는 Sensitive Data Scanner에 의해 스캔되지 않습니다. 메시지 텍스트, 도구 인수 및 도구 결과는 평소와 같이 스캔됩니다.
모범 사례
형식화된 미디어 필드를 사용하세요. 메시지의 content에 base64 문자열을 포함하는 대신 image_parts 및 audio_parts를 사용하여 미디어를 첨부하세요. 형식화된 필드만 트레이스 보기에서 렌더링됩니다.
오디오와 함께 대본을 첨부하세요. 오디오가 재생되기 전에도 스팬을 읽고, 검색하고, 평가자가 사용할 수 있도록 메시지 content를 턴 대본으로 설정하세요.