Model Serving Contract

Sprint 2 Handoff Package

mobile_artifacts/fp16/
  mobileclip2_s3_server_full_ce_hardneg_image_encoder_fp16_mixed.onnx
  mobileclip2_s3_server_full_ce_hardneg_image_encoder_fp16_mixed.onnx.data
  mobileclip2_s3_server_full_ce_hardneg_text_encoder_fp16_mixed.onnx
  mobileclip2_s3_server_full_ce_hardneg_text_encoder_fp16_mixed.onnx.data
  preprocessing.json
  tokenizer.json
  tokenizer_bundle.json
  text_index.json
  text_search_policy.json
  text_query_regression_set.json
  text_search_eval_report.json
  confidence_policy.json
  prototype_index.json
  classes.json
  labels_master.json
  manifest.json
  config.yaml

.onnx와 .onnx.data는 한 쌍이다. 둘 중 하나라도 빠지면 모델을 로드할 수 없다. 이미지 검색은 image encoder와 prototype_index.json를 사용하고, 텍스트 검색은 tokenizer_bundle.json으로 만든 text_tokens를 text encoder에 넣어 512차원 text embedding을 얻은 뒤 text_index.json과 비교한다.

GitHub main에는 manifest.json, classes.json, prototype_index.json, text_index.json, tokenizer_bundle.json, policy/eval JSON처럼 작은 계약 파일만 추적한다. 실제 실행에 필요한 4개 대용량 파일 image_encoder.onnx, image_encoder.onnx.data, text_encoder.onnx, text_encoder.onnx.data는 공유 압축본 또는 로컬 artifact source에서 assets/mobile_artifacts_fp16/ 아래에 넣어야 한다.

App Main Verification

파일 이름 규칙

파일명은 모델, encoder 종류, precision 정책을 드러내야 한다. 앱은 하드코딩된 파일명을 직접 쓰기보다 manifest.json의 image_encoder, text_encoder 항목을 읽는 것을 기본으로 한다.

mobileclip2_s3_server_full_ce_hardneg_image_encoder_fp16_mixed.onnx
mobileclip2_s3_server_full_ce_hardneg_text_encoder_fp16_mixed.onnx

fp16_mixed는 일부 weight를 FP16으로 저장하되, 계산 안정성을 위해 필요한 곳은 FP32 cast를 유지한다는 뜻이다. 순수 FP16보다 보수적이지만, 현재 검증에서는 image/text embedding parity가 안정적이다.

앱이 읽어야 하는 파일의 역할

Role Boundary

Image Search Input Contract

{
  "kind": "image",
  "image_path": "local/path/to/user_image.jpg",
  "top_k": 3
}

Text Search Input Contract

{
  "kind": "text",
  "query": "돌담 있는 공원",
  "top_k": 3,
  "language_hint": "ko"
}

text search는 앱에서 query를 정규화하고 tokenizer로 text_tokens를 만든 뒤 text encoder를 실행한다. 직접 문자열/alias match와 embedding similarity fusion은 검색 서비스 레이어에서 함께 사용할 수 있다.

Output Contract

{
  "status": "ambiguous",
  "message_key": "ambiguous_candidates",
  "top_k": [
    {
      "rank": 1,
      "landmark_id": "gwanghwamun",
      "landmark_name_ko": "광화문",
      "raw_score": 0.40,
      "display_score": 40,
      "score_type": "cosine_similarity"
    }
  ],
  "confidence": {
    "top1_score": 0.40,
    "top2_score": 0.31,
    "margin": 0.09,
    "policy_version": "sprint2-s3-fp16-policy-v1",
    "reason_codes": ["top1_below_match", "margin_low"]
  },
  "runtime": {
    "backend": "onnx-fp16-mixed",
    "artifact_dir": "mobile_artifacts/fp16",
    "model_version": "mobileclip2_s3_server_full_ce_hardneg_fold3_20260611_214421",
    "elapsed_ms": 314
  }
}

Text Search Output Additions

자연어 검색은 이미지 검색과 같은 Top-3 UI를 쓰되 score 의미를 분리한다. raw_score는 text encoder cosine similarity이고, final_text_score는 semantic score와 SQLite keyword score를 결합한 값이다.

{
  "rank": 1,
  "landmark_id": "naksan_park",
  "parent_landmark_id": null,
  "score_type": "semantic_text_fusion",
  "raw_score": 0.43,
  "semantic_score": 0.43,
  "keyword_score": 0.60,
  "final_text_score": 0.47,
  "display_score": 47,
  "matched_text": "성곽길과 도시 전망이 보이는 공원",
  "text_type": "description"
}

현재 fusion 기본값은 0.75 * semantic_score + 0.25 * keyword_score다. keyword hit가 없고 score/margin이 낮은 query는 out_of_scope로 처리한다.

Status Values

Versioning Rule

앱은 artifact 폴더명만 보고 동작하면 안 된다. manifest.json의 model_name, embedding_dim, image_encoder, text_encoder, class_count, precision_policy를 확인해야 한다. 모델이 바뀌면 prototype/text index도 같은 version으로 다시 생성해야 한다.