Tutorial: Route AI-verzoeken op semantische gelijkenis met Azure Managed Redis

Van toepassing op: ✅ Azure Managed Redis

Semantische routering stuurt een verzoek in natuurlijke taal naar de juiste handler, model, tool, prompt of workflow door het verzoek te vergelijken met representatieve voorbeelden voor elke route. In deze tutorial implementeer je semantische routing als een applicatiepatroon met RedisVL en Azure Managed Redis. Semantische routing is geen aparte Azure Managed Redis beheerde functie. Het gebruikt Redis vectorzoekopdracht en applicatiecode.

Vectorzoeken in Redis vereist RediSearch en is beschikbaar in Azure Managed Redis, zoals beschreven in het Azure Managed Redis vectorzoekoverzicht. Redis-modules, inclusief RediSearch, moeten ingeschakeld zijn wanneer je de Azure Managed Redis-instantie aanmaakt. Voor ondersteunde lagen en beleidslijnen, zie Use Redis-modules met Azure Managed Redis en RediSearch vereisten.

RedisVL biedt een SemanticRouter interface die Redis Search gebruikt om een verzoek te classificeren aan de hand van een set Route-referenties. Voor het onderliggende vectormodel slaat Redis vectoren en metadata op in hashes of JSON-objecten en doorzoekt deze met vectorvelden, afstandsmetrieken en KNN- of bereikzoekopdrachten. Voor meer informatie, zie de RedisVL SemanticRouter-gids en de concepten van Redis vectorzoekopdrachten.

In deze handleiding leer je hoe je:

Definieer benoemde semantische routes met representatieve referenties.
Creëer een RedisVL semantische router die wordt ondersteund door Azure Managed Redis.
Routeer verzoeken naar een of meer overeenkomende routes.
Verwerk gemiste en ambigue overeenkomsten.
Stel drempels af en voer semantische routing uit in productie.
Pas semantische routing toe op veelvoorkomende AI-toepassingspatronen.

Prerequisites

Een Azure-abonnement. Als u geen Azure-abonnement hebt, maakt u een gratis account.
Een Azure Managed Redis-instantie waarbij RediSearch is ingeschakeld tijdens het aanmaken. RediSearch is de Redis-module die vectorzoekopdrachten in Azure Managed Redis mogelijk maakt, en modules moeten worden geselecteerd wanneer de instantie wordt aangemaakt. Bekijk de ondersteunde modulematrix en RediSearch-beleidsvereisten in Use Redis-modules met Azure Managed Redis.
Een verbindingsreeks of Redis-URL voor je Azure Managed Redis-instantie. Gebruik TLS en de goedgekeurde authenticatiemethode van je applicatie.
Een Python-omgeving die RedisVL en de afhankelijkheden voor jouw gekozen embeddingmodel kan installeren.
Een inbeddings- of vectorisatiestrategie. Deze tutorial gebruikt de RedisVL HFTextVectorizer als beknopt voorbeeld. Gebruik hetzelfde embeddingmodel voor elke routereferentie en elk binnenkomend verzoek in een routerindex zodat vectorafmetingen en afstandsmetrieken uitgelijnd blijven. Redis-vectorindexen vereisen een vaste DIM en DISTANCE_METRIC voor het vectorveld. Voor meer informatie, zie Redis vectorzoekconcepten.

Installeer RedisVL:

pip install redisvl

Ontwerp je routes

Een route staat voor een beslissing van een applicatie, zoals een promptsjabloon, tool, model of workflow. Elke route omvat:

Een stable name die je applicatie koppelt aan een handler.
references, die representatieve uitingen zijn voor die route.
Optioneel metadata, zoals handler-ID's, promptversies, modelvoorkeuren of eigenaarinformatie.
Een per-route distance_threshold. In RedisVL gebruiken routedrempels Redis-afstandseenheden COSINE waarbij lagere waarden strengere matching vereisen. Drempels zijn modelspecifiek en moeten worden gevalideerd met je eigen verzoeken.

Een AI-assistent kan bijvoorbeeld de volgende routes gebruiken:

Route	Voorbeeldbestemming	Vertegenwoordigende referenties
`billing`	Facturatieworkflow of prompt	"Mijn factuur bijwerken", "waarom ben ik twee keer belast?"
`technical_support`	Triagehulpmiddel voor ondersteuning	"mijn cache loopt uit", "help me verbindingsfouten te debuggen"
`sales`	Verkoopworkflow	"plannen vergelijken", "met de verkoop praten over prijzen"

Kies referenties die het semantische oppervlak van de route bestrijken zonder andere routes te overlappen. Gebruik voorbeelden uit daadwerkelijk verkeer, supporttickets of speciaal samengestelde evaluatiegegevens. Vermijd verwijzingen die te algemeen zijn, zoals "help" of "vraag", omdat ze meerdere routes kunnen matchen.

Maak een semantische router aan

Stel je Redis-URL in een omgevingsvariabele. Het exacte URL-formaat hangt af van je authenticatiemethode en clientconfiguratie. Gebruik een rediss:// URL bij het verbinden met 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,
)

Bij het initialiseren maakt RedisVL een Redis-zoekindex voor de routereferenties aan en vult deze met gegevens. Redis gebruikt vectorvelden en metadatavelden in de index om gelijkeniszoekopdrachten uit te voeren over de ingebedde referenties. Voor details over routerinitialisatie en routevelden, zie de RedisVL SemanticRouter-gids. Voor details over Redis-vectorindexen, zie Redis-vectorzoekconcepten.

Tip

Gebruik per omgeving een aparte routernaam of Redis-sleutelprefix. Als verschillende tenants verschillende routesets nodig hebben, isoleer ze dan met aparte routerindexen of strikte tenant-specifieke sleutelbenaming zodat de referenties van de ene tenant de routeringsresultaten van een andere tenant niet beïnvloeden.

Routeer een verzoek

Het aanroepen van de router retourneert de best overeenkomende route. Als geen enkele route dicht genoeg is om aan zijn drempel te voldoen, geeft RedisVL een miss terug vergelijkbaar met 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)

Behandel distance het als een gelijkenisafstand, niet als een waarschijnlijkheid. Bij Redis COSINE-afstand komen lagere waarden meer overeen. Sla de bijbehorende route, afstand, drempel en geselecteerde bestemming op in je applicatie-telemetrie.

Omgaan met mislukte en dubbelzinnige overeenkomsten

Semantische routers hebben deterministisch gedrag nodig wanneer geen routeovereenkomsten zijn of meerdere routes plausibel zijn.

Bij missers:

Route naar een fallback-workflow, zoals een algemene assistent-prompt, trefwoordrouter, formulier of menselijke overdracht.
Stel een verduidelijkende vraag wanneer de intentie van de gebruiker onvolledig is.
Log het verzoek om offline beoordeling in. Het kan een ontbrekende route of referentie onthullen.

Gebruik bij mogelijke overeenkomsten met meerdere routes route_many() om kandidaatroutes en afstanden te bekijken:

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)

Als beide routes geldig zijn, kies dan een deterministische regel, zoals laagste afstand, expliciete prioriteitsmetadata of een verduidelijkende vraag. Vermijd het in stilte een route te kiezen wanneer de hoogste afstanden dichtbij zijn en de actie zakelijke of beveiligingsimpact heeft.

Update en serialiseer routerconfiguratie

Beheer routedefinities als applicatieconfiguratie. RedisVL ondersteunt het serialiseren van een routerconfiguratie naar een woordenboek of YAML en het later terugzetten ervan. Gebruik deze mogelijkheid om routewijzigingen te bekijken, ze te promoten in omgevingen en routedefinities in lijn te houden met prompt- en toolversies. Je kunt bijvoorbeeld routeconfiguratie opslaan met je applicatie-implementatieartefacten en de router tijdens het opstarten opnieuw aanmaken.

RedisVL ondersteunt ook het dynamisch toevoegen, vermelden en verwijderen van routereferenties. Gebruik dynamische updates zorgvuldig: valideer nieuwe referenties, volg wie ze heeft veranderd en test de impact van de routering voordat je ze naar productie promoot.

Pas drempelwaarden aan met een evaluatieset

Drempels bepalen wanneer een route overeenkomt. Omdat RedisVL-routewaarden distance_threshold Redis COSINE afstandseenheden gebruiken, zijn lagere drempels strenger. De juiste waarde hangt af van je embeddingmodel, taal, referenties en verzoekverdeling.

Gebruik dit afstemproces:

Verzamel gelabelde voorbeelden voor elke route en negatieve voorbeelden die niet bij een route zouden moeten passen.
Splits voorbeelden op in afstemmings- en validatiesets.
Evalueer elke route onafhankelijk en meet valse acceptaties, valse afwijzingen en ambigue matches.
Begin met strengere drempels voor acties met hoge impact en versoepel deze alleen wanneer validatiedata dit ondersteunt.
Evalueer de drempels opnieuw telkens wanneer je het embeddingmodel, referenties of routetaxonomie verandert.

Vergelijk geen afstandswaarden tussen routers die verschillende embeddingmodellen gebruiken. Redis-vectorindexen vereisen queryvectoren die overeenkomen met de vectorveldafmetingen, en modelwijzigingen vereisen meestal het herbouwen of versieëren van de routerindex. Voor meer informatie, zie Redis vectorzoekconcepten.

Begrijp afstand, drempels en prioriteiten

Routeafstand is de gelijkenisafstand tussen de inkomende verzoek-embedding en de routereferentie-embeddings. Met de COSINE afstandsmetriek van de Semantische Router van de RedisVL betekent een kleinere waarde dat het verzoek dichter bij een routereferentie ligt. De router accepteert een route alleen wanneer de resulterende afstand binnen die distance_thresholdroute ligt.

Vermijd het behandelen van routeafstand als een betrouwbaarheidspercentage. Een afstand van 0.35 betekent niet 35% vertrouwen, en een drempel die werkt voor het ene embeddingmodel werkt misschien niet voor een ander. Gebruik afstanden als rangschikkings- en acceptatiesignalen die je afweegt met gelabelde voorbeelden.

RedisVL-routes hebben geen aparte semantische gewichtinstelling. Gebruik in plaats daarvan deze routeringshendels:

Lever	Wanneer gebruikt u het?	Effect
Lager `distance_threshold`	Een route activeert een kostbare, gevoelige of onomkeerbare actie.	Minder valse acceptaties, maar meer vangvakken of verzoeken om verduidelijking.
Hoger `distance_threshold`	De route is laag risico, breed of kan veilig stroomafwaarts terugkeren.	Meer overeenkomsten, maar ook meer risico dat niet-gerelateerde verzoeken in de route terechtkomen.
Betere referenties	De route is te smal, te breed of verward met een andere route.	Verschuift de routegrens door te veranderen wat de route vertegenwoordigt.
Samenvoegingsmethode	Een route heeft meerdere referenties en één referentie zou voldoende moeten zijn om te matchen.	`min` kan de dichtstbijzijnde referentie prefereren; Gemiddelde stijl aggregatie geeft de voorkeur aan routes waarvan de referenties consequent dicht bij elkaar liggen.
Metagegevens over toepassingsprioriteit	Twee semantisch geldige routes liggen dicht bij elkaar en je bedrijfslogica heeft een tiebreaker nodig.	Stelt de app in staat een deterministische winnaar te kiezen zonder te doen alsof de route semantisch dichter bij elkaar ligt.

Kies strengere drempels voor routes die accountgegevens benaderen, tools oproepen, status wijzigen of escaleren naar mensen. Kies meer permissieve drempels voor laag-risico routes zoals FAQ-selectie, documentatiezoektocht of modelselectie wanneer de downstream-prompt nog steeds een verduidelijkende vraag kan stellen. Als de twee bovenste routeafstanden dicht bij elkaar liggen, geef dan de voorkeur aan een verduidelijkingsstap of een deterministische prioriteitsregel in plaats van stilletjes een actie met hoge impact te kiezen.

Gebruik semantische routing in echte AI-patronen

Semantische routing is nuttig wanneer een AI-app een snelle, uitlegbare beslissing nodig heeft voordat het een model, prompt, tool of workflow oproept. Enkele veelvoorkomende patronen zijn:

Patroon	Hoe semantische routing helpt
Routering van modellen	Stuur eenvoudige verzoeken naar een kleiner of goedkoper model, en reserveer grotere modellen voor complexe redeneer-, codeer- of veiligheidsgevoelige taken.
Prompt routing	Kies de juiste systeemprompt of prompttemplate voor facturatie, ondersteuning, verkoop, probleemoplossing of beleidsvragen.
Gereedschapsroutering	Kies of de agent zoeken, ticketing, diagnostiek, facturering, CRM of helemaal geen hulpmiddel moet aanroepen.
RAG-routering	Kies de juiste opzoekindex, kennisbasis, tenantcorpus of productdocumentatieset voordat je vectorzoekopdrachten uitvoert.
Menselijke overdrachtsroutering	Stuur verzoeken door naar specialistische wachtrijen, escalatiepaden of menselijke beoordeling wanneer de semantische intentie overeenkomt met gevoelige workflows.
Veiligheid en beleidsroutering	Detecteer verzoeken die een strengere beveiligingsmaatregel, ingeperkte prompt, auditspoor of weigerprocedure vereisen voordat de hoofdassistent wordt aangeroepen.

Semantische routing in productie uitvoeren

Gebruik deze werkwijzen voor productiewerklasten:

Houd routes gescheiden. Splits of hernoem overlappende routes. Voeg routes samen die stelselmatig dubbelzinnige overeenkomsten opleveren.
Ik geef de voorkeur aan zorgvuldig samengestelde referenties. Voeg representatieve uitingen toe die aan één route worden gekoppeld. Verwijder verwijzingen die niet-gerelateerd verkeer aantrekken.
Gebruik fallback bewust. Implementeer een terugvalmechanisme in de applicatielogica. Een brede fallbackroute kan verzoeken opvangen die eigenlijk missers hadden moeten zijn.
Configuratie van de versieroute. Voeg prompt-, tool-, model- en routeversiemetadata op. Rol routewijzigingen terug zoals andere aanpassingen in applicatieconfiguraties.
Let op de routingkwaliteit. Houd het hitpercentage van routes, het mispercentage, de belangrijkste route, de afstand, de drempel, het aantal dubbelzinnige overeenkomsten, het fallbackpercentage en de succesindicatoren verderop in de keten bij. Bekijk afstandsverdelingen en verdelingen van betrouwbaarheidsklassen per route.
Scheid huurders wanneer nodig. Gebruik geïsoleerde routers, sleutelprefixen of Redis-instanties wanneer tenants verschillende routingsets hebben of strikte vereisten voor gegevensisolatie.
Bescherm gevoelige metadata. Sla geen geheimen op in metagegevens van routes of referenties. Behandel routevoorbeelden als applicatiegegevens.
Capaciteit plannen. Routereferenties zijn ingebed en geïndexeerd in Redis. Houd routesets compact en representatief, en monitor geheugen, latentie en indexgrootte naarmate referenties groeien.

De hulpbronnen opschonen

Als u de resources wilt blijven gebruiken die u in dit artikel hebt gemaakt, moet u de resourcegroep behouden.

Als u klaar bent met de resources, kunt u de Azure-resourcegroep verwijderen die u hebt gemaakt om kosten te voorkomen.

Important

Het verwijderen van een resourcegroep kan niet ongedaan worden gemaakt. Wanneer u een resourcegroep verwijdert, worden alle resources in de groep definitief verwijderd. Zorg ervoor dat u niet per ongeluk de verkeerde bron of bronngroep verwijdert. Als u de resources in een bestaande resourcegroep hebt gemaakt die resources bevat die u wilt behouden, kunt u elke resource afzonderlijk verwijderen in plaats van de resourcegroep te verwijderen.

Een resourcegroep verwijderen

Meld u aan bij de Azure-portal en selecteer vervolgens Resource-groepen.
Selecteer de resourcegroep die u wilt verwijderen.

Als er veel resourcegroepen zijn, gebruikt u het vak Filter voor een veld... en typt u de naam van de resourcegroep die u voor dit artikel hebt gemaakt. Selecteer de bronnen groep in de lijst met resultaten.
Selecteer Resourcegroep verwijderen.
U wordt gevraagd om het verwijderen van de resourcegroep te bevestigen. Typ ter bevestiging de naam van de resourcegroep. Selecteer vervolgens Verwijderen.

Na enkele ogenblikken worden de resourcegroep en alle bijbehorende resources verwijderd.

Feedback

Is deze pagina nuttig?

Last updated on 2026-07-30