번역

번역 (Translation)

경고: 음성 번역은 실험적 기능이에요.

AI SDK는 라이브 음성을 다른 언어로 번역하는 experimental_streamTranslate 함수를 제공해요. 번역은 스트리밍 전용 모달리티로, 모델이 라이브 소스 오디오를 대상 언어의 오디오와 텍스트로 번역해요.

experimental_streamTranslate는 음성 번역 모델 명세(Experimental_SpeechTranslationModelV4)를 기반으로 해요.

참고: 음성 번역 모델 명세의 provider 구현은 별도로 배포돼요. Experimental_SpeechTranslationModelV4를 구현하는 어떤 모델 인스턴스든 전달하세요 — 사용 가능한 번역 모델은 provider 문서를 참고하세요.

import { openai } from '@ai-sdk/openai';
import { experimental_streamTranslate as streamTranslate } from 'ai';

const result = streamTranslate({
  model: openai.translation('gpt-realtime-translate'),
  audio: audioStream, // ReadableStream<Uint8Array | string>
  inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
  targetLanguage: 'es',
});

for await (const part of result.fullStream) {
  if (part.type === 'output-text-delta') {
    process.stdout.write(part.delta);
  }

  if (part.type === 'audio') {
    // translated audio chunk (Uint8Array or base64 string)
  }

  if (part.type === 'source-transcript-final') {
    console.log('source:', part.text);
  }
}

console.log(await result.translationText);

audio 스트림은 원시 오디오 청크를 담고 있어야 해요. Uint8Array 청크는 원시 바이트, string 청크는 base64 인코딩된 원시 바이트예요. 보내는 청크에 맞게 항상 inputAudioFormat을 설정하세요.

targetLanguage(선택 sourceLanguage)는 BCP-47 스타일 언어 태그예요(예: en, es, fr-CA). 지원 값은 provider별로 다르며 provider가 검증해요.

sourceLanguage가 없으면 provider가 소스 언어를 자동 감지해요.

fullStream은 단일 소비자 라이브 스트림이라 한 번만 접근할 수 있어요. 스트림 파트와 최종 결과가 모두 필요할 때는 fullStream을 먼저 접근하고, 소비하면서 또는 소비한 뒤에 결과 promise를 await하세요. 결과 promise를 먼저 접근하면 내부적으로 스트림을 소비하므로 fullStream을 더 이상 쓸 수 없어요. 이는 라이브 오디오에 대해 무제한 재생 버퍼를 유지하지 않기 위해서예요.

최종 번역 메타데이터에 접근하려면:

const sourceText = await result.sourceText; // final source-language transcript
const translationText = await result.translationText; // final translated text
const durationInSeconds = await result.durationInSeconds; // duration of the source audio in seconds, if available
const usage = await result.usage; // audio/text token usage, if reported

번역 스트림은 audio 파트가 하나 이상 emit되거나 최종 출력 텍스트가 비어 있지 않을 때 성공으로 간주돼요. 오디오 출력만 생성하는 provider의 경우 translationText가 빈 문자열로 resolve될 수 있어요.

출처: 문서

본문

스트림 파트 (Stream parts)

fullStream은 다음 파트 타입을 내보내요:

• audio: 대상 언어로 된 번역 오디오 청크.
• output-text-delta: 추가 전용(append-only) 번역 텍스트 델타.
• output-text-final: provider가 정의한 세그먼트 또는 발화에 대한 최종 번역 텍스트.
• source-transcript-delta: 추가 전용 소스 트랜스크립트 델타.
• source-transcript-partial: 이후 파트에 의해 수정될 수 있는 비최종 소스 트랜스크립트 텍스트.
• source-transcript-final: provider가 정의한 세그먼트 또는 발화에 대한 최종 소스 트랜스크립트 텍스트.
• raw: includeRawChunks가 활성화됐을 때의 원시 provider 청크.
• error: 스트림 오류.

출력 텍스트는 추가 전용이에요: provider는 output-text-delta 파트를 스트리밍하고 발화별로 output-text-final로 확정해요. 현재는 설계상 출력 텍스트에 대한 partial/revision 파트가 없어요.

설정 (Settings)

출력 오디오 형식 (Output audio format)

번역 오디오 청크의 특정 오디오 형식을 요청하려면 outputAudioFormat을 사용하세요. 없으면 provider 기본 출력 형식이 사용돼요.

import { openai } from '@ai-sdk/openai';
import { experimental_streamTranslate as streamTranslate } from 'ai';

const result = streamTranslate({
  model: openai.translation('gpt-realtime-translate'),
  audio: audioStream,
  inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
  outputAudioFormat: { type: 'audio/pcm', rate: 24000 },
  targetLanguage: 'es',
});

provider별 설정 (Provider-Specific settings)

번역 모델은 종종 provider 또는 모델별 설정이 있는데, providerOptions 파라미터로 설정할 수 있어요.

import { openai } from '@ai-sdk/openai';
import { experimental_streamTranslate as streamTranslate } from 'ai';

const result = streamTranslate({
  model: openai.translation('gpt-realtime-translate'),
  audio: audioStream,
  inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
  targetLanguage: 'es',
  providerOptions: {
    openai: {
      // provider-specific options
    },
  },
});

Abort 신호 (Abort Signals)

번역을 취소하려면 abortSignal을 전달하세요:

import { openai } from '@ai-sdk/openai';
import { experimental_streamTranslate as streamTranslate } from 'ai';

const result = streamTranslate({
  model: openai.translation('gpt-realtime-translate'),
  audio: audioStream,
  inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
  targetLanguage: 'es',
  abortSignal: AbortSignal.timeout(60_000), // abort after 1 minute
});

오류 처리 (Error Handling)

experimental_streamTranslate가 번역을 만들 수 없을 때 — audio 파트가 emit되지 않고 최종 출력 텍스트가 비어 있거나, 스트림이 finish 이벤트 없이 끝나면 — AI_NoTranslationGeneratedError와 함께 오류가 나요.

이 오류는 문제를 기록하는 데 도움이 되도록 다음 정보를 보존해요:

• response: 음성 번역 모델 응답에 대한 메타데이터. timestamp, model, headers를 포함해요.
• cause: 오류의 원인. 더 상세한 오류 처리를 위해 사용할 수 있어요.

import { openai } from '@ai-sdk/openai';
import {
  experimental_streamTranslate as streamTranslate,
  NoTranslationGeneratedError,
} from 'ai';

try {
  const result = streamTranslate({
    model: openai.translation('gpt-realtime-translate'),
    audio: audioStream,
    inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
    targetLanguage: 'es',
  });

  console.log(await result.translationText);
} catch (error) {
  if (NoTranslationGeneratedError.isInstance(error)) {
    console.log('NoTranslationGeneratedError');
    console.log('Cause:', error.cause);
    console.log('Response:', error.response);
  }
}

번역 모델 (Translation Models)

위는 AI SDK provider가 지원하는 번역 모델의 일부일 뿐이에요. 더 자세한 내용은 각 provider 문서를 참고하세요.

더 알아보기 (Learn more)

• experimental_streamTranslate
• Transcription
• Speech
• Realtime