AiHubMix에서 Jev 호출하기: 구조화된 분류 튜토리얼

짧은 답변: jev-1.13 은 텍스트를 생성하지 않습니다. 텍스트 조각과 명명된 질문 세트를 https://aihubmix.com/v1/systemone에 POST하면, 질문 이름에 따라 키가 지정된 답변을 받게 됩니다 — 카테고리, 점수 또는 확률. 파싱할 필요가 없습니다. 아래는 작동하는 요청, 전체 응답 형식, 그리고 조용히 정확성을 떨어뜨릴 수 있는 하나의 설계 실수입니다.

Jev의 용도

단락이 아닌 판단 이 필요할 때 사용하세요: 지원 티켓 라우팅, 심각도 점수 매기기, 긴급성 플래그 지정, 콘텐츠 게이팅. 모델 페이지는 이를 명확히 설명합니다 — "텍스트 생성 없음, 파싱할 필요 없음."

설명, 요약 또는 자유 형식 출력을 필요로 할 때는 일반 채팅 모델을 대신 사용하세요. jev는 이를 생성할 수 없습니다.

시작하기 전에

[ ] Python 3 설치됨 (표준 라이브러리면 충분함)
[ ] AiHubMix 계정 및 API 키
[ ] 키가 AIHUBMIX_API_KEY 로 내보내짐, 소스에 하드코딩하지 않음

OpenAI SDK, LangChain 또는 requests 패키지가 필요하지 않습니다.

1단계 — 엔드포인트 알기

POST https://aihubmix.com/v1/systemone
Authorization: Bearer YOUR_KEY
Content-Type: application/json

이것은 모델 전용 경로이며, 아니요 /v1/chat/completions. OpenAI 호환 클라이언트는 이를 호출할 수 없습니다. 일반 HTTP를 사용하세요.

2단계 — 질문 유형 선택

세 가지가 있으며, 하나의 요청에서 자유롭게 혼합할 수 있습니다:

유형	사용 용도	제공해야 할 것
`choice`	하나의 카테고리 선택	`criteria` 를 dict로: label → definition
`score`	정렬된 척도에서의 평가	`criteria` 를 리스트로, 낮은 것부터 먼저
`noul`	예/아니오 판단	그 외에는 아무것도 `instructions`

3단계 — 요청 구성하기

state 는 판단할 텍스트입니다. questions 키는 당신이 만든 이름입니다; 응답은 동일한 이름을 사용합니다.

payload = {
    "model": "jev-1.13",
    "state": "안녕하세요, 저는 3일 동안 제 Stripe 계정을 연결하려고 했지만 계속 실패하고 있습니다. 매출이 줄어들고 있습니다. 가능한 한 빨리 도와주세요.",
    "questions": {
        "department": {
            "type": "choice",
            "instructions": "어떤 팀이 이 문제를 처리해야 합니까",
            "criteria": {
                "billing":   "결제 또는 구독 문제",
                "technical": "버그 또는 통합 문제",
                "sales":     "가격 또는 계정 질문",
            },
        },
        "frustration": {
            "type": "score",
            "instructions": "고객이 얼마나 불만족해 보이는지",
            "criteria": [
                "차분하고 사실만 진술",
                "불만족하지만 예의 바름",
                "매우 화남, 강한 언어 사용",
            ],
        },
        "is_urgent": {
            "type": "noul",
            "instructions": "메시지가 긴급성 또는 시간 민감성을 전달하는지",
        },
    },
}

4단계 — 표준 라이브러리로 전송하기

import json, os, urllib.error, urllib.request

def ask(payload):
    req = urllib.request.Request(
        "https://aihubmix.com/v1/systemone",
        data=json.dumps(payload).encode(),
        headers={"Authorization": "Bearer " + os.environ["AIHUBMIX_API_KEY"],
                 "Content-Type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=60) as r:
            return json.loads(r.read())
    except urllib.error.HTTPError as e:
        raise SystemExit(f"HTTP {e.code}: {e.read().decode(errors='replace')[:500]}")

요청 구성을 함수 내에 유지하세요. 모듈 수준에서 빌드하고 전송하면 파일을 가져올 때 호출이 다시 발생하고 토큰이 소모됩니다.

5단계 — 답변 읽기

각 답변은 자신의 type 에 해당하는 키 아래에 값을 저장하므로 하나의 접근자가 세 가지를 모두 커버합니다:

data = ask(payload)
for name, ans in data["answers"].items():
    kind = ans["type"]
    print(name, kind, ans[kind], ans.get("confidence"))
print("usage:", data.get("usage"))

검증된 출력:

department   choice  billing   0.51
frustration  score   1         1
is_urgent    noul    1         None
usage: {'input_tokens': 424, 'output_tokens': 73}

6단계 — 전체 응답 이해하기

인쇄 루프는 유용한 필드를 숨깁니다. score 답변에 대한 원시 JSON:

{
  "type": "score",
  "score": 1,
  "legend": {"0": "차분하고 사실만 진술", "1": "불만족하지만 예의 바름", "2": "매우 화남, 강한 언어 사용"},
  "probabilities": {"0": 0, "1": 1, "2": 0},
  "confidence": 1
}

legend 는 인덱스를 당신의 용어로 다시 매핑합니다 — 정수는 스스로 설명하므로 코드에 조회 테이블이 필요하지 않습니다.
probabilities 는 전체 분포를 제공합니다. 이는 근접한 동점을 감지하는 데 유용합니다.
noul 은 confidence 필드가 없습니다. 그 확률이 신호입니다.

최상위 수준은 또한 usage, id, provider (TypeSafe), 그리고 해결된 백엔드 버전 typesafe/jev-1.13-20260917 를 반환합니다.

정확성을 떨어뜨리는 실수

위 요청에서 department 는 billing 을 0.51 의 신뢰도로 반환했습니다. 동일한 요청을 반복했을 때 0.38 의 신뢰도로 동일한 레이블이 반환되었습니다 — 답변은 안정적이었지만, 명시된 확신은 그렇지 않았습니다.

원인은 기준에 있으며, 모델에 있지 않습니다. billing 은 "결제 또는 구독 문제"이고 technical 은 "버그 또는 통합 문제"입니다. Stripe 통합 이 계속 실패 하는 것은 실제로 두 가지 모두에 해당합니다. 모델은 스키마에 작성된 모호성을 보고하고 있었습니다.

생산 전에 두 가지 규칙:

choice 기준을 상호 배타적으로 작성하세요. 사람이 두 레이블 사이에서 주저할 경우, 모델도 그렇게 할 것입니다.
신뢰도 임계값을 설정하고 낮은 신뢰도의 결과를 인간 대기열로 라우팅하여 이를 결정으로 수용하지 마세요. 불확실성을 인정하는 모델이 숨기는 모델보다 더 가치가 있습니다.

출시 전 체크리스트

[ ] 환경에서 키 로드 또는 VCS가 무시하는 600 모드 파일
[ ] choice 기준 중복 검토
[ ] 신뢰도 임계값 정의, 그 아래의 대체 경로 포함
[ ] noul 답변을 별도로 처리 — 신뢰도가 없습니다.
[ ] 사용되지 않는 질문 제거 (3개의 질문은 424 입력 토큰을 소모; 2개는 355 소모)
[ ] 원시 본문과 함께 비-2xx 응답 기록

자주 묻는 질문

OpenAI SDK를 사용할 수 있나요? 아니요. /v1/systemone 은 OpenAI 호환 경로가 아닙니다.

jev가 문장이나 요약을 반환할 수 있나요? 아니요. 정의한 질문에 대해서만 답변합니다.

요청당 몇 개의 질문을 할 수 있나요? 검증된 테스트에서는 두 개와 세 개를 사용했습니다. 각 질문은 입력 및 출력 토큰을 추가하므로, 행동할 것만 포함하세요.

버전 별칭이 있나요? 모델 페이지에는 jev-latest 별칭이 jev-1.13 옆에 나열되어 있습니다. 재현 가능성이 중요하다면 명시적인 버전을 고정하세요.

비용은 얼마인가요? 모델 페이지는 $0.0462 / M 입력 토큰과 $0 / M 출력 토큰을 게시합니다. 이는 공급업체 수치입니다 — 예산을 세우기 전에 현재 가격을 확인하세요.

컨텍스트 윈도우는 무엇인가요? 모델 페이지는 불일치합니다: 헤더에는 64K, 공급자 테이블에는 32K로 나와 있습니다. 의존하기 전에 자신의 가장 긴 입력과 비교하여 확인하세요.

이 가이드의 범위

위의 모든 내용은 단일 입력에 대해 세 번의 실시간 호출로 검증되었습니다. 지연, 배치, 처리량 또는 예제와 다른 입력에 대한 동작은 다루지 않습니다. 신뢰도 변동은 재현된 관찰이며, 측정된 오류율이 아닙니다 — 임계값을 설정하기 전에 자신의 데이터로 반복하세요.

AiHubMix에서 시작하기

jev-1.13 은 AiHubMix를 통해 사용할 수 있으며, 모델 페이지에는 이 튜토리얼에서 참조한 모든 내용이 포함되어 있습니다: /v1/systemone 엔드포인트, 세 가지 질문 유형과 그 criteria 형식, 전체 응답 필드, 그리고 $0.0462 / M 입력 토큰과 $0 / M 출력 토큰의 게시된 가격. jev-latest 별칭은 최신 릴리스로 해결되므로 버전이 변경되더라도 최신 상태를 유지합니다.

여기서 시작하세요: https://aihubmix.com/model/jev-latest

다음 단계:

AiHubMix 계정을 만들고 API 키를 생성하세요
3단계의 요청과 4단계의 ask() 함수를 복사하세요
state 를 자신의 큐에서 실제 레코드로 교체하세요
결과를 오늘날 그 레코드를 분류하는 방법과 비교하세요

이 가이드가 유용했다면, 구조화된 출력 모델 및 분류 파이프라인에 대한 향후 게시물을 구독하세요.