Deepgram Provider — Deepgram 프로바이더

Deepgram Provider — Deepgram 프로바이더

Deepgram의 전사(transcription)와 음성 생성(speech generation) API를 AI SDK에서 사용하는 방법을 알려드려요. Deepgram 프로바이더는 Deepgram 전사 및 음성 생성 API에 대한 언어 모델 지원을 포함해요.

출처: 문서

본문

Deepgram 프로바이더는 Deepgram 전사 및 음성 생성 API에 대한 언어 모델 지원을 포함해요.

설정 (Setup)

Deepgram 프로바이더는 @ai-sdk/deepgram 모듈에서 사용할 수 있어요. 다음으로 설치할 수 있어요:

npm install @ai-sdk/deepgram

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/deepgram에서 기본 프로바이더 인스턴스 deepgram을 import할 수 있어요:

import { deepgram } from '@ai-sdk/deepgram';

맞춤 설정이 필요하면 @ai-sdk/deepgram에서 createDeepgram을 import하고 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createDeepgram } from '@ai-sdk/deepgram';

const deepgram = createDeepgram({
  // custom settings, e.g.
  fetch: customFetch,
});

Deepgram 프로바이더 인스턴스를 맞춤 설정하는 데 사용할 수 있는 선택적 설정은 다음과 같아요:

• apiKey string — Authorization 헤더로 보내지는 API 키. 기본값은 DEEPGRAM_API_KEY 환경 변수예요.
• headers Record<string,string> — 요청에 포함할 커스텀 헤더.
• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response> — 커스텀 fetch 구현. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 사용하거나, 예를 들어 테스트용 맞춤 fetch 구현을 제공하는 데 사용할 수 있어요.

음성 모델 (Speech Models)

.speech() 팩토리 메서드로 Deepgram 텍스트-음성 API를 호출하는 모델을 만들 수 있어요.

첫 번째 인자는 음성 패밀리 ID예요: aura-2 (현재 세대) 또는 aura (Aura-1). 음성과 언어는 generateSpeech의 voice와 language 옵션으로 선택돼요 — 프로바이더가 업스트림 Deepgram 모델 ID를 <family>-<voice>-<language>로 조합해요 (언어 기본값은 en):

import { generateSpeech } from 'ai';
import { deepgram } from '@ai-sdk/deepgram';

const result = await generateSpeech({
  model: deepgram.speech('aura-2'),
  voice: 'thalia',
  language: 'en',
  text: 'Hello, world!',
});

전체 음성 모델 ID (예: deepgram.speech('aura-2-helena-en'))도 그대로 통과하지만, 위의 패밀리 ID + voice/language 형태가 권장되는 경로예요 — 다른 음성 프로바이더의 음성 선택과 일치해요.

providerOptions 인자로 추가 프로바이더 특정 옵션을 전달할 수도 있어요:

import { generateSpeech } from 'ai';
import { deepgram, type DeepgramSpeechModelOptions } from '@ai-sdk/deepgram';

const result = await generateSpeech({
  model: deepgram.speech('aura-2'),
  voice: 'helena',
  text: 'Hello, world!',
  providerOptions: {
    deepgram: {
      encoding: 'linear16',
      sampleRate: 24000,
    } satisfies DeepgramSpeechModelOptions,
  },
});

다음 프로바이더 옵션을 사용할 수 있어요:

• encoding string — 오디오 출력의 인코딩 타입. 지원 값: 'linear16', 'mulaw', 'alaw', 'mp3', 'opus', 'flac', 'aac'. 선택.
• container string — 출력 오디오의 컨테이너 형식. 지원 값: 'wav', 'ogg', 'none'. 선택.
• sampleRate number — 출력 오디오의 샘플 레이트(Hz). 지원 값은 인코딩에 따라 달라요: 8000, 16000, 24000, 32000, 48000. 선택.
• bitRate number | string — 오디오의 비트레이트(bits per second). mp3: 32000 또는 48000. opus: 4000에서 650000. aac: 4000에서 192000. 선택.
• callback string — Deepgram이 오디오와 함께 콜백 요청을 보낼 URL. 선택.
• callbackMethod enum — 콜백 요청의 HTTP 메서드. 허용 값: 'POST', 'PUT'. 선택.
• mipOptOut boolean — Deepgram Model Improvement Program에서 요청을 제외해요. 선택.
• tag string | array of strings — 사용량 보고 중 식별을 위해 요청에 라벨을 붙여요. 선택.

음성 결과는 providerMetadata.deepgram에 Deepgram 응답 세부 정보가 포함돼요: modelName (해석된 업스트림 모델), modelUuid, additionalModelUuids, charCount (청구된 문자 수), breaksApplied, pronunciationsApplied, pronunciationWarnings (있을 때), requestId.

generateSpeech의 speed 옵션은 Deepgram의 speed 파라미터로 전달돼요. Deepgram은 0.7–1.5 범위의 속도를 받아들이고 범위를 벗어난 값은 400 에러로 거부해요; speed는 모든 언어에서 지원되지는 않아요. instructions는 지원되지 않으며 경고와 함께 무시돼요.

모델 기능 (Model Capabilities)

모든 음성 이름과 악센트는 전체 음성 목록을 참고하세요.

전사 모델 (Transcription Models)

.transcription() 팩토리 메서드로 Deepgram 전사 API를 호출하는 모델을 만들 수 있어요.

첫 번째 인자는 모델 ID예요 (예: nova-3).

const model = deepgram.transcription('nova-3');

providerOptions 인자로 추가 프로바이더 특정 옵션을 전달할 수도 있어요. 예를 들어 summarize 옵션을 제공하면 콘텐츠 구간의 요약이 활성화돼요.

import { transcribe } from 'ai';
import {
  deepgram,
  type DeepgramTranscriptionModelOptions,
} from '@ai-sdk/deepgram';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: deepgram.transcription('nova-3'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    deepgram: {
      summarize: true,
    } satisfies DeepgramTranscriptionModelOptions,
  },
});

다음 프로바이더 옵션을 사용할 수 있어요:

• language string — 오디오의 언어 코드. 다양한 ISO-639-1 및 ISO-639-3 언어 코드를 지원해요. 선택.
• detectLanguage boolean — 자동 언어 감지 활성화 여부. true면 Deepgram이 오디오의 언어를 감지해요. 선택.
• smartFormat boolean — 전사에 스마트 포맷팅 적용 여부. 선택.
• punctuate boolean — 전사에 구두점 추가 여부. 선택.
• summarize enum | boolean — 전사의 요약 생성 여부. 허용 값: 'v2', false. 선택.
• topics boolean — 전사에서 토픽 감지 여부. 선택.
• detectEntities boolean — 전사에서 엔티티 감지 여부. 선택.
• redact string | array of strings — 전사에서 편집(redact)할 콘텐츠를 지정해요. 선택.
• search string — 전사에서 찾을 검색어. 선택.
• diarize boolean — 전사에서 서로 다른 화자를 식별할지 여부. 기본값은 false예요. Deepgram은 화자 분리(diarization)를 분당 추가 요금으로 청구한다는 점을 참고하세요. 선택.
• utterances boolean — 전사를 발화(utterance) 단위로 분할할지 여부. 선택.
• uttSplit number — 발화 분할 임계값. 선택.
• fillerWords boolean — 전사에 필러 단어(um, uh 등)를 포함할지 여부. 선택.
• paragraphs boolean — 전사를 문단으로 포맷팅할지 여부. 선택.
• intents boolean — 전사에서 의도(intent) 감지 여부. 선택.
• sentiment boolean — 전사에서 감정(sentiment) 분석 여부. 선택.
• keyterm string — 인식 정확도를 높일 핵심 용어. 선택.
• replace string — 편집된 콘텐츠를 대체할 문자열. 선택.

모델 기능 (Model Capabilities)

더 알아보기 (Learn more)

• AI SDK Core — 코어 기능
• OpenAI Provider — OpenAI 프로바이더