Samouczek: Kieruj żądania AI według podobieństwa semantycznego do Azure Managed Redis

Dotyczy: ✅ Azure Managed Redis

Routowanie semantyczne kieruje żądanie sformułowane w języku naturalnym do właściwego modułu obsługującego, modelu, narzędzia, polecenia lub przepływu pracy, porównując je z reprezentatywnymi przykładami dla każdej ścieżki. W tym samouczku wdrażasz routing semantyczny jako wzorzec aplikacyjny za pomocą RedisVL i Azure Managed Redis. Routing semantyczny nie jest odrębną funkcją usługi Azure Managed Redis. Wykorzystuje wyszukiwanie wektorowe Redisa oraz kod aplikacyjny.

Wyszukiwanie wektorowe w Redis wymaga RediSearch i jest dostępne w Azure Managed Redis, jak opisano w przeglądzie wyszukiwania wektorowego Azure Managed Redis. Moduły Redis, w tym RediSearch, muszą być włączone podczas tworzenia instancji Azure Managed Redis. Wspierane poziomy i polityki można znaleźć w artykule Użyj modułów Redis z Azure Managed Redis oraz wymagania RediSearch.

RedisVL udostępnia SemanticRouter interfejs, który wykorzystuje mechanizm wyszukiwania Redis do sklasyfikowania żądania względem zestawu Route odniesień. Dla modelu wektorowego Redis przechowuje wektory i metadane w skrótach lub obiektach JSON i przeszukuje je za pomocą pól wektorowych, metryk odległości oraz zapytań KNN lub zakresu. Więcej informacji można znaleźć w przewodniku RedisVL SemanticRouter oraz koncepcjach wyszukiwania wektorowego Redis.

W tym poradniku nauczysz się, jak:

Definiuj nazwane trasy semantyczne z reprezentatywnymi odniesieniami.
Utwórz router semantyczny RedisVL oparty na Azure Managed Redis.
Przekierowuj żądania do jednej lub więcej pasujących tras.
Radzenie sobie z niepodaniami i niejednoznacznymi dopasowaniami.
Dostosuj progi i korzystaj z trasowania semantycznego w środowisku produkcyjnym.
Stosuj routing semantyczny do typowych wzorców aplikacji AI.

Prerequisites

Subskrypcja platformy Azure. Jeśli nie masz subskrypcji platformy Azure, utwórz bezpłatne konto.
Instancja Azure Managed Redis z włączonym RediSearch w momencie tworzenia. RediSearch to moduł Redis, który umożliwia wyszukiwanie wektorowe w Azure Managed Redis, a moduły muszą być wybierane podczas tworzenia instancji. Przejrzyj macierz obsługiwanych modułów oraz wymagania zasad RediSearch w artykule Korzystanie z modułów Redis w usłudze Azure Managed Redis.
Parametry połączenia lub adres URL Redis dla twojej instancji usługi Azure Managed Redis. Użyj TLS oraz zatwierdzonej przez Twoją aplikację metody uwierzytelniania.
Środowisko Python, które potrafi zainstalować RedisVL oraz zależności dla wybranego modelu osadzania.
Strategia embeddingu lub wektoryzacji. Ten samouczek wykorzystuje RedisVL HFTextVectorizer jako zwięzły przykład. Używaj tego samego modelu osadzeń dla każdej referencji trasy i każdego przychodzącego żądania w indeksie rutera, aby wymiary wektorów i metryki odległości pozostawały spójne. Indeksy wektorowe Redis wymagają stałego DIM i DISTANCE_METRIC dla pola wektorowego. Więcej informacji można znaleźć w artykule o koncepcjach wyszukiwania wektorowego w Redis.

Instalacja RedisVL:

pip install redisvl

Projektuj swoje trasy

Trasa reprezentuje decyzję aplikacyjną, taką jak szablon promptu, narzędzie, model lub workflow. Każda trasa obejmuje:

Stabilność name , którą twoja aplikacja mapuje na handlera.
references, które są reprezentatywnymi wypowiedziami dla tej trasy.
Opcjonalne metadata, takie jak identyfikatory handlerów, wersje promptów, preferencje modelu lub informacje o właścicielu.
Dla każdej trasy distance_threshold. W RedisVL progi trasowania wykorzystują jednostki odległości Redis COSINE, przy czym niższe wartości wymagają bardziej rygorystycznego dopasowania. Progi są specyficzne dla modelu i powinny być weryfikowane na podstawie własnych żądań.

Na przykład asystent AI może korzystać z następujących tras:

Marszruta	Przykładowe miejsce docelowe	Reprezentatywne odniesienia
`billing`	Przepływ pracy rozliczeń lub monit	"zaktualizuj fakturę", "dlaczego zostałem obciążony dwa razy?"
`technical_support`	Narzędzie pomocnicze do triage	"moja pamięć podręczna się kończy", "pomóż mi debugować błędy połączenia"
`sales`	Przepływ pracy sprzedaży	"porównaj pakiety", "skontaktuj się z działem sprzedaży w sprawie cen"

Wybierz odniesienia obejmujące powierzchnię semantyczną trasy, nie nakładając się na inne trasy. Korzystaj z przykładów z rzeczywistego ruchu, zgłoszeń wsparcia lub wybranych danych ewaluacji. Unikaj zbyt ogólnych odniesień, takich jak "pomoc" czy "pytanie", ponieważ mogą pasować do wielu ścieżek.

Stwórz router semantyczny

Ustaw swój adres Redis w zmiennej środowiskowej. Dokładny format URL zależy od metody uwierzytelniania i konfiguracji klienta. Użyj rediss:// adresu URL podczas łączenia się z 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,
)

Po inicjalizacji RedisVL tworzy i wypełnia indeks wyszukiwania Redis dla odniesień do tras. Redis wykorzystuje pola wektorowe i pola metadanych w indeksie do wyszukiwania podobieństw w osadzonych referencjach. Szczegóły dotyczące inicjalizacji routera i pól trasowania można znaleźć w przewodniku RedisVL SemanticRouter. Szczegóły dotyczące indeksów wektorowych Redisa można znaleźć w artykule o koncepcjach wyszukiwania wektorowego Redisa.

Wskazówka

Używaj osobnej nazwy routera lub prefiksu klucza Redis dla każdego środowiska. Jeśli różni tenantzy potrzebują różnych zestawów tras, wyodrębnij je za pomocą oddzielnych indeksów routerów lub ścisłego nazewnictwa klucza specyficznego dla tenanta, aby referencje jednego tenanta nie wpływały na wyniki routingu drugiego tenanta.

Kieruj żądanie

Połączenie routera daje najlepsze dopasowanie trasy. Jeśli żadna trasa nie jest wystarczająco bliska, aby spełnić swój próg, RedisVL zwraca wynik braku trafienia podobny do 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)

Traktuj distance jako miarę podobieństwa, a nie prawdopodobieństwo. W przypadku odległości Redis COSINE niższe wartości oznaczają lepsze dopasowanie. Przechowuj dopasowaną trasę, odległość, próg i wybrany cel w telemetrii aplikacji.

Nieudane i niejednoznaczne dopasowania

Routery semantyczne potrzebują deterministycznego zachowania, gdy żadna trasa się nie zgadza lub kilka tras jest możliwych.

Za chybienia:

Przekieruj do zapasowego przepływu pracy, takiego jak ogólny monit asystenta, mechanizm trasowania słów kluczowych, formularz lub przekazanie do człowieka.
Zadaj pytanie wyjaśniające, gdy intencja użytkownika jest niepełna.
Zgłoś prośbę o przegląd offline. Może to ujawnić brakującą trasę lub brakujące odniesienie.

W przypadku możliwych dopasowań dla wielu tras użyj route_many(), aby sprawdzić kandydatów tras i odległości:

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)

Jeśli obie trasy są ważne, wybierz regułę deterministyczną, taką jak najniższa odległość, metadane priorytetowe lub pytanie wyjaśniające. Unikaj cichego wybierania trasy, gdy największe odległości są blisko, a akcja ma wpływ biznesowy lub bezpieczeństwa.

Aktualizuj i serializuj konfigurację routera

Zarządzaj definicjami tras jako konfiguracją aplikacji. RedisVL obsługuje serializację konfiguracji routera do słownika lub formatu YAML oraz jej późniejsze przywrócenie. Wykorzystaj tę możliwość do przeglądania zmian tras, promowania ich w różnych środowiskach oraz utrzymywania zgodności definicji tras z wersjami promptów i narzędzi. Na przykład możesz przechowywać konfigurację routingu wraz z artefaktami wdrożeniowymi aplikacji i odtworzyć router podczas uruchamiania.

RedisVL obsługuje także dynamiczne dodawanie, listę i usuwanie referencji do tras. Używaj aktualizacji dynamicznych ostrożnie: weryfikuj nowe referencje, śledź, kto je zmienił, i testuj wpływ routingu przed promowaniem ich do produkcji.

Dostosuj progi za pomocą zestawu walidacyjnego

Progi określają, kiedy trasa pasuje. Ponieważ wartości ścieżki distance_threshold RedisVL używają jednostek odległości Redis COSINE, niższe progi są bardziej rygorystyczne. Odpowiednia wartość zależy od modelu osadzania, języka, odniesień i dystrybucji żądań.

Skorzystaj z tego procesu strojenia:

Zbierz oznaczone przykłady dla każdej trasy oraz negatywne przykłady, które nie powinny pasować do żadnej trasy.
Podziel dane na zbiory dostrajania i walidacji.
Oceń każdą ścieżkę niezależnie i mierz fałszywe akceptacje, fałszywe odrzucenia oraz niejednoznaczne dopasowania.
Zacznij od surowszych progów dla działań o dużym wpływie i luzuj je tylko wtedy, gdy dane walidacyjne to potwierdzają.
Ponownie oceniaj progi za każdym razem, gdy zmieniasz model osadzania, odniesienia lub taksonomię tras.

Nie porównuj wartości odległości między routerami używającymi różnych modeli osadzania. Indeksy wektorowe Redis wymagają wektorów zapytań, aby dopasowały się do wymiarów pola wektorowego, a zmiany modelu zwykle wymagają przebudowy lub wersji indeksu routera. Więcej informacji można znaleźć w artykule o koncepcjach wyszukiwania wektorowego w Redis.

Zrozum odległość, progi i priorytety

Odległość trasy to odległość podobieństwa między osadzeniem żądania przychodzącego a osadzeniem referencji trasy. Dzięki metryce odległości semantycznego routera COSINE RedisVL mniejsza wartość oznacza, że żądanie jest bliższe referencji trasy. Router akceptuje trasę tylko wtedy, gdy uzyskana odległość mieści się w obrębie tej trasy .distance_threshold

Unikaj traktowania odległości trasy jako procentu pewności. Odległość wynosząca 0.35 nie oznacza 35% poziomu pewności, a próg, który działa dla jednego modelu embeddingowego, może nie działać dla innego. Używaj odległości jako sygnałów rankingu i akceptacji, które kalibrujesz za pomocą oznaczonych przykładów.

Trasy RedisVL nie mają osobnego ustawienia wagi semantycznej. Zamiast tego użyj tych dźwigni trasowania:

Dźwignia	Kiedy należy go używać	Efekt
Obniż `distance_threshold`	Trasa ta wywołuje kosztowne, wrażliwe lub nieodwracalne działanie.	Mniej fałszywych akceptacji, ale więcej przypadków użycia metody alternatywnej lub próśb o doprecyzowanie.
Wyżej `distance_threshold`	Trasa jest niskiego ryzyka, szeroka i można bezpiecznie wrócić w dół rzeki.	Więcej dopasowań, ale większe ryzyko wejścia na trasę niezwiązanych ze sobą.
Lepsze źródła	Trasa jest zbyt wąska, zbyt szeroka lub mylona z inną trasą.	Przesuwa granicę trasy poprzez zmianę tego, co trasa reprezentuje.
Metoda agregacji	Trasa ma kilka odniesień i jedno powinno wystarczyć, by się dopasować.	`min` może faworyzować najbliższą referencję; agregacja oparta na średniej preferuje trasy, których referencje są stale bliskie.
Metadane priorytetu aplikacji	Dwie semantycznie poprawne ścieżki są do siebie zbliżone, a logika biznesowa wymaga mechanizmu rozstrzygającego.	Pozwala aplikacji wybrać deterministycznego zwycięzcę, nie udając, że trasa jest semantycznie bliższa.

Wybierz bardziej rygorystyczne progi dla ścieżek, które uzyskują dostęp do danych konta, wywołują narzędzia, zmieniają stan lub eskalują do człowieka. Wybierz mniej restrykcyjne progi dla ścieżek o niskim ryzyku, takich jak wybór odpowiedzi z FAQ, przeszukiwanie dokumentacji czy wybór modelu, gdy kolejny prompt może nadal zadać pytanie doprecyzowujące. Jeśli dwie pierwsze odległości tras są do siebie zbliżone, należy preferować etap doprecyzowania lub deterministyczną regułę priorytetu zamiast niejawnego wyboru działania o poważnych skutkach.

Wykorzystaj routing semantyczny w rzeczywistych wzorcach AI

Trasowanie semantyczne jest przydatne zawsze, gdy aplikacja AI potrzebuje szybkiej decyzji, którą można wyjaśnić, zanim wywoła model, polecenie, narzędzie lub przepływ pracy. Typowe wzorce obejmują:

Wzór	Jak pomaga routing semantyczny
Model routingu	Wysyłaj proste żądania do mniejszego lub tańszego modelu, a większe rezerwuj do złożonych zadań rozumowania, kodowania lub zadań związanych z bezpieczeństwem.
Routing monitów	Wybierz odpowiedni monit systemowy lub szablon monitu dla kwestii związanych z rozliczeniami, pomocą techniczną, sprzedażą, rozwiązywaniem problemów lub pytaniami dotyczącymi zasad.
Trasowanie narzędzi	Wybierz, czy agent powinien użyć wyszukiwania, obsługi zgłoszeń, diagnostyki, rozliczeń, CRM lub żadnego narzędzia.
Trasowanie RAG	Wybierz odpowiedni indeks wyszukiwania, bazę wiedzy, korpus najemcy lub zestaw dokumentacji produktu przed uruchomieniem wyszukiwania wektorowego.
Trasowanie przekazania przez człowieka	Przekierowuj żądania do kolejek specjalistycznych, ścieżek eskalacji lub do weryfikacji przez człowieka, jeśli intencja semantyczna odpowiada wrażliwym przepływom pracy.
Bezpieczeństwo i trasowanie polityki	Wykrywaj żądania wymagające bardziej rygorystycznego mechanizmu zabezpieczającego, promptu z ograniczeniami, ścieżki audytu lub procesu odmowy przed uruchomieniem głównego asystenta.

Obsługuj trasowanie semantyczne w produkcji

Stosuj te praktyki do zadań produkcyjnych:

Trzymaj trasy oddzielone. Rozdziel lub zmieniaj nazwy nakładających się tras. Łącz trasy, które konsekwentnie generują niejednoznaczne mecze.
Wolę wyselekcjonowane źródła. Dodaj reprezentatywne wypowiedzi, które przypisują się jednej trasie. Usuń odniesienia, które przyciągają niepowiązany ruch.
Stosuj plan awaryjny celowo. Wprowadź mechanizm awaryjny w logice aplikacji. Zbyt ogólna ścieżka awaryjna może przechwytywać żądania, które nie powinny do niej trafiać.
Konfiguracja trasy wersji. Dołącz metadane dotyczące wersji promptu, narzędzia, modelu i trasy. Cofnij zmiany tras, tak jak inne zmiany w konfiguracji aplikacji.
Obserwuj jakość trasowania. Wskaźnik trafień tras, wskaźnik chybień, najwyższa trasa, odległość, próg, liczba niejednoznacznych dopasowań, wskaźnik awaryjny oraz wskaźniki sukcesu w dalszej fazie. Przejrzyj rozkłady odległości i grup ufności według tras.
Oddzielnie najemców, gdy jest to potrzebne. Używaj izolowanych routerów, prefiksów kluczy lub instancji Redis, gdy najemcy mają różne zestawy tras lub rygorystyczne wymagania dotyczące izolacji danych.
Chroń wrażliwe metadane. Nie przechowuj sekretów w metadanych trasy ani w referencjach. Traktuj przykłady tras jako dane aplikacyjne.
Planowanie pojemności. Odniesienia do tras są osadzone i indeksowane w Redis. Utrzymuj zestawy tras kompaktowe i reprezentatywne oraz monitoruj pamięć, opóźnienia i rozmiar indeksu wraz ze wzrostem referencji.

Uprzątnij zasoby

Jeśli chcesz nadal korzystać z zasobów utworzonych w tym artykule, zachowaj grupę zasobów.

W przeciwnym razie, jeśli skończysz z zasobami, możesz usunąć utworzoną grupę zasobów platformy Azure, aby uniknąć naliczania opłat.

Ważna

Usunięcie grupy zasobów jest nieodwracalne. Jeśli usuniesz grupę zasobów, wszystkie zawarte w niej zasoby zostaną trwale usunięte. Uważaj, aby nie usunąć przypadkowo niewłaściwych zasobów lub grupy zasobów. Jeśli zasoby zostały utworzone w istniejącej grupie zasobów zawierającej zasoby, które chcesz zachować, możesz usunąć każdy zasób indywidualnie zamiast usuwać grupę zasobów.

Aby usunąć grupę zasobów

Zaloguj się do witryny Azure Portal, a następnie wybierz pozycję Grupy zasobów.
Wybierz grupę zasobów, którą chcesz usunąć.

Jeśli istnieje wiele grup zasobów, użyj pola Filtruj dla dowolnego pola... wpisz nazwę grupy zasobów utworzonej dla tego artykułu. Wybierz grupę zasobów na liście wyników.
Wybierz pozycję Usuń grupę zasobów.
Poproszono Cię o potwierdzenie usunięcia grupy zasobów. Wpisz nazwę grupy zasobów w celu potwierdzenia, a następnie wybierz pozycję Usuń.

Po krótkim czasie grupa zasobów i wszystkie jej zasoby zostaną usunięte.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-07-30