# 플랫폼·모델 선택 데이터 규격

2026-09-11 · schema 1.0.0 · 공개 메타데이터 조사. 이 폴더는 데이터·명세·선택 견본이며 제품 DB를 변경하지 않는다.

**‘사용한 앱’, ‘모델’, ‘실행 제공자’를 독립된 값으로 저장한다.** 모델 선택에는 표시 이름만 저장하지 않고 정확한 저장소 ID와 사용 리비전을 남긴다. [선택 견본](../catalog.html) / [수집 모델 목록](MODEL_INDEX.md).

## 실제 조사 결과

[Hugging Face Models](https://huggingface.co/models), [공개 태그 API](https://huggingface.co/api/models-tags-by-type), 모델 상세 API를 직접 조회했다. 공개 모델 90개를 수집했다. 원문 README·채팅 템플릿·가중치·데이터셋 본문은 수집하지 않았다.

| 확인한 항목 | 수집량 | 우리 시스템의 사용 |
|---|---:|---|
| 모델 저장소 | 90 | 검색 가능한 초기 참조 목록. 전체 Hub 목록·품질 추천 아님 |
| 작업 유형 | 52 | HF ID 유지 + 한국어 라벨 + 상위 유형 7개 |
| 라이브러리 필터 | 53 | 고급 필터. GGUF 등 형식이 섞인 HF 원본 분류도 보존 |
| 라이선스 필터 | 82 | 라이선스 식별자 사전. 이용 가능 여부를 자동 판정하지 않음 |
| 앱 | 17 | HF Apps에서 직접 추출. 기존 앱 등 6개와 합쳐 플랫폼 23개 |
| 추론 제공자 | 18 | 플랫폼과 분리. 실제 표본 모델에서 확인된 제공자는 12개 |
| 언어 식별자 | 657 | ko/en/ja/zh/multilingual 및 표본의 명시 언어. 능력 평가 아님 |

전체 태그 API에는 언어 5,608개와 데이터셋 태그 2,683개 등도 있었다. 필요한 항목만 선택 사전으로 정리했으며 전체 원본 응답은 `hf-tags.snapshot.json`에 보관한다. 숫자는 저장한 조회 시점의 값이다. HF 모델 총수나 실시간 가용성을 고정값으로 쓰지 않는다.

수집은 12개 작업 유형별 다운로드 순 상위 12개를 조회하여 각 6개, trending 12개, `coder` 이름 검색 상위 12개 중 8개를 취합하고 중복을 제거했다. `trl-internal-testing/tiny-Qwen2ForCausalLM-2.5`는 명시적인 테스트 저장소 이름이어서 제외했다. 그 밖의 항목은 성능·안전성·원 개발사 검증을 거친 추천으로 취급하지 않는다. 질의별 반환 ID·순위·제외 이유는 `hf-discovery.snapshot.json`에 있다. `coder`는 검색어이며 HF의 독립 task ID가 아니다.

## 항목을 섞지 않는 기준

| 개념 | 예 | 저장 필드 |
|---|---|---|
| 작업에 사용한 앱/도구 | Cursor, Codex, Claude 앱, Claude Code, LM Studio | `platform.platformId` |
| 실행 라이브러리/런타임 | Transformers, Diffusers, llama.cpp, vLLM | 모델 `libraryId`, 플랫폼 `kind=runtime` |
| 모델 원본 저장소 | Qwen/Qwen3-0.6B | `modelId=hf:Qwen/Qwen3-0.6B` |
| 배포·양자화 변형 | 같은 계열의 AWQ/GGUF/MLX 저장소 | 별도 모델 ID와 원본 관계. 이름에서 변형을 제거하지 않음 |
| 추론 제공자 | Together AI, Groq, HF Inference API | `execution.providerId` |
| 모델 등록소 | Hugging Face Hub | 모델 `source=huggingface` |
| 작업 유형 | text-to-image, image-text-to-text | 모델 `taskId` |
| 우리 컴포넌트 카테고리 | 레이아웃 → 섹션 → 갤러리 | 별도 `categoryId`; HF task로 대체하지 않음 |
| 조절 위젯 | 열 수, 간격, 모서리 | 컴포넌트 `controls`; 모델/카테고리 항목 아님 |

HF의 Apps 그룹은 실행 런타임과 사용자 앱을 함께 포함한다. 원본 ID/라벨은 보존하고, 우리 `kind`는 해석값으로 표시한다. provider의 `task=conversational`은 Hub의 `pipeline_tag=text-generation`과 다른 어휘이므로 강제로 합치지 않는다.

## 모델 레코드와 출처

`models.schema.json`은 JSON Schema 2020-12다. `models.json`의 모든 필드를 닫힌 레코드로 정의한다. 필수 키를 생략하는 대신 확인할 수 없는 단일 값은 `null`, 미기재 집합은 `[]`로 저장한다. 누락을 ‘지원 안 함’으로 바꾸지 않는다.

| 필드 | 규칙 |
|---|---|
| `id`, `repoId`, `sourceObjectId` | `hf:` namespace, 원본 대소문자·슬래시 보존, HF 객체 ID도 보관 |
| `publisherNamespace`, `creatorVerified` | 게시 namespace와 원 개발사를 혼동하지 않음. 현재 개발사 인증 미수행 |
| `revision`, `updatedAt`, `retrievedAt` | 관찰한 commit SHA·서버 수정 시각·조회 시각을 분리 |
| `baseModelRepoIds`, `baseRelation` | 원본 관계는 다대다. 명시 메타/Hub 관계 태그와 근거 필드를 보존 |
| `taskId`, `libraryId`, `architectureType` | 직접 제공된 서로 다른 분류. 없는 task를 모델 이름으로 추정하지 않음 |
| `parameterCount`, `parameterCountEvidence` | API safetensors/gguf 숫자와 근거. 이름의 7B 등을 파싱하지 않음. 활성 파라미터 수와도 다름 |
| `languages`, `licenseIds`, `customLicense` | 카드 선언과 라이선스 태그. ‘한국어 능력 검증’·‘상업 사용 승인’으로 해석하지 않음 |
| `gated`, `private`, `disabled` | 메타데이터 접근 조건. gated=false도 추론 무료/무제한을 뜻하지 않음 |
| `providerOfferings[]` | 제공자·제공자 모델 ID·task·status·관찰 시각. 제공자와 모델은 다대다 |
| `metrics` | downloads/likes와 시각. 사용자 수·성능 점수로 쓰지 않음 |
| `selectionEvidence` | 어떤 조회에서 포함되었는지 추적. 품질 보증 아님 |

필터 사전에 없는 라이브러리 선언도 9종 관찰했다. `chatterbox`, `audio.cpp`, `Model Optimizer` 등은 `observedCustomLibraries`에 원문과 해당 저장소를 따로 보관한다. 공식 필터 목록에 없다는 이유로 정상 메타데이터를 삭제하지 않는다.

`selection.example.json`은 저장 구조를 보여 주는 가상 선택이며 실제 LM Studio 실행·호환성 검증의 증거가 아니다.

모델 2개의 task, 9개의 library, 45개의 language, 2개의 license, 20개의 parameterCount가 미기재였다. 원본 누락을 그대로 남겼다. 개별 응답 URL·조회 시각·응답 SHA-256과 필요한 원본 메타 필드는 `hf-models.snapshot.json`에 있다. 해시는 전체 수신 바이트 기준이며 저장한 투영 JSON의 해시로 주장하지 않는다. 갱신 시 모델 이름 변경은 `sourceObjectId`로 대조하고 별칭을 추가한다. 기존 게시물 ID/표시는 조용히 바꾸지 않는다.

## 선택 UX와 저장 규격

1. **사용한 앱/도구**를 선택한다. 목록에 없으면 도구명을 직접 입력한다.
2. **실제로 사용한 모델**을 검색한다. 결과는 정확한 repo ID·task·원본/변형 관계로 구별한다. 수십 개 항목을 한꺼번에 늘어놓는 select 대신 검색 결과를 제공한다.
3. 목록에 없으면 **직접 입력**, 자동 라우팅이면 **Auto**, 알 수 없으면 **모델 미확인**을 선택한다. Auto/미확인을 실제 모델 ID로 만들지 않는다.
4. 선택적으로 사용한 리비전·파일명·실행 제공자·제공자 모델 ID를 기록한다. 조회 당시 최신 SHA와 사용자가 실제 사용한 SHA는 다를 수 있으므로 사용 리비전을 자동 확정하지 않는다.
5. `selection.schema.json`으로 검증하고 게시물에 선택 당시 값을 보존한다. 조합/TXT에도 앱·정확한 모델 표기·알고 있는 실행 정보가 전달되어야 한다.

플랫폼을 선택했다고 HF 모델을 특정 앱의 ‘지원 모델’로 자동 연결하지 않는다. Hugging Face 목록에는 ChatGPT/Codex/Claude/Cursor의 완전한 모델 카탈로그가 없다. 이 앱들의 최신 독점 모델은 별도의 공식 자료 커넥터에서 수집해야 한다. 현재 데이터는 앱의 존재와 출처만 기록하며 비공개 모델명을 만들어 채우지 않는다. `unverifiedAppModelEdges=[]`가 이를 명시한다.

HF가 반환한 제공자 매핑도 조회 당시의 관찰이다. `hf_mapping_observed`는 사용 성공·권한·가격·앱 호환성 검증을 뜻하지 않는다. 매핑 없는 조합을 기록하면 `user_reported`로 보존한다. 나중에 실제로 생성·실행하는 서비스가 된다면 실행 직전 가용성 검사가 별도로 필요하다.

## 기존 시스템에 적용할 때

현재 `db/schema.ts`에는 platform/model/category 텍스트 컬럼, 게시 폼에는 플랫폼 고정 목록과 최대 100자 모델 입력이 있다. 이 조사에서는 제품 코드를 수정하지 않았다.

- 기존 platform/model 원문을 유지하면서 versioned `generationEnvironment` 선택 객체를 추가한다. 참조 카탈로그의 앱·모델·제공자 ID는 별도로 인덱싱한다.
- 모델 ID는 최소 256자 수용을 제안한다. 원래 이름을 잘라 저장하지 않는다. 표시만 줄이고 전체 이름을 읽을 수 있게 한다.
- 기존 Cursor/Codex/ChatGPT 값은 명확한 플랫폼 ID로 연결할 수 있다. 기존 `Claude`는 앱/Code 여부를 알 수 없어 원문을 보존하고 확인 대상으로 둔다.
- 기존 모델명은 exact ID 일치만 자동 연결한다. 비슷한 이름·제작사명·family 단위로 자동 합치지 않는다. 미일치 데이터는 custom으로 보존한다.
- 초기에는 원문과 ID를 함께 읽는 호환 단계를 둔다. 검증 후 쓰기 경로를 바꾼다. 오래된 기록은 현재 카탈로그에서 사라져도 표시 가능해야 한다.

## 갱신과 재현

다음 명령은 모두 이 디렉터리에서 실행한다. 첫 두 명령은 공개 HF 메타데이터 GET을 수행한다. 인증·추론·가중치 다운로드를 하지 않는다. 명령을 수동으로 실행할 때만 갱신하며 자동화는 등록하지 않았다.

```sh
python3 collect_huggingface.py
python3 collect_hf_filters.py
python3 build_catalog.py
python3 create_schemas.py
python3 validate_catalog.py
```

수집은 동시 요청 3개, 요청당 25초 제한, 429/일시적 서버 오류에 제한 재시도를 사용한다. 새 결과는 검증을 통과한 뒤 제품 카탈로그로 승인하는 것이 적용 계약이다. 현재 collector는 로컬 조사 스냅샷만 갱신한다. 자동 운영 때는 세대별 staging과 검증 후 원자적 활성화를 추가한다. 일부 조회 실패는 기록하고 성공한 빈 목록과 구별한다. 라이선스/가용성 등 변경은 기존 사용자 기록을 재작성하지 않는다.

## 근거

- [Hub API](https://huggingface.co/docs/hub/api): 공개 API와 rate limit, OpenAPI 명세 경로.
- [Model Cards](https://huggingface.co/docs/hub/model-cards): pipeline tag, library, language, license, base model 메타데이터.
- [Local Apps](https://huggingface.co/docs/hub/local-apps): 앱을 통한 로컬 모델 사용의 구분.
- [Inference Providers](https://huggingface.co/docs/inference-providers/index): 제공자별 모델 실행 경로.
- [Download Stats](https://huggingface.co/docs/hub/models-download-stats): 다운로드 지표의 집계 규칙. 성능 순위로 해석하지 않음.