고객이 떠나기 전 이탈(Churn) 예측하기

부제: Telnyx AI Inference를 사용하여 고객 활동 신호를 이탈 위험, 권장 조치 및 유지(Retention)를 위한 다음 단계로 전환하는 Python 앱을 구축합니다.

대부분의 고객 이탈(Churn)이 놀랍게 느껴지는 이유는 신호들이 흩어져 있었기 때문입니다.

한 곳에서는 사용량이 감소했습니다. 다른 곳에서는 지원 티켓(Support tickets)이 증가했습니다. 갱신 날짜가 다가왔습니다. 2주 동안 로그인이 발생하지 않았습니다. 결제 문제가 나타나기 시작했습니다. 이러한 신호 중 어느 하나만으로는 고객이 떠난다는 것을 증명할 수 없지만, 이들이 모이면 대개 하나의 이야기를 들려줍니다.

그것이 바로 제가 구축을 더 쉽게 만들고 싶었던 워크플로(Workflow)입니다. 고객 활동 데이터를 가져와 추론 모델(Inference model)을 통과시킨 후, 제품 팀이나 고객 성공(Customer success) 팀이 실제로 사용할 수 있는 구조화된 이탈 평가를 반환하는 것입니다.

예제는 여기에 있습니다:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-customer-churn-predictor-python

이것은 chat-completions API를 통해 Telnyx AI Inference를 사용하는 작은 Flask 앱입니다.

앱 구조

앱은 몇 가지 라우트(Route)를 노출합니다:

POST /predict: 고객 한 명에 대한 예측
POST /predict/batch: 최대 20명의 고객에 대한 배치(Batch) 예측
GET /predictions: 최근 인메모리(In-memory) 예측 결과
GET /health: 앱 상태 확인

현재 기본 모델은 .env.example에 설정되어 있습니다:

AI_MODEL=moonshotai/Kimi-K2.6

내부적으로 앱은 다음을 호출합니다:

POST https://api.telnyx.com/v2/ai/chat/completions

프롬프트(Prompt)는 모델에게 고객 성공 분석가(Customer success analyst)처럼 행동하고 JSON만 반환하도록 요청합니다. 이 부분이 중요합니다. 이것은 챗봇(Chatbot)이 아닙니다. 구조화된 출력(Structured output)을 생성하는 애플리케이션 엔드포인트(Endpoint)입니다.

입력 데이터

요청은 다음과 같이 보일 수 있습니다:

curl -X POST http://localhost:5000/predict \
  -H "Content-Type: application/json" \
  -d '{
...

이 필드들은 의도적으로 단순하게 구성되었습니다. 핵심은 패턴을 보여주는 것이지, 이것이 완전한 엔터프라이즈급 이탈 모델인 척하는 것이 아닙니다.

모델은 트렌드 데이터(trend data), 지원 컨텍스트(support context), 계정 생성 기간(account age), 갱신 주기(renewal window), 최근 로그인 시점(login recency), 결제 문제(payment issues)를 전달받습니다. 그런 다음 위험도(risk), 확률(probability), 위험 요인(risk factors), 권장 조치(recommended actions), 긴급도(urgency), 그리고 위험 노출 매출 컨텍스트(revenue-at-risk context)를 반환합니다.

이 응답은 대시보드에 데이터를 공급하거나, 고객 성공(customer success) 태스크를 트리거하거나, 검토 큐(review queue)를 생성하거나, 더 큰 리텐션(retention) 워크플로우의 일부가 될 수 있습니다.

이 패턴을 선호하는 이유

많은 AI 제품 아이디어들이 빈 채팅창(blank chat box)에서 시작됩니다.

하지만 유용한 많은 AI 앱들은 빈 채팅창이 아닙니다. 이들은 명확한 입력(input)과 명확한 출력(output)을 가진 작은 의사결정 엔드포인트(decision endpoints)입니다.

이탈(churn) 예측의 경우, 출력 형태(output shape)가 중요합니다:

{
  "churn_risk": "high",
  "probability": 0.82,
...

이는 긴 문단(paragraph)보다 구축하기가 더 쉽습니다. 데이터를 정렬, 저장, 검증, 라우팅하거나 제품 내에 표시할 수 있기 때문입니다.

중요한 작은 디테일

앱은 JSON을 요청하지만, 여전히 모델의 출력을 주의 깊게 다룹니다.

파싱(parsing)하기 전에 마크다운 펜스(markdown fences)를 제거하고 JSON 객체를 추출하는 헬퍼(helper)가 포함되어 있습니다. 이것이 바로 AI 앱에서 원하는 방식입니다. 프롬프트(Prompt)가 도움이 되긴 하지만, 검증(validation)은 여전히 중요합니다.

이 샘플은 개발자가 한 파일에서 전체 흐름을 검사할 수 있도록 구현 내용을 읽기 쉽게 유지합니다.

다음에 추가하고 싶은 것들

이 예제는 로컬에서 쉽게 실행할 수 있도록 인메모리 저장소(in-memory storage)를 사용합니다. 실제 운영 환경(production)이라면 다음과 같은 것들을 추가하겠습니다:

예측 데이터를 위한 지속성 저장소(Persistent storage)
API 경로에 대한 인증(Auth)
실제 고객 데이터 소스
엄격한 스키마 검증(Strict schema validation)
큐(queue)를 통한 배치 처리(Batch processing)
고위험 계정에 대한 알림(Alerting)
고객 대상 개입 전 인간의 검토(Human review)

또한 이 리포지토리(repo)는 에이전트가 읽을 수 있도록 구조화되어 있습니다. 즉, 여러분의 코딩 에이전트(coding agent)가 README, API 레퍼런스, 가이드, 환경 파일(environment file), 앱 코드를 검사한 뒤 기능을 확장하는 것을 도와줄 수 있다는 뜻입니다. 에이전트에게 지속성 기능을 추가하거나, 테스트를 작성하거나, 출력을 CRM에 연결하거나, 배치 엔드포인트를 예약된 워크플로우로 전환해 달라고 요청할 수 있습니다.