TCM ↔ AMD 라벨 연동 명세서

TAD 아웃바운드 오토콜은 모든 발신 통화의 녹취를 MinIO S3에 남깁니다. 여기에는 상대가 받는 응답 순간과 early-media(연결 전 음성)까지 포함됩니다 — 예: "연결이 되지 않아 소리샘으로 연결됩니다" 같은 통신사·사서함 안내 멘트까지 캡처됩니다.

TCM은 그 wav를 가져가(read) STT+LLM으로 8클래스 분류한 뒤, 같은 키(decision_id)로 결과를 써넣습니다(write). 우리는 이 라벨을 모아 AMD 모델의 학습 및 자기강화(self-reinforcing) 데이터셋으로 사용합니다.

모든 객체(오디오 · 컨텍스트 라벨 · 정정 결과)는 콜 단위 고유 ID인 decision_id로 키링됩니다. 따라서 전화번호나 통화 시각으로 별도 매칭을 할 필요가 전혀 없습니다.

decision_id는 UUID 형태의 불투명(opaque) 문자열입니다. 의미를 해석하지 말고 그대로 전달·보존하세요.

• (1) 나열: ListObjectsV2(prefix="amd/audio/"). 키 형식은 amd/audio/YYYY/MM/DD/{decision_id}.wav — 파일명(확장자 제외)이 decision_id.
• (2) 멱등 체크: ListObjectsV2(prefix="amd/corrections/{decision_id}/") 결과 객체들을 보고, 그중 method=="tcm"인 정정이 이미 있으면 재처리하지 않고 스킵.
• (3) 분석: wav를 GET으로 받아 STT+LLM으로 8클래스 분류.
• (4) write: 결과를 correction 객체로 PUT (다음 섹션 출력 스펙 참조).

// npm i @aws-sdk/client-s3
import { S3Client, ListObjectsV2Command, GetObjectCommand, PutObjectCommand }
  from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3intra.tlabs.team:9000",
  region: "us-east-1",
  forcePathStyle: true,                 // ★ MinIO 필수
  credentials: { accessKeyId: ACCESS_KEY, secretAccessKey: SECRET_KEY } // 안전채널로 수령
});
const BUCKET = "tad";

// 1) 오디오 나열 → decision_id 추출
async function listDecisionIds(token) {
  const r = await s3.send(new ListObjectsV2Command({
    Bucket: BUCKET, Prefix: "amd/audio/", ContinuationToken: token
  }));
  return {
    ids: (r.Contents || [])
      .filter(o => o.Key.endsWith(".wav"))
      .map(o => ({ key: o.Key, id: o.Key.split("/").pop().replace(".wav", "") })),
    next: r.IsTruncated ? r.NextContinuationToken : null
  };
}

// 2) 멱등: 이미 TCM이 처리했나?
async function alreadyDone(id) {
  const r = await s3.send(new ListObjectsV2Command({
    Bucket: BUCKET, Prefix: `amd/corrections/${id}/`
  }));
  for (const o of (r.Contents || [])) {
    const body = await getJson(o.Key);
    if (body && body.method === "tcm") return true;  // 스킵
  }
  return false;
}

// 3) wav 분석 → 4) 결과 write
async function processOne({ key, id }) {
  if (await alreadyDone(id)) return;
  const wav = await s3.send(new GetObjectCommand({ Bucket: BUCKET, Key: key }));
  const { klass, transcript, confidence } = await sttLlmClassify(wav.Body); // TCM 내부

  const result = {
    schemaVersion: 1,
    correction_of: id,
    "class": klass,                 // 8클래스 중 하나
    method: "tcm",
    confidence,                       // 0.0 ~ 1.0
    transcript,                       // STT 텍스트
    model: "tcm-stt-llm-v1",
    at: new Date().toISOString()      // ISO8601 UTC
  };
  await s3.send(new PutObjectCommand({
    Bucket: BUCKET,
    Key: `amd/corrections/${id}/${Date.now()}.json`,
    Body: JSON.stringify(result),
    ContentType: "application/json"
  }));
}

YYYY/MM/DD는 콜이 기록된 날짜 파티션이며, 파일명(확장자 제외)이 decision_id입니다.

이 JSON은 분석 정확도를 높이기 위한 힌트로만 쓰세요. 읽지 않아도 무방하며, 어떤 경우에도 수정 금지입니다(섹션 7 참조).

{epoch_ms}는 쓰기 시각의 epoch 밀리초(예: Date.now()). 같은 decision_id 폴더에 객체를 append하는 구조입니다.

{
  "schemaVersion": 1,
  "correction_of": "3f2a7c9e-1b4d-4a6f-8c11-9d0e2f5a7b33",
  "class": "voicemail_greeting",
  "method": "tcm",
  "confidence": 0.94,
  "transcript": "연결이 되지 않아 소리샘으로 연결됩니다. 삐 소리 후...",
  "model": "tcm-stt-llm-v1",
  "at": "2026-05-27T08:21:33.512Z"
}

S3에 직접 객체를 쓰는 대신 HTTP API로 결과를 제출하고 싶다면 아래 엔드포인트를 사용할 수 있습니다.

POST https://auto.tla.so/api/amd/label/{decision_id}
Content-Type: application/json

{
  "class": "<8클래스>",
  "method": "tcm",
  "confidence": 0.0,
  "transcript": "STT 텍스트"
}

• 배치 주기: 예시로 5~15분 간격 폴링. 신규 오디오만 집어 처리하므로 주기는 처리량에 맞춰 조정.
• 신규분만 처리(멱등): 매 배치마다 섹션 4 STEP 2의 멱등 체크로 이미 처리한 콜은 건너뜀. 재실행해도 안전.
• 동시성 / 레이트: 적정 동시 처리 수와 요청 레이트를 설정해 MinIO/네트워크에 과부하를 주지 않도록. (점진적으로 올려가며 조정 권장)
• 실패 시: 일시 실패는 지수 백오프 재시도, 반복 실패 건은 격리(quarantine)해 두고 다음 배치에서 다시 시도. 한 건 실패가 배치 전체를 멈추지 않도록.
• 로깅: 처리량 · 지연(latency) · 스킵/성공/실패 카운트를 로깅해 추이를 관찰.

우리 export 단계가 decision_id별로 라벨과 정정들을 모아 우선순위 규칙으로 최종 effective_class를 산출합니다. 우선순위는 다음과 같습니다.