Embed (Embeddings): foundations

accepted

Status

accepted — ratificada 2026-05-09 (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

Self-hosted-first analysis (5 gates)

  • G1 Feature parity: zero como service
  • G2 Performance: NA (a calibrar contra OpenAIVoyage)
  • G3 Stability: N/A
  • G4 Capability: BGEE5Voyage rodam local
  • G5 Critical-path readiness: bloqueia consolidação RAGkortexrecsys

Open questions

  • Q1: Migrar embeddings de kortexragrecsys pra cá ou coexistir?
  • Q2: Default model — pt-BR friendly (BGE-multilingual)?

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.