Embeddings

AI / ML Intermediate

debt(d8/e7/b6/t7)

d8 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'silent in production until users hit it' (d9), scored d8. The detection_hints explicitly state 'automated: no' and the code patterns (mismatched models, missing normalisation, no caching) produce no compiler or linter errors. Retrieval quality silently degrades — results are returned but semantically wrong — and users only notice when search relevance is poor. Slightly below d9 because careful code review or integration testing can sometimes catch model mismatch issues before full production load.

e7 Effort Remediation debt — work required to fix once spotted

Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix states switching models 'invalidates your entire index and requires re-embedding all documents' — this means re-running embedding generation for all stored content, updating the vector DB, and re-deploying. Common mistakes like mismatched models or wrong chunking strategy affect the entire retrieval pipeline. This is more than a one-component fix but not quite a full architectural rewrite, landing at e7.

b6 Burden Structural debt — long-term weight of choosing wrong

Closest to 'persistent productivity tax' (b5), scored b6. Embeddings are load-bearing across web and CLI contexts per applies_to, and the vector-database tag indicates infrastructure commitment. Every search, RAG pipeline, and recommendation feature is shaped by the choice of embedding model and chunking strategy. Model choice creates lock-in because changing it invalidates the index. This is a persistent tax on multiple workstreams but doesn't fully define the system's shape at b7.

t7 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'serious trap (contradicts how a similar concept works elsewhere)' (t7). The misconception field states developers believe embeddings are 'just keyword matching' — an extremely common wrong mental model imported from traditional search. Additionally, the common_mistakes show multiple non-obvious gotchas: vectors from different models are incomparable, normalisation is required for correct cosine similarity, and chunking strategy substantially affects precision. These contradictions of intuitive expectations from keyword-search experience place this firmly at t7.

About DEBT scoring → scored by claude-sonnet-4-6 · 2026-05-07 · reviewed by human

Also Known As

vector embeddings text embeddings semantic vectors

TL;DR

Dense numerical vector representations of text, images, or other data — capturing semantic meaning so that similar items have similar vectors and can be found via distance search.

Explanation

An embedding model converts text into a vector of floats (e.g. 1536 dimensions for text-embedding-3-small). The key property: semantically similar texts have vectors that are close in high-dimensional space, measurable by cosine similarity or dot product. Embeddings power semantic search, recommendation systems, and RAG pipelines. Generating them via API (OpenAI, Cohere, local models via Ollama) and storing them in a vector database enables fast approximate nearest-neighbour search at scale.

Diagram

flowchart LR
    TEXT[Text input<br/>PHP array functions] --> MODEL[Embedding model<br/>text-embedding-3-small]
    MODEL --> VEC[Vector<br/>1536 dimensions<br/>0.2 0.8 -0.3 ...]
    subgraph Similarity_Search
        Q[Query: how to sort arrays] --> QV[Query vector]
        QV -->|cosine similarity| DB3[(Vector DB<br/>pgvector Pinecone)]
        DB3 -->|nearest neighbours| RESULTS2[Similar documents ranked]
    end
    subgraph Use_Cases
        SEARCH2[Semantic search<br/>finds related not just keyword]
        RAG2[RAG retrieval<br/>find relevant context]
        CLUSTER[Cluster similar items]
    end
style MODEL fill:#6e40c9,color:#fff
style VEC fill:#1f6feb,color:#fff
style RESULTS2 fill:#238636,color:#fff

Common Misconception

✗ Embeddings are just keyword matching — embeddings capture semantic meaning; 'car' and 'automobile' have similar vectors despite sharing no characters.

Why It Matters

Embeddings enable semantic search that finds relevant results even when the exact words differ — the foundation of RAG, recommendation engines, and duplicate detection.

Common Mistakes

Comparing embeddings from different models — vectors from model A are not comparable to vectors from model B; always use the same model.
Not normalising vectors before cosine similarity — unnormalised vectors give incorrect similarity scores.
Chunking documents too large before embedding — a 10-page document embedded as one vector loses fine-grained retrieval precision.
Not caching embeddings — regenerating embeddings for unchanged text wastes API costs; store them in a vector DB.

Code Examples

✗ Vulnerable

// Mixing embeddings from different models — meaningless comparison:
$vec1 = openai()->embed('PHP security', model: 'text-embedding-3-small'); // 1536 dims
$vec2 = cohere()->embed('PHP security', model: 'embed-english-v3.0');     // 1024 dims
$similarity = cosineSimilarity($vec1, $vec2); // Comparing apples to oranges

✓ Fixed

// Consistent model, stored embeddings, cosine similarity:
$model = 'text-embedding-3-small';
// Store once:
$embedding = $openai->embeddings->create(['input' => $text, 'model' => $model]);
$vector = $embedding->data[0]->embedding;
$db->query('INSERT INTO documents (content, embedding) VALUES (?, ?)', [$text, json_encode($vector)]);
// Search:
$queryVec = $openai->embeddings->create(['input' => $query, 'model' => $model])->data[0]->embedding;
// Vector DB finds nearest neighbours via cosine similarity

References

https://platform.openai.com/docs/guides/embeddings