{"record":{"id":"13a8e5b069aa2ba5","repo":"deepinsight/insightface","slug":"1-n-without-auto-split-requires-gallery-and-probe","errorCode":null,"errorMessage":"1:N without Auto Split requires gallery/ and probe/ folders.","messagePattern":"1:N without Auto Split requires gallery/ and probe/ folders\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/gui/core/evaluation.py","lineNumber":799,"sourceCode":"    gallery_items: List[Dict[str, Any]] = []\n    probe_items: List[Dict[str, Any]] = []\n    identities_root = _identity_root_for_auto_split(root)\n    for identity_dir in _identity_dirs(identities_root):\n        gallery, probes = _auto_split_identity_images(identity_dir)\n        if gallery is None:\n            continue\n        identity = _identity_name(identity_dir)\n        gallery_items.append({\"identity\": identity, \"path\": gallery})\n        probe_items.extend({\"identity\": identity, \"path\": path} for path in probes)\n    return gallery_items, probe_items, []\n\n\ndef _collect_gallery_probe_structured(root: Path) -> tuple[List[Dict[str, Any]], List[Dict[str, Any]], List[Path]]:\n    gallery_root = root / \"gallery\"\n    probe_root = root / \"probe\"\n    unknown_root = root / \"unknown\"\n    if not gallery_root.is_dir() or not probe_root.is_dir():\n        raise ValueError(\"1:N without Auto Split requires gallery/ and probe/ folders.\")\n    gallery_items: List[Dict[str, Any]] = []\n    probe_items: List[Dict[str, Any]] = []\n    for identity_dir in _identity_dirs(gallery_root):\n        identity = _identity_name(identity_dir)\n        gallery_items.extend({\"identity\": identity, \"path\": path} for path in sorted(list_images(identity_dir, recursive=True)))\n    for identity_dir in _identity_dirs(probe_root):\n        identity = _identity_name(identity_dir)\n        probe_items.extend({\"identity\": identity, \"path\": path} for path in sorted(list_images(identity_dir, recursive=True)))\n    unknown_items = sorted(list_images(unknown_root, recursive=True)) if unknown_root.is_dir() else []\n    return gallery_items, probe_items, unknown_items\n\n\ndef _rank_identities(query_embedding: np.ndarray, gallery: List[Dict[str, Any]]) -> List[tuple[str, float]]:\n    best_by_identity: Dict[str, float] = {}\n    for sample in gallery:\n        score = cosine_similarity(query_embedding, sample[\"embedding\"])\n        identity = str(sample[\"identity\"])\n        if identity not in best_by_identity or score > best_by_identity[identity]:","sourceCodeStart":781,"sourceCodeEnd":817,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/gui/core/evaluation.py#L781-L817","documentation":"Raised by _collect_gallery_probe_structured when running 1:N identification without auto_split and the dataset root lacks either a gallery/ or probe/ subdirectory. The structured mode requires a specific directory layout: root/gallery/<identity>/* and root/probe/<identity>/* (plus optional root/unknown/).","triggerScenarios":"Calling run_identity_identification_evaluation with auto_split=False on a root that has identity folders directly (flat layout) instead of gallery/ and probe/ subfolders.","commonSituations":"Mixing up auto-split and structured layouts; wrong dataset_root level; folder named 'Gallery' (case) or 'test' instead of 'probe'; dataset downloaded in flat LFW-style layout.","solutions":["Create gallery/ and probe/ subdirectories under dataset_root, each containing per-identity folders","Or set auto_split=True to have the library split flat identity folders automatically","Double-check exact lowercase folder names gallery and probe","Point dataset_root at the parent that actually contains these subfolders"],"exampleFix":"# directory layout required (auto_split=False)\n# root/\n#   gallery/alice/1.jpg\n#   probe/alice/2.jpg\n#   unknown/stranger.jpg\nresult = run_identity_identification_evaluation(root, auto_split=False)","handlingStrategy":"validation","validationCode":"from pathlib import Path\nroot = Path(dataset_root)\nif not (root / \"gallery\").is_dir() or not (root / \"probe\").is_dir():\n    # either create structure or use auto_split=True\n    auto_split = True","typeGuard":null,"tryCatchPattern":"try:\n    result = run_identity_identification_evaluation(root, auto_split=False)\nexcept ValueError as e:\n    if \"requires gallery/ and probe/\" in str(e):\n        result = run_identity_identification_evaluation(root, auto_split=True)","preventionTips":["Standardize on the gallery/probe/unknown layout for 1:N datasets","Document the required directory contract for contributors","Add a CI fixture that asserts the layout exists"],"tags":["insightface","dataset-layout","identification","directory-structure"],"backgroundTag":"missing-required-directory","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}