Azure VoiceLive 클라이언트 라이브러리 for JavaScript - 버전 1.0.0-beta.1

Azure VoiceLive는 음성 상담원을 위한 저지연 고품질의 음성 간 상호작용을 가능하게 하는 관리형 서비스입니다. 이 서비스는 음성 인식, 생성형 AI, 텍스트-음성 변환 기능을 하나의 통합 인터페이스로 통합하여 원활한 음성 기반 경험을 위한 종단 간 솔루션을 제공합니다.

클라이언트 라이브러리를 사용하여 다음을 수행합니다.

실시간 음성 비서 및 대화형 에이전트를 만드세요
최소한의 지연 시간으로 음성 간 애플리케이션을 구축하세요
소음 억제와 에코 캔슬링 같은 고급 대화 기능을 통합하세요
다양한 사용 사례에 맞게 여러 AI 모델(GPT-4o, GPT-4o-mini, Phi)을 활용하세요
동적 응답을 위한 함수 호출 및 도구 통합을 구현하세요
시각적 요소와 함께 아바타 음성 상호작용을 생성하세요

참고: 이 패키지는 브라우저와 Node.js 환경 모두를 지원합니다. WebSocket 연결은 실시간 통신에 사용됩니다.

시작하기

현재 지원되는 환경

Node.js의 LTS 버전
Safari, Chrome, Edge 및 Firefox의 최신 버전

필수 조건

Azure 서비스 구독
Voice Live API 접근 기능이 있는 Azure AI Foundry 리소스

패키지 설치

npm을 사용하여 Azure VoiceLive 클라이언트 라이브러리를 설치하세요:

npm install @azure/ai-voicelive

식별 라이브러리 설치

VoiceLive 클라이언트는 Azure Identity Library를 통해 인증합니다. 설치도 하세요:

npm install @azure/identity

TypeScript 구성

TypeScript 사용자는 Node 타입 정의를 설치해야 합니다:

npm install @types/node

또한 tsconfig.json에서 활성화 compilerOptions.allowSyntheticDefaultImports 해야 합니다. 활성화 시 , allowSyntheticDefaultImports 기본값으로 활성화되어 있다는 점에 유의하세요compilerOptions.esModuleInterop.

JavaScript 번들

브라우저에서 이 클라이언트 라이브러리를 사용하려면 먼저 번들러를 사용해야 합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 번들링 설명서를 참조하세요.

주요 개념

보이스라이브 클라이언트

Azure VoiceLive 서비스와의 연결을 구축하는 주요 인터페이스입니다. 이 클라이언트를 사용해 실시간 음성 상호작용을 위한 인증 및 세션 생성에 사용하세요.

보이스라이브세션

실시간 음성 통신을 위한 활발한 WebSocket 연결을 나타냅니다. 이 수업은 양방향 통신을 다루며, 실시간으로 오디오 입력을 주고받고, 텍스트 전사, 기타 이벤트를 받을 수 있게 합니다.

세션 구성

이 서비스는 세션 구성을 통해 음성 상호작용의 다양한 측면을 제어합니다:

턴 감지: 사용자가 말을 시작하고 멈출 때 서비스가 어떻게 감지하는지 설정하세요
오디오 처리: 노이즈 억제 및 에코 캔슬링 활성화
음성 선택: 표준 Azure 음성, 고화질 음성, 또는 커스텀 음성 중에서 선택할 수 있습니다
모델 선택: 필요에 가장 적합한 AI 모델(GPT-4o, GPT-4o-mini, Phi 변형)을 선택하세요

모델 및 기능

VoiceLive API는 다양한 기능을 가진 여러 AI 모델을 지원합니다:

Model	Description	사용 사례
`gpt-4o-realtime-preview`	실시간 오디오 처리 기능이 있는 GPT-4o	고품질 대화형 AI
`gpt-4o-mini-realtime-preview`	경량 GPT-4o 변형	빠르고 효율적인 상호작용
`phi4-mm-realtime`	멀티모달 지원 Phi 모델	비용 효율적인 음성 애플리케이션

대화 개선사항

VoiceLive API는 Azure 특유의 향상된 기능을 제공합니다:

Azure Semantic VAD: 채우기 단어를 제거하는 고급 음성 활동 감지
소음 억제: 주변 배경 소음 감소
에코 캔슬링: 모델 자신의 목소리에서 에코를 제거합니다
턴 종료 감지: 조기 중단 없이 자연스러운 멈춤을 허용합니다

Azure Active Directory 사용으로 인증하기

VoiceLive 서비스는 API 요청을 인증하기 위해 Azure Active Directory에 의존합니다. @azure/identity 패키지는 애플리케이션에서 이 작업을 수행하는 데 사용할 수 있는 다양한 자격 증명 유형을 제공합니다. @azure/identity 대한 추가 정보는 시작하기 위한 자세한 내용과 샘플을 제공합니다.

Azure VoiceLive 서비스와 상호작용하려면 클래스의 VoiceLiveClient 인스턴스, 서비스 엔드포인트 , 그리고 자격증명 객체를 생성해야 합니다. 이 문서에 제시된 예시들은 , 로컬 개발 및 운영 환경을 포함한 대부분의 시나리오에 적합한 자격 증명 객체 DefaultAzureCredential를 사용합니다. 운영 환경에서 인증할 때 관리형 신원 사용을 권장합니다.

다양한 인증 방법과 해당 자격 증명 유형에 대한 자세한 정보는 Azure Identity 문서에서 확인할 수 있습니다.

간단한 예시를 하나 드릴게요. 먼저, 가져오기 DefaultAzureCredential 와 VoiceLiveClient:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();

// Build the URL to reach your AI Foundry resource
const endpoint = "https://your-resource.cognitiveservices.azure.com";

// Create the VoiceLive client
const client = new VoiceLiveClient(endpoint, credential);

API 키를 이용한 인증

개발 시나리오에서는 API 키를 사용해 인증할 수도 있습니다:

import { AzureKeyCredential } from "@azure/core-auth";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const endpoint = "https://your-resource.cognitiveservices.azure.com";
const credential = new AzureKeyCredential("your-api-key");

const client = new VoiceLiveClient(endpoint, credential);

예시

다음 섹션에서는 Azure VoiceLive를 사용하는 일반적인 작업 중 일부를 다루는 코드 스니펫을 제공합니다. 여기서 다루는 시나리오는 다음과 같습니다:

기본 음성 비서 만들기
세션 옵션 구성
실시간 이벤트 처리
함수 호출 구현

기본 음성 비서 만들기

이 예시는 음성 간 상호작용을 처리할 수 있는 간단한 음성 비서를 만드는 방법을 보여줍니다:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";

// Create the client
const client = new VoiceLiveClient(endpoint, credential);

// Create and connect a session
const session = await client.startSession("gpt-4o-mini-realtime-preview");

// Configure session for voice conversation
await session.updateSession({
  modalities: ["text", "audio"],
  instructions: "You are a helpful AI assistant. Respond naturally and conversationally.",
  voice: {
    type: "azure-standard",
    name: "en-US-AvaNeural",
  },
  turnDetection: {
    type: "server_vad",
    threshold: 0.5,
    prefixPaddingMs: 300,
    silenceDurationMs: 500,
  },
  inputAudioFormat: "pcm16",
  outputAudioFormat: "pcm16",
});

세션 옵션 구성

음성 상호작용의 다양한 측면을 맞춤 설정할 수 있습니다:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";
const client = new VoiceLiveClient(endpoint, credential);
const session = await client.startSession("gpt-4o-realtime-preview");

// Advanced session configuration
await session.updateSession({
  modalities: ["audio", "text"],
  instructions: "You are a customer service representative. Be helpful and professional.",
  voice: {
    type: "azure-custom",
    name: "your-custom-voice-name",
    endpointId: "your-custom-voice-endpoint",
  },
  turnDetection: {
    type: "server_vad",
    threshold: 0.6,
    prefixPaddingMs: 200,
    silenceDurationMs: 300,
  },
  inputAudioFormat: "pcm16",
  outputAudioFormat: "pcm16",
});

실시간 이벤트 처리

VoiceLive 클라이언트는 실시간 상호작용을 위한 이벤트 기반 커뮤니케이션을 제공합니다:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";
const client = new VoiceLiveClient(endpoint, credential);
const session = await client.startSession("gpt-4o-mini-realtime-preview");

// Set up event handlers using subscription pattern
const subscription = session.subscribe({
  onResponseAudioDelta: async (event, context) => {
    // Handle incoming audio chunks
    const audioData = event.delta;
    // Play audio using Web Audio API or other audio system
    playAudioChunk(audioData);
  },

  onResponseTextDelta: async (event, context) => {
    // Handle incoming text deltas
    console.log("Assistant:", event.delta);
  },

  onInputAudioTranscriptionCompleted: async (event, context) => {
    // Handle user speech transcription
    console.log("User said:", event.transcript);
  },
});

// Send audio data from microphone
function sendAudioChunk(audioBuffer: ArrayBuffer) {
  session.sendAudio(audioBuffer);
}

함수 호출 구현

음성 비서가 외부 기능과 도구를 호출할 수 있도록 활성화하세요:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";
const client = new VoiceLiveClient(endpoint, credential);
const session = await client.startSession("gpt-4o-mini-realtime-preview");

// Define available functions
const tools = [
  {
    type: "function",
    name: "get_weather",
    description: "Get current weather for a location",
    parameters: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "The city and state or country",
        },
      },
      required: ["location"],
    },
  },
];

// Configure session with tools
await session.updateSession({
  modalities: ["audio", "text"],
  instructions:
    "You can help users with weather information. Use the get_weather function when needed.",
  tools: tools,
  toolChoice: "auto",
});

// Handle function calls
const subscription = session.subscribe({
  onResponseFunctionCallArgumentsDone: async (event, context) => {
    if (event.name === "get_weather") {
      const args = JSON.parse(event.arguments);
      const weatherData = await getWeatherData(args.location);

      // Send function result back
      await session.addConversationItem({
        type: "function_call_output",
        callId: event.callId,
        output: JSON.stringify(weatherData),
      });

      // Request response generation
      await session.sendEvent({
        type: "response.create",
      });
    }
  },
});

Troubleshooting

일반적인 오류 및 예외

인증 오류: 인증 오류가 발생하면 다음을 확인하세요:

Azure AI Foundry 리소스가 올바르게 구성되어 있습니다
API 키나 자격 증명은 필요한 권한을 가지고 있습니다
엔드포인트 URL은 올바르고 접근 가능합니다

WebSocket 연결 문제: VoiceLive는 WebSocket 연결을 사용합니다. 다음 사항을 확인합니다.

네트워크에서 WebSocket 연결을 허용하세요
방화벽 규칙은 다음 연결로 인해 *.cognitiveservices.azure.com
브라우저 정책은 WebSocket과 마이크 접근을 허용합니다(브라우저 사용 시)

오디오 문제: 오디오 관련 문제:

브라우저에서 마이크 권한을 확인하세요
오디오 포맷(PCM16, PCM24)이 지원되는지 확인하세요
재생을 위해 적절한 오디오 컨텍스트 설정이 있는지 확인하세요

로깅 (로그 기록)

로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. WebSocket 메시지와 응답 로그를 보려면 환경 변수info를 AZURE_LOG_LEVEL 로 설정하세요. 또는 setLogLevel@azure/logger 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

로그를 사용하도록 설정하는 방법에 대한 자세한 지침은 @azure/로거 패키지 문서를 참조하세요.

다음 단계

다음 링크에서 더 많은 코드 샘플을 찾으실 수 있습니다:

Contributing

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-18