Tutoriel : Acheminer les requêtes IA par similarité sémantique avec Azure Managed Redis

S’applique à: ✅ Azure Managed Redis

Le routage sémantique envoie une requête en langage naturel au bon gestionnaire, modèle, outil, invite ou workflow en comparant la requête avec des exemples représentatifs pour chaque route. Dans ce tutoriel, vous implémentez le routage sémantique comme un motif d’application avec RedisVL et Azure Managed Redis. Le routage sémantique n'est pas une fonctionnalité gérée séparée d'Azure Managed Redis. Il utilise la recherche vectorielle Redis et le code applicatif.

La recherche vectorielle dans Redis nécessite RediSearch et est disponible dans Azure Managed Redis, comme décrit dans l’aperçu de la recherche vectorielle Azure Managed Readis. Les modules Redis, y compris RediSearch, doivent être activés lors de la création de l’instance Azure Managed Redis. Pour les niveaux et politiques pris en charge, voir Utiliser les modules Redis avec Azure Managed Redis et les exigences RediSearch.

RedisVL fournit une SemanticRouter interface qui utilise la recherche Redis pour classer une requête à partir d’un ensemble de Route références. Pour le modèle vectoriel sous-jacent, Redis stocke les vecteurs et les métadonnées dans des hachages ou des objets JSON et les recherche avec des champs vectoriels, des métriques de distance et des requêtes KNN ou de plage. Pour plus d’informations, consultez le guide RedisVL SemanticRouter et les concepts de recherche vectorielle RedisVL.

Dans ce tutoriel, vous allez apprendre à :

Définir des routes sémantiques nommées avec des références représentatives.
Créez un routeur sémantique RedisVL soutenu par Azure Managed Redis.
Acheminez les requêtes vers une ou plusieurs routes correspondantes.
Gérer les échecs et les correspondances ambiguës.
Ajustez les seuils et opérez le routage sémantique en production.
Appliquez le routage sémantique aux schémas courants d’application IA.

Prerequisites

Un abonnement Azure. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit.
Une instance Azure Managed Redis avec RediSearch activé au moment de la création. RediSearch est le module Redis qui permet la recherche vectorielle dans Azure Managed Redis, et les modules doivent être sélectionnés lors de la création de l’instance. Examinez la matrice de modules supportée et les exigences de politique RediSearch dans Utilisez les modules Redis avec Azure Managed Redis.
Une chaîne de connexion ou une URL Redis pour votre instance Azure Managed Redis. Utilisez TLS et la méthode d’authentification approuvée de votre application.
Un environnement Python qui peut installer RedisVL et les dépendances pour le modèle d’embedding que vous avez choisi.
Une stratégie d’encodage ou de vectorisation. Ce tutoriel utilise le RedisVL HFTextVectorizer comme exemple concis. Utilisez le même modèle d’intégration vectorielle pour chaque référence de route et chaque requête entrante dans un index du routeur afin que les dimensions vectorielles et les métriques de distance restent alignées. Les index vectoriels Redis nécessitent des valeurs fixes pour DIM et DISTANCE_METRIC dans le champ vectoriel. Pour plus d’informations, voir concepts de recherche vectorielle de Redis.

Installer RedisVL :

pip install redisvl

Concevez vos itinéraires

Une route représente une décision prise par l’application, comme un modèle de prompt, un outil, un modèle ou un flux de travail. Chaque gamme comprend les éléments suivants :

Un stable name que votre application associe à un gestionnaire.
references, qui sont des énoncés représentatifs pour cette voie.
Facultatif metadata, comme les identifiants des gestionnaires, les versions de prompt, les préférences relatives au modèle ou les informations sur le propriétaire.
Un par itinéraire distance_threshold. Dans RedisVL, les seuils de route utilisent des unités de distance Redis COSINE là où les valeurs plus basses nécessitent un accouplement plus strict. Les seuils sont spécifiques au modèle et doivent être validés avec vos propres demandes.

Par exemple, un assistant IA pourrait utiliser ces itinéraires :

Itinéraire	Exemple de destination	Références représentatives
`billing`	Processus de facturation ou invite	« mettre à jour ma facture », « pourquoi ai-je été facturé deux fois ? »
`technical_support`	Outil de triage de soutien	« mon cache expire », « aidez-moi à déboguer les erreurs de connexion »
`sales`	Flux de travail commercial	« Comparer les offres », « parler des tarifs avec l’équipe commerciale »

Choisissez des références qui couvrent la surface sémantique de l’itinéraire sans chevaucher les autres itinéraires. Utilisez des exemples issus du trafic réel, des tickets de support ou des données d’évaluation soigneusement sélectionnées. Évitez les références trop génériques, comme « aide » ou « question », car elles peuvent correspondre à plusieurs itinéraires.

Créer un routeur sémantique

Définissez votre URL Redis dans une variable d’environnement. Le format exact de l’URL dépend de votre méthode d’authentification et de la configuration du client. Utilisez une rediss:// URL lors de la connexion avec 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,
)

Une fois initialisé, RedisVL crée et remplit un index de recherche Redis pour les références de route. Redis utilise des champs vectoriels et des champs de métadonnées dans l’index pour effectuer une recherche de similarité sur les références intégrées. Pour plus de détails sur l’initialisation du routeur et les champs de route, voir le guide RedisVL SemanticRouter. Pour plus de détails sur les index vectoriels de Rederis, voir concepts de recherche vectorielle de Rederis.

Conseil / Astuce

Utilisez un nom de routeur séparé ou un préfixe de clé Redis par environnement. Si différents locataires ont besoin de différents ensembles de routes, isole-les avec des index de routeur séparés ou un nom strict de clé spécifique au locataire afin que les références d’un locataire n’affectent pas les résultats de routage d’un autre.

Acheminer une demande

L’appel au routeur renvoie la meilleure correspondance de route. Si aucun itinéraire n’est suffisamment proche pour satisfaire son seuil, RedisVL renvoie une absence de correspondance, comme dans 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)

Considérez distance la distance de similarité, pas la probabilité. Avec la distance Redis, COSINE les valeurs les plus faibles indiquent des correspondances plus proches. Stockez la route correspondante, la distance, le seuil et la destination sélectionnée dans la télémétrie de votre application.

Gérer les absences de correspondance et les correspondances ambiguës

Les routeurs sémantiques nécessitent un comportement déterministe lorsqu’aucune correspondance de route ou plusieurs routes ne sont plausibles.

Pour les échecs :

Acheminez vers un flux de travail de repli, comme un prompt d’assistant général, un routeur de mots-clés, un formulaire ou un transfert vers un agent humain.
Posez une question de clarification lorsque l’intention de l’utilisateur est incomplète.
Enregistrez la demande de révision hors ligne. Cela peut révéler une route manquante ou une référence manquante.

Pour les cas possibles de correspondance entre plusieurs itinéraires, utilisez route_many() pour examiner les itinéraires candidats et les distances :

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 deux routes sont toutes deux valides, choisissez une règle déterministe, comme la distance la plus faible, les métadonnées de priorité explicite ou une question clarifiante. Évitez de choisir silencieusement un itinéraire lorsque les distances supérieures sont proches et que l’action a un impact commercial ou de sécurité.

Mettre à jour et sérialiser la configuration du routeur

Gérer les définitions de routes comme configuration d’applications. RedisVL prend en charge la sérialisation d’une configuration de routeur vers un dictionnaire ou un YAML et la restauration ultérieure. Utilisez cette capacité pour examiner les modifications de route, les promouvoir dans différents environnements et maintenir les définitions de route alignées avec les versions des prompts et des outils. Par exemple, vous pouvez stocker la configuration des routes avec les artefacts de déploiement de votre application et recréer le routeur au démarrage.

RedisVL prend également en charge l’addition, la liste et la suppression dynamique des références de route. Utilisez les mises à jour dynamiques avec soin : validez les nouvelles références, suivez qui les a modifiées et testez l’impact du routage avant de les promouvoir en production.

Ajuster les seuils avec un ensemble d’évaluation

Les seuils déterminent quand une route est considérée comme correspondante. Parce que les valeurs de route distance_threshold RedisVL utilisent des unités de distance Redis COSINE , les seuils plus bas sont plus stricts. La bonne valeur dépend de votre modèle d’intégration, du langage, des références et de la distribution des requêtes.

Utilisez ce procédé d’accordage :

Collectez des exemples identifiés pour chaque route et des exemples négatifs qui ne devraient correspondre à aucune route.
Divisez les exemples en ensembles d’accordage et de validation.
Évaluez chaque itinéraire indépendamment et mesurez les fausses acceptations, les faux rejets et les correspondances ambiguës.
Commencez par des seuils plus stricts pour les actions à fort impact et ne les assouplissez que lorsque les données de validation le permettent.
Réévaluez les seuils chaque fois que vous changez le modèle d’intégration, les références ou la taxonomie des routes.

Ne comparez pas les valeurs de distance entre des routeurs qui utilisent différents modèles d’embedding. Les indices vectoriels Redis nécessitent que les vecteurs de requête correspondent aux dimensions du champ vectoriel, et les modifications du modèle nécessitent généralement une reconstruction ou un versionnement de l’index du routeur. Pour plus d’informations, voir concepts de recherche vectorielle de Redis.

Comprendre la distance, les seuils et les priorités

La distance de route est la distance de similarité entre l’inclusion de requête entrante et celle de référence de route. Avec la métrique de distance du COSINE routeur sémantique RedisVL, une valeur plus petite signifie que la requête est plus proche d’une référence de route. Le routeur n’accepte une route que lorsque la distance résultante se situe dans les limites de distance_threshold de cette route.

Évitez de considérer la distance de l’itinéraire comme un pourcentage de confiance. Une distance de 0.35 ne signifie pas 35% de confiance, et un seuil qui fonctionne pour un modèle d’intégration peut ne pas fonctionner pour un autre. Utilisez les distances comme signaux de classement et d’acceptation que vous calibrez avec des exemples indiqués.

Les routes RedisVL n’ont pas de réglage sémantique séparé du poids. Utilisez plutôt ces leviers de routage :

Levier	Quand l′utiliser ?	Résultat
Abaisser `distance_threshold`	Cette voie déclenche une action coûteuse, sensible ou irréversible.	Moins de fausses acceptations, mais plus de demandes de repli ou de clarification.
Plus haut `distance_threshold`	La route est à faible risque, large ou peut être récupérée en toute sécurité en aval.	Plus de correspondances, mais plus de risques que des demandes sans lien entrent sur la route.
Meilleures références	L’itinéraire est trop étroit, trop large ou confondu avec un autre itinéraire.	Modifie la limite de l’itinéraire en modifiant ce que représente l’itinéraire.
Méthode d’agrégation	Un itinéraire contient plusieurs références et une référence devrait suffire à correspondre.	`min` peut favoriser la référence la plus proche ; l’agrégation par moyenne favorise les routes dont les références sont systématiquement proches.
Métadonnées de priorité d’application	Deux routes sémantiquement valides sont proches et votre logique métier a besoin d’un départage.	Cela permet à l’application de choisir un gagnant déterministe sans prétendre que la route est sémantiquement plus proche.

Choisissez des seuils plus stricts pour les routes qui accèdent aux données du compte, appellent des outils, changent d’état ou escaladent vers les humains. Choisissez des seuils plus permissifs pour les flux à faible risque, tels que le choix d’une FAQ, la recherche dans la documentation ou le choix du modèle, lorsque le prompt en aval peut encore poser une question de précision. Si les deux distances de route supérieures sont proches, il faut privilégier une étape de clarification ou une règle de priorité déterministe plutôt que de choisir silencieusement une action à fort impact.

Utiliser le routage sémantique dans les schémas d’IA réels

Le routage sémantique est utile chaque fois qu’une application d’IA a besoin d’une décision rapide et explicable avant d’appeler un modèle, une invite, un outil ou un workflow. Les modèles courants sont les suivants :

Modèle	Comment le routage sémantique aide
Routage des modèles	Envoyez des requêtes simples à un modèle plus petit ou moins coûteux, et réservez les modèles plus grands pour des tâches complexes de raisonnement, de codage ou sensibles à la sécurité.
Routage prompt	Sélectionnez le bon modèle de consigne système ou de demande pour la facturation, le support, la vente, le dépannage ou les questions de politique.
Routage d’outils	Choisissez si l’agent doit utiliser l’outil de recherche, la gestion des tickets, l’outil de diagnostic, la facturation, le CRM ou n’utiliser aucun outil.
Routage RAG	Choisissez le bon index de récupération, la base de connaissances, le bon corpus de locataires ou le bon ensemble de documentation produit avant de lancer la recherche vectorielle.
Routage par transfert humain	Transférez les requêtes vers des files d’attente spécialisées, des chemins d’escalade ou une révision humaine lorsque l’intention sémantique correspond aux flux de travail sensibles.
Sécurité et routage politique	Détectez les requêtes nécessitant une garde plus stricte, une consigne restreinte, une trace d’audit ou un flux de refus avant d’invoquer l’assistant principal.

Déployer le routage sémantique en production

Utilisez ces pratiques pour les charges de travail en production :

Gardez les itinéraires distincts. Divisez ou renommez les routes qui se chevauchent. Fusionnez les routes qui génèrent systématiquement des correspondances ambiguës.
Je préfère les références soigneusement sélectionnées. Ajoutez des énoncés représentatifs qui correspondent à une seule route. Supprimez les références qui attirent des trafics sans rapport.
Utilisez la solution de secours volontairement. Implémentez un plan de repli dans la logique applicative. Une large voie de repli peut capturer des demandes qui auraient dû être manquées.
Configuration du routage de version. Incluez les métadonnées de version du prompt, de l’outil, du modèle et de la route. Annulez les changements de route comme d’autres modifications de configuration d’applications.
Observez la qualité du routage. Suivez le taux de réussite de la route, le taux de ratés, la route supérieure, la distance, le seuil, le nombre de correspondances ambiguës, le taux de repli et les métriques de réussite en aval. Examinez la répartition des distances et des niveaux de confiance selon l’itinéraire.
Séparez les locataires quand c’est nécessaire. Utilisez des routeurs isolés, des préfixes de clé ou des instances Redis lorsque les locataires ont des ensembles de routes différents ou des exigences strictes d’isolement des données.
Protégez les métadonnées sensibles. Ne stockez pas de secrets dans les métadonnées ou références de route. Considérez les exemples de routes comme des données d’application.
Planifiez la capacité. Les références de route sont intégrées et indexées dans Redis. Gardez les ensembles de routes compacts et représentatifs, et surveillez la mémoire, la latence et la taille de l’index à mesure que les références augmentent.

Nettoyer les ressources

Si vous souhaitez continuer à utiliser les ressources que vous avez créées dans cet article, conservez le groupe de ressources.

Sinon, si vous avez terminé avec les ressources, vous pouvez supprimer le groupe de ressources Azure que vous avez créé pour éviter les frais.

Important

La suppression d’un groupe de ressources est irréversible. Quand vous supprimez un groupe de ressources, toutes les ressources qu’il contient sont supprimées définitivement. Veillez à ne pas supprimer accidentellement des ressources ou un groupe de ressources incorrects. Si vous avez créé les ressources dans un groupe de ressources existant contenant des ressources que vous souhaitez conserver, vous pouvez supprimer chaque ressource individuellement, au lieu de supprimer l’intégralité du groupe de ressources.

Pour supprimer un groupe de ressources

Connectez-vous au Portail Azure, puis sélectionnez Groupes de ressources.
Recherchez le groupe de ressources à supprimer.

S’il existe de nombreux groupes de ressources, utilisez la zone Filtrer pour n’importe quel champ..., saisissez le nom du groupe de ressources que vous avez créé pour cet article. Sélectionnez le groupe de ressources dans la liste des résultats.
Sélectionnez Supprimer le groupe de ressources.
Vous êtes invité à confirmer la suppression du groupe de ressources. Saisissez le nom de votre groupe de ressources pour confirmer, puis sélectionnez Supprimer.

Après quelques instants, le groupe de ressources et toutes ses ressources sont supprimés.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-07-30