Tutorial: Encaminhar pedidos de IA por similaridade semântica com o Azure Managed Redis

O encaminhamento semântico envia um pedido em linguagem natural para o handler, modelo, ferramenta, prompt ou fluxo de trabalho certo, comparando o pedido com exemplos representativos para cada rota. Neste tutorial, implementas o encaminhamento semântico como um padrão de aplicação com o RedisVL e o Azure Managed Redis. O encaminhamento semântico não é uma funcionalidade gerida separada do Azure Managed Redis. Utiliza pesquisa vetorial Redis e código de aplicação.

A pesquisa vetorial no Redis requer RediSearch e está disponível no Azure Managed Redis, conforme descrito na visão geral da pesquisa vetorial do Azure Managed Redis. Os módulos do Redis, incluindo o RediSearch, devem estar ativados quando cria a instância do Azure Managed Readis. Para níveis e políticas suportados, consulte Usar módulos Redis com requisitos de Azure Managed Redis e RediSearch.

O RedisVL fornece uma SemanticRouter interface que utiliza a pesquisa Redis para classificar um pedido contra um conjunto de Route referências. Para o modelo vetorial subjacente, o Redis armazena vetores e metadados em hashes ou objetos JSON e pesquisa-os com campos vetoriais, métricas de distância e KNN ou consultas por intervalo. Para mais informações, consulte o guia RedisVL SemanticRouter e os conceitos de pesquisa vetorial do RedisVL.

Neste tutorial, aprenderás como:

• Defina rotas semânticas nomeadas com referências representativas.
• Crie um router semântico RedisVL suportado pelo Azure Managed Redis.
• Encaminhe as solicitações para uma ou mais rotas correspondentes.
• Lidar com falhas e correspondências ambíguas.
• Ajuste os limiares e utilize o encaminhamento semântico em produção.
• Aplicar o encaminhamento semântico a padrões comuns de aplicações de IA.

Pré-requisitos

• Uma assinatura do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita.
• Uma instância Azure Managed Redis com RediSearch ativado na criação. O RediSearch é o módulo Redis que permite a pesquisa vetorial no Azure Managed Redis, e os módulos devem ser selecionados quando a instância é criada. Revise a matriz de módulos suportada e os requisitos da política RediSearch em Use Redis modules with Azure Managed Redis.
• Uma cadeia de ligação ou um URL do Redis para a sua instância do Azure Managed Redis. Use o TLS e o método de autenticação aprovado da sua aplicação.
• Um ambiente Python que possa instalar o RedisVL e as dependências do modelo de embedding escolhido.
• Uma estratégia de incorporação ou de vetorização. Este tutorial usa o RedisVL HFTextVectorizer como exemplo conciso. Use o mesmo modelo de embedding para cada referência de rota e cada pedido recebido num índice de router para que as dimensões vetoriais e métricas de distância permaneçam alinhadas. Os índices vetoriais do Redis exigem um DIM e um DISTANCE_METRIC fixos para o campo vetorial. Para mais informações, consulte conceitos de pesquisa vetorial de Redis.

Instalar RedisVL:

pip install redisvl

Desenhe as suas rotas

Uma via representa uma decisão da aplicação, como um modelo de prompt, uma ferramenta, um modelo ou um fluxo de trabalho. Cada rota inclui:

• Um stable name que a tua aplicação mapeia para um handler.
• references, que são enunciados representativos para essa rota.
• Opcionais metadata, como IDs de handler, versões de prompt, preferências de modelos ou informações do proprietário.
• Uma por rota distance_threshold. No RedisVL, os limiares de rota utilizam unidades de distância Redis COSINE onde valores mais baixos exigem correspondências mais rigorosas. Os limiares são específicos de cada modelo e devem ser validados com as suas próprias solicitações.

Por exemplo, um assistente de IA pode usar estas rotas:

Percurso	Exemplo de destino	Referências representativas
billing	Fluxo de trabalho de faturação ou prompt	"atualiza a minha fatura", "porque é que me cobraram duas vezes?"
technical_support	Ferramenta de triagem do suporte	"A minha cache está a expirar", "ajuda-me a depurar erros de ligação"
sales	Fluxo de trabalho de vendas	"Comparar planos", "Contactar a equipa de vendas sobre preços"

Escolha referências que cubram a área semântica da rota sem sobrepor outras rotas. Use exemplos de tráfego real, tickets de suporte ou dados de avaliação selecionados. Evite referências demasiado genéricas, como "ajuda" ou "pergunta", porque podem corresponder a várias rotas.

Crie um router semântico

Defina o seu URL Redis numa variável de ambiente. O formato exato do URL depende do seu método de autenticação e da configuração do cliente. Use uma rediss:// URL ao ligar com o 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 inicializado, o RedisVL cria e preenche um índice de pesquisa Redis para as referências de rota. O Redis utiliza campos vetoriais e campos de metadados no índice para realizar pesquisa de similaridade sobre as referências incorporadas. Para detalhes sobre inicialização do router e campos de rota, consulte o guia RedisVL SemanticRouter. Para detalhes sobre índices vetoriais de Redis, veja conceitos de pesquisa vetorial de Redis.

Sugestão

Use um nome de router separado ou um prefixo de chave Redis por ambiente. Se diferentes inquilinos precisarem de conjuntos de rotas diferentes, isole-os com índices de router separados ou nomeação estrita de chaves específicas para cada inquilino, para que as referências de um inquilino não afetem os resultados de roteamento de outro.

Encaminhar uma solicitação

Ligar para o router devolve a melhor correspondência da rota. Se nenhuma rota estiver suficientemente próxima para cumprir o respetivo limiar, o RedisVL devolve uma falha semelhante 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)

Trate distance como uma distância de semelhança, não como uma probabilidade. Com a distância Redis COSINE, valores mais baixos correspondem a resultados mais semelhantes. Armazene a rota, distância, limiar e destino selecionado correspondentes na telemetria da sua aplicação.

Falhas de handle e partidas ambíguas

Os routers semânticos precisam de um comportamento determinístico quando nenhuma rota corresponde ou quando várias rotas são plausíveis.

Para falhas:

• Encaminhe para um fluxo de trabalho de contingência, como um prompt de um assistente geral, encaminhamento por palavras‑chave, formulário ou transferência para um operador humano.
• Faça uma pergunta esclarecedora quando a intenção do utilizador estiver incompleta.
• Regista o pedido de revisão offline. Pode revelar uma rota em falta ou uma referência em falta.

Para possíveis correspondências de vários percursos, use route_many() para inspecionar os percursos candidatos e as respetivas distâncias:

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 duas rotas forem ambas válidas, escolha uma regra determinística, como a distância mais baixa, metadados de prioridade explícita ou uma questão clarificadora. Evite selecionar silenciosamente uma rota quando as distâncias superiores são próximas e a ação tem impacto no negócio ou na segurança.

Atualizar e serializar a configuração do router

Gerir definições de rotas como configuração da aplicação. O RedisVL suporta serializar uma configuração de router para um dicionário ou YAML e restaurá-la posteriormente. Use esta funcionalidade para rever alterações de rota, promovê-las entre ambientes e manter as definições de rota alinhadas com as versões dos prompts e das ferramentas. Por exemplo, pode armazenar a configuração de rotas com os artefactos de implementação da sua aplicação e recriar o router durante o arranque.

O RedisVL também suporta a adição, listagem e eliminação dinâmica de referências de rota. Utilize as atualizações dinâmicas com cuidado: valide novas referências, registe quem as alterou e teste o impacto do encaminhamento antes de as promover para produção.

Ajustar os limiares com um conjunto de avaliação

Os limites determinam quando uma rota coincide. Como os valores de rota distance_threshold RedisVL usam unidades de distância RedisVL COSINE , os limiares mais baixos são mais rigorosos. O valor correto depende do seu modelo de embedding, linguagem, referências e distribuição de pedidos.

Use este processo de afinação:

1. Recolhe exemplos rotulados para cada rota e exemplos negativos que não devam corresponder a nenhuma rota.
2. Divide os exemplos em conjuntos de afinação e validação.
3. Avalie cada rota de forma independente e meça falsas aceitações, falsas rejeições e correspondências ambíguas.
4. Comece com limiares mais rigorosos para ações de alto impacto e relaxe-os apenas quando os dados de validação o apoiarem.
5. Reavalie os limiares sempre que mudar o modelo de embedding, referências ou taxonomia de rotas.

Não compare valores de distância entre routers que usam modelos de embedding diferentes. Os índices vetoriais Redis requerem que vetores de consulta correspondam às dimensões do campo vetorial, e as alterações no modelo normalmente exigem reconstrução ou versionamento do índice do router. Para mais informações, consulte conceitos de pesquisa vetorial de Redis.

Compreender a distância, os limiares e as prioridades

A distância da rota é a distância de similaridade entre a representação vetorial da solicitação recebida e as representações vetoriais de referência da rota. Com a métrica de distância semântica do COSINE router RedisVL, um valor menor significa que o pedido está mais próximo de uma referência de rota. O router só aceita uma rota quando a distância resultante está dentro do distance_threshold dessa rota.

Evite tratar a distância da rota como uma percentagem de confiança. Uma distância de 0.35 não significa 35% de confiança, e um limiar que funcione para um modelo de embedding pode não funcionar para outro. Utilize as distâncias como sinais de classificação e de aceitação, calibrando-as com exemplos anotados.

As rotas RedisVL não têm uma definição separada de peso semântico. Use estas alavancas de roteamento em vez disso:

Alavanca	Quando utilizá-lo	Effect
Inferior distance_threshold	A rota desencadeia uma ação dispendiosa, sensível ou irreversível.	Menos falsas aceitações, mas mais pedidos de recuo ou esclarecimento.
Mais alto distance_threshold	A rota é de baixo risco, larga ou pode ser recuperada em segurança a jusante.	Mais correspondências, mas maior risco de pedidos não relacionados entrarem na rota.
Melhores referências	O percurso é demasiado estreito, demasiado largo ou confundido com outro percurso.	Move o limite da rota alterando o que a rota representa.
Método de agregação	Uma rota tem várias referências e uma referência deve ser suficiente para corresponder.	min pode favorecer a referência mais próxima; a agregação por média favorece rotas cujas referências se mantêm consistentemente próximas.
Metadados de prioridade da aplicação	Duas rotas semanticamente válidas estão próximas e a lógica do teu negócio precisa de um critério de desempate.	Permite à aplicação escolher um vencedor determinístico sem fingir que a rota é semanticamente mais próxima.

Escolha limiares mais rigorosos para rotas que acedam a dados da conta, liguem a ferramentas, alterem estado ou escalem para humanos. Escolha limites mais permissivos para rotas de baixo risco, como seleção de FAQ, pesquisa na documentação ou escolha do modelo, quando o prompt subsequente ainda puder fazer uma pergunta de esclarecimento. Se as duas principais distâncias de rota forem próximas, prefira um passo de clarificação ou uma regra de prioridade determinística em vez de escolher silenciosamente uma ação de alto impacto.

Usar o encaminhamento semântico em padrões de IA do mundo real

O encaminhamento semântico é útil sempre que uma aplicação de IA precisa de uma decisão rápida e explicável antes de chamar um modelo, prompt, ferramenta ou fluxo de trabalho. Os padrões comuns incluem:

Pattern	Como ajuda o encaminhamento semântico
Roteamento de modelos	Envie pedidos simples para um modelo mais pequeno ou de menor custo, e reserve modelos maiores para raciocínio complexo, programação ou tarefas sensíveis à segurança.
Encaminhamento rápido	Selecione o system prompt ou o modelo de prompt adequados para perguntas sobre faturação, suporte, vendas, resolução de problemas ou políticas da empresa.
Roteamento de ferramentas	Escolha se o agente deve chamar a pesquisa, a gestão de tickets, os diagnósticos, a faturação, o CRM ou não chamar nenhuma ferramenta.
Roteamento RAG	Escolha o índice de recuperação, a base de conhecimento, o tenant corpus ou o conjunto de documentação do produto antes de executar a pesquisa vetorial.
Encaminhamento para operador humano	Encaminhe pedidos para filas especializadas, caminhos de escalonamento ou revisão humana quando a intenção semântica corresponde a fluxos de trabalho sensíveis.
Segurança e encaminhamento de políticas	Identificar pedidos que necessitem de um mecanismo de controlo mais rigoroso, de uma instrução restrita, de um registo de auditoria ou de um fluxo de recusa antes de invocar o assistente principal.

Gerir o encaminhamento semântico em produção

Utilize estas práticas para as cargas de trabalho em produção:

• Mantenha as rotas distintas. Dividir ou renomear rotas sobrepostas. Mesclar rotas que produzem, de forma consistente, correspondências ambíguas.
• Prefiro referências selecionadas. Adicione enunciados representativos que correspondam a uma rota. Remove referências que atraem tráfego não relacionado.
• Utilize a alternativa deliberadamente. Implemente uma alternativa na lógica da aplicação. Uma via de recuo ampla pode captar pedidos que deveriam ter sido falhados.
• Configuração da rota da versão. Inclua metadados do pedido, da ferramenta, do modelo e da versão da rota. Reverta as alterações de rotas tal como outras alterações de configuração da aplicação.
• Monitorize a qualidade do encaminhamento. Acompanhe a taxa de acerto da rota, a taxa de não correspondência, a rota principal, a distância, o limiar, o número de correspondências ambíguas, a taxa de recurso e as métricas de sucesso subsequentes. Analise as distribuições de distância e de intervalos de confiança por rota.
• Separe os inquilinos quando necessário. Utilize routers isolados, prefixos de chave ou instâncias Redis quando os locatários tiverem conjuntos de rotas diferentes ou requisitos rigorosos de isolamento de dados.
• Proteger metadados sensíveis. Não guarde segredos em metadados de rota ou referências. Trate exemplos de rotas como dados de aplicação.
• Planeje a capacidade. As referências de rota estão incorporadas e indexadas no Redis. Mantenha os conjuntos de rotas compactos e representativos, e monitorize a memória, latência e tamanho do índice à medida que as referências aumentam.

Limpeza de recursos

Se quiser continuar a usar os recursos criados neste artigo, mantenha o grupo de recursos.

Caso contrário, se tiver terminado os recursos, pode eliminar o grupo de recursos do Azure que criou para evitar cobranças.

Importante

A eliminação de um grupo de recursos é irreversível. Quando elimina um grupo de recursos, todos os recursos nele contidos são eliminados permanentemente. Certifique-se de que não elimina acidentalmente grupos de recursos ou recursos errados. Se você criou os recursos dentro de um grupo de recursos existente que contém recursos que deseja manter, poderá excluir cada recurso individualmente em vez de excluir o grupo de recursos.

Para eliminar um grupo de recursos

1. Inicie sessão no Portal do Azure e selecione Grupos de recursos.

2. Selecione o grupo de recursos que pretende eliminar.

   Se houver muitos grupos de recursos, use a caixa Filtrar para qualquer campo... , digite o nome do grupo de recursos criado para este artigo. Selecione o grupo de recursos na lista de resultados.

   

3. Selecione Eliminar grupo de recursos.

4. É-lhe pedido que confirme a eliminação do grupo de recursos. Escreva o nome do grupo de recursos para confirmar e, em seguida, selecione Eliminar.

   

Após alguns instantes, o grupo de recursos e todos os respetivos recursos são eliminados.

Conteúdo relacionado

• Sobre representações vetoriais e pesquisa vetorial no Azure Managed Redis
• Utilize módulos do Redis com o Azure Managed Redis
• Guia do RedisVL SemanticRouter
• Conceitos de pesquisa vetorial Redis
• Quickstart: Criar uma instância Azure Managed Redis