ENDPOINTS

카테고리 정규화기 V1

마켓별 카테고리를 스마트스토어 기준으로 자동 정규화합니다. 다국어 임베딩 모델과 벡터 유사도 검색으로 카테고리 경로뿐 아니라 자연어 입력도 가장 가까운 스마트스토어 카테고리로 매핑합니다.

POST/api/v1/category-normalize

작동 원리

e5-large 다국어 임베딩 모델이 입력 텍스트를 1024차원 벡터로 변환하고, 사전 인덱싱된 스마트스토어 카테고리 2,623개와 유사도를 비교하여 가장 가까운 카테고리를 반환합니다.

입력: "스포츠/레져>구기스포츠>당구/포켓볼"
        │
        ▼
  e5-large 임베딩 (1024차원 벡터 변환)
        │
        ▼
  FAISS 벡터 검색 (L2 distance, top_k개)
        │
        ▼
출력: "스포츠/레저>당구용품" (similarity: 0.895)

●

카테고리 경로 입력 — 다른 마켓의 카테고리 경로를 넣으면 높은 정확도(0.89~1.0)로 스마트스토어 카테고리 매칭

●

자연어 입력 — "삼성 에어컨 추천" 같은 일반 텍스트도 의미적으로 가장 가까운 카테고리를 검색 (유사도 0.85 수준)

●

재학습 불필요 — 새 카테고리 추가 시 임베딩만 계산하면 즉시 검색 가능. 모델 재학습이나 fine-tuning 없음

인증 (Authentication)

모든 요청에 x-api-key 헤더가 필요합니다.

vac-••••••••••••••••••••••••••••••••••••••••••••

API 키 발급 및 문의 사항은 고퍼소프트 관계자에게 문의하세요.

요청 파라미터 (Request Body)

Content-Type: application/json

파라미터	타입	필수	설명
`input_category`	string	required	정규화할 카테고리 경로 또는 자연어 텍스트
`top_k`	integer	optional	반환할 결과 수 (기본: 1, 범위: 1-10)

요청 예시

curl -X POST https://0-mac-studio-1.tailed52b5.ts.net/api/v1/category-normalize \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input_category": "스포츠/레저>당구용품", "top_k": 3}'

응답 스펙 (Response)

필드	타입	설명
`input_category`	string	입력 카테고리 경로
`results`	array	매칭된 카테고리 목록 (유사도 내림차순)
`results[].ss_id`	string	스마트스토어 카테고리 ID
`results[].ss_path`	string	스마트스토어 카테고리 경로
`results[].similarity`	number	코사인 유사도 점수 (0.0 ~ 1.0)
`latency_ms`	number	처리 시간 (ms)

유사도 해석 가이드

유사도 범위	의미	입력 유형 예시
≥ 0.95	정확 매칭 또는 거의 동일	동일한 카테고리 경로
0.85 ~ 0.94	매우 유사, 신뢰할 수 있음	다른 마켓의 유사 카테고리
0.75 ~ 0.84	관련 있으나 검증 권장	자연어 입력, 약간 다른 분류 체계
< 0.75	참고용, 수동 확인 필요	모호한 입력, 존재하지 않는 카테고리

에러 코드

코드	이름	설명
400	Bad Request	필수 파라미터 누락 또는 형식 오류
401	Unauthorized	API 키 누락 또는 무효
503	Service Unavailable	ML 서버 연결 실패
504	Gateway Timeout	요청 처리 시간 초과 (>30초)

성능 지표

정확도

실험 중

검증 진행 중

평균 응답

25ms

목표 100ms 이하

가용성

24/7

프로덕션

모델 스펙

모델명	e5-large (intfloat/multilingual-e5-large)
아키텍처	Transformer 기반 다국어 임베딩 (100+ 언어)
임베딩 차원	1024
인덱싱	FAISS (L2 distance)
카테고리 수	2,623개 (스마트스토어 마스터)
정확도	실험 중
추론 속도	평균 25ms (warm-up 후)
하드웨어	Apple Silicon MPS 가속

작동 원리

입력: "스포츠/레져>구기스포츠>당구/포켓볼"
        │
        ▼
  e5-large 임베딩 (1024차원 벡터 변환)
        │
        ▼
  FAISS 벡터 검색 (L2 distance, top_k개)
        │
        ▼
출력: "스포츠/레저>당구용품" (similarity: 0.895)

●

카테고리 경로 입력 — 다른 마켓의 카테고리 경로를 넣으면 높은 정확도(0.89~1.0)로 스마트스토어 카테고리 매칭

●

자연어 입력 — "삼성 에어컨 추천" 같은 일반 텍스트도 의미적으로 가장 가까운 카테고리를 검색 (유사도 0.85 수준)

●

재학습 불필요 — 새 카테고리 추가 시 임베딩만 계산하면 즉시 검색 가능. 모델 재학습이나 fine-tuning 없음

파라미터

타입

필수

설명

input_category

string

required

정규화할 카테고리 경로 또는 자연어 텍스트

top_k

integer

optional

반환할 결과 수 (기본: 1, 범위: 1-10)

curl -X POST https://0-mac-studio-1.tailed52b5.ts.net/api/v1/category-normalize \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"input_category": "스포츠/레저>당구용품", "top_k": 3}'

응답 스펙 (Response)

필드	타입	설명
`input_category`	string	입력 카테고리 경로
`results`	array	매칭된 카테고리 목록 (유사도 내림차순)
`results[].ss_id`	string	스마트스토어 카테고리 ID
`results[].ss_path`	string	스마트스토어 카테고리 경로
`results[].similarity`	number	코사인 유사도 점수 (0.0 ~ 1.0)
`latency_ms`	number	처리 시간 (ms)

유사도 해석 가이드

유사도 범위	의미	입력 유형 예시
≥ 0.95	정확 매칭 또는 거의 동일	동일한 카테고리 경로
0.85 ~ 0.94	매우 유사, 신뢰할 수 있음	다른 마켓의 유사 카테고리
0.75 ~ 0.84	관련 있으나 검증 권장	자연어 입력, 약간 다른 분류 체계
< 0.75	참고용, 수동 확인 필요	모호한 입력, 존재하지 않는 카테고리

코드

이름

설명

400

Bad Request

필수 파라미터 누락 또는 형식 오류

401

Unauthorized

API 키 누락 또는 무효

503

Service Unavailable

ML 서버 연결 실패

504

Gateway Timeout

요청 처리 시간 초과 (>30초)

모델 스펙

모델명	e5-large (intfloat/multilingual-e5-large)
아키텍처	Transformer 기반 다국어 임베딩 (100+ 언어)
임베딩 차원	1024
인덱싱	FAISS (L2 distance)
카테고리 수	2,623개 (스마트스토어 마스터)
정확도	실험 중
추론 속도	평균 25ms (warm-up 후)
하드웨어	Apple Silicon MPS 가속