docs/places_semantic_deployment.md

Backfill y activacion del retriever semantico de Places

Esta guia despliega exclusivamente el retriever de Places. El modelo BERT de intencion se configura por separado con PLACES_CHAT_BERT_* y no participa en el backfill de place_embeddings_semantic_v1.

Regla principal de seguridad

El proveedor, la dimension y las funciones SQL deben cambiar como un solo perfil. Nunca mezcles un embedding de 768 dimensiones con las funciones FastText de 300 dimensiones.

Etapa	Proceso	Proveedor	Dimension	Lectura	Escritura
Durante backfill	Space productivo	fasttext	300	match_places	funciones legacy
Durante backfill	Colab	sentence_transformer	768	no se usa	funciones *_semantic_v1
Despues de verificar	Space productivo	sentence_transformer	768	funciones *_semantic_v1	funciones *_semantic_v1

Si el Space ya tiene PLACES_EMBEDDING_PROVIDER=sentence_transformer y todavia usa PLACES_PGVECTOR_MATCH_FUNCTION=match_places, pausalo o vuelve temporalmente al perfil FastText antes de desplegar el codigo nuevo.

1. Identificar exactamente el modelo

En el repositorio del retriever de Hugging Face abre Files and versions, entra al historial del commit publicado y copia el SHA completo de 40 caracteres. No uses main: el contenido de main puede cambiar.

Conserva estos dos valores:

MODEL_ID=tu-usuario/places-e5-retriever-v1
MODEL_SHA=0123456789abcdef0123456789abcdef01234567

PLACES_EMBEDDING_MODEL_REVISION controla los archivos exactos descargados. PLACES_EMBEDDING_VERSION es la etiqueta que queda visible en PostgreSQL. Se recomienda places-e5-retriever-v1@<MODEL_SHA>.

2. Preparar Colab

No se necesita GPU para el backfill. Con CPU usa lotes pequenos; una GPU solo reduce el tiempo.

En Colab > Secrets crea y habilita el acceso al notebook para:

• PGVECTOR_WRITER_PASSWORD: password del rol nlp_writer.
• MAIN_API_INTERNAL_TOKEN: solo si la API principal protege el snapshot.
• HF_TOKEN: solo es obligatorio si el repositorio del retriever es privado.

No pongas passwords o tokens directamente en una celda.

Clona la rama o commit que contiene esta implementacion:

!git clone --branch RAMA_CON_ESTOS_CAMBIOS \
  https://github.com/AlleksDev/Frimeet-API-NLP.git \
  /content/Frimeet-API-NLP
%cd /content/Frimeet-API-NLP
!git rev-parse HEAD

Configura solamente valores no secretos. Sustituye cada ejemplo por el valor real del entorno:

import os

MODEL_ID = "tu-usuario/places-e5-retriever-v1"
MODEL_SHA = "0123456789abcdef0123456789abcdef01234567"

os.environ["PLACES_EMBEDDING_MODEL"] = MODEL_ID
os.environ["PLACES_EMBEDDING_MODEL_REVISION"] = MODEL_SHA
os.environ["PLACES_EMBEDDING_VERSION"] = f"places-e5-retriever-v1@{MODEL_SHA}"
os.environ["PLACES_EMBEDDING_FIX_MISTRAL_REGEX"] = "true"
os.environ["PLACES_EMBEDDING_DEVICE"] = "cpu"
os.environ["PLACES_EMBEDDING_BATCH_SIZE"] = "8"

os.environ["MAIN_API_BASE_URL"] = "https://URL-DE-TU-API-PRINCIPAL"
os.environ["MAIN_API_PLACES_SNAPSHOT_PATH"] = "/api/v1/internal/places/snapshot"
os.environ["MAIN_API_PLACES_CHANGES_PATH"] = "/api/v1/internal/places/changes"

os.environ["PGVECTOR_HOST"] = "HOST-DE-RDS"
os.environ["PGVECTOR_PORT"] = "5432"
os.environ["PGVECTOR_DATABASE"] = "nlp_vectors"
os.environ["PGVECTOR_WRITER_USER"] = "nlp_writer"
os.environ["PGVECTOR_SSL_MODE"] = "require"

Si RDS restringe IPs, autoriza temporalmente la IP publica de ese runtime de Colab como una regla /32. Nunca abras 0.0.0.0/0 y elimina la regla al terminar.

3. Ensayo sin escritura

Antes del ensayo ejecuta en la base pgvector, en este orden:

sql/migrations/20260716_02_places_semantic_v1.sql
sql/migrations/20260721_03_place_facets_and_incremental_sync.sql

La segunda migracion es aditiva: crea indices de facetas, validaciones NOT VALID, checkpoint incremental y funciones auxiliares. No borra ni reescribe embeddings.

El modo --semantic configura automaticamente el proveedor de 768d, los prefijos E5 y las funciones SQL de la tabla nueva:

!python scripts/colab_initial_load_places.py \
  --semantic \
  --dry-run \
  --max-pages 1 \
  --page-limit 5 \
  --batch-size 5

El ensayo es correcto cuando termina con errors=0. En --dry-run, upserted=0 es esperado: los vectores se calculan, pero no se escriben.

Errores habituales:

• 401 o 403: falta MAIN_API_INTERNAL_TOKEN o no tiene acceso al snapshot.
• timeout a RDS: falta la regla /32, la ruta de red o el puerto 5432.
• Repository Not Found: el ID es incorrecto o falta HF_TOKEN para un repo privado.
• dimension distinta de 768: se subio el artefacto equivocado o la migracion no coincide.
• error de funciones legacy: faltan las dos variables de escritura semantica; el modo --semantic las establece automaticamente.

4. Backfill completo

Reutiliza las dependencias ya instaladas:

!python scripts/colab_initial_load_places.py \
  --semantic \
  --skip-install \
  --page-limit 50 \
  --batch-size 16

No agregues --max-pages. Una primera carga correcta de una tabla vacia termina con valores equivalentes a:

Finished place sync processed=N skipped=0 upserted=N errors=0

El job trabaja por lotes y es idempotente. Si Colab se desconecta, ejecuta el mismo comando otra vez; no trunques la tabla. Una segunda corrida sin cambios debe mostrar aproximadamente processed=N, skipped=N, upserted=0, errors=0.

Despues del snapshot, programa la sincronizacion incremental:

python -m app.jobs.sync_place_embeddings --mode incremental

El checkpoint se guarda en place_sync_checkpoints; un fallo no adelanta el cursor.

5. Verificar PostgreSQL

Ejecuta sql/verify_places_semantic_v1.sql desde pgAdmin con un rol de lectura sobre la tabla. El archivo falla si la tabla esta vacia y muestra conteos, normas, modelo, version y version del documento.

Confirma:

• rows > 0 y rows = unique_ids.
• rows coincide con processed=N del snapshot completo.
• min_norm y max_norm estan cerca de 1.0.
• aparece un solo embedding_model, igual a MODEL_ID.
• aparece una sola embedding_version, igual a places-e5-retriever-v1@MODEL_SHA.
• la version del documento es la esperada por el codigo actual.
• el indice HNSW y las funciones semanticas existen.

Con pocas filas PostgreSQL puede elegir un escaneo secuencial aunque HNSW exista; eso no significa por si solo que el indice este roto.

6. Activar el Space

En Settings > Variables and secrets > Variables cambia el perfil completo en una sola ventana:

PLACES_EMBEDDING_PROVIDER=sentence_transformer
PLACES_EMBEDDING_DIMENSION=768
PLACES_EMBEDDING_MODEL=tu-usuario/places-e5-retriever-v1
PLACES_EMBEDDING_MODEL_REVISION=SHA_COMPLETO_DE_40_CARACTERES
PLACES_EMBEDDING_FIX_MISTRAL_REGEX=true
PLACES_EMBEDDING_VERSION=places-e5-retriever-v1@SHA_COMPLETO_DE_40_CARACTERES
PLACES_EMBEDDING_QUERY_PREFIX=query:
PLACES_EMBEDDING_PASSAGE_PREFIX=passage:
PLACES_EMBEDDING_BATCH_SIZE=8
PLACES_EMBEDDING_DEVICE=cpu
PLACES_PGVECTOR_MATCH_FUNCTION=match_places_semantic_v1
PLACES_PGVECTOR_HYBRID_FUNCTION=search_places_semantic_v1
PLACES_PGVECTOR_UPSERT_FUNCTION=upsert_place_embedding_semantic_v1
PLACES_PGVECTOR_HASH_FUNCTION=get_place_content_hashes_semantic_v1

La aplicacion agrega el espacio separador de query: y passage: aunque la UI de Hugging Face recorte espacios finales.

PLACES_EMBEDDING_FIX_MISTRAL_REGEX=true aplica al tokenizer del retriever el ajuste indicado por Transformers. Debe permanecer igual en evaluacion, backfill y produccion para que los mismos textos produzcan los mismos tokens.

Mantiene en Secrets:

• HF_TOKEN, si cualquiera de los modelos es privado.
• passwords de PostgreSQL.
• MAIN_API_INTERNAL_TOKEN, NLP_SERVICE_TOKEN, GROQ_API_KEY y cualquier otra credencial.

Reinicia el Space y espera a que termine el build.

Hugging Face documenta que las conexiones salientes de Spaces se permiten por los puertos 80, 443 y 8080. Si PGVECTOR_PORT=5432, confirma primero que la ruta actual realmente funciona con /ready. Si el puerto esta bloqueado, el cutover no puede completarse con una conexion directa: se necesita una ruta TCP segura por un puerto permitido o ejecutar la API en infraestructura con acceso a RDS.

7. Smoke tests obligatorios

1. GET /health debe responder HTTP 200.
2. GET /ready debe responder HTTP 200 y reportar ejecutables match_places_semantic_v1 y search_places_semantic_v1.
3. Haz una consulta real para forzar la descarga y carga diferida del modelo.
4. Prueba /places/chat con lenguaje no literal, por ejemplo: unas donitas chidas para llevar y algo tranqui pa platicar, sin musica fuerte.
5. Revisa los logs del Space: no debe haber errores de autenticacion de HF, dimension, memoria ni funciones SQL.

/ready por si solo no prueba el modelo porque la carga es diferida.

Ejemplo de busqueda publica, sustituyendo la URL:

curl -X POST "https://TU-SPACE.hf.space/places/search" \
  -H "Content-Type: application/json" \
  -d '{"query":"unas donitas chidas para llevar","limit":5}'

Si PLACES_CHAT_V2_ENABLED=true, fuerza el flujo semantico del chat enviando un conversation_id:

curl -X POST "https://TU-SPACE.hf.space/places/chat" \
  -H "Content-Type: application/json" \
  -d '{"message":"algo tranqui pa platicar, sin musica fuerte","conversation_id":"11111111-1111-4111-8111-111111111111","limit":5}'

8. Rollback

No borres place_embeddings_semantic_v1. Para volver atras, restaura de forma coordinada:

PLACES_EMBEDDING_PROVIDER=fasttext
PLACES_EMBEDDING_DIMENSION=300
PLACES_EMBEDDING_MODEL=facebook/fasttext-es-vectors
PLACES_EMBEDDING_MODEL_REVISION=
PLACES_EMBEDDING_FIX_MISTRAL_REGEX=true
PLACES_EMBEDDING_VERSION=common-crawl-300-v1
PLACES_EMBEDDING_QUERY_PREFIX=
PLACES_EMBEDDING_PASSAGE_PREFIX=
PLACES_PGVECTOR_MATCH_FUNCTION=match_places
PLACES_PGVECTOR_HYBRID_FUNCTION=
PLACES_PGVECTOR_UPSERT_FUNCTION=upsert_place_embedding
PLACES_PGVECTOR_HASH_FUNCTION=get_place_content_hashes

Reinicia y repite los smoke tests. Como la migracion es aditiva, la tabla semantica queda disponible para diagnostico o un nuevo intento.

Referencias oficiales

• SentenceTransformers, parametro revision y prefijos de retrieval: https://www.sbert.net/docs/package_reference/sentence_transformer/model.html
• Hugging Face Spaces, variables, secrets y puertos de red permitidos: https://huggingface.co/docs/hub/main/spaces-overview