README_ko.md

<div align="center">
  <img class="block dark:hidden" src="assets/AX_K2_Raon_Logo_Black.png" alt="A.X-K2-Raon Logo" width="80%">
  <img class="hidden dark:block" src="assets/AX_K2_Raon_Logo_White.png" alt="A.X-K2-Raon Logo" width="80%">
</div>

# A.X K2 Raon-Speech

<p align="center">
  <a href="https://www.krafton.ai/"><img src="https://img.shields.io/badge/Homepage-KRAFTON%20AI-blue?style=flat&logo=google-chrome&logoColor=white" alt="Homepage"></a>
  <a href="https://krafton.ai/blog/posts/2026-06-30-ax-raon/ax-raon-kr.html"><img src="https://img.shields.io/badge/Tech%20Blog-A.X%20K2%20Raon-orange?style=flat&logo=rss&logoColor=white" alt="Tech Blog"></a>
  <a href="https://github.com/krafton-ai/Raon-Speech"><img src="https://img.shields.io/badge/GitHub-Raon-white?style=flat&logo=github&logoColor=black" alt="GitHub"></a>
  <a href="https://huggingface.co/KRAFTON"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-KRAFTON-yellow?style=flat" alt="Hugging Face"></a>
  <a href="https://creativecommons.org/licenses/by-nc/4.0/"><img src="https://img.shields.io/badge/License-CC%20BY--NC%204.0-lightgrey?style=flat" alt="License"></a>
</p>

<p align="center">
  <a href="https://huggingface.co/KRAFTON/A.X-K2-Raon-Speech-21B-A3B">English</a> | <b>한국어</b>
</p>

A.X K2 Raon-Speech는 약 21.2B의 전체 파라미터와 약 3.5B의 활성 파라미터를
갖는 영어/한국어 이중언어 음성 언어 모델(SpeechLM)입니다. SK텔레콤이 개발한
A.X K2 Light 20B-A3B mixture-of-experts 텍스트 backbone 위에 크래프톤이
독자 학습한 AuT 음성 인코더와 Mimi 계열 neural audio codec을 결합해, 음성
이해와 음성 생성을 하나의 멀티모달 모델로 통합했습니다. 크래프톤이
오픈소스로 공개한 음성 언어 모델
[Raon-Speech-9B](https://huggingface.co/KRAFTON/Raon-Speech-9B)의 recipe를
기반으로 학습되었습니다.

## Key Features

- **End-to-End 음성 언어 모델**: SK텔레콤의 A.X K2 Light 20B-A3B
  mixture-of-experts backbone 위에 구축된 21.2B 파라미터(활성 약 3.5B)
  멀티모달 모델입니다.
- **독자 학습 음성 모듈**: curated 데이터와 자체 파이프라인으로 학습한 AuT
  음성 인코더(약 317M 파라미터)와 Mimi 계열 neural audio codec(약 96M
  파라미터)을 사용합니다.
- **이중언어 지원**: 30B 이하급 공개 음성 언어 모델 중 한국어 종합 1위,
  영어 종합 3위를 기록했습니다.
- **멀티태스크 역량**: STT, TTS, SpeechQA, SpokenQA, turn 기반 멀티모달
  chat을 하나의 통합 모델에서 지원합니다.
- **Paralinguistic 인지**: 사용자 목소리에 담긴 감정, 억양 등의 정보를
  활용해 자연스러운 음성 답변을 생성합니다.
- **화자 목소리 conditioning**: ECAPA embedding을 통해 선택적 화자
  reference 오디오로 voice conditioning TTS를 지원합니다.
- **TTS Continuation**: Prefill 기반 continuation으로 reference 오디오에서
  운율이 자연스럽게 이어지는 음성을 생성합니다.

## Architecture

| Component | Configuration |
|---|---|
| Text backbone | A.X K2 Light 20B-A3B MoE, 48 layers, 2,048 hidden size |
| Experts | 128 routed experts, top-8 routing |
| Speech encoder | Qwen3-ASR 아키텍처 기반 독자 학습 AuT encoder, 24 layers, 약 317M 파라미터 |
| Speech codec | 독자 학습 Mimi 계열 codec, 약 96M 파라미터 |
| Codec configuration | 32 quantizers, 2,048-entry codebooks, 24 kHz, 12.5 frames per second |
| SpeechLM code interface | 입력 8 code groups, 생성 출력 16 code groups |
| Talker | Qwen3 기반 talker, 4 layers, 2,048 hidden size |
| Text-backbone context window | 최대 131,072 tokens |

핵심 음성 이해와 direct-TTS 경로에 필요한 모든 구성 요소는 checkpoint에
포함되어 있습니다. 화자 조건 TTS와 continuation TTS는 추가로 frozen
SpeechBrain ECAPA 화자 인코더를 사용하며, 최초 호출 시 자동으로
다운로드됩니다.

## Evaluation

평가는 음성 인식, 음성 합성, 음성 이해, 음성 질의응답, 텍스트 질의응답,
도구 호출 등 총 6개 영역에서 진행했으며, LibriSpeech, KsponSpeech,
VoiceBench, KVoiceBench, MMAU, KMMAU, API-Bank, FunctionChat-Bench 등을
포함해 한국어 24개, 영어 22개 등 총 46개의 벤치마크를 활용했습니다. 각
평가 결과를 0~1 범위로 정규화한 뒤 언어별 종합 점수를 산출했으며, 세부 평가
방법과 결과는
[크래프톤 AI 테크 블로그](https://krafton.ai/blog/posts/2026-06-30-ax-raon/ax-raon-kr.html)에서
확인할 수 있습니다.

30B 이하급 공개 음성 언어 모델 중 한국어 종합 성능 1위(0.72), 영어 종합
성능 3위(0.75)를 기록했습니다.

<div align="center">
  <img src="assets/ax-k2-raon-speech-fig1-radar.png" alt="A.X K2 Raon-Speech per-category benchmark radar" width="800">
</div>

카테고리별 성능이며, 각 점수는 0부터 해당 카테고리 최고 점수까지로
정규화되어 있습니다. 비교 모델은 아래 표의 영어 상위 모델 중 영어와
한국어를 모두 지원하는 모델입니다.

### Aggregate scores

| Korean Rank | Model | Korean | English | English Rank |
|---|---|---|---|---|
| 1 | **A.X K2 Raon-Speech** | **0.72** | **0.75** | **3** |
| 2 | Raon-Speech | 0.70 | 0.79 | 1 |
| 3 | Qwen3-Omni | 0.65 | 0.78 | 2 |
| 4 | HyperCLOVA X 8B Omni | 0.60 | 0.68 | 8 |
| 5 | MOSS-Audio | 0.58 | 0.62 | 13 |
| 6 | Qwen2.5-Omni | 0.55 | 0.73 | 5 |
| 7 | Fun-Audio-Chat | 0.53 | 0.69 | 7 |
| 8 | Step-Audio 2 mini | 0.32 | 0.67 | 10 |
| 9 | Interactive-Omni | 0.27 | 0.71 | 6 |
| 10 | Ming-Lite-Omni v1.5 | 0.21 | 0.68 | 8 |
| 10 | AF-Next | 0.21 | 0.65 | 11 |
| 12 | COVO-Audio | 0.18 | 0.41 | 15 |
| — | MiniCPM-o 4.5 | — | 0.74 | 4 |
| — | Kimi-Audio | — | 0.65 | 11 |
| — | Audio Flamingo 3 | — | 0.60 | 14 |

### Speech encoder

독자 학습한 AuT 음성 인코더는 Qwen3-ASR-1.7B AuT에 대해 보고된 약 4,000만
시간 대비 약 100만 시간의 오디오로 학습되었으면서도 SpeechLM subtask에서
Qwen3-ASR AuT에 필적하는 성능을 보입니다(Qwen AuT = 100% 기준 상대 성능).

| Task / Metric | English | Korean | Language Average |
|---|---|---|---|
| Speech Recognition | 96.7% | 104.6% | 100.7% |
| SpokenQA (Accuracy) | 90.3% | 104.8% | 97.6% |
| SpeechQA (Accuracy) | 98.8% | 100.2% | 99.5% |
| **Overall Language Average** | **95.3%** | **103.2%** | **99.2%** |

### Speech codec

독자 학습한 codec은 약 50만 시간의 오디오로 학습되어 Mimi 성능에
근접합니다(Mimi = 100% 기준 상대 성능). Moshi는 오디오 pretraining에 700만
시간 규모의 unsupervised corpus를 보고했습니다.

| Metric | English | Korean | Language Average |
|---|---|---|---|
| PESQ | 83.7% | 83.3% | 83.5% |
| ESTOI | 96.8% | 94.7% | 95.8% |
| Speech Recognition | 100.7% | 112.6% | 106.7% |
| Speaker Similarity | 96.9% | 99.6% | 98.3% |
| UTMOS | 94.4% | 95.7% | 95.1% |
| **Overall Language Average** | **94.5%** | **97.2%** | **95.9%** |

### Post-training ablations

<div align="center">
  <img src="assets/ax-k2-ablation-combined.png" alt="Post-training ablation results" width="800">
</div>

직전 checkpoint 대비, tool-use fine-tuning은 tool-call 점수를 0.543에서
0.740으로, paralinguistic self-distillation은 emotion/speaker 점수를
0.566에서 0.613으로 개선했으며, TTS direct preference optimization은 평균
TTS 오류율을 3.6%에서 3.1%로 낮췄습니다.

## Requirements

```bash
pip install -r requirements.txt

# Optional: lower-latency attention on supported CUDA systems
pip install flash-attn --no-build-isolation
```

`transformers>=4.57.1`이 필요합니다. 화자 조건 및 continuation TTS API에는
`speechbrain`이 필요합니다.

## Load the model

```python
from transformers import AutoConfig
from transformers.dynamic_module_utils import get_class_from_dynamic_module

MODEL_ID = "KRAFTON/A.X-K2-Raon-Speech-21B-A3B"

config = AutoConfig.from_pretrained(MODEL_ID, trust_remote_code=True)
RaonPipeline = get_class_from_dynamic_module(
    "modeling_raon.RaonPipeline",
    MODEL_ID,
    revision=getattr(config, "_commit_hash", None),
)

pipe = RaonPipeline(
    MODEL_ID,
    device="cuda",
    dtype="bfloat16",
)
```

BF16 checkpoint는 약 42.4 GB의 weights를 포함하므로 80 GB GPU 또는 적절한
multi-GPU 구성을 권장합니다.

## Usage

### Speech-to-text

```python
text = pipe.stt("audio.wav")
```

### Text-to-speech

```python
audio, sample_rate = pipe.tts("Hello, how are you?")
pipe.save_audio((audio, sample_rate), "output.wav")
```

### 화자 조건 TTS

```python
audio, sample_rate = pipe.tts(
    "안녕하세요. 만나서 반갑습니다.",
    speaker_audio="speaker_reference.wav",
)
pipe.save_audio((audio, sample_rate), "conditioned.wav")
```

### Reference 오디오로부터의 TTS continuation

```python
audio, sample_rate = pipe.tts_continuation(
    "And this is how the story continues.",
    ref_audio="reference.wav",
)
pipe.save_audio((audio, sample_rate), "continuation.wav")
```

### SpeechQA (오디오 context, 텍스트 질문)

```python
messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "context.wav"},
            {"type": "text", "text": "Please answer the question in this audio."},
        ],
    }
]

response = pipe.chat(messages)
```

### SpokenQA (오디오 context, 오디오 질문)

```python
messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "spoken_question.wav"},
        ],
    }
]

response = pipe.chat(messages)
```

## Training

공개된 checkpoint는 다음 과정을 거친 최종 모델입니다.

1. A.X K2 Light backbone을 고정한 상태의 speech-module alignment
2. Text-task mixing을 포함한 joint 멀티모달 supervised fine-tuning
3. A.X K2 Light로부터의 텍스트 및 cross-modal distillation
4. Speech-conditioned tool-use fine-tuning
5. Paralinguistic 행동을 위한 ParaBridge 계열 on-policy self-distillation
6. 생성 음성의 음절 늘어짐·반복, 불완전한 종결, 인식 오류를 줄이기 위한
   TTS direct preference optimization

Repository packaging과 추론 API는 영어·한국어 STT, direct TTS, 화자 조건
TTS, continuation TTS, SpeechQA, SpokenQA를 포함한 12개 smoke-matrix 호출로
end-to-end 검증되었습니다.

```bash
python validate_repo.py
python validate_model.py
```

## Intended use

이 checkpoint는 이중언어 음성 인식 및 생성, 음성 질의응답, 오디오 이해,
음성 기반 assistant 분야의 연구 및 비상업적 prototyping을 목적으로 합니다.
식별 가능한 화자가 관련된 voice conditioning이나 생성에 앞서 동의를 확보할
책임은 사용자에게 있습니다.

## Acknowledgments

This work was supported by the Ministry of Science and ICT (MSIT), Republic of
Korea, through the National IT Industry Promotion Agency (NIPA) (Grant No.
PJT-26-010018). This research was also conducted as part of the Sovereign AI
Foundation Model Project (Data Track), organized by the Ministry of Science and
ICT (MSIT) and supported by the National Information Society Agency (NIA),
Republic of Korea (Grant No. 2026-AIData-WII01).

## License

이 모델은 [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/)
라이선스로 공개됩니다. 함께 포함된 A.X K2 Light 구현 코드의 Apache License
2.0 notice는 해당 코드에만 적용됩니다.