LlamaIndex - Typecast Documentation

LlamaIndex란?

LlamaIndex는 컨텍스트 기반 LLM 애플리케이션을 구축하기 위한 Python 프레임워크입니다. 데이터 수집, 인덱싱, 쿼리 도구와 외부 도구를 사용할 수 있는 에이전트 기능을 제공합니다.

Typecast 도구를 사용하면 LlamaIndex 에이전트에서:

텍스트로부터 음성 생성 - 다양한 목소리로 커스터마이징 가능
감정 조절 - 행복, 슬픔, 화남, 속삭임 등 다양한 감정 표현
목소리 탐색 - 모델, 성별, 연령, 용도별 필터링
재현 가능한 오디오 생성 - seed 파라미터 활용

사전 요구사항

시작하기 전에 다음을 준비하세요:

요구사항	버전
Python	3.11+
LlamaIndex Core	0.13–0.14
타입캐스트 API 키	여기서 발급받기

설치

LlamaIndex용 Typecast 도구를 설치합니다:

pip install llama-index-tools-typecast

빠른 시작

LlamaIndex 에이전트에서 Typecast TTS를 사용하는 간단한 예제입니다:

from llama_index.tools.typecast import TypecastToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

# Typecast 도구 초기화
speech_tool = TypecastToolSpec(api_key="your-typecast-key")

# Typecast 기능을 가진 에이전트 생성
agent = FunctionAgent(
    tools=speech_tool.to_tool_list(),
    llm=OpenAI(model="gpt-4o-mini"),
)

# 에이전트를 통해 음성 생성
result = await agent.run(
    'Create speech from the text "Hello world!" with a happy emotion '
    'and output the file to "speech.wav"'
)
print(result)

제공되는 도구

TypecastToolSpec은 에이전트에서 사용할 수 있는 세 가지 도구를 제공합니다:

text_to_speech

텍스트를 음성으로 변환. 감정, 피치, 템포 조절 및 재현 가능한 결과 생성.

get_voices

선택적 필터링과 함께 사용 가능한 모든 Typecast 목소리 목록 조회.

get_voice

ID로 특정 목소리의 상세 정보 조회.

직접 사용 (에이전트 없이)

더 세밀한 제어가 필요한 경우 도구를 직접 사용할 수 있습니다:

목소리 탐색

from llama_index.tools.typecast import TypecastToolSpec

speech_tool = TypecastToolSpec(api_key="your-typecast-key")

# 선택적 필터로 사용 가능한 목소리 조회
voices = speech_tool.get_voices(
    model="ssfm-v30",
    gender="female",
    age="young_adult",
    use_case="Audiobook"
)
print(f"{len(voices)}개의 목소리를 찾았습니다")

for voice in voices:
    print(f"{voice['voice_name']} ({voice['voice_id']})")

목소리 상세 정보 조회

# 특정 목소리 정보 조회
voice = speech_tool.get_voice("tc_62a8975e695ad26f7fb514d1")
print(f"목소리: {voice['voice_name']}")
print(f"성별: {voice.get('gender')}, 연령: {voice.get('age')}")
print(f"용도: {voice.get('use_cases')}")

# 모델별 지원 감정 확인
for model in voice["models"]:
    print(f"모델 {model['version']}: 감정 = {model['emotions']}")

음성 생성

# 모든 파라미터를 사용한 텍스트-음성 변환
output_path = speech_tool.text_to_speech(
    text="안녕하세요! 테스트입니다.",
    voice_id="tc_62a8975e695ad26f7fb514d1",
    output_path="speech.wav",
    model="ssfm-v30",
    language="kor",
    emotion_preset="happy",
    emotion_intensity=1.5,
    volume=100,
    audio_pitch=0,
    audio_tempo=1.0,
    audio_format="wav",
    seed=42,  # 부호 없는 정수 시드 (재현 가능한 결과)
)
print(f"오디오 저장 완료: {output_path}")

기능

다양한 음성 모델

Typecast는 여러 AI 음성 모델 버전을 지원합니다:

모델	설명
`ssfm-v30`	향상된 감정 표현이 가능한 최신 모델 (권장)
`ssfm-v21`	하위 호환성을 위한 레거시 모델

감정 조절

생성되는 음성의 감정 표현을 조절할 수 있습니다:

감정	ssfm-v30	ssfm-v21
`normal`	✓	✓
`happy`	✓	✓
`sad`	✓	✓
`angry`	✓	✓
`whisper`	✓	-
`toneup`	✓	-
`tonedown`	✓	-

emotion_intensity (0.0 - 2.0)로 표현력을 조절합니다. 1.0보다 큰 값은 강도를 높입니다.

다국어 지원

Typecast는 27개 이상의 언어를 지원합니다:

영어 (eng)
한국어 (kor)
일본어 (jpn)
중국어 (zho)
스페인어 (spa)
그 외 다수...

오디오 커스터마이징

오디오 출력을 세밀하게 조정할 수 있습니다:

파라미터	범위	설명
`volume`	0 - 200	오디오 볼륨 (백분율)
`audio_pitch`	-12 ~ 12	반음 단위 조정
`audio_tempo`	0.5 - 2.0	재생 속도 (권장: 0.85 - 1.15)
`audio_format`	`wav`, `mp3`	출력 형식
`seed`	uint32	재현 가능한 오디오 생성을 위한 부호 없는 정수 시드 (≥ 0)

전체 에이전트 예제

목소리를 탐색하고 음성을 생성하는 에이전트의 전체 예제입니다:

import os
from llama_index.tools.typecast import TypecastToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

# API 키 설정
os.environ["OPENAI_API_KEY"] = "your-openai-key"

# Typecast 도구 초기화
speech_tool = TypecastToolSpec(api_key="your-typecast-key")

# Typecast 기능을 가진 에이전트 생성
agent = FunctionAgent(
    tools=speech_tool.to_tool_list(),
    llm=OpenAI(model="gpt-4o-mini"),
)

# 에이전트가 목소리를 탐색하고 음성을 생성하도록 요청
result = await agent.run(
    'Get the list of available voices, select the first female voice, '
    'and use it to create speech from the text "Welcome to Typecast!" '
    'with a happy emotion, saving to "welcome.wav"'
)
print(result)