教學：依據 Azure Managed Redis 的語意相似度路由 AI 請求

語意路由透過將請求與每條路由的代表範例進行比較，將自然語言請求傳送給正確的處理者、模型、工具、提示或工作流程。 在這個教學中，你會用 RedisVL 和 Azure Managed Redis 實作語意路由作為應用程式模式。 語意路由並不是 Azure Managed Redis 獨立的管理功能。 它使用 Redis 向量搜尋和應用程式程式碼。

Redis中的向量搜尋需要RediSearch，且可在Azure管理Redis中找到，詳見Azure管理的Redis向量搜尋總覽。 在建立 Azure Managed Redis 實例時，必須啟用包括 RediSearch 在內的 Redis 模組。 關於支援的層級與政策，請參閱使用 Redis 模組與 Azure Managed Redis及 RediSearch 需求。

RedisVL 提供一個 SemanticRouter 介面，利用 Redis 搜尋來對一組 Route 參考進行請求分類。 對於底層向量模型，Redis 將向量與元資料儲存在雜湊值或 JSON 物件中，並透過向量場、距離指標及 KNN 或範圍查詢來搜尋。 欲了解更多資訊，請參閱 RedisVL SemanticRouter 指南 及 Redis 向量搜尋概念。

在這個教學中，你會學到如何：

• 定義命名的語意路徑，並附上具代表性的參考資料。
• 建立一個由 Azure Managed Redis 支援的 RedisVL 語義路由器。
• 將請求轉送至一個或多個相符的路由。
• 處理失誤和模糊的比賽。
• 調整閾值並在生產環境中操作語意路由。
• 將語意路由應用於常見的 AI 應用模式。

Prerequisites

• Azure 訂用帳戶。 如果您沒有 Azure 訂閱，請建立免費帳戶。
• 一個在建立時啟用 RediSearch 的 Azure Managed Redis 實例。 RediSearch 是 Redis 模組，能在 Azure 管理的 Redis 中啟用向量搜尋功能，且在建立實例時必須選擇模組。 請檢視 Use Redis 模組與 Azure Managed Redis 中的支援模組矩陣及 RediSearch 政策要求。
• 一個 連接字串 或 Redis URL 用於你的 Azure Managed Redis 實例。 使用 TLS 以及你應用程式核准的認證方式。
• 一個可以安裝 RedisVL 及你選擇嵌入模型相依關係的 Python 環境。
• 嵌入或向量化策略。 本教學以 RedisVL HFTextVectorizer 為簡明範例。 在路由器索引中，每個路由參考和每個收到的請求都使用相同的嵌入模型，這樣向量尺寸和距離指標才能保持一致。 Redis 向量索引需要為向量欄位設定固定的 DIM 和 DISTANCE_METRIC。 更多資訊請參閱 Redis 向量搜尋概念。

安裝 RedisVL：

pip install redisvl

設計你的路線

路由代表應用程式的決策，例如提示範本、工具、模型或工作流程。 每條路線包含：

• 你的應用程式對應至處理常式的穩定 name。
• references，這些語句是該路徑的代表性語句。
• 選填的 metadata，例如處理常式 ID、提示版本、模型偏好設定或擁有者資訊。
• 每條路線 distance_threshold。 在 RedisVL 中，路由閾值使用 Redis COSINE 距離單位，較低的值則需要更嚴格的匹配。 門檻因模型而異，應以您自己的請求進行驗證。

例如，AI 助理可能會使用以下路徑：

路由	目的地範例	代表性參考資料
billing	計費工作流程或提示	「更新我的發票」、「為什麼我被收了兩次費用？」
technical_support	支援分流工具	「我的快取逾時了」、「幫我偵錯連線錯誤」
sales	銷售工作流程	「比較方案」、「與業務討論價格」

選擇能涵蓋路由語意表面積且不與其他路徑重疊的參考。 請使用來自實際流量、客服工單或經過整理的評估資料的範例。 避免使用過於籠統的引用，例如「幫助」或「問題」，因為它們可能會對應多條路徑。

建立語意路由器

在環境變數中設定你的 Redis URL。 具體的網址格式取決於你的認證方式和客戶端設定。 連接 TLS 時請使用 rediss:// 網址。

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

初始化後，RedisVL 會建立並填充 Redis 搜尋索引以取得路由參考。 Redis 在索引中使用向量場和元資料欄位來對嵌入的參考進行相似性搜尋。 關於路由器初始化與路由欄位的詳細資訊，請參閱 RedisVL SemanticRouter 指南。 關於 Redis 向量索引的詳細資訊，請參見 Redis 向量搜尋概念。

Tip

每個環境使用不同的路由器名稱或 Redis 鍵前綴。 如果不同租戶需要不同的路由集，可以用獨立的路由器索引或嚴格的租戶專屬金鑰命名來隔離，這樣一個租戶的參考資料就不會影響另一個租戶的路由結果。

為請求設定路由

呼叫路由器會回傳最佳路由匹配。 若無路由足夠接近以滿足其閾值，RedisVL 會回傳類似 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)

將 distance 視為相似度距離，而不是機率。 以 Redis COSINE 距離來說，較低的數值代表匹配度較近。 將匹配的路線、距離、閾值及所選目的地儲存在您的應用程式遙測中。

處理失誤與模糊匹配

語意路由器需要在沒有路由匹配或多條路由可能存在時，具備確定性行為。

對於未命中：

• 引導至備用工作流程，例如一般助理提示、關鍵字路由器、表單或人工交接。
• 當使用者意圖不完整時，提出澄清性問題。
• 請將申請離線審查記錄下來。 這可能會揭露缺失的路線或缺失的參考。

對於可能的多路線匹配，請使用 route_many() 來檢查候選路線與距離：

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)

如果兩條路徑都有效，則選擇確定性規則，例如最低距離、明確優先順序的元資料，或是澄清性問題。 避免在最高距離接近且行動對業務或安全有影響時默默選擇路線。

更新與序列化路由器設定

將路由定義視為應用程式設定。 RedisVL 支援將路由器設定序列化成字典或 YAML，之後還原。 利用此功能檢視路由變更、跨環境推廣，並保持路由定義與提示詞及工具版本一致。 例如，你可以將路由設定與應用程式部署工件一起儲存，並在啟動時重新建立路由器。

RedisVL 也支援動態新增、列出及刪除路由參考。 請謹慎使用動態更新：驗證新的參照項目、追蹤是誰變更了這些項目，並在將其推送至正式環境前測試對路由的影響。

用評估集調整閾值

門檻決定路由何時會符合條件。 由於 RedisVL 路由 distance_threshold 值使用 Redis COSINE 距離單位，較低的門檻會更嚴格。 正確的數值取決於你的嵌入模型、語言、參考資料和請求分布。

請使用此調整流程：

1. 收集每條路線的標註範例，以及不應該符合任何路線的負面範例。
2. 將範例拆分為調校組和驗證組。
3. 獨立評估每條路由，並測量假接受、假拒絕及模糊匹配。
4. 一開始就對高影響動作採用較嚴格的門檻，只有在驗證資料支持這麼做時才放寬。
5. 每當你更改嵌入模型、參考資料或路由分類法時，請重新評估閾值。

不要比較不同嵌入模型的路由器之間的距離值。 Redis 向量索引需要查詢向量以匹配向量場的維度，模型變更通常需要重建或設定路由器索引的版本。 更多資訊請參閱 Redis 向量搜尋概念。

了解距離、門檻與優先順序

路由距離是輸入請求嵌入與路由參考嵌入之間的相似距離。 以 RedisVL 語意路由器 COSINE 的距離指標來說，值越小表示請求越接近路由參考。 路由器只有在最終距離在該路由 範圍內時才會接受該路由 distance_threshold。

避免將路線距離視為信心百分比。 0.35 的距離並不表示有 35% 的信心，而適用於某個嵌入模型的門檻，可能不適用於另一個模型。 使用距離作為排名和接受信號，並用標示的範例來校準。

RedisVL 路由沒有獨立的語意權重設定。 改用以下這些路由槓桿：

槓桿	何時使用它	Effect
下層 distance_threshold	這條路線會觸發昂貴、敏感或不可逆的行動。	虛假接受較少，但後備要求或澄清的請求較多。
較高 distance_threshold	該路線風險低、寬廣，或能安全沿下游恢復。	符合的項目更多，但無關請求進入此路由的風險也更高。
更好的參考資料	路線過窄、過寬，或與其他路線混淆。	透過改變路線所代表的範圍來移動路由邊界。
聚合方法	一條路線包含多個參照，只要有一個參照符合即可比對成功。	min 可以偏好最接近的參考;平均型聚合偏好參考點一致接近的路線。
應用程式優先權元資料	兩條在語意上都成立的路徑彼此非常接近，而你的業務邏輯需要一個判定依據。	讓應用程式選擇一個確定性的贏家，而不必假裝路線語意上更接近。

對於存取帳號資料、呼叫工具、變更狀態或升級至人工的路由，請選擇更嚴格的門檻。 當下游提示仍可進一步提出澄清問題時，對於 FAQ 選擇、文件搜尋或模型選擇等低風險路由，請選用較寬鬆的門檻。 如果前兩條路線距離相近，建議採用澄清步驟或確定性優先規則，而非默默選擇高影響力行動。

在現實世界的 AI 模式中使用語意路由

語意路由在 AI 應用程式需要快速且可解釋的決策後，在呼叫模型、提示、工具或工作流程前非常有用。 常見的模式包括：

Pattern	語意路由如何發揮作用
模型路由	將簡單請求傳送到較小或成本較低的模型，較大的模型則保留給複雜的推理、編碼或安全敏感任務。
提示路由	請選擇適合的系統提示或提示範本，用於帳單、支援、銷售、故障排除或政策相關問題。
刀具路徑	選擇代理程式是否應呼叫搜尋、票務、診斷、帳務、CRM，或完全不使用任何工具。
RAG 路由	在執行向量搜尋前，請選擇正確的檢索索引、知識庫、租戶語料庫或產品文件集。
人工切換路由	當語意與敏感工作流程相符時，將請求導向專業佇列、升級路徑或人工審核。
安全與政策路由	偵測需要更嚴格護欄、限制提示、審計追蹤或拒絕工作流程的請求，然後再呼叫主助理。

在生產環境中操作語意路由

在生產工作負載中運用以下做法：

• 保持路線分明。 將重疊路線拆分或重新命名。 合併那些經常產生模糊匹配的路線。
• 偏好精選的參考資料。 新增代表性語句，映射到一條路徑。 移除吸引無關流量的參考資料。
• 有意識地採用後援機制。 在應用程式邏輯中實作後備機制。 廣泛的備援路徑可以捕捉本應錯過的請求。
• 版本路由設定。 包含提示詞、工具、模型及路由版本的元資料。 像其他應用程式設定變更一樣回滾路由變更。
• 觀察路由品質。 追蹤路線命中率、未命中率、頂線路徑、距離、閾值、模糊匹配數、備用率及下游成功指標。 按路線檢視距離與信心分組分布。
• 在需要時分開租戶。 當租戶有不同的路由集或嚴格的資料隔離要求時，請使用隔離路由器、金鑰前綴或 Redis 實例。
• 保護敏感的元資料。 不要將機密資訊儲存在路由中繼資料或參照內。 將路由範例視為應用程式資料。
• 規劃容量。 路由參考會嵌入並索引於 Redis 中。 保持路由集緊湊且具代表性，並隨著參考增加，監控記憶體、延遲與索引大小。

清理資源

如果您想要繼續使用在本文中建立的資源，請保留該資源群組。

否則，若已完成資源使用，則可刪除您建立的 Azure 資源群組，以避免衍生費用。

Important

刪除資源群組是無法回復的動作。 當您刪除資源群組時，其中包含的所有資源都將永久刪除。 請確定您不會不小心刪除錯誤的資源群組或資源。 如果您是在包含需保留資源的現有資源群組內部建立資源，則可以個別刪除每個資源，而不必刪除整個資源群組。

刪除資源群組

1. 登入 Azure 入口網站，然後選擇 Resource Groups。

2. 選取您想要刪除的資源群組。

   如果有許多資源群組，請使用 [篩選任何欄位] 方塊，並輸入您針對本文所建立資源群組的名稱。 選取結果清單中的資源群組。

   

3. 選擇 刪除資源群組。

4. 系統將會要求您確認是否刪除資源群組。 輸入您的資源群組名稱以進行確認，然後選取 [刪除]。

   

不久後，系統便會刪除該資源群組及其所有的資源。

相關內容

• 關於 Azure Managed Redis 中的向量嵌入與向量搜尋
• 使用 Redis 模組搭配 Azure Managed Redis。
• RedisVL SemanticRouter 指南
• Redis 向量搜尋概念
• 快速入門：建立 Azure 受控 Redis 執行個體