콘텐츠로 이동

파이프라인 및 워크플로

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은 전체 오디오 전사가 있고 그에 대한 결과만 생성하려는 경우에 사용됩니다. 화자가 말하기를 마쳤는지 감지할 필요가 없는 경우에 유용합니다. 예를 들어, 사전 녹음된 오디오가 있거나 사용자가 말하기를 마친 시점이 명확한 push-to-talk 앱에서 사용할 수 있습니다.
  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는 해당 턴에 대한 모든 오디오가 전달된 후 트리거됩니다. 이러한 이벤트를 사용하여 모델이 턴을 시작할 때 화자의 마이크를 음소거하고, 해당 턴과 관련된 모든 오디오를 플러시한 뒤 음소거를 해제할 수 있습니다.