콘텐츠로 이동

파이프라인과 워크플로

VoicePipeline 클래스는 에이전트 워크플로를 음성 앱으로 손쉽게 전환할 수 있게 해줍니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오 전사, 오디오 종료 시점 감지, 적절한 타이밍에 워크플로 호출, 워크플로 출력을 다시 오디오로 변환하는 작업을 처리합니다

graph LR
    %% Input
    A["🎤 Audio Input"]

    %% Voice Pipeline
    subgraph Voice_Pipeline [Voice Pipeline]
        direction TB
        B["Transcribe (speech-to-text)"]
        C["Your Code"]:::highlight
        D["Text-to-speech"]
        B --> C --> D
    end

    %% Output
    E["🎧 Audio Output"]

    %% Flow
    A --> Voice_Pipeline
    Voice_Pipeline --> E

    %% Custom styling
    classDef highlight fill:#ffcc66,stroke:#333,stroke-width:1px,font-weight:700;

파이프라인 구성

파이프라인을 생성할 때 다음을 설정할 수 있습니다:

  1. 새 오디오가 전사될 때마다 실행되는 코드인 workflow
  2. 사용할 speech-to-text 및 text-to-speech 모델
  3. 다음과 같은 항목을 설정할 수 있는 config
    • 모델 공급자로, 모델 이름을 실제 모델에 매핑할 수 있음
    • 트레이싱으로, 트레이싱 비활성화 여부, 오디오 파일 업로드 여부, 워크플로 이름, 트레이스 ID 등
    • TTS 및 STT 모델의 프롬프트, 언어, 사용되는 데이터 타입 등의 설정

파이프라인 실행

파이프라인은 run() 메서드를 통해 실행하며, 오디오 입력을 두 가지 형태로 전달할 수 있습니다:

  1. AudioInput 은 전체 오디오 발화가 준비되어 있고 그 결과만 생성하면 되는 경우에 사용합니다. 이는 화자가 발화를 마쳤는지 감지할 필요가 없는 상황, 예를 들어 사전 녹음된 오디오나 푸시투토크 앱처럼 사용자의 발화 종료가 명확한 경우에 유용합니다
  2. StreamedAudioInput 은 사용자의 발화 종료를 감지해야 할 수 있는 경우에 사용합니다. 오디오 청크를 감지되는 대로 푸시할 수 있으며, 음성 파이프라인이 "activity detection" 과정을 통해 적절한 시점에 에이전트 워크플로를 자동으로 실행합니다

결과

음성 파이프라인 실행 결과는 StreamedAudioResult 입니다. 이는 이벤트가 발생하는 대로 스트리밍할 수 있는 객체입니다. VoiceStreamEvent 는 다음과 같은 종류가 있습니다:

  1. 오디오 청크를 담는 VoiceStreamEventAudio
  2. 턴 시작/종료와 같은 라이프사이클 이벤트를 알려주는 VoiceStreamEventLifecycle
  3. 오류 이벤트인 VoiceStreamEventError
result = await pipeline.run(input)

async for event in result.stream():
    if event.type == "voice_stream_event_audio":
        # play audio
    elif event.type == "voice_stream_event_lifecycle":
        # lifecycle
    elif event.type == "voice_stream_event_error"
        # error
    ...

모범 사례

인터럽션(중단 처리)

Agents SDK 는 현재 StreamedAudioInput 에 대해 내장된 인터럽션(중단 처리) 기능을 지원하지 않습니다. 대신 감지된 각 턴에 대해 워크플로를 별도로 실행합니다. 애플리케이션 내에서 중단 처리를 하고 싶다면 VoiceStreamEventLifecycle 이벤트를 청취할 수 있습니다. turn_started 는 새 턴이 전사되어 처리가 시작됨을 나타냅니다. turn_ended 는 해당 턴의 모든 오디오가 전송된 후에 트리거됩니다. 이러한 이벤트를 사용해 모델이 턴을 시작할 때 화자의 마이크를 음소거하고, 해당 턴에 대한 관련 오디오를 모두 전송한 뒤 음소거를 해제할 수 있습니다