Es importante mantener los embeddings actualizados y sincronizados con el contenido actual. Si tenemos los embeddings desactualizados y el contenido de los documentos cambia, estaremos haciendo búsquedas en los embeddings sobre contenido que ya no existe.
Change feed
El change feed es un log persistente y ordenado de todos los inserts y updates de un contenedor. Las aplicaciones se suscriben al feed y procesan los cambios en tiempo real tal como pasan, lo que permite arquitecturas event-driven donde los updates a los embeddings ocurren a la vez que los cambios en los documentos
Un buen mecanismo de sincronización de embeddings debe tener:
- persistent record: los cambios se almacenan y se procesan incluso si la App está offline
- delivery ordenado: los cambios dentro de una partition key llegan en orden
- Just-once opportunity: Cada cambio aparece una única vez en el feed
- Automatic enablement: el change feed está enabled by default en todos los contenedores
Push / pull modes
CosmosDB ofrece dos maneras de consumir el change feed.
- push model (entrega cambios a tu codigo automaticamente)
- built-in partition management y load balancing a lo largo de múltiples instancias
- es más sencillo
- mejor para CD
- pull model (eres tu quien hace pull de los cambios)
- más control de cuando y como se integran los cambios
- menos consumo
- sin dependencias externas
- util para batch refreshes
Para PROD el push model es más seguro y simple. Usar Azure Functions o el change feed processor library para implementar el push model
Azure Functions for change feed processing
IMPORTANTE
Azure Functions ofrecen la integración más simple con el change feed. El CosmosDB trigger invoca automáticamente la función cuando los documentos cambian, se encarga del partition management y mantiene checkpoints para seguir el progreso
/IMPORTANTE
regenera embeddings cuando los documentos cambian en el knowledge container
import azure.functions as func
from openai import AzureOpenAI
from azure.cosmos import CosmosClient
import os
app = func.FunctionApp()
@app.cosmos_db_trigger(
arg_name="documents",
container_name="knowledge-base",
database_name="support-db",
connection="CosmosDBConnection",
lease_container_name="leases",
create_lease_container_if_not_exists=True
)
def refresh_embeddings(documents: func.DocumentList):
if not documents:
return
# Initialize clients
openai_client = AzureOpenAI(
api_key=os.environ["OPENAI_API_KEY"],
api_version="2024-02-01",
azure_endpoint=os.environ["OPENAI_ENDPOINT"]
)
cosmos_client = CosmosClient.from_connection_string(
os.environ["CosmosDBConnection"]
)
container = cosmos_client.get_database_client("support-db").get_container_client("knowledge-base")
for doc in documents:
# Check if content that affects embeddings changed
if should_refresh_embedding(doc):
# Generate new embedding from updated content
text_content = f"{doc.get('title', '')} {doc.get('content', '')}"
response = openai_client.embeddings.create(
input=text_content,
model="text-embedding-ada-002"
)
# Update document with new embedding
doc["embedding"] = response.data[0].embedding
container.upsert_item(doc)
def should_refresh_embedding(doc):
"""Determine if the document needs a new embedding."""
# Always refresh if no embedding exists
if "embedding" not in doc or doc["embedding"] is None:
return True
# Check for content-related fields that affect embeddings
# In a full implementation, compare against the previous version
return True
La config del trigger especifica el contenedor a monitorizar knowledge-base, la BBDD support-db y el lease container leases para hacer tracking del progreso. La opción create_lease_container_if_not_exists crea automaticamente el lease container si se necesita.
Lease Container
El change feed processor (usado por Azure Functions triggers) requiere un contenedor separado para almacenar leases. Los leases hacen tracking de que particiones ownea cada instancia del processor y el track del progreso de cada particion. Esto da:
- Checkpointing: Si el processing falla o se reinicia, lo retoma desde el último checkpoint en vez de comenzar de nuevo.
- Coordination: Multiples processor instances se dividen las particiones, permitiendo un escalado horizontal
- Failover: Si una instancia falla, otras adquieren su lease y continúan
Asegurarse que el lease container tiene un nombre diferente de los data containers. Múltiples funciones monitorizando el mismo data container pueden compartir un lease container si se usa leaseContainerPrefix
Selective embedding refresh
Refrescar los embeddings para cada documento es caro. Podemos implementar lógica para selective refresh para actualizar los embeddings solo cuando haya cambios en el contenido semántico.
comparar versiones de un doc para ver si es necesario un refresh
def should_refresh_embedding(current_doc, previous_doc=None):
"""
Determine if document changes require new embeddings.
Returns True if content affecting embeddings has changed.
"""
# New document always needs embedding
if previous_doc is None:
return "embedding" not in current_doc
# Check fields that contribute to the embedding
content_fields = ["title", "content", "description", "summary"]
for field in content_fields:
current_value = current_doc.get(field, "")
previous_value = previous_doc.get(field, "")
if current_value != previous_value:
return True
# Metadata-only changes don't need new embeddings
# Examples: category changes, status updates, access permission changes
return False
Para PROD podemos hacerlo mediante un hash del contenido usado para generar un embedding. De esta forma es más eficiente. Al refrescar el contenido, actualizamos el hash
import hashlib
def compute_content_hash(doc):
"""Compute hash of content used for embedding generation."""
text_content = f"{doc.get('title', '')} {doc.get('content', '')}"
return hashlib.sha256(text_content.encode()).hexdigest()
def should_refresh_embedding(doc):
"""Check if content hash changed since last embedding."""
current_hash = compute_content_hash(doc)
stored_hash = doc.get("contentHash", "")
return current_hash != stored_hash
High-volume changes
Para aplicaciones con cambios de embeddings frecuentes o mucho volumen es necesario tomar una estrategia:
- Batch API calls: Agrupamos llamadas por batches
- Rage limiting and backoff: Retry logic con backoff exponencial
- Queue-based processing: Escribir cambios en un Azure Queue Storage y procesarlos con una función aparte. Esto hace decoupling de change detection y embedding generation, por lo que podemos hacer scaling por separado.
- Prioritized refresh: priorizar documentos de alta prioridad vs baja prioridad y que vayan por separado con límites separados
Pull model con Python SDK
Esto lo hacemos mediante query_items_change_feed(). El continuation token guarda la posición en el change feed entre runs. Se puede guardar de manera persistente para asegurarse de no perder el por donde ibamos, y tener que reprocesar todo de nuevo.
from azure.cosmos import CosmosClient
cosmos_client = CosmosClient(endpoint, credential)
container = cosmos_client.get_database_client("support-db").get_container_client("knowledge-base")
def process_change_feed_batch():
"""Process a batch of changes using the pull model."""
# Read changes from the beginning or from a continuation token
change_feed_iterator = container.query_items_change_feed(
start_time="Beginning" # Or use a stored continuation token
)
continuation_token = None
for page in change_feed_iterator.by_page():
for change in page:
if should_refresh_embedding(change):
new_embedding = generate_embedding(change.get("content", ""))
change["embedding"] = new_embedding
change["contentHash"] = compute_content_hash(change)
container.upsert_item(change)
# Store continuation token for next batch
continuation_token = change_feed_iterator.continuation_token
# Save continuation_token for next run
return continuation_token
Handle errors (idempotency)
Nuestra app tiene que ser idempotente. En algunas ocsasiones el change feed puede enviar varias veces el mismo cambio en casos de fallo. Debemos asegurarnos de que solo aplicamos los cambios una única vez.