언어 학습 앱은 화면상에서는 잘 작동하지만, 가장 어려운 부분은 화면이 피하는 것, 즉 실제로 소리 내어 말하고 자신이 맞게 말했는지에 대한 즉각적인 피드백을 받는 것입니다.

대부분의 음성 기반 언어 도구는 녹음된 내용을 재생하거나 사용자의 음성을 텍스트로 변환(Transcription)할 뿐입니다. 이들은 상호작용하는 루프(Loop) 안에서 이 두 가지를 모두 수행하지 않습니다. 저는 문장을 재생하고, 사용자가 그것을 따라 하는 것을 들은 뒤, 제대로 했는지 알려주는 무언가를 만들고 싶었습니다.

Telnyx 코드 예제는 다음과 같습니다:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/language-learning-flashcards-python

이것은 브라우저 UI를 갖춘 Python Flask 앱입니다. 전화번호도, 웹훅 터널(Webhook tunnel)도, 클라우드 스토리지(Cloud Storage)도 필요하지 않습니다.

루프 (The Loop)

이 앱은 하나의 상호작용적인 왕복 과정(Round-trip)에서 세 가지 Telnyx AI 프리미티브(Primitives)를 모두 사용합니다:

1. TTS가 말함 — Ultra 음성(스페인어는 Camila, 프랑스어는 Valerie)이 플래시카드 문장을 재생합니다. 오디오는 자동 재생됩니다.
2. 사용자가 반복함 — 'Record'를 클릭하고, 문장을 말한 뒤, 'Stop'을 클릭합니다.
3. STT가 텍스트로 변환함 — Whisper가 사용자의 음성을 텍스트로 변환(Transcription)합니다.
4. 추론(Inference)이 채점함 — Kimi-K2.6이 사용자의 변환된 텍스트를 목표 문장과 비교하여 정답(Correct), 유사(Close), 또는 오답(Wrong) 점수를 반환하며, 한 문장의 팁을 제공합니다.

하나의 플랫폼, 하나의 API 키로 외부 서비스 없이 작동합니다.

이것이 번역기와 다른 점

기존의 ai-content-translator-python 예제는 STT → 번역 → TTS 과정을 거칩니다. 이는 단방향입니다. 즉, 사용자가 말하면 앱이 번역합니다. 반면 이 예제는 상호작용적입니다. 앱이 사용자에게 말을 걸고, 사용자가 대답하면, 앱이 사용자를 평가합니다. 동일한 세 가지 Telnyx 프리미티브를 사용함에도 불구하고 흐름이 완전히 다릅니다.

음성 (The Voices)

이 앱은 language_boost를 사용하는 하나의 영어 음성이 아니라, 언어별로 네이티브 Ultra 음성을 사용합니다:

더 많은 언어를 추가하려면 GET /v2/text-to-speech/voices를 통해 음성 목록을 열거하고, app.py의 LANGUAGE_VOICE_MAP에 추가하세요.

채점 방식 (How the Scoring Works)

추론 (Inference) 호출은 Kimi에게 대상 문구와 사용자의 음성 텍스트를 비교하고 점수와 팁이 포함된 JSON을 반환하도록 지시하는 시스템 프롬프트 (System Prompt)를 사용합니다:

{"score": "correct", "feedback": "Great job, your pronunciation matched the target phrase perfectly!"}

Kimi-K2.6은 추론 모델 (Reasoning Model)입니다. 점수를 매기기 전에 생각하는 데 약 10초가 소요되지만, 결과는 단순한 문자열 비교보다 더 미묘한 차이를 반영합니다. 미세한 악센트 차이(correct), 잘못된 단어나 누락된 단어와 같은 눈에 띄는 오류(close), 그리고 완전히 틀린 발음(wrong)을 구분합니다.

데크 (The Decks)

앱에는 4개의 사전 구축된 플래시카드 데크 (Flashcard Decks)가 포함되어 있습니다:

app.py의 FLASHCARD_DECKS를 편집하여 더 추가할 수 있습니다. 각 카드에는 phrase (TTS가 말하고 사용자가 따라 하는 문구)와 translation (힌트로 표시되는 번역)이 있습니다.

실행 방법 (Run It)

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/language-learning-flashcards-python
cp .env.example .env    # TELNYX_API_KEY를 입력하세요
...

브라우저를 열고, 데크를 선택하고, 듣고, 따라 하고, 점수를 받으세요.

주의할 점 (One Thing to Watch)

Kimi-K2.6은 추론 모델 (Reasoning Model)입니다. JSON 점수를 생성하기 전에 생각하는 데 토큰 (Tokens)을 소비합니다. 만약 max_tokens가 너무 낮으면 (처음에 200으로 시도했습니다), 추론 과정 중에 토큰이 소진되어 빈 콘텐츠를 반환합니다. 해결 방법은 max_tokens: 1000으로 설정하는 것입니다. 이는 추론과 짧은 JSON 응답을 모두 처리하기에 충분한 양입니다. 이는 Kimi 특유의 동작입니다. Llama-3.3-70B와 같은 비추론 모델 (Non-reasoning model)은 200 토큰으로도 작동하겠지만, Telnyx에서는 Kimi 모델을 권장합니다.

관련 예제 (Related Examples)

관련 예제 (Related Examples)

• ai-language-learning-phone-tutor-python — 전화 기반 언어 튜터
• ai-content-translator-python — STT + 번역 + TTS 파이프라인
• multi-character-narrator-python — 감정을 담은 다중 음성 TTS