Vector stores

Vector stores es RAG-as-a-service: creas una colección, subes texto, y Geek Hub se encarga de chunking + embedding + almacenamiento en pgvector con índice HNSW. Consulta con top-k por similitud coseno. Cuándo usar esto en vez de tu propio pgvector/Pinecone:

Prototipo de RAG en horas, no días
Uno menos servicio que operar
Cost inline en cada operación (mismo tokenización que /v1/embeddings)
Aisla por org via RLS de Supabase

Cuándo NO:

Más de ~1M chunks — el índice HNSW empieza a costar RAM en Postgres
Metadata filtering complejo (hybrid search, reranking) — usa una DB dedicada
Ya tienes pipeline de embeddings — no ganas nada

Crear colección

curl -X POST https://api.geekhub.mx/v1/vector-stores \
  -H "Authorization: Bearer ghub_sk_live_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "docs-producto",
    "model": "openai/text-embedding-3-small"
  }'

Devuelve el id del store, que usarás en las siguientes llamadas.

Subir texto

curl -X POST https://api.geekhub.mx/v1/vector-stores/$STORE_ID/files \
  -H "Authorization: Bearer ghub_sk_live_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "faq.md",
    "text": "…contenido completo del documento…",
    "chunk_tokens": 512,
    "overlap_tokens": 64,
    "metadata": { "source": "notion", "version": "v2" }
  }'

El gateway:

Split del texto en chunks de ~512 tokens con 64 de overlap
Embed todos los chunks (batch al proveedor)
Insert en pgvector con tu metadata
Cobra los input_tokens del embedding

Response:

{
  "id": "file_uuid",
  "store_id": "store_uuid",
  "filename": "faq.md",
  "chunk_count": 24,
  "input_tokens": 12480,
  "created_at": "2026-07-06T18:03:12Z"
}

Consultar top-k

curl -X POST https://api.geekhub.mx/v1/vector-stores/$STORE_ID/query \
  -H "Authorization: Bearer ghub_sk_live_TU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cómo genero mi API key",
    "top_k": 5
  }'

Response:

{
  "object": "list",
  "data": [
    {
      "id": "chunk_uuid",
      "file_id": "file_uuid",
      "chunk_index": 3,
      "content": "Para generar una API key, ve a /dashboard/keys …",
      "metadata": { "source": "notion", "version": "v2" },
      "similarity": 0.83
    }
  ],
  "usage": { "prompt_tokens": 7 }
}

similarity va de 1 (idéntico) a -1 (opuesto). En la práctica útil > 0.7.

Otros endpoints

GET /v1/vector-stores — lista todos los stores de tu org
GET /v1/vector-stores/:id — detalle + files
DELETE /v1/vector-stores/:id — borra store + cascade a files y chunks

Costos

Embedding de upload y query: tokens × precio del modelo del store
Almacenamiento: gratis en v1 (subject a change si empieza a costar)
Query: solo el embedding de la query (no del corpus almacenado)

Roadmap

Upload de PDF/DOCX con parsing server-side
Hybrid search (BM25 + vectors)
Metadata filtering con filter: { key: value }
Chunking configurable por semantic boundaries (usando LLM)

Empezar

Conceptos

Features avanzadas

Legal & cumplimiento

Crear colección

Subir texto

Consultar top-k

Otros endpoints

Costos

Roadmap

​Crear colección

​Subir texto

​Consultar top-k

​Otros endpoints

​Costos

​Roadmap

Crear colección

Subir texto

Consultar top-k

Otros endpoints

Costos

Roadmap