云数据库 Tair（兼容 Redis®）：语义缓存实例开通说明

前提条件

• 已注册阿里云账号并完成实名认证。

• 目标地域已有专有网络（VPC）和交换机。若没有，请先创建专有网络。

步骤一：创建 Tair 实例

语义缓存需要一个 Tair 实例作为存储后端。如果您已有 Tair 内存版集群实例（代理模式），也可跳过本步骤。

进入 Tair 控制台 - 实例列表，单击创建实例，注意以下参数的选择：

步骤二：创建语义缓存网关实例

1. 登录 Tair 语义缓存控制台，单击创建实例。

2. 配置以下参数：

   参数	建议值	说明
   计费方式	按量付费	公测期间免费
   地域和可用区设置	与 Tair 实例相同	必须在同一地域和可用区
   专有网络 / 虚拟交换机	与 Tair 实例相同	网关需要通过内网访问 Tair
   规格	公测节点	公测免费规格

   说明

   语义缓存能力是语义缓存网关实例的插件功能，可以在网关实例开通之后，单击实例ID进入实例详情页- 插件管理页面开通。若不开通语义缓存插件，则只享受模型服务能力。

3. 单击立即购买。

步骤三：配置语义缓存插件

1. 单击实例ID进入语义缓存网关实例详情页。

2. 单击插件管理 > 新增插件，根据您的场景选择一种模式。首次体验建议选择 OpenAI兼容模式。

配置完成后，单击确定，等待语义缓存插件创建（约 30 秒内）。

步骤四：获取接入信息和设置白名单

1. 在 Tair 语义缓存网关实例详情页中，进入实例信息页面，在网络访问（Endpoint/BaseURL）区域，获取到服务地址：

   信息	用途	格式示例
   专有网络	用于在相同 VPC 环境下，替换 OpenAI SDK 中的 base_url。	https://<您的服务地址>/compatible-mode/v1
   公网访问	用于在公网访问中，替换 OpenAI SDK 中的 base_url。默认关闭状态，若需要公网访问，则需要单击公网访问右侧申请按钮。	https://<您的服务地址>/compatible-mode/v1

   说明

   使用公网访问的时候，需要配合 IP 白名单使用，避免无法访问的情况出现。

2. 在 Tair 语义缓存网关实例详情页中，进入 API Key 页面，可以创建、管理、查看自己的 API Key。

步骤五：验证效果

1. 验证 OpenAI 模型服务是否生效（不包含语义缓存插件）。

   curl https://<您的服务地址>/compatible-mode/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <你的apikey>" \
     -d '{
       "model": "qwen3.7-plus",
       "messages": [{"role": "user", "content": "你好"}],
       "stream": true,
       "enable_thinking": false
     }'

2. 验证语义缓存插件是否生效。

   通过以下代码验证语义缓存插件已生效。核心验证逻辑：发送两个语义相似的问题，第二次应该显著更快（缓存命中）。

   说明

   因为下面示例代码未配置流式输出，所以第一次响应结果可能较慢，需要耐心等待。个人使用的场景中，可自行选择流式配置。

import time
from openai import OpenAI

client = OpenAI(
    base_url="https://<您的服务地址>/compatible-mode/v1",  # 替换为实际地址
    api_key="<您的 API Key>"                             # 替换为实际 Key
)

# 第一次请求：缓存未命中，调用 LLM（较慢）
start = time.time()
resp1 = client.chat.completions.create(
    model="qwen3.6-plus",
    messages=[{"role": "user", "content": "什么是语义缓存？"}]
)
print(f"首次请求耗时: {time.time() - start:.2f}s")
print(f"回答: {resp1.choices[0].message.content[:100]}")

# 第二次请求：语义相似的问题，预期缓存命中
start = time.time()
resp2 = client.chat.completions.create(
    model="qwen3.6-plus",
    messages=[{"role": "user", "content": "语义缓存是什么意思？"}]  # 语义相似
)
print(f"\n相似问题耗时: {time.time() - start:.2f}s") 
print(f"回答: {resp2.choices[0].message.content[:100]}")

首次请求耗时: 41.67s
回答: **语义缓存（Semantic Caching）**是一种基于查询“含义”而非“字面完全匹配”的智能缓存技术。它主要应用于大语言模型（LLM）、自然语言处理（NLP）和搜索系统中，用于降低计算成本、减少 Token 消耗。

相似问题耗时: 0.17s
回答: **语义缓存（Semantic Caching）**是一种基于查询“含义”而非“字面完全匹配”的智能缓存技术。它主要应用于大语言模型（LLM）、自然语言处理（NLP）和搜索系统中，用于降低计算成本、减少 Token 消耗。

# LangCache 兼容模式 - 快速验证脚本
# 用法：替换下面 3 个变量，然后执行：python verify_langcache.py

import requests, time

BASE_URL = "https://<YOUR_BASE_URL>"   # 替换为实际服务地址（必须包含 http:// 或 https://）
CACHE_ID = "<YOUR_CACHE_ID>"          # 替换为实际 Cache ID
API_KEY  = "<YOUR_API_KEY>"           # 替换为实际 API Key

URL = f"{BASE_URL}/v1/caches/{CACHE_ID}"
H = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. 插入缓存
print("1. 插入缓存...")
r = requests.post(f"{URL}/entries", headers=H, json={
    "prompt": "什么是语义缓存？",
    "response": "语义缓存是一种基于语义相似度匹配的缓存技术，通过对用户请求进行向量化表示，"
                "在缓存中查找语义相近的历史请求并复用其响应结果，避免对大模型的重复调用，"
                "降低成本与延迟。"
})
print(f"   状态: {r.status_code} | 响应: {r.text}")

# 等待索引构建
time.sleep(3)

# 2. 语义搜索
print("2. 语义搜索...")
r = requests.post(f"{URL}/entries/search", headers=H, json={
    "prompt": "语义缓存是什么意思？",
    "searchStrategies": ["exact", "semantic"]
})
print(f"   状态: {r.status_code} | 响应: {r.text}")

# 3. 判定结果
if r.status_code == 200 and r.json().get("data"):
    print("\n验证通过：LangCache 实例工作正常。")
else:
    print("\n验证失败：请检查配置或参见错误码。")

后续步骤

• 调整相似度阈值优化命中率：阈值越低命中越多但可能不够精确，阈值越高越精确但命中率下降。

• 使用动态阈值降低调参成本（仅 OpenAI 兼容模式）：动态阈值模式下，只需设置业务可接受的错误率上限，相似度阈值由系统自动调整。错误率上限越小，缓存策略越保守。

• 配置 TTL 管理缓存时效性：对于答案可能过时的场景，设置合理的过期时间。

• 查看 API 完整能力：技术架构与接口说明。