技术架构与接口说明

OpenAI 兼容模式

OpenAI 兼容模式处理一次请求的完整链路：

1. 请求接入 — 接收 OpenAI 兼容格式的请求。

2. Key 提取 — 通过 GJSON PATH 表达式从请求 JSON 中提取缓存 Key（默认提取最后一条 user message）。

3. 精确匹配 — 在 Tair 中查找完全一致的缓存。命中则直接返回（延迟约 1~2 ms）。

4. Embedding — 精确未命中时，调用 Embedding 模型将文本向量化。

5. 语义检索 — 在 Tair Vector 中执行 KNN 近似搜索。

6. 相似度判定 — 最相似结果达到阈值则返回缓存（延迟约 5~20 ms）。

7. LLM 回退 — 均未命中，请求透传至百炼平台获取推理结果。

8. 缓存写入 — LLM 结果自动写入 Tair，后续相同/相似请求可复用。

LangCache 兼容模式

LangCache 模式仅提供缓存的增删查能力，不代理 LLM 调用。开发者通过 API 主动管理缓存条目，自行决定何时查询缓存、何时调用 LLM、何时写入缓存。

Chat Completions API

何时使用：标准多轮对话场景，兼容所有 OpenAI Chat 格式的请求。

POST /compatible-mode/v1/chat/completions

示例：

curl -X POST http://<Base URL>/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer <API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-plus",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "什么是语义缓存？"}
    ]
  }'

Responses API

何时使用：简单单轮问答，无需维护 messages 数组。

POST /compatible-mode/v1/responses

示例：

curl -X POST http://<Base URL>/compatible-mode/v1/responses \
  -H "Authorization: Bearer <API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-plus",
    "input": "简要介绍下语义缓存的工作原理"
  }'

百炼 DashScope API

何时使用：已使用百炼 SDK 的应用，不想切换到 OpenAI 格式。

POST /api/v1/services/aigc/text-generation/generation

示例：

curl -X POST http://<Base URL>/api/v1/services/aigc/text-generation/generation \
  -H "Authorization: Bearer <API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-plus",
    "input": {
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "什么是向量检索？"}
      ]
    },
    "parameters": {"result_format": "message"}
  }'

SDK 接入

支持通过以下 SDK 接入，安装方式参见安装SDK：

• OpenAI Python SDK / OpenAI Node.js SDK

• DashScope Python SDK / DashScope Java SDK

核心配置参数

语义搜索

何时使用：查询缓存中是否存在与当前请求语义相似的已有回答。这是 LangCache 模式的核心操作——先搜索，命中则使用缓存，未命中则自行调用 LLM。

POST /v1/caches/{cacheId}/entries/search

请求参数

响应示例

{
  "data": [
    {
      "id": "5b84acef3ce360988d1b35adbaaaccb1",
      "prompt": "Tell me how semantic caching works",
      "response": "Semantic caching stores and retrieves data based on meaning rather than exact string matching.",
      "attributes": {"language": "en", "topic": "cache"},
      "similarity": 0.95,
      "searchStrategy": "semantic"
    }
  ]
}

如果无命中结果，data 为空数组。

插入缓存

何时使用：调用 LLM 获得回答后，将问答对存入缓存供后续复用。

POST /v1/caches/{cacheId}/entries

请求参数

响应

{
  "entryId": "a1b2c3d4e5f6..."
}

删除缓存条目

何时使用：某条缓存内容过时或错误，需要单独移除。

DELETE /v1/caches/{cacheId}/entries/{entryId}

成功返回 HTTP 204（无响应体）。

清空缓存

何时使用：需要重建整个缓存（如模型升级后旧答案不再适用）。

POST /v1/caches/{cacheId}/flush

成功返回 HTTP 204。

核心配置参数

SDK 接入