语义缓存接入自建 Agent-云数据库 Tair（兼容 Redis®）(Tair)-阿里云帮助中心

模式说明

LangCache 兼容模式与 OpenAI 兼容模式的核心区别：

对比项	OpenAI 兼容模式	LangCache 兼容模式
工作方式	代理 LLM 调用，自动缓存。	仅提供缓存 API，不代理 LLM。
接入方式	替换 Base URL 即可。	在代码中主动调用缓存 API。
适用场景	使用现成 Agent 框架（如 OpenClaw、Hermes）或标准 OpenAI 协议客户端。	自建 Agent 系统，需灵活控制缓存策略。
控制粒度	全自动，开发者无需关注缓存逻辑。	开发者完全控制何时读缓存、何时写缓存。

说明

选择建议：如果您的 Agent 系统有自己的 LLM 调用链路，且希望精确控制哪些请求走缓存、哪些不走，请选择 LangCache 兼容模式。

前提条件

条件	说明
语义缓存实例	已完成创建并处于运行中状态。若未创建，请参见语义缓存实例开通说明。
接入信息	已获取服务地址（Base URL）、API Key 和 Cache ID。
网络访问	若从非 VPC 环境访问（如本地开发机），已申请公网访问地址。
开发环境	已具备 Python 开发环境。

步骤一：获取接入信息

登录 Tair 控制台，在左侧导航栏单击Tair 语义缓存网关实例。
在实例列表中，单击目标实例名称，进入实例详情页。
在接入信息区域，获取 Base URL 和 API Key。

进入插件管理页签，在语义缓存插件区域获取 Cache ID。

信息	用途	格式示例
服务地址（Endpoint/Base URL）	API 请求的目标地址	`https://tg-bp1******.redis.rds.aliyuncs.com`
API Key	身份认证	`sk-****`
Cache ID	标识缓存实例，用于 API 路径	`r-bp1xxxxxx`

说明

Cache ID 需要在实例详情页的插件管理页面中获取，不同于实例 ID。若需公网访问，在网络访问区域单击公网访问右侧的申请按钮；公网地址与内网地址不同，请确认使用与网络环境匹配的地址。

步骤二：理解接入逻辑

LangCache 兼容模式不代理 LLM 调用。您需要在自己的 Agent 代码中实现以下流程：

用户提问
   │
   ▼
搜索缓存（POST /entries/search）
   │
   ├── 命中 → 直接返回缓存中的回答（毫秒级）
   │
   └── 未命中 → 调用您自己的 LLM 获取回答
                    │
                    ▼
              写入缓存（POST /entries）
                    │
                    ▼
              返回 LLM 回答给用户

核心 API 只有两个（其余 API 接口可参考技术架构与接口说明）：

API	用途	端点
搜索缓存	查找是否有语义相似的已缓存回答。	`POST /v1/caches/{cacheId}/entries/search`
插入缓存	将新的问答对写入缓存。	`POST /v1/caches/{cacheId}/entries`

步骤三：接入代码实现

以下以 Python SDK 为例演示完整接入流程。

Python SDK

安装 SDK：

pip install langcache

完整示例：

from langcache import LangCache
from openai import OpenAI  # 以 OpenAI SDK 调用 LLM 为例

# ============ 配置信息 ============
LANGCACHE_BASE_URL = "https://tg-xxxxxx.redis.rds.aliyuncs.com"
LANGCACHE_API_KEY  = "sk-xxxxxx"
CACHE_ID           = "r-bp1xxxxxx"

# 您自己的 LLM 配置（语义缓存未命中时调用）
LLM_API_KEY  = "<Your-LLM-API-Key>"
LLM_BASE_URL = "<Your-LLM-Base-URL>"
LLM_MODEL    = "<Your-LLM-Model>"

# ============ 初始化客户端 ============
cache_client = LangCache(
    server_url=LANGCACHE_BASE_URL,
    api_key=LANGCACHE_API_KEY,
    cache_id=CACHE_ID,
)

llm_client = OpenAI(
    api_key=LLM_API_KEY,
    base_url=LLM_BASE_URL,
)

# ============ 核心逻辑 ============
def ask(question: str) -> str:
    """带语义缓存的问答函数"""

    # 第一步：搜索缓存
    search_result = cache_client.search(prompt=question)

    if search_result.data:
        # 缓存命中，直接返回
        print(f"[缓存命中] 相似度: {search_result.data[0].similarity}")
        return search_result.data[0].response

    # 第二步：缓存未命中，调用 LLM
    print("[缓存未命中] 调用 LLM...")
    completion = llm_client.chat.completions.create(
        model=LLM_MODEL,
        messages=[{"role": "user", "content": question}],
    )
    answer = completion.choices[0].message.content

    # 第三步：将问答对写入缓存
    cache_client.set(prompt=question, response=answer)

    return answer


# ============ 使用示例 ============
if __name__ == "__main__":
    # 首次提问（走 LLM）
    print(ask("什么是语义缓存？"))

    # 语义相似的提问（走缓存，毫秒级返回）
    print(ask("语义缓存是什么意思？"))

其他接入方式

除 Python SDK 外，您还可以通过以下方式接入：

JavaScript/Node.js SDK：npm install @redis-ai/langcache
HTTPS API 直接调用：适用于任何编程语言。

详细的 API 接口规范、请求参数和响应格式，请参见技术架构与接口说明。

步骤四：验证缓存效果

完成代码接入后，按以下方式验证缓存是否正常工作：

发送一个问题（如什么是 Redis Cluster），观察是否正常返回 LLM 回答。
发送一个语义相似但表述不同的问题（如Redis Cluster 是什么），观察：
- 返回内容是否与第一次一致。
- 响应速度是否显著加快（从数十秒缩短至毫秒级）。

若第二次请求快速返回且内容一致，说明语义缓存已正常工作。

注意事项

注意项	说明
服务端口	LangCache 兼容模式为 HTTPS 服务，不是 Redis 端口 6379。
公网与内网	公网地址和内网地址不同，请确认使用与网络环境匹配的地址。API Key 不受影响。
Cache ID	在实例详情页的插件管理中获取（以 `r-` 开头），不是网关实例 ID（以 `tg-` 开头）。
搜索策略	默认按 `["exact", "semantic"]` 顺序搜索：先精确匹配，再语义匹配。
相似度阈值	默认 0.85，可在搜索请求中通过 `similarityThreshold` 参数按次覆盖。