Qdrant는 수십억(billion) 규모에서 "이 쿼리와 가까운 벡터는 무엇인가?"라는 질문에 밀리초(ms) 단위로 답합니다. 하지만 근접성(nearness) 자체가 완전히 잘못된 기준이 되는 질문 유형이 있습니다:

"Slack을 인수한 회사의 창업자는 어디에서 공부했나요?"

이 질문에 답하는 구절은 Marc Benioff와 USC에 대해 이야기합니다. Slack에 대해서는 전혀 언급하지 않습니다. 코사인 유사도(Cosine similarity) — 즉, 어떤 종류의 유사도든 — 이 구절의 순위를 낮게 매깁니다. 왜냐하면 정답이 질문과 닮아 보이지 않기 때문입니다. 정답은 질문과 세 단계의 엔티티 홉(entity-hops)을 통해 연결되어 있습니다: Slack → Salesforce에 의해 인수됨 → Benioff가 설립함 → USC에서 공부함. 이것은 위상(topology) 문제이며, 아무리 ANN 속도가 빨라도 위상 문제를 해결할 수는 없습니다.

hubmesh는 기존 Qdrant 컬렉션 위에 위상 레이어를 추가하는 작은 MIT 라이브러리입니다. Qdrant는 자신이 가장 잘하는 일(1차 ANN)을 계속 수행하고, hubmesh는 인덱싱(index) 시점에 엔티티-문서 그래프(entity–document graph)를 구축합니다. 그리고 쿼리(query) 시점에는 질문의 엔티티로부터 해당 그래프를 통해 개인화된 페이지랭크(Personalized PageRank)를 확산(diffuse)시켜, 그래프 도달 가능성(reachability)을 코사인 점수와 결합합니다. 쿼리 시점에는 LLM이 관여하지 않습니다. 검색은 하나의 희소 행렬 반복(sparse matrix iteration)이며, 결정론적(deterministic)이고, 3만 개의 문서 코퍼스에서 약 100ms가 소요됩니다.

설정 (Setup)

pip install "hubmesh[qdrant,kg]"
python -m spacy download en_core_web_sm

인덱싱: 당신의 Qdrant 컬렉션 + 엔티티 그래프

from hubmesh import Planner
from hubmesh.adapters import QdrantStore
from hubmesh.kg import build_entity_kg
...

쿼리: 확산(diffusion) + 유사도(similarity) 결합

result = planner.retrieve(
    "Where did the founder of the company that acquired Slack study?",
    top_k=10,
...

해당 reasoning 필드는 사후 설명(post-hoc explanation)이 아닙니다. 각 문서를 찾아낸 실제 그래프 경로(graph route)이며, 이는 당신의 RAG 파이프라인이 특정 구절이 왜 검색되었는지 보여줄 수 있음을 의미합니다.

점수 산정의 실제 방식

각 후보 문서는 정규화되어 결합된 세 가지 신호의 복합체(composite)를 얻습니다 (이 공식은 네트워크 토폴로지(network-topology) 논문인 NNSI, ICOMP'25에서 유래되었으며, 해당 논문에서도 동일한 교훈이 등장했습니다: 단일 중심성 지표(centrality metric)는 중요한 노드를 식별할 수 없지만, 가중치가 적용된 복합체는 가능합니다):

• 관련성 (Relevance) — 당신의 Qdrant 벡터에 대한 코사인 유사도 (기하학적 구조, geometry)
• 구조 (Structure) — 질문의 엔티티(entities)로부터 확산된 개인화된 페이지랭크(Personalized PageRank) 질량 (토폴로지, topology)
• 수렴 (Convergence) — 엔티티별 확산의 기하 평균(geometric mean). 따라서 문서는 단지 하나의 앵커(anchor)로부터 점수가 쏟아지는 것이 아니라, 질문 내의 모든 앵커로부터 도달 가능해야 합니다.

수치 (레포지토리의 harness 및 원본 JSON 포함)

공개된 트레이드오프(trade-off): 수렴(convergence) 항은 상위 순위 정밀도(top-rank precision)를 희생하여 깊이 있는 재현율(depth recall)을 확보합니다. 즉, full dev 데이터셋에서 recall@2는 단순 코사인 방식보다 0.75 pts 낮습니다. 만약 top_k=2로 검색한다면, 이 기능을 비활성화하십시오 (use_convergence=False). benchmarks/에 있는 스크립트를 통해 위 모든 결과가 재현됩니다.

에이전트가 이를 제어할 수 있습니다

retrieve는 seed_entities와 exclude_docs를 허용하므로, 에이전트가 검색, 읽기, 그 다음 방금 발견한 엔티티를 향한 두 번째 홉(hop two)을 목표로 하는 반복 작업을 수행할 수 있습니다. MCP 서버가 포함되어 있으며 (hubmesh-mcp, 공식 MCP Registry에 등재됨) — 레포지토리에는 Perplexity가 도구 호출(tool call)을 하나씩 수행하며 이를 통해 3-홉 체인(3-hop chain)을 구동한 현장 보고서가 포함되어 있습니다.

사용하지 말아야 할 때

유사도(similarity)만으로도 충분한 단일 홉(Single-hop) 코퍼스; 코퍼스 전체 요약 질문 ("주요 주제가 무엇인가요?") — 이는 커뮤니티 요약(community-summary) 영역(Microsoft GraphRAG의 사용 사례)이며, 다른 유형의 쿼리 클래스입니다. hubmesh는 멀티홉(multi-hop) 사실적 검색(factual retrieval)을 위한 것이며, 의도적으로 Qdrant를 하단의 기하학 엔진(geometry engine)으로 유지합니다.

Repo: github.com/DemigodDSK/hubmesh · PyPI: pip install hubmesh · MIT