Handledning: Routea AI-förfrågningar efter semantisk likhet med Azure Managed Redis

Semantisk routing skickar en förfrågan på naturligt språk till rätt hanterare, modell, verktyg, prompt eller arbetsflöde genom att jämföra förfrågan med representativa exempel för varje rutt. I denna handledning implementerar du semantisk routing som ett applikationsmönster med RedisVL och Azure Managed Redis. Semantisk routing är inte en separat Azure Managed Redis-hanterad funktion. Den använder Redis-vektorsökning och applikationskod.

Vektorsökning i Redis kräver RediSearch och finns tillgänglig i Azure Managed Redis, som beskrivs i Azure Managed Redis vektorsökningsöversikt. Redis-moduler, inklusive RediSearch, måste aktiveras när du skapar Azure Managed Redis-instansen. För stödda nivåer och policyer, se Use Redis-moduler med Azure Managed Redis och RediSearch-krav.

RedisVL tillhandahåller ett SemanticRouter gränssnitt som använder Redis-sökning för att klassificera en förfrågan mot en uppsättning Route referenser. För den underliggande vektormodellen lagrar Redis vektorer och metadata i hashar eller JSON-objekt och söker i dem med vektorfält, avståndsmått och KNN- eller intervallfrågor. För mer information, se RedisVL SemanticRouter-guiden och Redis vektorsökningskoncept.

I den här tutorialen lär du dig följande:

Prerequisites

• Ett Azure-abonnemang. Om du inte har någon Azure-prenumeration kan du skapa ett kostnadsfritt konto.
• En Azure Managed Redis-instans med RediSearch aktiverat vid skapandetillfället. RediSearch är Redis-modulen som möjliggör vektorsökning i Azure Managed Redis, och moduler måste väljas när instansen skapas. Gå igenom den stödda modulmatrisen och RediSearch-policykraven i Use Redis-moduler med Azure Managed Redis.
• En reťazec pripojenia eller Redis-URL för din Azure Managed Redis-instans. Använd TLS och din applikations godkända autentiseringsmetod.
• En Python-miljö som kan installera RedisVL och beroendena för din valda embedding-modell.
• En inbäddnings- eller vektoriseringsstrategi. Denna handledning använder RedisVL HFTextVectorizer som ett kortfattat exempel. Använd samma inbäddningsmodell för varje ruttreferens och varje inkommande förfrågan i ett routerindex så att vektordimensioner och avståndsmått förblir i linje. Redisvektorindex kräver ett fast DIM och DISTANCE_METRIC för vektorfältet. För mer information, se Redis vektorsökningskoncept.

Installera RedisVL:

pip install redisvl

Designa dina rutter

En rutt representerar ett applikationsbeslut, såsom en promptmall, verktyg, modell eller arbetsflöde. Varje rutt inkluderar:

• En beständig name som din applikation kopplar till en hanterare.
• references, som är representativa exempelyttranden för den rutten.
• Valfritt metadata, såsom handler-ID:n, promptversioner, modellpreferenser eller ägarinformation.
• En per rutt distance_threshold. I RedisVL använder rutttrösklar Redis-avståndsenheter COSINE där lägre värden kräver striktare matchning. Trösklar är modellspecifika och bör valideras med dina egna förfrågningar.

Till exempel kan en AI-assistent använda dessa rutter:

Välj referenser som täcker ruttens semantiska yta utan att överlappa andra rutter. Använd exempel från verklig trafik, supportärenden eller kuraterade utvärderingsdata. Undvik referenser som är för generiska, som "hjälp" eller "fråga", eftersom de kan matcha flera vägar.

Skapa en semantisk router

Ställ in din Redis-URL i en miljövariabel. Det exakta URL-formatet beror på din autentiseringsmetod och klientkonfiguration. Använd en rediss:// URL när du ansluter till 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,
)

När den initieras skapar och fyller RedisVL ett Redis-sökindex för ruttreferenserna. Redis använder vektorfält och metadatafält i indexet för att utföra likhetssökning över de inbäddade referenserna. För detaljer om routerinitialisering och ruttfält, se RedisVL SemanticRouter-guiden. För detaljer om Redis-vektorindex, se Redis-vektorsökningskoncept.

Dirigera en begäran

Att anropa routern returnerar den bästa ruttmatchningen. Om ingen rutt är tillräckligt nära för att uppfylla sitt tröskelvärde returnerar RedisVL ingen träff, ungefär som 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)

Betrakta distance som en likhetsdistans, inte som en sannolikhet. Med Redis COSINE-avstånd innebär lägre värden närmare träffar. Spara den matchade rutten, avståndet, tröskeln och valt mål i din applikations telemetri.

Hantera missar och tvetydiga matcher

Semantiska routrar behöver deterministiskt beteende när inga ruttmatchningar eller flera rutter är rimliga.

För missar:

• Styr till ett reservarbetsflöde, såsom en allmän assistentprompt, nyckelordsrouter, formulär eller mänsklig handoff.
• Ställ en förtydligande fråga när användarens avsikt är ofullständig.
• Registrera begäran för offlinegranskning. Det kan avslöja en saknad rutt eller en saknad referens.

För möjliga matchningar med flera rutter, använd route_many() för att inspektera kandidatrutter och avstånd:

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)

Om båda rutterna är giltiga, välj en deterministisk regel, såsom lägsta avstånd, explicit prioriterad metadata eller en förtydligande fråga. Undvik att tyst välja en rutt när de största avstånden är nära och handlingen har affärs- eller säkerhetspåverkan.

Uppdatera och serialisera routerkonfigurationen

Hantera ruttdefinitioner som applikationskonfiguration. RedisVL stöder att serialisera en routerkonfiguration till en ordbok eller YAML och återställa den senare. Använd denna funktion för att granska ruttändringar, främja dem över miljöer och hålla ruttdefinitioner anpassade till prompt- och verktygsversioner. Till exempel kan du lagra ruttkonfiguration med artefakter från applikationsutplacering och återskapa routern vid uppstart.

RedisVL stöder också dynamiskt att lägga till, lista och ta bort ruttreferenser. Använd dynamiska uppdateringar noggrant: validera nya referenser, spåra vem som ändrat dem och testa routningseffekten innan du marknadsför dem till produktion.

Justera tröskelvärden med en utvärderingsuppsättning

Tröskelvärden avgör när en rutt stämmer överens. Eftersom RedisVL-ruttvärden distance_threshold använder Redis-avståndsenheter COSINE är lägre trösklar striktare. Rätt värde beror på din embeddingmodell, språk, referenser och förfrågningsfördelning.

Använd följande justeringsprocess:

1. Samla märkta exempel för varje rutt och negativa exempel som inte borde matcha någon rutt.
2. Dela upp exempel i justerings- och valideringsset.
3. Utvärdera varje rutt oberoende och mät falska acceptanser, falska refuseringar och tvetydiga matchningar.
4. Börja med striktare trösklar för åtgärder med stor påverkan och slappna av dem endast när valideringsdata stöder det.
5. Omvärdera tröskelvärdena varje gång du ändrar inbäddningsmodellen, referenserna eller rutttaxonomin.

Jämför inte avståndsvärden mellan routrar som använder olika embedding-modeller. Redis-vektorindex kräver att frågevektorer matchar vektorfältens dimensioner, och modelländringar kräver vanligtvis ombyggnad eller versionshantering av routerindexet. För mer information, se Redis vektorsökningskoncept.

Förstå avstånd, tröskelvärden och prioriteringarna

Ruttavstånd är likhetsavståndet mellan embeddingen för den inkommande begäran och referensembeddingarna för rutten. För RedisVL:s semantiska routers COSINE avståndsmått betyder ett lägre värde att begäran ligger närmare en ruttreferens. Routern accepterar bara en rutt när det resulterande avståndet ligger inom den ruttens distance_threshold.

Undvik att behandla ruttavståndet som en konfidensprocent. Ett avstånd på 0.35 betyder inte 35% förtroende, och en tröskel som fungerar för en inbäddningsmodell kanske inte fungerar för en annan. Använd avstånd som rangordnings- och acceptanssignaler som du kalibrerar med märkta exempel.

RedisVL-rutter har ingen separat semantisk viktinställning. Använd istället dessa routingspakar:

Välj striktare trösklar för rutter som får tillgång till kontodata, anropar verktyg, ändrar tillstånd eller eskalerar till människor. Välj mer tillåtande tröskelvärden för lågriskvägar som FAQ-val, dokumentationssökning eller modellval när downstream-prompten fortfarande kan ställa en förtydligande fråga. Om de två översta ruttavstånden är nära, föredra ett förtydligande steg eller en deterministisk prioriteringsregel istället för att tyst välja en högpåverkande åtgärd.

Använd semantisk routing i verkliga AI-mönster

Semantisk routing är användbar när en AI-app behöver ett snabbt, förklarbart beslut innan den anropar en modell, prompt, verktyg eller arbetsflöde. Vanliga mönster är:

Kör semantisk routing i produktion

Använd dessa metoder för produktionsarbetsbelastningar:

• Håll rutterna åtskilda. Dela upp eller byt namn på överlappande vägar. Slå ihop rutter som konsekvent ger tvetydiga matchningar.
• Föredrar kuraterade referenser. Lägg till representativa yttranden som kopplas till en rutt. Ta bort referenser som lockar orelaterad trafik.
• Använd reservlösningen avsiktligt. Implementera en reservlösning i programlogiken. En bred reservväg kan fånga förfrågningar som borde ha missats.
• Konfiguration av versionsrutt. Inkludera metadata för prompt, verktyg, modell och ruttversion. Återställ ändringar av rutter precis som andra ändringar i applikationskonfigurationen.
• Övervaka routningskvaliteten. Följ träfffrekvens för rutter, missfrekvens, vanligaste rutt, avstånd, tröskelvärde, antal tvetydiga matchningar, fallback-frekvens och nedströms framgångsmått. Granska fördelningar för avstånd och konfidensintervall efter rutt.
• Särskilja hyresgäster vid behov. Använd isolerade routrar, nyckelprefix eller Redis-instanser när hyresgäster har olika ruttuppsättningar eller strikta krav på dataisolering.
• Skydda känslig metadata. Spara inte hemligheter i ruttmetadata eller referenser. Behandla ruttexempel som applikationsdata.
• Planera för kapacitet. Ruttreferenser är inbäddade och indexerade i Redis. Håll ruttuppsättningarna kompakta och representativa, och övervaka minne, latens och indexstorlek när referenserna växer.

Rensa resurser

Om du vill fortsätta att använda de resurser som du skapade i den här artikeln behåller du resursgruppen.

Om du är klar med resurserna kan du ta bort den Azure-resursgrupp som du skapade för att undvika avgifter.

Ta bort en resursgrupp

1. Logga in på Azure-portalen och välj Resursgrupper.

2. Välj den resursgrupp som du vill ta bort.

   Om det finns många resursgrupper använder du rutan Filter för alla fält... och skriver namnet på resursgruppen som du skapade för den här artikeln. Välj resursgruppen i resultatlistan.

   

3. Välj Ta bort resursgrupp.

4. Du blir ombedd att bekräfta borttagningen av resursgruppen. Skriv namnet på din resursgrupp för att bekräfta och välj sedan Ta bort.

   

Efter en liten stund tas resursgruppen och de resurser som finns i den bort.

Relaterat innehåll

• Om vektorinbäddningar och vektorsökning i Azure Managed Redis
• Använd Redis-moduler med Azure Managed Redis
• RedisVL SemanticRouter-guide
• Redis-vektorsökningskoncept
• Quickstart: Create an Azure Managed Redis instance