🐍05. 스트리밍·구조화 출력·멀티모달 입력

사용자 체감 속도를 높이려면 스트리밍이 필요하고, 운영 안정성을 높이려면 구조화 출력이 필요합니다. 여기에 이미지·문서 같은 멀티모달 입력까지 붙으면 실서비스 형태에 가까워집니다.

AI 활용 안내: 이 문서는 생성형 AI를 활용해 작성했으며, Pydantic AI 공식 문서를 1차 출처로 검토해 정리했습니다.

공식문서 흐름 점검 (개요 보완)

• 흐름: 스트리밍 이벤트 설계 → 구조화 출력 모드 선택/검증 → 멀티모달 입력(이미지·오디오·문서) 지원 모델 확인 → 업로드/URL 입력 전략 선택.
• 이번 편에서 빠지면 안 되는 포인트:
  • 스트리밍 속도와 구조화 검증을 분리해 설명한다.
  • 입력 타입별(provider별) 지원 차이를 개요에서 먼저 경고한다.
  • streamed result와 최종 결과 확정 시점을 명확히 구분한다.
• 공식 문서 체크 링크:
  • https://ai.pydantic.dev/output/index.md
  • https://ai.pydantic.dev/input/index.md
  • https://ai.pydantic.dev/agent/index.md

세 가지를 같이 봐야 하는 이유

• 스트리밍: 기다림을 줄여 UX 개선
• 구조화 출력: 후처리 자동화 안정화
• 멀티모달 입력: 텍스트 밖의 실제 업무 데이터 수용

공식 문서:

• Agent streaming: https://ai.pydantic.dev/agent/
• Output streaming: https://ai.pydantic.dev/output/
• Input types: https://ai.pydantic.dev/input/

flowchart LR
  A[텍스트/이미지/문서 입력] --> B[Agent run_stream]
  B --> C[중간 토큰/이벤트 전달]
  C --> D[최종 구조화 결과 검증]
  D --> E[UI/자동화 파이프라인 전달]

미니 사례 A: 응답이 20초 걸려 사용자 이탈이 생긴 경우

최종 답변만 한 번에 보내던 챗 화면에서 이탈률이 높았습니다. 스트리밍으로 진행 상황을 먼저 보여주자, 같은 처리 시간이어도 이탈이 줄었습니다.

미니 사례 B: 스트리밍은 빠른데 후처리가 자주 깨진 경우

텍스트 위주 출력으로는 파서가 자주 실패했습니다. 마지막 결과만큼은 output_type으로 고정해 UI 파이프라인 오류를 줄였습니다.

실무 적용 순서

1. 사용자-facing 채널은 스트리밍 우선 도입
2. 저장/연동 구간은 구조화 출력 강제
3. 파일 입력(문서/이미지) 1개 시나리오부터 시작

성공 판정:

• 사용자 체감 대기 시간이 줄었다
• 후처리 파싱 오류율이 내려갔다
• 멀티모달 입력 1개를 안정적으로 처리한다

다음 글

• 🐍06. 멀티에이전트·A2A 패턴
• 🐍04. 메시지 히스토리·Retry·에러 복원
• 🐍 PydanticAI 허브