ajianaz/codomate/embeddinggemma-qdrant

EmbeddingGemma ONNX — Base Skill

Base skill for local embedding pipeline. Use the specific skill for your use case:

• embeddinggemma-knowledge — hermes-knowledge collection (newsletter, riset, digest, blog)
• embeddinggemma-novel — novel chapters collection

Architecture

Text → EmbeddingGemma ONNX (768d) → embed_utils.py (rate control) → Qdrant (cosine similarity)

Quick Start

import sys; sys.path.insert(0, "${SCRIPTS_DIR}")
import embeddinggemma
vec = embeddinggemma.embed_one("Hello world", dimensions=768)
vectors = embeddinggemma.embed_texts(["Hello", "World"], dimensions=512)

Packages: onnxruntime + tokenizers only. NO optimum/transformers/torch.

Rate Limits (MANDATORY)

Server: 4 cores, Qdrant on same machine. ALWAYS use `embed_utils.py`:

from embed_utils import embed_with_control, embed_one_with_control, acquire_embed_lock, release_embed_lock
# Single
vec = embed_one_with_control("text", dimensions=768)
# Batch with lock
fd = acquire_embed_lock()
try:
    vectors = embed_with_control(texts, dimensions=768)
finally:
    release_embed_lock(fd)

Collections

⛔ Match dimension to collection — mismatch → 400 crash.

Critical Gotchas

• Server crash = embedding too fast. Always use embed_utils.py, never inline load checks.
• No concurrent jobs — combine check_load() + acquire_embed_lock().
• Qdrant URL must use ${QDRANT_URL} — localhost:6333 doesn't work from inside Docker.
• Point IDs must be UUID strings (use str(uuid.uuid4())). Hex truncation like uuid.uuid4().hex[:16] → 400 error.
• Qdrant client `https=False` required when connecting to local Qdrant from within Docker. Without it, SSL handshake fails: record layer failure. Also suppress warning: UserWarning: Api key is used with an insecure connection.
• `embeddinggemma` is a local module at ${EMBEDDINGGEMMA_MODULE}, not a pip package.
• Mean pooling: NEVER use keepdims=True — produces wrong shape (batch,1,768).

References

• Setup & Configuration — Model storage, packages, Qdrant config, collections, stress test
• Code Examples — Loading, embed functions, Qdrant client/REST, embed_utils, migration
• Pitfalls — All gotchas and critical warnings