Tutoriál: Směrovat AI požadavky podle sémantické podobnosti s Azure Managed Redis

Sémantické směrování odesílá požadavek v přirozeném jazyce správnému handleru, modelu, nástroji, promptu nebo workflow porovnáním požadavku s reprezentativními příklady pro každou trasu. V tomto tutoriálu implementujete sémantické směrování jako aplikační vzor pomocí RedisVL a Azure Managed Redis. Sémantické směrování není samostatná spravovaná funkce Azure Managed Redis. Používá vektorové vyhledávání Redis a aplikační kód.

Vektorové vyhledávání v Redis vyžaduje RediSearch a je dostupné v Azure Managed Redis, jak je popsáno v přehledu vektorového vyhledávání Azure Managed Redis. Moduly Redis, včetně RediSearch, musí být povoleny při vytváření instance Azure Managed Redis. Informace o podporovaných úrovních a zásadách najdete v článcích Používání modulů Redis se službou Azure Managed Redis a Požadavky na RediSearch.

RedisVL poskytuje SemanticRouter rozhraní, které pomocí vyhledávání Redis klasifikuje požadavek na základě sady Route referencí. Pro základní vektorový model Redis ukládá vektory a metadata do hashů nebo JSON objektů a vyhledává je pomocí vektorových polí, metrik vzdálenosti a dotazů KNN nebo rozsahu. Pro více informací viz průvodce RedisVL SemanticRouter a koncepty vektorového vyhledávání v Redisu.

V tomto návodu se naučíte, jak:

• Definujte pojmenované sémantické trasy s reprezentativními odkazy.
• Vytvořte sémantický směrovač RedisVL využívající Azure Managed Redis.
• Směrujte požadavky na jednu nebo více odpovídajících tras.
• Zvládejte chyby a nejasné shody.
• Ladit prahy a provozovat sémantické směrování v produkci.
• Aplikujte sémantické směrování na běžné AI aplikační vzory.

Prerequisites

• Předplatné služby Azure. Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet.
• Instance Azure Managed Redis s povolenou funkcí RediSearch při vytváření. RediSearch je modul Redis, který umožňuje vektorové vyhledávání v Azure Managed Redis a moduly musí být vybrány při vytváření instance. Prohlédněte si podporovanou matici modulů a požadavky na politiku RediSearch v Používejte Redis moduly s Azure Managed Redis.
• Připojovací řetězec nebo adresa URL Redis pro vaši instanci Azure Managed Redis. Používejte TLS a schválenou autentizační metodu vaší aplikace.
• Python prostředí, které dokáže nainstalovat RedisVL a závislosti pro zvolený model vkládání.
• Strategie embeddingu nebo vektorizace. Tento tutoriál používá RedisVL HFTextVectorizer jako stručný příklad. Použijte stejný model vkládání pro každou referenci trasy a každý příchozí požadavek v indexu routeru, aby vektorové rozměry a metriky vzdálenosti zůstaly v souladu. Indexy vektoru v Redisu vyžadují pro vektorové pole pevně dané hodnoty DIM a DISTANCE_METRIC. Pro více informací viz koncepty vektorového vyhledávání v Redisu.

Instalace RedisVL:

pip install redisvl

Navrhněte si trasy

Trasa představuje rozhodnutí aplikace, například šablonu promptu, nástroj, model nebo workflow. Každá trasa zahrnuje:

• Stabilní name , kterou vaše aplikace mapuje na handler.
• references, které jsou reprezentativními výroky pro danou trasu.
• Volitelné metadata, jako jsou identifikátory obslužných zařízení, verze promptů, preference modelu nebo informace o vlastníci.
• Jeden na trasu distance_threshold. V RedisVL používají prahové hodnoty tras jednotky vzdálenosti Redis COSINE, přičemž nižší hodnoty vyžadují přísnější shodu. Prahy závisí na konkrétním modelu a měly by být ověřeny na základě vašich vlastních požadavků.

Například AI asistent může použít tyto trasy:

Cesta	Příklad cíle	Reprezentativní odkazy
billing	Pracovní postup fakturace nebo výzva	"aktualizovat fakturu", "proč mi účtovali dvakrát?"
technical_support	Podpůrný nástroj pro třídění	"platnost mé mezipaměti vyprší", "pomozte mi diagnostikovat chyby připojení"
sales	Prodejní pracovní postup	"porovnejte plány", "mluvte s prodejci o cenách"

Vyberte odkazy, které pokrývají sémantickou plochu trasy, aniž by se překrývaly s jinými trasami. Použijte příklady z reálné návštěvnosti, podporních tiketů nebo pečlivě vybraných hodnotících dat. Vyhněte se příliš obecným odkazům, jako je "pomoc" nebo "otázka", protože mohou odpovídat více cestám najednou.

Vytvořte sémantický router

Nastavte URL Redis v proměnné prostředí. Přesný formát URL závisí na vaší autentizační metodě a konfiguraci klienta. Při připojování k TLS použijte rediss:// URL.

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,
)

Po inicializaci RedisVL vytvoří a naplní vyhledávací index Redis pro odkazy na trasy. Redis používá vektorová pole a metadata pole v indexu k vyhledávání podobností mezi vloženými referencemi. Podrobnosti o inicializaci routeru a polích trasování naleznete v příručce RedisVL SemanticRouter. Podrobnosti o indexech Redis vektorů naleznete v článku o konceptech vektorového vyhledávání v Redisu.

Tip

Používejte samostatné jméno routeru nebo prefix Redis klíče pro každé prostředí. Pokud různí tenanti potřebují různé sady tras, izolujte je pomocí samostatných indexů routerů nebo přísného pojmenovávání klíčů specifických pro tenanta, aby reference jednoho tenanta neovlivnily výsledky směrování druhého tenanta.

Směrovat požadavek

Volání routeru vrátí nejvhodnější odpovídající trasu. Pokud žádná trasa není dostatečně blízko k dosažení svého prahu, RedisVL vrací chybu podobnou .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)

Berte distance jako vzdálenost podobnosti, ne jako pravděpodobnost. U vzdálenosti Redis COSINE jsou nižší hodnoty těsnější shody. Uložte si spárovanou trasu, vzdálenost, práh a vybraný cíl do telemetrie aplikace.

Zpracování nenalezených případů a nejednoznačných shod

Sémantické směrovače potřebují deterministické chování, když žádná trasa neodpovídá nebo je možné více tras.

Za chyby:

• Přejděte na záložní pracovní postup, například obecný prompt asistenta, router klíčových slov, formulář nebo lidské předání.
• Zeptejte se na upřesňující otázku, když je záměr uživatele neúplný.
• Zaznamenejte žádost o offline kontrolu. Může to odhalit chybějící trasu nebo chybějící odkaz.

Pro možné shody více tras použijte route_many() ke kontrole možných tras a vzdáleností:

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)

Pokud jsou obě trasy platné, zvolte deterministické pravidlo, například nejnižší vzdálenost, explicitní prioritní metadata nebo upřesňující otázku. Vyhněte se tichému výběru trasy, když jsou nejvyšší vzdálenosti blízko a akce má obchodní nebo bezpečnostní dopad.

Aktualizovat a serializovat konfiguraci routeru

Spravujte definice tras jako konfiguraci aplikace. RedisVL podporuje serializaci konfigurace routeru do slovníku nebo YAML a její pozdější obnovení. Použijte tuto schopnost k prohlížení změn tras, jejich propagaci napříč prostředími a udržování definic tras v souladu s verzemi promptů a nástrojů. Například můžete uložit konfiguraci směrování spolu s artefakty nasazení vaší aplikace a během spouštění znovu vytvořit router.

RedisVL také podporuje dynamické přidávání, uvádění a mazání odkazů na trasy. Dynamické aktualizace používejte opatrně: ověřujte nové odkazy, sledujte, kdo je změnil, a před jejich nasazením do produkce otestujte dopad na směrování.

Laďte prahové hodnoty pomocí vyhodnocovací sady

Prahové hodnoty určují, kdy cesta odpovídá. Protože hodnoty trasy distance_threshold v RedisVL používají jednotky vzdálenosti Redis COSINE, nižší prahové hodnoty jsou přísnější. Správná hodnota závisí na vašem modelu vkládání, jazyce, odkazech a distribuci požadavků.

Použijte tento proces ladění:

1. Sbírejte označené příklady pro každou trasu a negativní příklady, které by neměly odpovídat žádné trase.
2. Rozdělte příklady na ladící a validační sady.
3. Každou trasu vyhodnoťte nezávisle a měřte falešná přijetí, falešná odmítnutí a nejednoznačné shody.
4. Začněte s přísnějšími prahy pro vysoce dopadné akce a uvolněte je pouze tehdy, když to validační data podporují.
5. Znovu zhodnoťte prahy pokaždé, když změníte model vložení, odkazy nebo taxonomii tras.

Neporovnávejte hodnoty vzdáleností mezi routery, které používají různé modely embeddingu. Vektorové indexy Redis vyžadují dotazovací vektory, aby odpovídaly rozměrům vektorového pole, a změny modelu obvykle vyžadují přestavbu nebo verzi indexu routeru. Pro více informací viz koncepty vektorového vyhledávání v Redisu.

Porozumět vzdálenosti, prahům a prioritám

Vzdálenost trasy je podobnostní vzdálenost mezi příchozím vložením požadavku a vložením referenčních tras. U metriky vzdálenosti sémantického routeru COSINE RedisVL znamená menší hodnota, že požadavek je blíže referenčnímu směru. Router přijímá trasu pouze tehdy, když je výsledná vzdálenost v rámci této trasy distance_threshold.

Vyhněte se považování vzdálenosti trasy za procento spolehlivosti. Vzdálenost 0.35 neznamená 35% míru jistoty a práh, který funguje pro jeden embeddingový model, nemusí fungovat pro jiný. Používejte vzdálenosti jako signály hodnocení a přijetí, které kalibrujete podle označených příkladů.

Trasy RedisVL nemají samostatné nastavení sémantické váhy. Použijte místo toho tyto směrovací páky:

Páka	Kdy ji použít	Účinek
Nižší distance_threshold	Tato cesta spouští nákladnou, citlivou nebo nevratnou akci.	Méně falešných přijetí, ale více záložních nebo žádostí o upřesnění.
Vyšší distance_threshold	Trasa je nízkoriziková, široká nebo lze bezpečně obnovit po proudu.	Více shod, ale větší riziko, že do trasy vstoupí nesouvisející požadavky.
Lepší odkazy	Trasa je příliš úzká, příliš široká nebo zaměněná s jinou trasou.	Posune hranici trasy změnou toho, co trasa představuje.
Metoda agregace	Trasa má několik referencí a k nalezení shody by měla stačit jedna reference.	min může upřednostnit nejbližší odkaz; Průměrná agregace upřednostňuje trasy, jejichž odkazy jsou konzistentně blízké.
Metadata priorit aplikace	Dvě sémanticky platné trasy jsou si velmi podobné a vaše aplikační logika potřebuje rozhodovací kritérium.	Umožňuje aplikaci vybrat deterministického vítěze, aniž by předstírala, že trasa je sémanticky blíž.

Vyberte přísnější prahy pro trasy, které přistupují k datům účtů, volacím nástrojům, mění stav nebo eskalují na lidi. Zvolte více povolených prahů pro nízkorizikové trasy, jako je výběr FAQ, vyhledávání dokumentace nebo výběr modelu, pokud může následný prompt stále položit upřesňující otázku. Pokud jsou dvě horní vzdálenosti tras blízké, raději upřesněte krok nebo deterministické pravidlo priority místo tichého výběru akce s vysokým dopadem.

Používejte sémantické směrování v reálných AI vzorcích

Sémantické směrování je užitečné vždy, když AI aplikace potřebuje rychlé a vysvětlitelné rozhodnutí před tím, než zavolá model, výzvu, nástroj nebo pracovní postup. Mezi běžné vzorce patří:

Pattern	Jak pomáhá sémantické směrování
Směrování modelů	Posílejte jednoduché požadavky na menší nebo levnější model a větší modely si vyhraďte pro složité uvažování, kódování nebo bezpečnostní úkoly.
Směrování promptů	Vyberte správný systémový prompt nebo šablonu promptu pro fakturaci, podporu, prodej, řešení problémů nebo otázky ohledně politiky.
Směrování nástrojů	Zvolte, zda má agent použít vyhledávání, ticketovací systém, diagnostiku, fakturaci, CRM, nebo žádný nástroj.
Směrování RAG	Vyberte si správný index vyhledávání, znalostní základnu, korpus nájemců nebo sadu dokumentace produktu před spuštěním vektorového vyhledávání.
Směrování předání operátorovi	Směrujte požadavky do specializovaných front, eskalačních cest nebo lidské kontroly, pokud sémantický záměr odpovídá citlivým pracovním postupům.
Bezpečnost a směrování politiky	Rozpoznávejte požadavky, které před vyvoláním hlavního asistenta vyžadují přísnější bezpečnostní omezení, omezenou výzvu, auditní stopu nebo proces odmítnutí.

Provoz sémantického směrování v produkci

Použijte tyto postupy pro produkční pracovní zátěže:

• Udržujte trasy oddělené. Rozdělit nebo přejmenovat překrývající se trasy. Spojte trasy, které konzistentně vytvářejí nejednoznačné zápasy.
• Preferujte pečlivě vybrané reference. Přidejte reprezentativní promluvy, které odpovídají jedné trase. Odstraňte odkazy, které přitahují nesouvisející návštěvnost.
• Používejte záložní mechanismus záměrně. Implementujte záložní systém v aplikační logice. Příliš obecná záložní trasa může zachytit požadavky, které měly skončit jako nezachycené.
• Konfigurace verzní trasy. Zahrňte metadata o verzi promptu, nástroje, modelu a trasy. Vraťte změny tras zpět stejně jako ostatní změny konfigurace aplikace.
• Sledujte kvalitu směrování. Sledujte míru shod tras, míru neshod, nejčastější trasu, vzdálenost, práh, počet nejednoznačných shod, míru využití záložního řešení a metriky úspěšnosti v navazujících krocích. Prohlédněte si rozdělení vzdáleností a rozdělení podle skupin míry spolehlivosti podle trasy.
• Oddělte tenanty podle potřeby. Používejte izolované routery, klíčové prefixy nebo instance Redis, pokud mají nájemci různé sady tras nebo přísné požadavky na izolaci dat.
• Chraňte citlivá metadata. Neukládejte citlivé údaje do metadat tras ani do odkazů. Příklady tras považujte za data aplikace.
• Naplánujte kapacitu. Odkazy na trasy jsou vloženy a indexovány v Redis. Udržujte sady tras kompaktní a reprezentativní a sledujte paměť, latenci a velikost indexu, jak odkazy rostou.

Vyčistěte zdroje

Pokud chcete dál používat prostředky, které jste vytvořili v tomto článku, ponechte skupinu prostředků.

Jinak pokud jste s prostředky hotovi, můžete odstranit skupinu prostředků Azure, kterou jste vytvořili, abyste se vyhnuli poplatkům.

Důležité

Odstranění skupiny prostředků je nevratné. Při odstranění skupiny prostředků se všechny prostředky, které obsahuje, trvale odstraní. Ujistěte se, že nechtěně neodstraníte nesprávnou skupinu prostředků nebo jednotlivé prostředky. Pokud jste prostředky vytvořili v existující skupině prostředků, která obsahuje prostředky, které chcete zachovat, můžete každý prostředek odstranit jednotlivě místo odstranění skupiny prostředků.

Odstranit skupinu prostředků

1. Přihlaste se k portálu Azure a vyberte Sourcové skupiny.

2. Vyberte skupinu prostředků, kterou chcete odstranit.

   Pokud existuje mnoho skupin prostředků, použijte filtr pro jakékoli pole... zadejte název skupiny prostředků, kterou jste vytvořili pro tento článek. V seznamu výsledků vyberte skupinu prostředků.

   

3. Vyberte odstranit skupinu zdrojů.

4. Zobrazí se výzva k potvrzení odstranění skupiny prostředků. Zadejte název vaší skupiny prostředků pro potvrzení a poté vyberte Odstranit.

   

Po chvíli se skupina prostředků včetně všech prostředků, které obsahuje, odstraní.

Související obsah

• O vektorových embeddingech a vektorovém vyhledávání v Azure Managed Redis
• Používejte Redis moduly s Azure Managed Redis
• Průvodce RedisVL SemanticRouter
• Koncepty vektorového vyhledávání v Redisu
• Quickstart: Vytvořit instanci Azure Managed Redis