Files
skills/public/hip-0046.html

548 lines
34 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-0046</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-0046.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-0046">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-0046.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-0046</h1><p class="lede">HIP-46: Embeddings Standard. Status Draft. Hanzo&#x27;s own standard — read this before implementing against it.</p><h1>HIP-0046: Embeddings Standard</h1>
<h2>Abstract</h2>
<p>This proposal defines the Embeddings Standard for the Hanzo ecosystem. It specifies a unified, OpenAI-compatible API for text and multimodal embedding generation served through the LLM Gateway (HIP-0004). The standard covers multi-provider routing, batch processing, dimension reduction, caching, chunking strategies, and integration with downstream consumers including Search (HIP-0012), Vector stores (HIP-0042), Agent memory (HIP-0009), and Chat RAG pipelines.</p>
<p><strong>Gateway Endpoint</strong>: <code>POST /v1/embeddings</code> <strong>Gateway Port</strong>: 4000 <strong>Protocol</strong>: OpenAI-compatible REST API</p>
<h2>Specification</h2>
<p>| <code>text-embedding-ada-002</code> | OpenAI | 1536 | 8191 | $0.10 | Legacy, wide compatibility | | <code>embed-english-v3.0</code> | Cohere | 1024 | 512 | $0.10 | English retrieval | | <code>embed-multilingual-v3.0</code> | Cohere | 1024 | 512 | $0.10 | 100+ languages | | <code>embed-english-light-v3.0</code> | Cohere | 384 | 512 | $0.10 | Lightweight English | | <code>hanzo/bge-large</code> | Engine | 1024 | 8192 | Self-hosted | On-prem, no data egress | | <code>hanzo/e5-large</code> | Engine | 1024 | 512 | Self-hosted | On-prem, multilingual | | <code>hanzo/clip-vit-l-14</code> | Engine | 768 | N/A | Self-hosted | Multimodal (text + image) |</p>
<p>*Supports Matryoshka dimension reduction: 256, 512, 1024, or full size.</p>
<h4>Model Selection Guidelines</h4>
<pre><code class="lang-yaml">Use Cases:
high_quality_retrieval:
model: text-embedding-3-large
dimensions: 3072
rationale: Maximum semantic fidelity for critical search
general_rag:
model: text-embedding-3-large
dimensions: 1024
rationale: Good quality at 1/3 storage cost
real_time_search:
model: text-embedding-3-small
dimensions: 512
rationale: Sub-10ms latency, acceptable quality
multilingual:
model: embed-multilingual-v3.0
rationale: Best cross-language performance
cost_sensitive:
model: text-embedding-3-small
dimensions: 256
rationale: Lowest cost, suitable for coarse filtering
air_gapped:
model: hanzo/bge-large
rationale: No external API calls, full data sovereignty
multimodal:
model: hanzo/clip-vit-l-14
rationale: Shared text-image embedding space</code></pre>
<h3>Batch API</h3>
<p>For bulk embedding workloads (document ingestion, index rebuilding), the batch API provides asynchronous processing with higher throughput limits and lower per-token cost.</p>
<h4>Create Batch</h4>
<pre><code>POST /v1/embeddings/batches
Content-Type: application/json
Authorization: Bearer sk-hanzo-...</code></pre>
<pre><code class="lang-json">{
&quot;model&quot;: &quot;text-embedding-3-large&quot;,
&quot;input_file_id&quot;: &quot;file-abc123&quot;,
&quot;dimensions&quot;: 1024,
&quot;encoding_format&quot;: &quot;base64&quot;,
&quot;metadata&quot;: {
&quot;purpose&quot;: &quot;document_ingestion&quot;,
&quot;collection&quot;: &quot;knowledge_base_v2&quot;
}
}</code></pre>
<p>The <code>input_file_id</code> references a JSONL file uploaded via the Files API, where each line is:</p>
<pre><code class="lang-jsonl">{&quot;custom_id&quot;: &quot;doc-001&quot;, &quot;input&quot;: &quot;First document text...&quot;}
{&quot;custom_id&quot;: &quot;doc-002&quot;, &quot;input&quot;: &quot;Second document text...&quot;}</code></pre>
<h4>Batch Response</h4>
<p>Returns a batch object with <code>id</code>, <code>status</code> (<code>queued</code> / <code>processing</code> / <code>completed</code> / <code>failed</code>), <code>request_counts</code> (total/completed/failed), and <code>output_file_id</code>. Poll status via <code>GET /v1/embeddings/batches/{batch_id}</code>. When completed, the output file is JSONL with <code>custom_id</code>, <code>embedding</code>, <code>index</code>, and <code>tokens</code> per line.</p>
<h4>Batch Pricing</h4>
<p>Batch embeddings are billed at 50% of the real-time rate. For <code>text-embedding-3-large</code>: $0.065 per 1M tokens instead of $0.13.</p>
<h3>Caching</h3>
<p>The Gateway implements a semantic embedding cache to eliminate redundant computation.</p>
<h4>Cache Architecture</h4>
<pre><code>┌────────────────┐ ┌───────────────┐ ┌──────────────┐
│ Embedding │────▶│ Cache Layer │────▶│ Provider │
│ Request │ │ (KV ) │ │ (OpenAI, │
│ │◀────│ │◀────│ Cohere) │
└────────────────┘ └───────────────┘ └──────────────┘</code></pre>
<h4>Cache Key Computation</h4>
<p>Cache keys are computed as:</p>
<pre><code>key = SHA-256(model || dimensions || encoding_format || normalize(input))</code></pre>
<p>Where <code>normalize(input)</code> applies:</p>
<ol><li>Unicode NFC normalization</li><li>Whitespace collapsing (multiple spaces to single)</li><li>Leading/trailing whitespace removal</li></ol>
<p>This ensures that semantically identical inputs with trivial formatting differences produce cache hits.</p>
<h4>Cache Configuration</h4>
<pre><code class="lang-yaml">embedding_cache:
enabled: true
backend: redis
ttl: 86400 # 24 hours default
max_entries: 10_000_000
max_memory: 8GB
eviction: lru
# Per-model TTL overrides
model_ttl:
text-embedding-3-large: 604800 # 7 days (expensive)
text-embedding-3-small: 86400 # 1 day (cheap)
# Skip cache for these patterns
bypass:
- &quot;hanzo/*&quot; # Local models have no API cost</code></pre>
<h4>Cache Metrics</h4>
<p>The Gateway exposes cache metrics via Prometheus (HIP-0031):</p>
<pre><code>hanzo_embedding_cache_hits_total{model=&quot;text-embedding-3-large&quot;}
hanzo_embedding_cache_misses_total{model=&quot;text-embedding-3-large&quot;}
hanzo_embedding_cache_hit_rate{model=&quot;text-embedding-3-large&quot;}
hanzo_embedding_cache_size_bytes
hanzo_embedding_cache_evictions_total</code></pre>
<h3>Chunking Strategies</h3>
<p>Embedding models have finite context windows. Documents exceeding the model&#x27;s max token limit MUST be split into chunks before embedding. The Gateway does not perform chunking; it is the responsibility of the caller. Three strategies are recommended.</p>
<p><strong>Fixed-Size Chunking</strong>: Split text into chunks of a fixed token count with configurable overlap. Default: 512 tokens, 64-token overlap (12.5%). Simple, predictable, works for uniform content like chat logs.</p>
<p><strong>Semantic Chunking</strong>: Split at natural boundaries (paragraphs, sections) while respecting token limits. Produces higher-quality embeddings because each chunk contains a coherent unit of meaning. Best for structured documents.</p>
<p><strong>Recursive Chunking</strong>: Split hierarchically -- first by section headers, then paragraphs, then sentences, then token boundaries. Most robust for heterogeneous documents. Falls back gracefully when structure is absent.</p>
<h4>Strategy Selection</h4>
<p>| Document Type | Strategy | Chunk Size | Overlap | Rationale | |--------------------|------------|------------|---------|------------------------------------| | Knowledge base | Semantic | 512 | - | Coherent units for retrieval | | Source code | Recursive | 1024 | 128 | Preserve function boundaries | | Chat logs | Fixed | 256 | 32 | Uniform message lengths | | Academic papers | Recursive | 512 | 64 | Respect section structure | | API documentation | Semantic | 384 | - | One endpoint per chunk |</p>
<h3>Normalization</h3>
<p>All embedding vectors MUST be L2-normalized before storage in vector databases. Normalized vectors have unit length (||v|| = 1), which makes cosine similarity equivalent to dot product. Dot product is computationally cheaper (no division), so normalization enables faster similarity search.</p>
<h4>Normalization Formula</h4>
<pre><code>v_normalized = v / ||v||_2
where ||v||_2 = sqrt(sum(v_i^2))</code></pre>
<h4>Implementation</h4>
<pre><code class="lang-python">import numpy as np
def normalize(embedding: list[float]) -&gt; list[float]:
v = np.array(embedding, dtype=np.float32)
norm = np.linalg.norm(v)
if norm == 0:
return v.tolist()
return (v / norm).tolist()</code></pre>
<p>OpenAI models return pre-normalized vectors. Cohere models do not; the Gateway normalizes Cohere outputs before returning them to callers. Local models vary; the Gateway checks and normalizes as needed.</p>
<p>The Gateway normalizes per-provider: OpenAI vectors are pre-normalized (skipped), Cohere and Engine outputs are normalized before returning to callers.</p>
<h3>Integration Points</h3>
<h4>Vector Store Ingestion (HIP-0042)</h4>
<p>The primary consumer of embeddings. Documents are chunked, embedded, and inserted into vector collections:</p>
<pre><code class="lang-python">from hanzo import embeddings, vector
# Chunk the document
chunks = semantic_chunk(document.text, max_tokens=512)
# Generate embeddings via Gateway
response = embeddings.create(
model=&quot;text-embedding-3-large&quot;,
input=chunks,
dimensions=1024
)
# Insert into vector store
vector.upsert(
collection=&quot;knowledge_base&quot;,
vectors=[
{
&quot;id&quot;: f&quot;{document.id}-{d.index}&quot;,
&quot;values&quot;: d.embedding,
&quot;metadata&quot;: {
&quot;document_id&quot;: document.id,
&quot;chunk_index&quot;: d.index,
&quot;text&quot;: chunks[d.index]
}
}
for d in response.data
]
)</code></pre>
<h4>Search Indexing (HIP-0012)</h4>
<p>The Search engine uses embeddings for hybrid search (BM25 + vector similarity):</p>
<pre><code class="lang-python"># Index document with embedding for hybrid search
search.index(
index=&quot;documents&quot;,
document={
&quot;id&quot;: doc.id,
&quot;title&quot;: doc.title,
&quot;content&quot;: doc.content,
&quot;_vectors&quot;: {
&quot;default&quot;: embeddings.create(
model=&quot;text-embedding-3-large&quot;,
input=doc.content[:8000],
dimensions=1024
).data[0].embedding
}
}
)</code></pre>
<h4>Agent Memory (HIP-0009)</h4>
<p>Agents embed memories for semantic recall. Store uses <code>text-embedding-3-small</code> at 512 dimensions for cost efficiency. Recall embeds the query with the same model and performs vector similarity search against the agent&#x27;s memory collection.</p>
<h4>Chat RAG Pipeline</h4>
<p>Chat (HIP-0011) uses embeddings for retrieval-augmented generation: embed the user query, retrieve top-k relevant chunks from the vector store, inject them as system context, and generate the response via LLM Gateway. The embedding model for RAG queries should match the model used during document ingestion to ensure consistent vector space alignment.</p>
<h3>Multimodal Embeddings</h3>
<p>Multimodal embeddings map text and images into the same vector space, enabling cross-modal search (e.g., searching images with text queries).</p>
<p>CLIP-based models are available via Engine for self-hosted deployments. Text inputs use the standard <code>input</code> field. Image inputs use <code>{&quot;type&quot;: &quot;image&quot;, &quot;data&quot;: &quot;&lt;base64&gt;&quot;}</code>. Both produce vectors in the same 768-dimensional space, enabling cross-modal similarity via dot product.</p>
<h4>Roadmap</h4>
<p>| Phase | Model | Modalities | Status | |-------|----------------|------------------|----------| | 1 | CLIP ViT-L/14 | Text + Image | Available| | 2 | SigLIP | Text + Image | Planned | | 3 | ImageBind | Text + Image + Audio + Video | Planned | | 4 | Unified Embed | All modalities | Research |</p>
<p>Multimodal embedding API extensions will be specified in a future HIP when the interface stabilizes.</p>
<h3>Rate Limits and Quotas</h3>
<p>Rate limits are enforced per API key at the Gateway level. Limits vary by model tier and account plan.</p>
<h4>Default Rate Limits</h4>
<p>| Plan | Requests/min | Tokens/min | Batch Quota/day | |-------------|-------------|--------------|-----------------| | Free | 60 | 100,000 | 500,000 tokens | | Developer | 500 | 1,000,000 | 10M tokens | | Team | 3,000 | 10,000,000 | 100M tokens | | Enterprise | 10,000 | 50,000,000 | Unlimited |</p>
<p>All responses include <code>X-RateLimit-*</code> headers: <code>Limit-Requests</code>, <code>Limit-Tokens</code>, <code>Remaining-Requests</code>, <code>Remaining-Tokens</code>, <code>Reset-Requests</code>, <code>Reset-Tokens</code>. On 429, clients SHOULD implement exponential backoff with jitter.</p>
<h3>Error Handling</h3>
<p>Errors follow the OpenAI error format: <code>{&quot;error&quot;: {&quot;message&quot;, &quot;type&quot;, &quot;code&quot;, &quot;param&quot;}}</code>.</p>
<h4>Error Codes</h4>
<p>| HTTP Status | Code | Description | |-------------|-------------------------|---------------------------------------------| | 400 | <code>invalid_request</code> | Malformed request body or missing fields | | 400 | <code>invalid_model</code> | Model not found or not an embedding model | | 400 | <code>invalid_dimensions</code> | Dimensions not supported by model | | 400 | <code>input_too_long</code> | Input exceeds model&#x27;s max token limit | | 400 | <code>batch_too_large</code> | More than 2048 inputs in array | | 401 | <code>invalid_api_key</code> | Missing or invalid API key | | 403 | <code>insufficient_quota</code> | Account has no remaining embedding quota | | 429 | <code>rate_limit_exceeded</code> | Rate limit hit; retry after indicated time | | 500 | <code>provider_error</code> | Upstream provider returned an error | | 503 | <code>provider_unavailable</code> | Provider is down; failover in progress |</p>
<h3>Monitoring and Observability</h3>
<p>The Gateway exposes embedding-specific metrics via Prometheus (HIP-0031) and logs to the unified observability stack.</p>
<h4>Prometheus Metrics</h4>
<pre><code># Latency histogram by model and provider
hanzo_embedding_latency_seconds{model, provider, status}
# Request counter by model
hanzo_embedding_requests_total{model, provider, status, encoding_format}
# Token counter by model
hanzo_embedding_tokens_total{model, provider}
# Batch size histogram
hanzo_embedding_batch_size{model}
# Dimension usage counter
hanzo_embedding_dimensions_used{model, dimensions}
# Cache metrics
hanzo_embedding_cache_hits_total{model}
hanzo_embedding_cache_misses_total{model}
hanzo_embedding_cache_hit_rate{model}
# Provider health
hanzo_embedding_provider_up{provider}
hanzo_embedding_provider_latency_p99{provider}</code></pre>
<h4>Alert Rules</h4>
<p>Recommended alerts: <code>EmbeddingLatencyHigh</code> (p99 &gt; 2s for 5m), <code>EmbeddingProviderDown</code> (provider_up == 0 for 1m, critical), <code>EmbeddingCacheHitRateLow</code> (hit_rate &lt; 0.3 for 15m), <code>EmbeddingErrorRateHigh</code> (error rate &gt; 5% for 5m, critical).</p>
<h4>Structured Logging</h4>
<p>Every embedding request produces a structured JSON log entry containing: timestamp, model, provider, dimensions, input_count, total_tokens, latency_ms, cache_hit, user_id, and api_key_hash. Raw input text MUST NOT appear in logs at INFO level.</p>
<h3>Gateway Routing Configuration</h3>
<p>The Gateway routes embedding requests based on the <code>model</code> field. Provider selection, failover, and load balancing are configured in the Gateway config:</p>
<pre><code class="lang-yaml"># /app/config.yaml (LLM Gateway)
embeddings:
providers:
openai:
api_key: ${OPENAI_API_KEY}
models:
- text-embedding-3-large
- text-embedding-3-small
- text-embedding-ada-002
rate_limit: 10000/min
timeout: 30s
retry:
max_attempts: 3
backoff: exponential
cohere:
api_key: ${COHERE_API_KEY}
models:
- embed-english-v3.0
- embed-multilingual-v3.0
- embed-english-light-v3.0
rate_limit: 5000/min
timeout: 30s
engine:
base_url: http://engine:8080
models:
- hanzo/bge-large
- hanzo/e5-large
- hanzo/clip-vit-l-14
rate_limit: 0 # No limit for local models
timeout: 10s
failover:
text-embedding-3-large:
- text-embedding-3-small # Same provider, smaller model
- embed-english-v3.0 # Different provider
embed-english-v3.0:
- text-embedding-3-small # Cross-provider failover
defaults:
encoding_format: float
normalize: true</code></pre>
<h3>Client Examples</h3>
<h4>Python (OpenAI SDK)</h4>
<pre><code class="lang-python">from openai import OpenAI
client = OpenAI(
base_url=&quot;https://llm.hanzo.ai/v1&quot;,
api_key=&quot;sk-hanzo-...&quot;
)
# Single embedding
response = client.embeddings.create(
model=&quot;text-embedding-3-large&quot;,
input=&quot;Hanzo provides unified AI infrastructure&quot;,
dimensions=1024
)
vector = response.data[0].embedding
print(f&quot;Dimensions: {len(vector)}&quot;) # 1024
# Batch embedding
texts = [&quot;First document&quot;, &quot;Second document&quot;, &quot;Third document&quot;]
response = client.embeddings.create(
model=&quot;text-embedding-3-small&quot;,
input=texts,
encoding_format=&quot;base64&quot;
)
for item in response.data:
print(f&quot;Index {item.index}: {len(item.embedding)} chars (base64)&quot;)</code></pre>
<h4>JavaScript (Hanzo SDK)</h4>
<pre><code class="lang-javascript">import { HanzoAI } from &#x27;@hanzoai/sdk&#x27;
const hanzo = new HanzoAI({ apiKey: &#x27;sk-hanzo-...&#x27; })
const response = await hanzo.embeddings.create({
model: &#x27;text-embedding-3-large&#x27;,
input: [&#x27;Hello world&#x27;, &#x27;Goodbye world&#x27;],
dimensions: 512
})
for (const item of response.data) {
console.log(`Index ${item.index}: [${item.embedding.slice(0, 3).join(&#x27;, &#x27;)}...]`)
}</code></pre>
<h4>cURL</h4>
<pre><code class="lang-bash">curl -X POST https://llm.hanzo.ai/v1/embeddings \
-H &quot;Content-Type: application/json&quot; \
-H &quot;Authorization: Bearer sk-hanzo-...&quot; \
-d &#x27;{
&quot;model&quot;: &quot;text-embedding-3-large&quot;,
&quot;input&quot;: &quot;Sample text&quot;,
&quot;dimensions&quot;: 1024
}&#x27;</code></pre>
<h2>Security Considerations</h2>
<ol><li><strong>Data in Transit</strong>: All API communication MUST use TLS 1.3. The Gateway terminates TLS; upstream provider calls use TLS.</li><li><strong>Data at Rest</strong>: Cached embeddings in KV SHOULD be encrypted at rest when the deployment requires it. Embeddings themselves are not directly invertible to source text, but they can leak semantic information.</li><li><strong>API Key Scoping</strong>: Embedding API keys can be scoped to specific models and rate limits. A key with <code>embedding:read</code> scope cannot access chat completions.</li><li><strong>Input Logging</strong>: Raw input text MUST NOT be logged at INFO level. Only token counts, model names, and latency are logged by default. Debug-level logging of inputs requires explicit opt-in.</li><li><strong>Provider Key Isolation</strong>: Provider API keys (OpenAI, Cohere) are stored in KMS (HIP-0027) and injected at runtime. They never appear in config files, logs, or error messages.</li></ol>
<h2>Test Vectors</h2>
<p>Conformance tests: (1) embed <code>&quot;hello&quot;</code> with <code>text-embedding-3-small</code> at 8 dimensions, verify vector length and values within tolerance 0.001; (2) embed <code>[&quot;hello&quot;, &quot;world&quot;]</code>, verify 2 results with indices [0, 1]; (3) embed <code>&quot;hello&quot;</code> with <code>text-embedding-3-large</code> at 256 dimensions, verify L2 norm equals 1.0 within tolerance 0.0001.</p>
<h2>Reference Implementation</h2>
<p>The reference implementation lives in the LLM Gateway codebase:</p>
<ul><li><strong>Gateway</strong>: <a href="https://github.com/hanzoai/llm">github.com/hanzoai/llm</a> -- <code>src/embeddings/</code></li><li><strong>Python SDK</strong>: <a href="https://github.com/hanzoai/python-sdk">github.com/hanzoai/python-sdk</a> -- <code>hanzoai/embeddings.py</code></li><li><strong>JS SDK</strong>: <a href="https://github.com/hanzoai/js-sdk">github.com/hanzoai/js-sdk</a> -- <code>src/resources/embeddings.ts</code></li><li><strong>Go SDK</strong>: <a href="https://github.com/hanzoai/go-sdk">github.com/hanzoai/go-sdk</a> -- <code>embeddings.go</code></li></ul>
<h2>References</h2>
<ul><li><a href="./hip-0004-llm-gateway-unified-ai-provider-interface.md">HIP-0004: LLM Gateway</a></li><li><a href="./hip-0009-agent-sdk-multi-agent-orchestration-framework.md">HIP-0009: Agent SDK</a></li><li><a href="./hip-0012-search-interface-standard.md">HIP-0012: Search Interface Standard</a></li><li><a href="./hip-0042-vector-search-standard.md">HIP-0042: Vector Store Standard</a></li><li><a href="https://platform.openai.com/docs/api-reference/embeddings">OpenAI Embeddings API Reference</a></li><li><a href="https://docs.cohere.com/reference/embed">Cohere Embed API Reference</a></li><li><a href="https://arxiv.org/abs/2205.13147">Matryoshka Representation Learning (Kusupati et al., 2022)</a></li><li><a href="https://huggingface.co/spaces/mteb/leaderboard">MTEB: Massive Text Embedding Benchmark</a></li></ul>
<h2>Copyright</h2>
<p>Copyright 2026 Hanzo AI Inc. All rights reserved.</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-0046.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div>
</body></html>