Tutorial: Enrutar solicitudes de IA por similitud semántica con Azure Managed Redis

Se aplica a: ✅ Azure Managed Redis

El enrutamiento semántico envía una petición en lenguaje natural al manejador, modelo, herramienta, prompt o flujo de trabajo adecuado comparando la solicitud con ejemplos representativos para cada ruta. En este tutorial, implementas el enrutamiento semántico como patrón de aplicación con RedisVL y Azure Managed Redis. El enrutamiento semántico no es una función gestionada separada de Azure Managed Redis. Utiliza búsqueda vectorial Redis y código de aplicación.

La búsqueda vectorial en Redis requiere RediSearch y está disponible en Azure Managed Redis, tal como se describe en la visión general de búsqueda vectorial de Azure Managed Redis. Los módulos de Redis, incluido RediSearch, deben estar habilitados cuando creas la instancia de Azure Managed Redis. Para niveles y políticas soportados, consulte Usar módulos Redis con Azure Managed Redis y requisitos de RediSearch.

RedisVL proporciona una SemanticRouter interfaz que utiliza la búsqueda de Redis para clasificar una solicitud frente a un conjunto de Route referencias. Para el modelo vectorial subyacente, Redis almacena vectores y metadatos en hashes u objetos JSON y los busca con campos vectoriales, métricas de distancia y consultas KNN o de rango. Para más información, consulte la guía RedisVL SemanticRouter y los conceptos de búsqueda vectorial de RedisVL.

En este tutorial, obtendrá información sobre cómo:

Define rutas semánticas nombradas con referencias representativas.
Crea un router semántico RedisVL respaldado por Azure Managed Redis.
Enruta las solicitudes a una o más rutas coincidentes.
Gestiona los casos sin coincidencia y las coincidencias ambiguas.
Ajusta los umbrales y gestiona el enrutamiento semántico en producción.
Aplica el enrutamiento semántico a patrones comunes de aplicaciones de IA.

Prerequisites

Una suscripción a Azure. Si no tiene una suscripción a Azure, cree una cuenta gratuita.
Una instancia de Azure Managed Redis con RediSearch activado en el momento de la creación. RediSearch es el módulo Redis que permite la búsqueda vectorial en Azure Managed Redis, y los módulos deben seleccionarse cuando se crea la instancia. Revisa la matriz de módulos soportada y los requisitos de política RediSearch en Usar módulos Redis con Azure Managed Redis.
Una cadena de conexión o una URL de Redis para su instancia de Azure Managed Redis. Utiliza TLS y el método de autenticación aprobado por tu aplicación.
Un entorno Python que pueda instalar RedisVL y las dependencias para el modelo de embedding que elijas.
Una estrategia de embebido o de vectorización. Este tutorial utiliza RedisVL HFTextVectorizer como ejemplo conciso. Utiliza el mismo modelo de incrustación para cada referencia de ruta y cada solicitud entrante en un índice de router para que las dimensiones vectoriales y las métricas de distancia se mantengan alineadas. Los índices vectoriales de Redis requieren un DIM y un DISTANCE_METRIC fijos para el campo vectorial. Para más información, véase conceptos de búsqueda vectorial de Redis.

Instalar RedisVL:

pip install redisvl

Diseña tus rutas

Una ruta representa una decisión de la aplicación, como una plantilla de instrucciones, una herramienta, un modelo o un flujo de trabajo. Cada ruta incluye:

Un name estable que tu aplicación asocia a un manejador.
references, que son enunciados representativos para esa ruta.
Opcional metadata, como identificadores de controladores, versiones de instrucciones, preferencias del modelo o información del propietario.
Una por ruta distance_threshold. En RedisVL, los umbrales de ruta utilizan unidades de distancia Redis COSINE donde valores más bajos requieren un emparejamiento más estricto. Los umbrales son específicos de cada modelo y deben validarse con tus propias solicitudes.

Por ejemplo, un asistente de IA podría usar estas rutas:

Route	Destino de ejemplo	Referencias representativas
`billing`	Flujo de trabajo de facturación o instrucción de facturación	"Actualizar mi factura", "¿por qué me cobraron dos veces?"
`technical_support`	Herramienta de clasificación de soporte	"mi caché está expirando", "ayúdame a depurar errores de conexión"
`sales`	Flujo de trabajo de ventas	"Comparar planes", "Hablar con el equipo de ventas sobre los precios"

Elige referencias que cubran el área de superficie semántica de la ruta sin solaparse con otras rutas. Utiliza ejemplos de tráfico real, tickets de soporte o datos de evaluación seleccionados. Evita referencias demasiado genéricas, como "ayuda" o "pregunta", porque pueden coincidir con varias rutas.

Crea un router semántico

Establece tu URL Redis en una variable de entorno. El formato exacto de la URL depende de tu método de autenticación y de la configuración del cliente. Usa una rediss:// URL al conectarte con TLS.

import os

from redisvl.extensions.router import Route, SemanticRouter
from redisvl.utils.vectorize import HFTextVectorizer

redis_url = os.environ["REDIS_URL"]  # Example: rediss://:<password>@<host>:10000

billing = Route(
    name="billing",
    references=[
        "I need a copy of my invoice",
        "why was my card charged twice",
        "change the billing email for my account",
    ],
    metadata={"handler": "billing_workflow", "prompt": "billing_v1"},
    distance_threshold=0.55,
)

technical_support = Route(
    name="technical_support",
    references=[
        "my cache is timing out",
        "help me debug Redis connection errors",
        "why am I seeing high server load",
    ],
    metadata={"handler": "support_triage_tool", "prompt": "support_v2"},
    distance_threshold=0.50,
)

sales = Route(
    name="sales",
    references=[
        "compare pricing plans",
        "I want to talk to sales",
        "which tier should I choose for production",
    ],
    metadata={"handler": "sales_workflow", "prompt": "sales_v1"},
    distance_threshold=0.60,
)

routes = [billing, technical_support, sales]
routes_by_name = {route.name: route for route in routes}

router = SemanticRouter(
    name="ai-request-router",
    vectorizer=HFTextVectorizer(),
    routes=routes,
    redis_url=redis_url,
    overwrite=False,
)

Cuando se inicializa, RedisVL crea y completa un índice de búsqueda Redis para las referencias de ruta. Redis utiliza campos vectoriales y campos de metadatos en el índice para realizar búsquedas de similitud sobre las referencias embebidas. Para detalles sobre la inicialización del router y los campos de ruta, consulte la guía de RedisVL SemanticRouter. Para detalles sobre los índices vectoriales de Redis, véase conceptos de búsqueda vectorial de Redis.

Sugerencia

Usa un nombre de router o un prefijo de clave Redis separado por entorno. Si diferentes inquilinos necesitan diferentes conjuntos de rutas, aíslalos con índices de router separados o nombres de clave específicos de inquilino para que las referencias de un inquilino no afecten a los resultados de enrutamiento de otro.

Enruta una solicitud

Llamar al router devuelve la mejor coincidencia de ruta. Si ninguna ruta es lo suficientemente cercana para satisfacer su umbral, RedisVL devuelve un error similar a RouteMatch(name=None, distance=None).

request = "The cache keeps timing out when my app connects."
match = router(request)

if match.name is None:
    destination = "fallback_workflow"
else:
    route = routes_by_name[match.name]
    destination = route.metadata["handler"]

print(match.name, match.distance, destination)

Trátalo distance como una distancia de similitud, no como una probabilidad. Con la distancia de Redis COSINE, los valores más bajos indican coincidencias más próximas. Guarda la ruta, distancia, umbral y destino seleccionado en la telemetría de tu aplicación.

Gestionar las no coincidencias y las coincidencias ambiguas

Los enrutadores semánticos necesitan un comportamiento determinista cuando no hay coincidencias de rutas o varias rutas son plausibles.

En caso de fallos:

Redirigir a un flujo de trabajo alternativo, como una instrucción de asistente general, un enrutador por palabras clave, un formulario o una derivación a un agente humano.
Haz una pregunta aclaratoria cuando la intención del usuario sea incompleta.
Registra la solicitud de revisión offline. Puede que revele una ruta o una referencia perdida.

Para posibles coincidencias entre varias rutas, se utiliza route_many() para inspeccionar rutas y distancias candidatas:

request = "Can you help me choose a production tier and estimate the price?"
matches = router.route_many(request, max_k=3)

for candidate in matches:
    print(candidate.name, candidate.distance)

Si ambas rutas son válidas, elige una regla determinista, como la distancia más baja, metadatos de prioridad explícita o una pregunta aclaratoria. Evita seleccionar silenciosamente una ruta cuando las distancias principales estén cerca y la acción tenga un impacto empresarial o de seguridad.

Actualizar y serializar la configuración del router

Gestionar las definiciones de rutas como configuración de la aplicación. RedisVL soporta serializar una configuración de router a un diccionario o YAML y restaurarla posteriormente. Utiliza esta capacidad para revisar cambios de ruta, promoverlos entre entornos y mantener las definiciones de ruta alineadas con las versiones de prompts y herramientas. Por ejemplo, puedes almacenar la configuración de rutas junto con artefactos de despliegue de tu aplicación y recrear el router durante el arranque.

RedisVL también permite añadir, listar y eliminar referencias de ruta de forma dinámica. Utiliza las actualizaciones dinámicas con cuidado: valida las nuevas referencias, haz un seguimiento de quién las cambió y prueba el impacto del enrutamiento antes de promocionarlas a producción.

Ajustar umbrales con un conjunto de evaluación

Los umbrales determinan cuándo una ruta coincide. Debido a que los valores de ruta distance_threshold de RedisVL utilizan unidades de distancia Redis COSINE , los umbrales más bajos son más estrictos. El valor correcto depende de tu modelo de incrustación, lenguaje, referencias y distribución de peticiones.

Utiliza este proceso de afinación:

Recoge ejemplos etiquetados para cada ruta y ejemplos negativos que no deberían coincidir con ninguna ruta.
Divide los ejemplos en conjuntos de afinación y validación.
Evalúa cada ruta de forma independiente y mide falsas aceptaciones, falsas rejeitas y coincidencias ambiguas.
Empieza con umbrales más estrictos para acciones de alto impacto y relájalos solo cuando los datos de validación lo permitan.
Reevalúa los umbrales cada vez que cambies el modelo de incrustación, las referencias o la taxonomía de rutas.

No compares valores de distancia entre enrutadores que usan distintos modelos de incrustación. Los índices vectoriales Redis requieren que los vectores de consulta coincidan con las dimensiones del campo vectorial, y los cambios en el modelo suelen requerir reconstruir o versionar el índice del router. Para más información, véase conceptos de búsqueda vectorial de Redis.

Comprende la distancia, los umbrales y las prioridades

La distancia de ruta es la distancia de similitud entre la incrustación de solicitudes entrantes y las incrustaciones de referencia de ruta. Con la métrica de distancia del COSINE router semántico RedisVL, un valor menor significa que la solicitud está más cerca de una referencia de ruta. El enrutador solo acepta una ruta cuando la distancia resultante está dentro de la de esa ruta distance_threshold.

Evita tratar la distancia de la ruta como un porcentaje de confianza. Una distancia de 0.35 no significa 35% de confianza, y un umbral que funcione para un modelo de embedding puede no funcionar para otro. Usa distancias como señales de clasificación y aceptación que calibres con ejemplos etiquetados.

Las rutas de RedisVL no tienen una configuración de peso semántico independiente. Utiliza estas palancas de enrutamiento en su lugar:

Palanca	Cuándo usarlo	Effect
Abajo `distance_threshold`	La ruta desencadena una acción costosa, sensible o irreversible.	Menos falsas aceptaciones, pero más solicitudes de respaldo o aclaración.
Más alto `distance_threshold`	La ruta es de bajo riesgo, ancha o puede recuperarse con seguridad río abajo.	Más coincidencias, pero más riesgo de que aparezcan solicitudes no relacionadas en la ruta.
Mejores referencias	La ruta es demasiado estrecha, demasiado ancha o se confunde con otra ruta.	Mueve el límite de la ruta modificando lo que esta representa.
Método de agregación	Una ruta tiene varias referencias y una referencia debería ser suficiente para coincidir.	`min` puede favorecer la referencia más cercana; la agregación basada en la media favorece las rutas cuyas referencias son cercanas de forma consistente.
Metadatos de prioridad de aplicación	Dos rutas semánticamente válidas son muy parecidas y tu lógica de negocio necesita un criterio de desempate.	Permite que la app elija un ganador determinista sin fingir que la ruta es semánticamente más cercana.

Elige umbrales más estrictos para las rutas que acceden a datos de la cuenta, invocan herramientas, cambian el estado o derivan a agentes humanos. Elige umbrales más permisivos para rutas de bajo riesgo, como la selección de preguntas frecuentes, la búsqueda de documentación o la selección de modelos, cuando el prompt posterior aún pueda plantear una pregunta aclaratoria. Si las dos distancias de ruta superiores son cercanas, prefiero un paso de aclaración o una regla de prioridad determinista en lugar de elegir silenciosamente una acción de alto impacto.

Uso del enrutamiento semántico en patrones de IA del mundo real

El enrutamiento semántico es útil siempre que una aplicación de IA necesita una decisión rápida y explicable antes de llamar a un modelo, prompt, herramienta o flujo de trabajo. Entre los patrones comunes se incluyen:

Pattern	Cómo ayuda el enrutamiento semántico
Enrutamiento de modelos	Envía peticiones simples a un modelo más pequeño o de menor coste, y reserva modelos más grandes para razonamientos, codificación o tareas sensibles a la seguridad complejas.
Enrutamiento rápido	Selecciona la instrucción del sistema o la plantilla de instrucciones adecuadas para preguntas de facturación, soporte, ventas, resolución de problemas o políticas.
Enrutamiento de herramientas	Elige si el agente debe usar la búsqueda, la gestión de tickets, el diagnóstico, la facturación, el CRM o no usar ninguna herramienta.
Enrutamiento RAG	Elige el índice de recuperación adecuado, la base de conocimiento, el corpus de tenentes o el conjunto de documentación del producto antes de ejecutar la búsqueda vectorial.
Enrutamiento por transferencia humana	Enruta las solicitudes a colas especializadas, rutas de escalada o revisión humana cuando la intención semántica coincide con flujos de trabajo sensibles.
Seguridad y enrutamiento de políticas	Detecta solicitudes que requieran un filtro de seguridad más estricto, un prompt restringido, un seguimiento de auditoría o un flujo de trabajo de rechazo antes de invocar al asistente principal.

Operar el enrutamiento semántico en producción

Utiliza estas prácticas para las cargas de trabajo de producción:

Mantén rutas distintas. Separa o renombra las rutas solapadas. Combina las rutas que producen coincidencias ambiguas de manera sistemática.
Prefiero referencias seleccionadas. Añade expresiones representativas asociadas a una ruta. Elimina referencias que atraigan tráfico no relacionado.
Usa el mecanismo de reserva de forma deliberada. Implementar un mecanismo alternativo en la lógica de la aplicación. Una ruta de respaldo amplia puede capturar solicitudes que deberían haberse pasado por alto.
Configuración de la ruta de la versión. Incluye metadatos del prompt, la herramienta, el modelo y la versión de ruta. Puede revertir los cambios en las rutas igual que otros cambios en la configuración de la aplicación.
Supervisa la calidad del enrutamiento. Supervisa la tasa de aciertos de la ruta, la tasa de errores, la ruta más frecuente, la distancia, el umbral, el número de coincidencias ambiguas, la tasa de recurso alternativo y las métricas de éxito posteriores. Revisa las distribuciones de distancia y de cubos de confianza por ruta.
Aparte a los inquilinos cuando sea necesario. Utiliza routers aislados, prefijos de clave o instancias Redis cuando los inquilinos tengan diferentes conjuntos de rutas o requisitos estrictos de aislamiento de datos.
Protege los metadatos sensibles. No almacenes datos sensibles en los metadatos de la ruta ni en las referencias. Trata los ejemplos de rutas como datos de aplicación.
Planificación de la capacidad. Las referencias de ruta están incrustadas e indexadas en Redis. Mantén los conjuntos de rutas compactos y representativos, y monitoriza la memoria, la latencia y el tamaño del índice a medida que crecen las referencias.

Limpieza de recursos

Si desea seguir usando los recursos que creó en este artículo, mantenga el grupo de recursos.

De lo contrario, si ya ha terminado con los recursos, puede eliminar el grupo de recursos de Azure que ha creado para evitar cargos.

Importante

La eliminación de un grupo de recursos es irreversible. Cuando elimine un grupo de recursos, todos los recursos contenidos en él se eliminan permanentemente. Asegúrese de no eliminar por accidente el grupo de recursos o los recursos equivocados. Si ha creado los recursos en un grupo de recursos existente que contiene recursos que desea conservar, puede eliminar cada recurso individualmente en lugar de eliminar el grupo de recursos.

Para eliminar un grupo de recursos

Inicie sesión en Azure Portal y después seleccione Grupos de recursos.
Seleccione el grupo de recursos que desea eliminar.

Si hay muchos grupos de recursos, use el cuadro Filtro para cualquier campo... y escriba el nombre del grupo de recursos que creó para este artículo. Seleccione el grupo de recursos en la lista de resultados.
Seleccione Eliminar grupo de recursos.
Se le pedirá que confirme la eliminación del grupo de recursos. Escriba el nombre del grupo de recursos para confirmar y, después, seleccione Eliminar.

Transcurridos unos instantes, el grupo de recursos y todos sus recursos se eliminan.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-07-30