Embed (Embeddings) — foundations RFC

Status

*ccepted*— ratificada 20260509 (mesmo dia da abertura) como parte da onda piloto de bootstrap servicesai. Implementação iniciada em `servicesaiembed; tickets em servicesaiembedbacklogpending/{001..005}`.

Summary

Foundation pra geração de embeddings — text, image, audio. Centraliza modelos, cache, vector store. Hoje kortex/ faz semantic indexing como produto, mas embeddings não é reutilizável.

Motivation

Toda RAGrecsyssearch depende de embeddings. Hoje cada um instancia próprio modelo (kortex tem, rag tem, recsys tem). Falta service unificado com cache + multi-model + benchmark.

Scope

In

• Text embed (multilíngue)
• Image embed (CLIP)
• Audio embed (CLAP)
• Cache
• Vector store integration (kdb-vector)

Out (yet)

• Vector indexing/search (já é kdb-vector infra)

Initial design

Surfaces

• backend/ — Go API + worker
• app/ — não aplicável v1

Key APIs

• POST /v1/embed/text — text embeddings
• POST /v1/embed/image — image embeddings
• POST /v1/embed/audio — audio embeddings
• GET /v1/embed/models — modelos disponíveis

Dependencies

• services/ai/gateway — fallback proxy pra embeddings hosted
• services/ai/runtime — modelos local
• infra/data/kdb-vector — vector store
• cache (response cache via cache/)

Relation to existing sectors

• Subsume embeddings hoje em kortexragrecsys
• Consumido por memory, search, classify, extract

Selfhostedfirst analysis (5 gates)

• *1 Feature parity* zero como service
• *2 Performance* NA (a calibrar contra OpenAIVoyage)
• *3 Stability* N/A
• *4 Capability* BGEE5Voyage rodam local
• *5 Critical-path readiness* bloqueia consolidação RAGkortexrecsys

Open questions

• Q1: Migrar embeddings de kortexragrecsys pra cá ou coexistir?
• Q2: Default model — ptBR friendly (BGEmultilingual)?

Next steps

1. Ratificar esta RFC (1 round of comments).
2. Criar sector dir services/ai/embed/ com koder.toml, README.md, skeleton.
3. Abrir tickets de implementação em services/ai/embed/backlog/pending/.
4. Registrar em meta/docs/stack/registries/self-hosted-pairs.md se substituir externo.