API Gateway：緩衝

語義化緩衝關鍵概念說明

為協助您更好理解語義化緩衝機制，以下為關鍵概念的說明：

功能優勢

• 雙模緩衝體系：根據業務需求靈活選擇兩種緩衝並動態調整匹配閾值。

  1. 精確緩衝：基於Redis的Key-Value儲存架構，對完全相同的請求實現毫秒級響應。

  2. 語義緩衝：通過DashVector向量資料庫（阿里雲向量檢索服務），對語義相近請求進行智能匹配（相似性閾值可調），突破傳統字串匹配局限。

• 減少重複計算：對於相同的AI請求，直接返回緩衝中的響應資料，避免重複調用大語言模型。

• 效能提升維度：通過快速從緩衝中擷取結果，顯著降低回應時間以及後端伺服器的負載壓力。通過語義緩衝可以實現"意圖級"響應，顯著提升使用者的滿意度和體驗。

• 情境覆蓋擴充：適配客服系統、知識庫查詢等標準情境，支援自然語言指令的變體處理（如"明天天氣""未來24小時氣象預報"）。

• 日誌監控：提供快取命中率指標分析。

操作步驟

1. 開啟AI網關控制台實例頁面，在頂部功能表列選擇目標執行個體所在地區，並單擊目標執行個體ID。

2. 在左側導覽列，單擊Model API，然後單擊目標API名称進入API详情頁面。

3. 單擊策略与插件，開啟緩存開關並配置相關參數。

   AI 網關已全面升級緩衝能力，支援语义化缓存和精确缓存，您需要根據策略對比選擇適合的緩衝方式。

   語義化緩衝

   重要

   攜帶要求標頭x-higress-skip-ai-cache: on時，當前請求將不會使用緩衝中的內容，而是直接轉寄給後端服務，同時也不會緩衝該請求返迴響應的內容。

   • 缓存键生成策略：選擇控制台預設的只取最新提问，或根據需要選擇整合历史提问。

   • 文本向量化配置：

     • AI 服务：選擇您建立好的AI 服務。若沒有AI 服務，單擊建立服務，建立一個新的AI 服務。

     • 模型名称：選擇您計劃使用的模型名稱。

     • 超时时间：設定逾時時間，預設5000ms。

   • 向量資料庫配置：

     • 服务提供者类型：若之前沒有開通向量檢索服務Dashvector，單擊前往控制台，跳轉至向量檢索服務的服務開通頁面進行開通。具體流程為：，記錄Collection名稱用於後續參數設定。

       重要

       建立Collection時距離度量方式選擇Cosine，向量維度要與文本向量化模型的維度對應。文本與多模態向量化可以查看到百鍊平台文本向量化模型的輸出向量維度。

     • 服务地址：輸入您的Dashvector服務地址。

     • Collection名稱：輸入您建立好的Collection的名稱。

     • API Key：訪問憑證。可以參考API-KEY管理。

     • 向量相似度阈值：該值決定系統對查詢和緩衝內容的匹配的嚴格程度。取值範圍為（0,1），建議您取值為0.8或者0.9，較大的值表示更大的語義相似性。詳細資料，請參考向量相似性閾值配置指南。

     • 超时时间：設定逾時時間，預設3000ms。

   精確緩衝

   重要

   • 請前往Redis控制台添加白名單。在Redis控制台中，您需要將網關執行個體的VPC網段添加至白名單。

   • 攜帶要求標頭x-higress-skip-ai-cache: on時，當前請求將不會使用緩衝中的內容，而是直接轉寄給後端服務，同時也不會緩衝該請求返迴響應的內容。

   • 缓存键生成策略：選擇控制台預設的只取最新提问，或根據需要選擇整合历史提问。

   • Redis緩衝配置：

     • Redis服务地址：輸入您的Redis服務地址。

     • 端口号：輸入您的連接埠號碼。

     • 访问方式：選擇Redis服務訪問方式，支援帳號+密碼登入、密碼登入、免密登入三種方式。

     • 数据库账号：若選擇帳號+密碼登入的訪問方式，需要您輸入資料庫帳號。

     • 数据库密码：若選擇帳號+密碼登入或密碼登入的訪問方式，需要您輸入資料庫密碼。

     • 数据库编号：指定的資料庫編號。

     • 缓存时长（秒)：緩衝時間長度預設為1800秒，在緩衝時間長度內，如果API接收到相同的AI請求，則會跳過LLM請求，直接返回緩衝的響應資料。

4. 確認配置資訊並單擊保存。

向量相似性閾值配置指南

快取命中率

快取命中率查詢條件（目前支援的查詢粒度為網關層級），以下是查詢範例程式碼：

cluster_id:{your-gatewayId} and inner-ai-cache-{your-gatewayId} | SELECT 
SUM(CASE WHEN content LIKE '%cache hit for key%' OR content LIKE '%key accepted%' THEN 1 ELSE 0 END) AS hit_count,
SUM(CASE WHEN content LIKE '%cache miss for key%' OR content LIKE '%score not meet the threshold%' THEN 1 ELSE 0 END) AS miss_count,
SUM(CASE WHEN content LIKE '%cache hit for key%' OR content LIKE '%key accepted%' THEN 1 ELSE 0 END) * 100.0 / 
NULLIF(SUM(CASE WHEN content LIKE '%cache hit for key%' OR content LIKE '%key accepted%' OR content LIKE '%cache miss for key%' 
           OR content LIKE '%score not meet the threshold%' THEN 1 ELSE 0 END), 0) AS hit_rate

• {your-gatewayId}替換為您的網關執行個體ID，注意前一處替換需要保留gw-首碼，後一處替換不用保留。從緩衝開關按鈕處進入外掛程式日誌查詢日誌系統查詢方塊內會內建cluster_id限制，此時只需將後續的查詢語句粘貼到其後即可。在監控（AI 緩衝）頁面中，單擊查看日誌進入日誌查詢介面，日誌源為 apig-plugin-log，將上述查詢語句輸入查詢欄並執行。

• 快取命中率查詢效果。

  查詢結果顯示：hit_count（快取命中次數）為 7，miss_count（緩衝未叫用次數）為 6，hit_rate（命中率）約為 53.85%。

效果展示

• 當開啟精確緩衝時，只匹配完全相同的查詢：在策略對比中，當使用者發送相同語義的查詢（如"你是誰"）時，若未命中緩衝，模型正常消耗 token（輸入 tokens: 127，輸出 tokens: 40）；若命中精確緩衝（from-cache），則輸入 tokens 和輸出 tokens 均為 0，直接返回緩衝結果，有效降低 token 消耗。

• 當開啟語義化緩衝時，語義相似的查詢也可以匹配，語義相似性低於閾值則不匹配：

  語義快取命中時，相似問題直接複用緩衝中的回複，輸入和輸出 tokens 均為 0，不消耗模型推理資源。

  例如，使用者提問我的快遞今天能送到哪裡？時，該問題與已緩衝的問題語義差異較大，緩衝未命中，模型 qwen-max 正常產生回複並消耗 tokens。