Tutorial: Instradare le richieste AI tramite somiglianza semantica con Azure Managed Redis

Il routing semantico invia una richiesta in linguaggio naturale al gestore, modello, strumento, prompt o workflow giusto confrontando la richiesta con esempi rappresentativi per ogni route. In questo tutorial, implementi il routing semantico come schema applicativo con RedisVL e Azure Managed Redis. Il routing semantico non è una funzione gestita separata da Azure Managed Redis. Utilizza la ricerca vettoriale Redis e il codice applicativo.

La ricerca vettoriale in Redis richiede RediSearch ed è disponibile in Azure Managed Redis, come descritto nella panoramica della ricerca vettoriale Azure Managed Redis. I moduli Redis, incluso RediSearch, devono essere abilitati quando si crea l'istanza Azure Managed Redis. Per livelli e policy supportati, vedi Usa moduli Redis con requisiti Azure Managed Redis e RediSearch.

RedisVL fornisce un'interfaccia SemanticRouter che utilizza la ricerca Redis per classificare una richiesta rispetto a un insieme di Route riferimenti. Per il modello vettoriale sottostante, Redis memorizza vettori e metadati in hashe o oggetti JSON e li cerca con campi vettoriali, metriche di distanza e query KNN o di intervallo. Per maggiori informazioni, consulta la guida RedisVL SemanticRouter e i concetti di ricerca vettoriale RedisVL.

In questa esercitazione apprenderai a:

Prerequisites

• Una sottoscrizione di Azure. Se non hai una sottoscrizione di Azure, crea un account gratuito.
• Un'istanza Azure Managed Redis con RediSearch abilitato al momento della creazione. RediSearch è il modulo Redis che consente la ricerca vettoriale in Azure Managed Redis, e i moduli devono essere selezionati quando l'istanza viene creata. Esamina la matrice dei moduli supportata e i requisiti della policy RediSearch in Use Redis modules with Azure Managed Redis.
• Una stringa di connessione o un URL Redis per l'istanza di Azure Managed Redis. Usa TLS e il metodo di autenticazione approvato dalla tua applicazione.
• Un ambiente Python che può installare RedisVL e le dipendenze per il modello di embedding scelto.
• Una strategia di embedding o vettorizzatore. Questo tutorial utilizza il RedisVL HFTextVectorizer come esempio conciso. Usa lo stesso modello di embedding per ogni riferimento di percorso e ogni richiesta in ingresso in un indice di router, così le dimensioni vettoriali e le metriche di distanza rimangono allineate. Gli indici vettoriali Redis richiedono un campo vettoriale fisso DIM e DISTANCE_METRIC per il campo vettoriale. Per maggiori informazioni, vedi concetti di ricerca vettoriale di Redis.

Installa RedisVL:

pip install redisvl

Progetta i tuoi percorsi

Un percorso rappresenta una decisione applicativa, come un modello di prompt, uno strumento, un modello o un flusso di lavoro. Ogni ciclo di lavorazione include:

• Un elemento stabile name che la tua applicazione associa a un handler.
• references, che sono enunciati rappresentativi per quella via.
• Opzionali metadata, come ID dei gestori, versioni dei prompt, preferenze del modello o informazioni sul proprietario.
• Un distance_threshold per percorso. In RedisVL, le soglie di percorso utilizzano unità di distanza Redis COSINE dove valori più bassi richiedono un matching più rigoroso. Le soglie sono specifiche per modello e dovrebbero essere validate con le tue richieste.

Ad esempio, un assistente IA potrebbe utilizzare queste rotte:

Scegli riferimenti che coprano l'area semantica della rotta senza sovrapporsi ad altri percorsi. Usa esempi tratti dal traffico reale, ticket di supporto o dati di valutazione selezionati. Evita riferimenti troppo generici, come "aiuto" o "domanda", perché possono corrispondere a più percorsi.

Crea un router semantico

Imposta il tuo URL Redis in una variabile di ambiente. Il formato esatto dell'URL dipende dal metodo di autenticazione e dalla configurazione del client. Usa un rediss:// URL quando ti connetti con 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,
)

Quando inizializzato, RedisVL crea e popola un indice di ricerca Redis per i riferimenti alle route. Redis utilizza campi vettoriali e campi metadati nell'indice per effettuare la ricerca di similarità sui riferimenti incorporati. Per dettagli sull'inizializzazione del router e sui campi di instradamento, consulta la guida RedisVL SemanticRouter. Per dettagli sugli indici vettoriali di Redis, vedi concetti di ricerca vettoriale di Redis.

Instradare una richiesta

Chiamare il router restituisce la route con la migliore corrispondenza. Se nessuna route è abbastanza vicina da soddisfare la sua soglia, RedisVL restituisce un errore simile a 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)

Considera distance una distanza di somiglianza, non una probabilità. Con la distanza Redis, valori più bassi COSINE indicano corrispondenze più vicine. Memorizza la rotta corrispondente, la distanza, la soglia e la destinazione selezionata nella telemetria della tua applicazione.

Gestisci le mancate corrispondenze e le corrispondenze ambigue

I router semantici richiedono un comportamento deterministico quando non corrisponde alcuna route o quando più route sono plausibili.

Per gli errori:

• Indirizza un flusso di lavoro di riserva, come un prompt di assistente generale, un router di parole chiave, un modulo o un handoff umano.
• Fai una domanda chiaramente quando l'intento dell'utente è incompleto.
• Registra la richiesta di revisione offline. Potrebbe rivelare una rotta o un riferimento mancante.

In caso di possibili corrispondenze su più percorsi, usa route_many() per esaminare i percorsi candidati e le relative distanze:

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)

Se entrambe le rotte sono valide, scegli una regola deterministica, come la distanza più bassa, metadati espliciti di priorità o una domanda chiarificante. Evita di selezionare silenziosamente un percorso quando le distanze principali sono vicine e l'azione ha un impatto commerciale o sulla sicurezza.

Aggiornare e serializzare la configurazione del router

Gestire le definizioni di rotte come configurazione applicativa. RedisVL supporta la serializzazione di una configurazione di router su un dizionario o YAML e il ripristino successivo. Usa questa capacità per rivedere le modifiche ai percorsi, promuoverle tra gli ambienti e mantenere le definizioni dei percorsi allineate con le versioni dei prompt e degli strumenti. Ad esempio, puoi memorizzare la configurazione delle route insieme agli artefatti di distribuzione dell'applicazione e ricreare il router durante l'avvio.

RedisVL supporta anche l'aggiunta, la lista e la cancellazione dinamica dei riferimenti di route. Usa con attenzione gli aggiornamenti dinamici: valida i nuovi riferimenti, traccia chi li ha modificati e testa l'impatto sull'instradamento prima di promuoverli in produzione.

Ottimizza le soglie con un set di valutazione

Le soglie determinano quando un percorso viene considerato corrispondente. Poiché i valori delle rotte distance_threshold RedisVL utilizzano unità di distanza Redis COSINE , le soglie più basse sono più rigide. Il valore corretto dipende dal tuo modello di embedding, dal linguaggio, dai riferimenti e dalla distribuzione delle richieste.

Usa questo processo di messa a punto:

1. Raccogli esempi etichettati per ogni percorso e esempi negativi che non dovrebbero corrispondere a nessun percorso.
2. Dividere gli esempi in set di ottimizzazione e di validazione.
3. Valuta ogni percorso indipendentemente e misura false accettazioni, falsi rifiuti e corrispondenze ambigue.
4. Inizia con soglie più rigide per azioni ad alto impatto e allentale solo quando i dati di validazione lo supportano.
5. Rivaluta le soglie ogni volta che cambi il modello di embedding, i riferimenti o la tassonomia di route.

Non confrontare i valori delle distanze tra router che usano modelli di embedding diversi. Gli indici vettoriali Redis richiedono che i vettori di query corrispondano alle dimensioni del campo vettoriale, e le modifiche al modello di solito richiedono la ricostruzione o la versionizzazione dell'indice del router. Per maggiori informazioni, vedi concetti di ricerca vettoriale di Redis.

Comprendi distanza, soglie e priorità

La distanza del percorso è la distanza di somiglianza tra l'embedding della richiesta in entrata e gli embedding di riferimento del percorso. Con la metrica di distanza del COSINE router semantico RedisVL, un valore più piccolo significa che la richiesta è più vicina a un riferimento di route. Il router accetta una rotta solo quando la distanza risultante rientra in quella di distance_thresholdquella strada.

Evita di considerare la distanza del percorso come una percentuale di fiducia. Una distanza di 0.35 non significa 35% di fiducia, e una soglia che funziona per un modello di embedding potrebbe non funzionare per un altro. Usa le distanze come segnali di classifica e accettazione che calibri con esempi etichettati.

Le rotte RedisVL non hanno un'impostazione separata del peso semantico. Usa invece queste leve di instradamento:

Scegli soglie più rigide per le rotte che accedono ai dati dell'account, invocano strumenti, cambiano stato o passano la richiesta a operatori umani. Scegli soglie più permissive per percorsi a basso rischio, come la selezione delle FAQ, la ricerca di documentazione o la selezione del modello, quando il prompt a valle può ancora porre una domanda chiaristiva. Se le due distanze di percorso superiori sono vicine, preferisci un passaggio di chiarificazione o una regola di priorità deterministica invece di scegliere silenziosamente un'azione ad alto impatto.

Usare il routing semantico in modelli di IA del mondo reale

Il routing semantico è utile ogni volta che un'app di IA necessita di una decisione rapida e spiegabile prima di chiamare un modello, un prompt, uno strumento o un flusso di lavoro. I modelli comuni includono:

Gestire il routing semantico in produzione

Utilizzare queste pratiche per i carichi di lavoro in produzione:

• Tieni i percorsi distinti. Dividere o rinominare i percorsi sovrapposti. Unisci le rotte che generano costantemente corrispondenze ambigue.
• Preferisco riferimenti curati. Aggiungi espressioni rappresentative che corrispondono a un unico percorso. Rimuovi i riferimenti che attirano traffico non correlato.
• Usa il fallback deliberatamente. Implementa il fallback nella logica applicativa. Un percorso di fallback troppo ampio può intercettare richieste che avrebbero dovuto risultare come miss.
• Configurazione del percorso della versione. Includi i metadati del prompt, dello strumento, del modello e della versione del percorso. Annulla i cambiamenti di routing come altre modifiche alla configurazione delle applicazioni.
• Osserva la qualità del percorso. Monitora la percentuale di corrispondenza del percorso, la percentuale di mancate corrispondenze, il percorso principale, la distanza, la soglia, il numero di corrispondenze ambigue, la percentuale di fallback e le metriche di successo nelle fasi successive. Esamina le distribuzioni delle distanze e per fasce di confidenza per percorso.
• Separa i tenant quando necessario. Usa router isolati, prefissi di chiave o istanze Redis quando i tenant hanno set di route diversi o requisiti rigorosi di isolamento dei dati.
• Proteggi i metadati sensibili. Non memorizzare segreti nei metadati o nei riferimenti dei percorsi. Considera gli esempi di rotte come dati applicativi.
• Pianificare la capacità. I riferimenti di percorso sono incorporati e indicizzati in Redis. Mantieni i route set compatti e rappresentativi, e monitora memoria, latenza e dimensione indice man mano che i riferimenti aumentano.

Pulire le risorse

Per continuare a usare le risorse create in questo articolo, mantenere il gruppo di risorse.

In caso contrario, se le risorse sono state completate, per evitare addebiti è possibile eliminare il gruppo di risorse di Azure creato.

Per eliminare un gruppo di risorse

1. Accedere al portale di Azure e selezionare Gruppi di risorse.

2. Scegliere il gruppo di risorse da eliminare.

   Se sono presenti molti gruppi di risorse, usare la casella Filtro per qualsiasi campo... e digitare il nome del gruppo di risorse creato per questo articolo. Nell’elenco dei risultati selezionare il gruppo di risorse.

   

3. Selezionare Elimina gruppo di risorse.

4. Verrà chiesto di confermare l'eliminazione del gruppo di risorse. Digitare il nome del gruppo di risorse per confermare e quindi selezionare Elimina.

   

Dopo qualche istante, il gruppo di risorse e tutte le risorse che contiene vengono eliminati.

Contenuti correlati

• Informazioni sugli embeddings vettoriali e la ricerca vettoriale in Azure Managed Redis
• Usa moduli Redis con Azure Managed Redis
• Guida RedisVL SemanticRouter
• Concetti di ricerca vettoriale di Redis
• Quickstart: Crea un'istanza Azure Managed Redis