`experimental_streamTranslate()`

experimental_streamTranslate()

경고: experimental_streamTranslate는 실험적 기능이에요.

라이브 원시 오디오를 음성-대-음성 번역으로 스트리밍해요. 모델이 라이브 소스 오디오를 대상 언어의 오디오와 텍스트로 번역해요.

experimental_streamTranslate는 음성 번역 모델 명세(Experimental_SpeechTranslationModelV4)를 기반으로 해요. 이 명세의 provider 구현은 별도로 배포되므로, 사용 가능한 번역 모델은 provider 문서를 참고하세요.

import { experimental_streamTranslate as streamTranslate } from 'ai';

const result = streamTranslate({
  // any provider model instance that implements the experimental
  // speech translation model specification (Experimental_SpeechTranslationModelV4):
  model: translationModel,
  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);
  }
}

console.log(await result.translationText);

출처: 문서

본문

Import

import { experimental_streamTranslate as streamTranslate } from "ai"

API 시그니처 (API Signature)

파라미터 (Parameters)

이름 타입 선택 설명
model Experimental_SpeechTranslationModelV4 사용할 음성 번역 모델. 번역은 스트리밍 전용 모달리티예요. 실험적 음성 번역 모델 명세를 구현하는 provider 모델 인스턴스를 전달하세요. 문자열 모델 ID는 전역 provider(AI Gateway가 기본)가 음성 번역 모델을 지원할 때 이를 통해 해석돼요.
audio ReadableStream<Uint8Array | string> 번역할 원시 오디오 청크. Uint8Array 청크는 원시 오디오 바이트, string 청크는 base64 인코딩된 원시 오디오 바이트.
inputAudioFormat { type: string; rate?: number } 원시 오디오 청크의 입력 오디오 형식, 예: { type: "audio/pcm", rate: 24000 }. 지원 타입은 provider별로 다름(예: audio/pcm, audio/pcmu, audio/pcma).
targetLanguage string 오디오를 번역할 언어, BCP-47 스타일 언어 태그(예: en, es, fr-CA). 지원 값은 provider별로 다르며 provider가 검증해요.
sourceLanguage string 선택 소스 오디오 언어, BCP-47 스타일 언어 태그. 없으면 provider가 소스 언어를 자동 감지해요.
outputAudioFormat { type: string; rate?: number } 선택 번역 오디오 청크의 원하는 오디오 형식. 없으면 provider 기본 출력 형식이 사용돼요.
providerOptions Record<string, JSONObject> 선택 추가 provider별 옵션.
abortSignal AbortSignal 선택 호출을 취소하는 선택적 abort 신호.
headers Record<string, string> 선택 provider가 지원한다면 추가 HTTP/WebSocket 헤더.
includeRawChunks boolean 선택 true면 provider가 원시 provider 청크를 raw 파트로 스트림에 포함해요.

반환 (Returns)

이름 타입 설명
fullStream AsyncIterableStream<TranslationStreamPart> 번역 파트(audio, output-text-delta, output-text-final, source-transcript-delta, source-transcript-partial, source-transcript-final, raw, error)의 단일 소비자 라이브 스트림. 스트림 파트와 최종 결과가 모두 필요할 때는 결과 promise보다 먼저, 한 번만 접근해야 해요. 결과 promise를 먼저 접근하면 내부적으로 스트림을 소비해 fullStream을 쓸 수 없어요.
sourceText Promise<string> 입력 오디오의 최종 소스 언어 트랜스크립트.
translationText Promise<string> 대상 언어로 된 최종 번역 텍스트. 오디오 출력만 생성하는 provider는 빈 문자열로 resolve될 수 있어요.
durationInSeconds Promise<number | undefined> 가능하다면 소스 오디오 길이(초).
usage Promise<Experimental_SpeechTranslationModelV4Usage | undefined> provider가 보고한다면 번역 호출의 사용량 정보: inputAudioSeconds, inputAudioTokens, outputAudioTokens, inputTextTokens, outputTextTokens(모두 선택 number).
warnings Promise<Warning[]> 호출에 대한 경고(예: 지원되지 않는 설정). 스트림 시작 시, 또는 stream-start가 emit되지 않았다면 finish 시 빈 배열로 resolve돼요.
response Promise<SpeechTranslationModelResponseMetadata> 응답 메타데이터(timestamp, model ID, headers).
providerMetadata Promise<Record<string, JSONObject>> 추가 provider별 메타데이터.

참고: 결과 promise는 스트림이 소비되면서 settle돼요. fullStream 소비를 일찍 멈추면(예: 루프에서 break), 기본 provider 연결이 닫히고 대기 중인 결과 promise가 reject돼요.

더 알아보기 (Learn more)