mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
738 lines
49 KiB
HTML
738 lines
49 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0042</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hip-0042.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0042">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0042.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hip-0042</h1><p class="lede">HIP-42: Vector Search Standard. Status Active. Hanzo's own standard — read this before implementing against it.</p><h1>HIP-0042: Vector Search Standard</h1>
|
|
<h2>Abstract</h2>
|
|
<p>This proposal defines the standard for Hanzo Vector, the high-performance vector database and similarity search infrastructure that powers retrieval-augmented generation (RAG), semantic search, recommendation engines, and embedding-based retrieval across all services in the Hanzo ecosystem. Hanzo Vector is built on Hanzo Vector, a Rust-based vector database purpose-built for approximate nearest neighbor (ANN) search, and is distributed as <code>hanzoai/vector:latest</code>. It exposes a gRPC API on port 6333 and an HTTP REST API on port 6334.</p>
|
|
<p><strong>Repository</strong>: <a href="https://github.com/hanzoai/vector">github.com/hanzoai/vector</a> <strong>Ports</strong>: 6333 (gRPC), 6334 (HTTP REST) <strong>Docker</strong>: <code>hanzoai/vector:latest</code> <strong>License</strong>: Apache-2.0</p>
|
|
<h2>Design Philosophy</h2>
|
|
<p>This section explains every major design decision and why the alternatives were rejected. Vector search is foundational to every AI feature in the Hanzo ecosystem. A wrong choice here propagates to every service that performs retrieval, recommendation, or semantic matching.</p>
|
|
<h3>Why Hanzo Vector over Milvus</h3>
|
|
<p>Milvus is a capable open-source vector database, but its architecture is complex:</p>
|
|
<ul><li><strong>Component count</strong>: Milvus requires etcd (metadata), MinIO (object storage), and Pulsar</li></ul>
|
|
<p> (message queue) as mandatory dependencies. A minimal Milvus deployment is four services. Hanzo Vector is a single binary with embedded storage -- zero external dependencies.</p>
|
|
<ul><li><strong>Operational overhead</strong>: Each Milvus component has its own failure modes, upgrade</li></ul>
|
|
<p> procedures, and resource requirements. etcd quorum loss, Pulsar topic compaction, MinIO bucket corruption -- each adds a distinct class of incidents. Hanzo Vector's failure mode is simple: the process crashes and restarts, replaying its WAL.</p>
|
|
<ul><li><strong>Developer experience</strong>: Milvus's SDK requires understanding its distributed concepts</li></ul>
|
|
<p> (segments, channels, sealed/growing segments) even for simple queries. Hanzo Vector's API is a straightforward CRUD interface on collections and points.</p>
|
|
<p>For our current scale (tens of millions of vectors, single-digit-millisecond latency requirements), Hanzo Vector's simpler architecture provides the same performance with far less operational burden. If we reach billions of vectors with petabyte-scale storage, Milvus's distributed architecture may become relevant -- but that is a future HIP.</p>
|
|
<h2>Specification</h2>
|
|
<h3>Core Concepts</h3>
|
|
<h4>Collections</h4>
|
|
<p>A collection is a named group of vectors with a fixed dimensionality and distance metric. Collections are the primary unit of organization, analogous to a table in a relational database or an index in Elasticsearch.</p>
|
|
<pre><code class="lang-json">{
|
|
"name": "documents",
|
|
"vectors": {
|
|
"size": 1536,
|
|
"distance": "Cosine"
|
|
},
|
|
"optimizers_config": {
|
|
"default_segment_number": 2,
|
|
"indexing_threshold": 20000
|
|
},
|
|
"replication_factor": 1,
|
|
"write_consistency_factor": 1
|
|
}</code></pre>
|
|
<p>Each collection has:</p>
|
|
<ul><li><strong>Vector configuration</strong>: Dimensionality and distance metric (immutable after creation)</li><li><strong>Optimizer configuration</strong>: Segment management and indexing thresholds</li><li><strong>Replication factor</strong>: Number of shard replicas (for distributed deployments)</li><li><strong>Write consistency factor</strong>: Minimum replicas that must acknowledge a write</li></ul>
|
|
<h4>Points</h4>
|
|
<p>A point is the fundamental unit of data. Each point contains:</p>
|
|
<ul><li><strong>ID</strong>: UUID or unsigned 64-bit integer, unique within the collection</li><li><strong>Vector</strong>: A dense floating-point array of fixed dimensionality</li><li><strong>Payload</strong>: Arbitrary JSON metadata attached to the point</li></ul>
|
|
<pre><code class="lang-json">{
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"vector": [0.042, -0.118, 0.391, "... 1536 floats total"],
|
|
"payload": {
|
|
"source": "knowledge-base",
|
|
"category": "technical",
|
|
"created_at": "2026-02-23T10:00:00Z",
|
|
"org_id": "hanzo",
|
|
"text": "Original document text for retrieval"
|
|
}
|
|
}</code></pre>
|
|
<h4>Payloads</h4>
|
|
<p>Payloads are JSON objects stored alongside vectors. Unlike pure vector databases that store only IDs (requiring a separate metadata lookup), Hanzo Vector stores payloads co-located with vectors. This eliminates the "fan-out" problem where a search returns IDs that must be resolved against a separate database.</p>
|
|
<p>Payload fields are automatically indexed for filtering. Supported field types:</p>
|
|
<p>| Type | Example | Filter Operations | |------|---------|-------------------| | <code>keyword</code> | <code>"category": "tech"</code> | match, match_any, match_except | | <code>integer</code> | <code>"priority": 5</code> | match, range (gt, gte, lt, lte) | | <code>float</code> | <code>"score": 0.95</code> | range | | <code>bool</code> | <code>"published": true</code> | match | | <code>text</code> | <code>"title": "Vector DB"</code> | full-text match | | <code>geo</code> | <code>"location": {"lat": 37.7, "lon": -122.4}</code> | geo_bounding_box, geo_radius | | <code>datetime</code> | <code>"created": "2026-02-23T00:00:00Z"</code> | range |</p>
|
|
<h4>Shards</h4>
|
|
<p>Each collection is divided into shards. Shards are the unit of distribution and parallelism. In standalone mode, all shards reside on the single node. In distributed mode, shards are distributed across nodes with configurable replication.</p>
|
|
<h3>Distance Metrics</h3>
|
|
<p>Hanzo Vector supports three distance metrics, chosen at collection creation time:</p>
|
|
<p>| Metric | Formula | Use Case | Range | |--------|---------|----------|-------| | <strong>Cosine</strong> | <code>1 - (A . B) / (\|A\| * \|B\|)</code> | Text embeddings, normalized vectors | [0, 2] | | <strong>Euclidean</strong> | <code>sqrt(sum((A_i - B_i)^2))</code> | Image embeddings, spatial data | [0, inf) | | <strong>Dot Product</strong> | <code>-(A . B)</code> | Pre-normalized embeddings, MaxIP | (-inf, inf) |</p>
|
|
<p><strong>Default</strong>: Cosine. Most embedding models (OpenAI, Cohere, Voyage) produce L2-normalized vectors where cosine similarity is the natural metric.</p>
|
|
<p><strong>Note on Dot Product</strong>: Hanzo Vector returns the negated dot product so that lower scores are always "closer" (consistent with Cosine and Euclidean). For maximum inner product search, negate the result.</p>
|
|
<h3>Indexing: HNSW</h3>
|
|
<p>Hanzo Vector uses HNSW (Hierarchical Navigable Small World) as its primary ANN index. HNSW builds a multi-layer navigable graph where each node is a vector and edges connect nearby points. Search starts at the top layer (sparse, long-range links) and descends to the bottom layer (dense, short-range links), performing greedy nearest-neighbor traversal at each level.</p>
|
|
<h4>HNSW Parameters</h4>
|
|
<p>| Parameter | Default | Description | Trade-off | |-----------|---------|-------------|-----------| | <code>m</code> | 16 | Max edges per node per layer | Higher = better recall, more memory | | <code>ef_construct</code> | 100 | Beam width during index build | Higher = better index quality, slower build | | <code>ef</code> | 128 | Beam width during search | Higher = better recall, slower search | | <code>full_scan_threshold</code> | 10000 | Below this count, skip HNSW and brute-force | Avoids index overhead for tiny collections | | <code>max_indexing_threads</code> | 0 (auto) | Parallel threads for index building | 0 = use all available cores |</p>
|
|
<p><strong>Tuning guidance</strong>:</p>
|
|
<ul><li>For recall-critical workloads (RAG, agent memory): increase <code>ef</code> to 256 or 512.</li></ul>
|
|
<p> Search latency increases from ~5ms to ~15ms but recall improves from 95% to 99%+.</p>
|
|
<ul><li>For throughput-critical workloads (real-time recommendation): keep <code>ef</code> at 64-128.</li></ul>
|
|
<p> Accept ~95% recall for sub-5ms latency.</p>
|
|
<ul><li><code>m</code> is set once at index creation. Changing it requires reindexing. The default of 16</li></ul>
|
|
<p> works well for dimensionalities up to 2048. For higher dimensions, increase to 32 or 64.</p>
|
|
<h3>Quantization</h3>
|
|
<p>Quantization reduces memory footprint by compressing vectors from 32-bit floats to lower precision representations. Hanzo Vector supports three quantization methods:</p>
|
|
<h4>Scalar Quantization</h4>
|
|
<p>Converts each float32 component to int8 (1 byte), reducing memory by 4x with minimal recall loss (~1-2%).</p>
|
|
<pre><code class="lang-json">{
|
|
"scalar": {
|
|
"type": "int8",
|
|
"quantile": 0.99,
|
|
"always_ram": true
|
|
}
|
|
}</code></pre>
|
|
<ul><li><strong>Memory</strong>: 1536-dim vector goes from 6KB to 1.5KB</li><li><strong>Use case</strong>: General-purpose, best default for most workloads</li><li><strong>Trade-off</strong>: ~1% recall loss, 4x memory reduction, ~30% faster search</li></ul>
|
|
<h4>Product Quantization</h4>
|
|
<p>Divides the vector into sub-vectors and quantizes each independently using a codebook. Achieves 8-32x compression.</p>
|
|
<pre><code class="lang-json">{
|
|
"product": {
|
|
"compression": "x16",
|
|
"always_ram": true
|
|
}
|
|
}</code></pre>
|
|
<ul><li><strong>Memory</strong>: 1536-dim vector goes from 6KB to ~384 bytes (x16) or ~192 bytes (x32)</li><li><strong>Use case</strong>: Large-scale deployments where memory is the bottleneck</li><li><strong>Trade-off</strong>: 3-5% recall loss, requires longer training phase during index build</li></ul>
|
|
<h4>Binary Quantization</h4>
|
|
<p>Converts each float to a single bit (positive = 1, negative = 0). Achieves 32x compression. Most effective with high-dimensional embeddings from models that produce roughly balanced positive/negative values (e.g., OpenAI, Cohere).</p>
|
|
<pre><code class="lang-json">{
|
|
"binary": {
|
|
"always_ram": true
|
|
}
|
|
}</code></pre>
|
|
<ul><li><strong>Memory</strong>: 1536-dim vector goes from 6KB to 192 bytes</li><li><strong>Use case</strong>: Billion-scale collections where memory cost dominates</li><li><strong>Trade-off</strong>: 5-10% recall loss, mitigated by rescoring with original vectors</li></ul>
|
|
<h3>Filtering</h3>
|
|
<p>Hanzo Vector applies payload filters during HNSW graph traversal, not as a post-processing step. This is critical for performance: a post-filter approach retrieves K candidates and then filters, potentially returning fewer than K results. Hanzo Vector's approach guarantees exactly K filtered results by continuing graph traversal until K matching points are found.</p>
|
|
<h4>Filter Conditions</h4>
|
|
<pre><code class="lang-json">{
|
|
"filter": {
|
|
"must": [
|
|
{ "key": "org_id", "match": { "value": "hanzo" } },
|
|
{ "key": "created_at", "range": { "gte": "2026-01-01T00:00:00Z" } }
|
|
],
|
|
"must_not": [
|
|
{ "key": "status", "match": { "value": "deleted" } }
|
|
],
|
|
"should": [
|
|
{ "key": "category", "match": { "value": "technical" } },
|
|
{ "key": "category", "match": { "value": "engineering" } }
|
|
]
|
|
}
|
|
}</code></pre>
|
|
<ul><li><strong>must</strong>: All conditions must match (AND)</li><li><strong>must_not</strong>: None of the conditions may match (NOT)</li><li><strong>should</strong>: At least one condition must match (OR)</li></ul>
|
|
<h4>Supported Filter Operations</h4>
|
|
<p>| Operation | Description | Example | |-----------|-------------|---------| | <code>match</code> | Exact value match | <code>{"key": "status", "match": {"value": "active"}}</code> | | <code>match_any</code> | Match any of values | <code>{"key": "tag", "match": {"any": ["ai", "ml"]}}</code> | | <code>match_except</code> | Match none of values | <code>{"key": "tag", "match": {"except": ["draft"]}}</code> | | <code>range</code> | Numeric/datetime range | <code>{"key": "score", "range": {"gte": 0.8}}</code> | | <code>geo_bounding_box</code> | Geographic rectangle | <code>{"key": "loc", "geo_bounding_box": {...}}</code> | | <code>geo_radius</code> | Geographic circle | <code>{"key": "loc", "geo_radius": {"center": ..., "radius": 1000}}</code> | | <code>values_count</code> | Array length filter | <code>{"key": "tags", "values_count": {"gte": 2}}</code> | | <code>is_empty</code> | Field exists check | <code>{"key": "deleted_at", "is_empty": {}}</code> | | <code>nested</code> | Filter on nested objects | <code>{"key": "metadata", "nested": {"filter": ...}}</code> |</p>
|
|
<h3>API</h3>
|
|
<h4>Connection Parameters</h4>
|
|
<pre><code class="lang-yaml">grpc_host: localhost:6334
|
|
grpc_port: 6333
|
|
http_host: localhost:6334
|
|
http_port: 6334
|
|
api_key: <from K8s secret "vector", key "api-key">
|
|
tls: false # intra-cluster</code></pre>
|
|
<h4>Collections API</h4>
|
|
<p><strong>Create collection</strong>:</p>
|
|
<pre><code>PUT /collections/{name}</code></pre>
|
|
<pre><code class="lang-json">{
|
|
"vectors": {
|
|
"size": 1536,
|
|
"distance": "Cosine"
|
|
},
|
|
"optimizers_config": {
|
|
"indexing_threshold": 20000
|
|
},
|
|
"quantization_config": {
|
|
"scalar": { "type": "int8", "always_ram": true }
|
|
}
|
|
}</code></pre>
|
|
<p><strong>Multi-vector collection</strong> (for models that produce multiple embeddings per document):</p>
|
|
<pre><code>PUT /collections/{name}</code></pre>
|
|
<pre><code class="lang-json">{
|
|
"vectors": {
|
|
"title": { "size": 384, "distance": "Cosine" },
|
|
"content": { "size": 1536, "distance": "Cosine" },
|
|
"image": { "size": 512, "distance": "Euclidean" }
|
|
}
|
|
}</code></pre>
|
|
<p><strong>Get collection info</strong>: <code>GET /collections/{name}</code></p>
|
|
<p><strong>Delete collection</strong>: <code>DELETE /collections/{name}</code></p>
|
|
<p><strong>List collections</strong>: <code>GET /collections</code></p>
|
|
<p><strong>Update collection parameters</strong>: <code>PATCH /collections/{name}</code></p>
|
|
<h4>Points API</h4>
|
|
<p><strong>Upsert points</strong> (insert or update):</p>
|
|
<pre><code>PUT /collections/{name}/points</code></pre>
|
|
<pre><code class="lang-json">{
|
|
"points": [
|
|
{
|
|
"id": "doc-001",
|
|
"vector": [0.042, -0.118, "..."],
|
|
"payload": {
|
|
"source": "knowledge-base",
|
|
"org_id": "hanzo",
|
|
"text": "Document content"
|
|
}
|
|
}
|
|
]
|
|
}</code></pre>
|
|
<p><strong>Search (nearest neighbors)</strong>:</p>
|
|
<pre><code>POST /collections/{name}/points/search</code></pre>
|
|
<pre><code class="lang-json">{
|
|
"vector": [0.042, -0.118, "..."],
|
|
"limit": 10,
|
|
"filter": {
|
|
"must": [
|
|
{ "key": "org_id", "match": { "value": "hanzo" } }
|
|
]
|
|
},
|
|
"with_payload": true,
|
|
"with_vectors": false,
|
|
"params": {
|
|
"hnsw_ef": 128,
|
|
"exact": false
|
|
}
|
|
}</code></pre>
|
|
<p><strong>Scroll (paginated retrieval)</strong>:</p>
|
|
<pre><code>POST /collections/{name}/points/scroll</code></pre>
|
|
<pre><code class="lang-json">{
|
|
"filter": {
|
|
"must": [
|
|
{ "key": "category", "match": { "value": "technical" } }
|
|
]
|
|
},
|
|
"limit": 100,
|
|
"offset": "last-point-id",
|
|
"with_payload": true
|
|
}</code></pre>
|
|
<p><strong>Recommend (find similar to positive examples, dissimilar from negative)</strong>:</p>
|
|
<pre><code>POST /collections/{name}/points/recommend</code></pre>
|
|
<pre><code class="lang-json">{
|
|
"positive": ["doc-001", "doc-005"],
|
|
"negative": ["doc-099"],
|
|
"limit": 10,
|
|
"filter": {
|
|
"must": [
|
|
{ "key": "org_id", "match": { "value": "hanzo" } }
|
|
]
|
|
}
|
|
}</code></pre>
|
|
<p><strong>Delete points</strong>: <code>POST /collections/{name}/points/delete</code></p>
|
|
<p><strong>Get points by ID</strong>: <code>POST /collections/{name}/points</code></p>
|
|
<h4>Batch Operations</h4>
|
|
<p>For bulk ingestion (initial data load, embedding pipeline output), use the batch upsert endpoint with payloads of up to 1000 points per request:</p>
|
|
<pre><code>PUT /collections/{name}/points?wait=false</code></pre>
|
|
<p>Setting <code>wait=false</code> returns immediately and processes the upsert asynchronously. This is appropriate for bulk ingestion where the caller does not need immediate confirmation that each point is searchable.</p>
|
|
<p><strong>Recommended batch size</strong>: 100-500 points per request. Larger batches consume more memory during processing; smaller batches increase HTTP overhead.</p>
|
|
<p><strong>Parallel ingestion</strong>: Use 4-8 concurrent connections for maximum throughput. Hanzo Vector handles concurrent writes to different segments safely.</p>
|
|
<h4>Snapshots</h4>
|
|
<p>Snapshots are point-in-time backups of a collection's data and index:</p>
|
|
<p><strong>Create snapshot</strong>: <code>POST /collections/{name}/snapshots</code></p>
|
|
<p><strong>List snapshots</strong>: <code>GET /collections/{name}/snapshots</code></p>
|
|
<p><strong>Download snapshot</strong>: <code>GET /collections/{name}/snapshots/{snapshot_name}</code></p>
|
|
<p><strong>Restore from snapshot</strong>: Upload the snapshot file to a new or existing collection.</p>
|
|
<p>Snapshots are stored locally on the node. For disaster recovery, snapshots should be uploaded to object storage (Hanzo Object Storage, HIP-0032) via a CronJob.</p>
|
|
<h3>Multi-Tenancy</h3>
|
|
<p>Hanzo Vector supports multi-tenancy through two mechanisms:</p>
|
|
<h4>Collection-per-Tenant</h4>
|
|
<p>Each tenant (organization) gets its own collection. This provides the strongest isolation: separate indices, separate resource consumption, separate snapshots.</p>
|
|
<pre><code>collections:
|
|
hanzo-documents # org: hanzo
|
|
lux-documents # org: lux
|
|
zoo-documents # org: zoo</code></pre>
|
|
<p><strong>Use when</strong>: Tenants have different vector dimensionalities, different distance metrics, or strict data isolation requirements.</p>
|
|
<h4>Payload-Based Tenancy</h4>
|
|
<p>All tenants share a single collection. Tenant isolation is enforced by mandatory payload filters on every query:</p>
|
|
<pre><code class="lang-json">{
|
|
"vector": [0.042, -0.118, "..."],
|
|
"filter": {
|
|
"must": [
|
|
{ "key": "tenant_id", "match": { "value": "hanzo" } }
|
|
]
|
|
},
|
|
"limit": 10
|
|
}</code></pre>
|
|
<p><strong>Use when</strong>: Tenants share the same embedding model and dimensionality, and operational simplicity (fewer collections to manage) outweighs isolation concerns.</p>
|
|
<p><strong>Important</strong>: The application layer MUST enforce the tenant filter. Hanzo Vector does not have built-in tenant isolation -- it is the caller's responsibility to include the filter on every query. The Hanzo Vector SDK enforces this by requiring a <code>tenant_id</code> parameter on all search methods.</p>
|
|
<h3>Integration with LLM Gateway (HIP-0004)</h3>
|
|
<p>The primary consumer of Hanzo Vector is the LLM Gateway's RAG pipeline:</p>
|
|
<pre><code>User Query
|
|
|
|
|
v
|
|
LLM Gateway (HIP-0004)
|
|
|
|
|
+--> Embeddings Service --> embed(query) --> query_vector
|
|
|
|
|
+--> Hanzo Vector --> search(query_vector, filter, limit=5) --> context_docs
|
|
|
|
|
+--> LLM Provider --> generate(query + context_docs) --> response
|
|
|
|
|
v
|
|
User Response</code></pre>
|
|
<ol><li><strong>Query embedding</strong>: The LLM Gateway calls the Embeddings service to convert the user's</li></ol>
|
|
<p> natural language query into a vector. Default model: <code>text-embedding-3-small</code> (1536 dimensions, cosine similarity).</p>
|
|
<ol><li><strong>Vector search</strong>: The query vector is sent to Hanzo Vector with optional payload</li></ol>
|
|
<p> filters (org_id, source, date range). Hanzo Vector returns the top-K most similar documents with their payloads.</p>
|
|
<ol><li><strong>Context assembly</strong>: The Gateway assembles the retrieved documents into a context</li></ol>
|
|
<p> window, respecting the target LLM's maximum context length.</p>
|
|
<ol><li><strong>Generation</strong>: The LLM generates a response grounded in the retrieved context.</li></ol>
|
|
<h3>Integration with Embeddings Service</h3>
|
|
<p>Hanzo Vector does not generate embeddings. It stores and searches pre-computed vectors. Embedding generation is handled by the Embeddings service, which is accessible through the LLM Gateway's <code>/embeddings</code> endpoint (OpenAI-compatible):</p>
|
|
<pre><code>POST /v1/embeddings
|
|
{
|
|
"model": "text-embedding-3-small",
|
|
"input": "What is vector search?"
|
|
}</code></pre>
|
|
<p>The pipeline for document ingestion:</p>
|
|
<ol><li><strong>Extract text</strong>: Parse documents (PDF, HTML, Markdown, code) into text chunks</li><li><strong>Generate embeddings</strong>: Call <code>/v1/embeddings</code> with each chunk</li><li><strong>Upsert to Vector</strong>: Store the embedding + metadata payload in Hanzo Vector</li><li><strong>Index</strong>: Hanzo Vector automatically builds/updates the HNSW index</li></ol>
|
|
<p>Supported embedding models (via LLM Gateway):</p>
|
|
<p>| Model | Dimensions | Provider | Use Case | |-------|-----------|----------|----------| | <code>text-embedding-3-small</code> | 1536 | OpenAI | General purpose (default) | | <code>text-embedding-3-large</code> | 3072 | OpenAI | High-accuracy retrieval | | <code>embed-english-v3.0</code> | 1024 | Cohere | English-optimized | | <code>embed-multilingual-v3.0</code> | 1024 | Cohere | Multilingual | | <code>voyage-3</code> | 1024 | Voyage AI | Code and technical docs |</p>
|
|
<h2>Implementation</h2>
|
|
<h3>Container Image</h3>
|
|
<p>The Dockerfile is minimal:</p>
|
|
<pre><code class="lang-dockerfile">ARG QDRANT_VERSION=1.13
|
|
|
|
FROM qdrant/qdrant:v${QDRANT_VERSION} AS base
|
|
FROM base
|
|
|
|
LABEL maintainer="[email protected]"
|
|
LABEL org.opencontainers.image.source="https://github.com/hanzoai/vector"
|
|
LABEL org.opencontainers.image.description="Hanzo Vector - High-performance vector search"
|
|
LABEL org.opencontainers.image.vendor="Hanzo AI"
|
|
|
|
EXPOSE 6333 6334
|
|
|
|
HEALTHCHECK --interval=15s --timeout=3s --start-period=10s --retries=3 \
|
|
CMD curl -sf http://localhost:6333/healthz || exit 1</code></pre>
|
|
<p>Key points:</p>
|
|
<ul><li><strong>Base image</strong>: <code>qdrant/qdrant:v1.13</code> (Rust binary on Debian slim, ~80MB compressed)</li><li><strong>No custom compilation</strong>: We use the upstream Hanzo Vector binary as-is. Custom patches</li></ul>
|
|
<p> would create a maintenance burden and diverge from upstream security fixes.</p>
|
|
<ul><li><strong>Two ports</strong>: 6333 for gRPC (primary, higher throughput), 6334 for HTTP REST (debugging,</li></ul>
|
|
<p> admin, lower overhead for simple queries)</p>
|
|
<h3>Configuration</h3>
|
|
<p>Production <code>config.yaml</code> (mounted from ConfigMap):</p>
|
|
<pre><code class="lang-yaml">storage:
|
|
storage_path: /qdrant/storage
|
|
snapshots_path: /qdrant/snapshots
|
|
|
|
# WAL configuration
|
|
wal:
|
|
wal_capacity_mb: 64
|
|
wal_segments_ahead: 0
|
|
|
|
# Optimizer configuration
|
|
optimizers:
|
|
deleted_threshold: 0.2
|
|
vacuum_min_vector_number: 1000
|
|
default_segment_number: 2
|
|
max_segment_size_kb: 0
|
|
memmap_threshold_kb: 50000
|
|
indexing_threshold_kb: 20000
|
|
flush_interval_sec: 5
|
|
max_optimization_threads: 0
|
|
|
|
# Performance tuning
|
|
performance:
|
|
max_search_threads: 0 # auto-detect
|
|
max_optimization_threads: 0
|
|
|
|
service:
|
|
host: 0.0.0.0
|
|
grpc_port: 6333
|
|
http_port: 6334
|
|
api_key: ${VECTOR_API_KEY}
|
|
enable_tls: false
|
|
|
|
# CORS for admin dashboard
|
|
enable_cors: true
|
|
|
|
cluster:
|
|
enabled: false # standalone mode</code></pre>
|
|
<h3>Health Checks</h3>
|
|
<p><strong>Readiness probe</strong> (is the instance ready to accept queries?):</p>
|
|
<pre><code class="lang-yaml">httpGet:
|
|
path: /healthz
|
|
port: 6334
|
|
initialDelaySeconds: 5
|
|
periodSeconds: 10
|
|
failureThreshold: 3</code></pre>
|
|
<p><strong>Liveness probe</strong> (is the instance alive?):</p>
|
|
<pre><code class="lang-yaml">httpGet:
|
|
path: /healthz
|
|
port: 6334
|
|
initialDelaySeconds: 15
|
|
periodSeconds: 30
|
|
failureThreshold: 5</code></pre>
|
|
<h3>Resource Allocation</h3>
|
|
<pre><code class="lang-yaml">resources:
|
|
requests:
|
|
cpu: 500m
|
|
memory: 1Gi
|
|
limits:
|
|
cpu: 4000m
|
|
memory: 8Gi</code></pre>
|
|
<p>Vector search is CPU- and memory-intensive. The memory limit must accommodate:</p>
|
|
<ul><li>HNSW index (in-memory graph structure)</li><li>Quantized vectors (if <code>always_ram: true</code>)</li><li>WAL buffer</li><li>Query execution buffers</li></ul>
|
|
<h3>Storage</h3>
|
|
<pre><code class="lang-yaml">volumeClaimTemplates:
|
|
- metadata:
|
|
name: vector-data
|
|
spec:
|
|
accessModes: [ReadWriteOnce]
|
|
resources:
|
|
requests:
|
|
storage: 50Gi</code></pre>
|
|
<p>Storage holds the WAL, segment files, snapshots, and (if using mmap) the vector data. 50Gi provides headroom for ~50M vectors at 1536 dimensions with scalar quantization.</p>
|
|
<h3>K8s Manifest Structure</h3>
|
|
<p>All manifests live in <code>universe/infra/k8s/vector/</code>:</p>
|
|
<pre><code class="lang-yaml"># kustomization.yaml
|
|
apiVersion: kustomize.config.k8s.io/v1beta1
|
|
kind: Kustomization
|
|
resources:
|
|
- statefulset.yaml
|
|
- service.yaml
|
|
- secret.yaml
|
|
- configmap.yaml</code></pre>
|
|
<h3>CI/CD Pipeline</h3>
|
|
<p>The deploy workflow (<code>.github/workflows/deploy.yml</code>):</p>
|
|
<p><strong>Stage 1: Build</strong></p>
|
|
<ol><li>Checkout source from <code>github.com/hanzoai/vector</code></li><li>Authenticate to Hanzo KMS (Universal Auth) to fetch CI secrets</li><li>Build multi-arch image (<code>linux/amd64</code>, <code>linux/arm64</code>) via Docker Buildx</li><li>Push to GHCR (<code>ghcr.io/hanzoai/vector</code>) with tags: <code>latest</code>, git SHA, semver</li><li>Push to Docker Hub (<code>docker.io/hanzoai/vector</code>) as fallback (continue-on-error)</li></ol>
|
|
<p><strong>Stage 2: Deploy (main branch only)</strong></p>
|
|
<ol><li>Authenticate to Hanzo KMS for DigitalOcean API token</li><li>Configure <code>kubectl</code> for <code>the cluster</code> cluster via <code>doctl</code></li><li>Rolling update: <code>kubectl set image statefulset/vector vector=ghcr.io/hanzoai/vector:latest</code></li><li>Wait for rollout: <code>kubectl rollout status statefulset/vector --timeout=180s</code></li></ol>
|
|
<h3>Client SDKs</h3>
|
|
<p>| Language | Package | Install | |----------|---------|---------| | Python | <a href="https://pypi.org/project/hanzo-vector">hanzo-vector</a> | <code>pip install hanzo-vector</code> | | Go | <a href="https://github.com/hanzoai/vector-go">hanzo/vector-go</a> | <code>go get github.com/hanzoai/vector-go</code> | | Node.js | <a href="https://github.com/hanzoai/vector-client">@hanzo/vector</a> | <code>npm install @hanzo/vector</code> |</p>
|
|
<p>All three wrap the Qdrant client libraries (<code>qdrant-client</code>, <code>go-client</code>, <code>@qdrant/js-client-rest</code>) with Hanzo-specific defaults: automatic tenant filtering, KMS secret resolution, connection pooling, and structured logging.</p>
|
|
<p><strong>Python SDK example</strong>:</p>
|
|
<pre><code class="lang-python">from hanzo_vector import VectorClient
|
|
|
|
client = VectorClient(
|
|
url="http://localhost:6334",
|
|
api_key=os.environ["VECTOR_API_KEY"],
|
|
tenant_id="hanzo",
|
|
)
|
|
|
|
# Upsert documents
|
|
client.upsert(
|
|
collection="documents",
|
|
points=[
|
|
{
|
|
"id": "doc-001",
|
|
"vector": embedding, # from LLM Gateway /v1/embeddings
|
|
"payload": {"source": "kb", "text": "..."},
|
|
}
|
|
],
|
|
)
|
|
|
|
# Search with automatic tenant filtering
|
|
results = client.search(
|
|
collection="documents",
|
|
query_vector=query_embedding,
|
|
limit=10,
|
|
filter={"category": "technical"},
|
|
)</code></pre>
|
|
<h2>Deployment</h2>
|
|
<h3>Standalone Mode (Current)</h3>
|
|
<p>Single StatefulSet with one replica. All shards reside on the single node. This is the current production configuration.</p>
|
|
<pre><code>vector-0 (StatefulSet pod)
|
|
|- gRPC :6333
|
|
|- HTTP :6334
|
|
|- storage: /qdrant/storage (PVC: vector-data, 50Gi)</code></pre>
|
|
<p><strong>Scale ceiling</strong>: A single Hanzo Vector node on a 16-core machine with 64GB RAM can handle ~100M vectors at 1536 dimensions with scalar quantization, serving ~10K queries/sec at sub-10ms p99 latency.</p>
|
|
<h3>Distributed Mode (Future)</h3>
|
|
<p>When the dataset or query throughput exceeds single-node capacity, Hanzo Vector supports distributed deployment with automatic sharding and replication:</p>
|
|
<pre><code>vector-0 (shard 1 primary, shard 3 replica)
|
|
vector-1 (shard 2 primary, shard 1 replica)
|
|
vector-2 (shard 3 primary, shard 2 replica)</code></pre>
|
|
<p>Configuration changes for distributed mode:</p>
|
|
<pre><code class="lang-yaml">cluster:
|
|
enabled: true
|
|
p2p:
|
|
port: 6335
|
|
consensus:
|
|
tick_period_ms: 100</code></pre>
|
|
<p>This will be specified in a future HIP when scale requirements demand it.</p>
|
|
<h2>Security</h2>
|
|
<h3>API Key Authentication</h3>
|
|
<p>All API requests must include an API key in the <code>api-key</code> header or <code>Authorization: Bearer</code> header:</p>
|
|
<pre><code class="lang-bash">curl -H "api-key: ${VECTOR_API_KEY}" \
|
|
http://localhost:6334/collections</code></pre>
|
|
<p>The API key is stored in a K8s Secret:</p>
|
|
<pre><code class="lang-yaml">apiVersion: v1
|
|
kind: Secret
|
|
metadata:
|
|
name: vector
|
|
namespace: hanzo
|
|
type: Opaque
|
|
stringData:
|
|
api-key: "<generated-value>"</code></pre>
|
|
<p>In production, this secret is synced from Hanzo KMS (<code>kms.hanzo.ai</code>) via the KMS Operator.</p>
|
|
<h3>Network Isolation</h3>
|
|
<ul><li><strong>Service type</strong>: ClusterIP (no external exposure)</li><li><strong>No NodePort, no LoadBalancer, no Ingress</strong></li><li>Only pods within the <code>hanzo</code> namespace can reach ports 6333/6334</li><li>The Hanzo Vector Web UI (served on the HTTP port) is accessible only via <code>kubectl port-forward</code></li></ul>
|
|
<p> for debugging</p>
|
|
<h3>TLS Encryption</h3>
|
|
<p>TLS is supported but not enabled for intra-cluster communication. The reasoning mirrors HIP-0028 (Key-Value Store):</p>
|
|
<ul><li>All traffic stays within the Kubernetes VPC, encrypted at the network layer</li><li>TLS adds latency overhead on every query</li><li>If cross-cluster replication or external access is required, TLS will be enabled via</li></ul>
|
|
<p> Hanzo Vector's built-in TLS configuration</p>
|
|
<h3>Collection-Level Access Control</h3>
|
|
<p>Hanzo Vector's single API key provides cluster-wide access. For collection-level isolation, the Hanzo Vector SDK enforces access control at the application layer:</p>
|
|
<ul><li>Each service is configured with a list of allowed collections</li><li>The SDK rejects operations on collections not in the allow-list</li><li>Audit logs record all collection access with caller identity</li></ul>
|
|
<p>For stricter isolation, use the collection-per-tenant model where each tenant's API key is scoped to their collections via an API gateway (future work).</p>
|
|
<h3>Payload Encryption at Rest</h3>
|
|
<p>Hanzo Vector stores payload data in segment files on disk. For sensitive payloads (PII, proprietary content), encryption at rest is provided by:</p>
|
|
<ol><li><strong>Volume encryption</strong>: Kubernetes volumes are encrypted at the block level by DigitalOcean</li><li><strong>Application-level encryption</strong>: The Hanzo Vector SDK supports encrypting payload</li></ol>
|
|
<p> fields before storage using AES-256-GCM with keys from Hanzo KMS. Encrypted fields are stored as opaque byte strings and decrypted on retrieval.</p>
|
|
<h2>Consumers</h2>
|
|
<p>Services in the Hanzo ecosystem that connect to Vector:</p>
|
|
<p>| Service | Use Case | Collection Pattern | |---------|----------|--------------------| | LLM Gateway | RAG context retrieval | <code>{org}-documents</code> | | Chat | Conversation history search | <code>{org}-chat-history</code> | | Search | Semantic search index | <code>{org}-search-index</code> | | Agent SDK | Agent long-term memory | <code>{org}-agent-memory</code> | | MCP | Tool context retrieval | <code>{org}-mcp-context</code> | | Cloud | Model registry search | <code>models</code> | | Commerce | Product recommendations | <code>{org}-products</code> | | Zen | Model capability matching | <code>zen-capabilities</code> |</p>
|
|
<h3>Collection Naming Convention</h3>
|
|
<p>All collections SHOULD follow the pattern <code>{org}-{purpose}</code> or <code>{purpose}</code> for system-wide collections. This enables:</p>
|
|
<ul><li>Per-org monitoring and quota enforcement</li><li>Targeted snapshot/backup schedules</li><li>Clear ownership when debugging resource consumption</li></ul>
|
|
<h2>Monitoring</h2>
|
|
<h3>Built-in Metrics</h3>
|
|
<p>Hanzo Vector exposes Prometheus metrics on the HTTP port at <code>/metrics</code>:</p>
|
|
<pre><code class="lang-bash">curl http://localhost:6334/metrics</code></pre>
|
|
<p>Key metrics:</p>
|
|
<p>| Metric | Description | Alert Threshold | |--------|-------------|-----------------| | <code>collections_total</code> | Number of collections | Informational | | <code>vectors_total</code> | Total vectors across collections | Capacity planning | | <code>grpc_responses_duration_seconds</code> | Search latency histogram | p99 > 50ms | | <code>rest_responses_duration_seconds</code> | REST API latency | p99 > 100ms | | <code>app_info</code> | Version and build info | Informational | | <code>segment_count</code> | Segments per collection | > 20 (needs optimization) |</p>
|
|
<h3>Health Endpoint</h3>
|
|
<pre><code class="lang-bash"># Quick health check
|
|
curl http://localhost:6334/healthz
|
|
|
|
# Detailed telemetry
|
|
curl -H "api-key: ${VECTOR_API_KEY}" \
|
|
http://localhost:6334/telemetry</code></pre>
|
|
<h3>Collection-Level Monitoring</h3>
|
|
<pre><code class="lang-bash"># Collection statistics
|
|
curl -H "api-key: ${VECTOR_API_KEY}" \
|
|
http://localhost:6334/collections/{name}
|
|
|
|
# Response includes:
|
|
# - vectors_count
|
|
# - indexed_vectors_count
|
|
# - points_count
|
|
# - segments_count
|
|
# - optimizer_status
|
|
# - index status (indexed vs indexing)</code></pre>
|
|
<h2>Reference Implementation</h2>
|
|
<p><strong>Repository</strong>: <a href="https://github.com/hanzoai/vector">github.com/hanzoai/vector</a></p>
|
|
<p><strong>Key Files</strong>:</p>
|
|
<ul><li><code>Dockerfile</code> -- Multi-arch container image based on Hanzo Vector 1.13</li><li><code>.github/workflows/deploy.yml</code> -- CI/CD: build, push to GHCR/Docker Hub, deploy to K8s</li><li><code>config/config.yaml</code> -- Full reference configuration</li><li><code>config/init-collections.sh</code> -- Bootstrap script for default collections</li></ul>
|
|
<p><strong>K8s Manifests</strong> (<code>universe/infra/k8s/vector/</code>):</p>
|
|
<ul><li><code>statefulset.yaml</code> -- StatefulSet <code>vector</code> with PVC and health checks</li><li><code>service.yaml</code> -- ClusterIP Service on ports 6333 (gRPC) and 6334 (HTTP)</li><li><code>configmap.yaml</code> -- Hanzo Vector configuration (storage, optimizer, service)</li><li><code>secret.yaml</code> -- API key secret</li><li><code>kustomization.yaml</code> -- Kustomize aggregation</li></ul>
|
|
<p><strong>Status</strong>: Specified, pending initial deployment on <code>the cluster</code></p>
|
|
<h2>References</h2>
|
|
<ol><li><a href="./hip-0000-hanzo-ai-architecture-framework.md">HIP-0: Hanzo AI Architecture Framework</a></li><li><a href="./hip-0004-llm-gateway-unified-ai-provider-interface.md">HIP-4: LLM Gateway</a></li><li><a href="./hip-0009-agent-sdk-multi-agent-orchestration-framework.md">HIP-9: Agent SDK</a></li><li><a href="./hip-0010-model-context-protocol-mcp-integration-standards.md">HIP-10: MCP Integration Standards</a></li><li><a href="./hip-0028-key-value-store-standard.md">HIP-28: Key-Value Store Standard</a></li><li>HIP-32: Object Storage Standard</li><li><a href="https://qdrant.tech/documentation/">Qdrant Documentation</a></li><li><a href="https://arxiv.org/abs/1603.09320">HNSW Algorithm Paper</a> -- Malkov & Yashunin, 2018</li><li><a href="https://hal.inria.fr/inria-00514462v2/document">Product Quantization for Nearest Neighbor Search</a> -- Jegou et al., 2011</li></ol>
|
|
<h2>Copyright</h2>
|
|
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hip-0042.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div>
|
|
</body></html> |