跳到主要内容
版本：3.10.x

在网关层实现 RAG

检索增强生成（RAG）利用从知识库检索到的上下文生成大语言模型的回答。API7 AI 网关可以在转发请求前检索上下文，集中处理提示词增强，无需每个应用分别实现。当前的 ai-rag 插件使用 Azure OpenAI 生成向量嵌入，并使用 Azure AI Search 执行向量搜索。

概览​

RAG 请求按以下流程处理：

  1. 客户端向 API7 AI 网关发送聊天请求。
  2. 网关使用 ai-rag 生成向量嵌入，并在 Azure AI Search 中执行向量搜索。
  3. 网关把检索到的上下文注入提示词。
  4. 网关通过 ai-proxy 将增强后的请求转发到 Azure OpenAI。
  5. 客户端收到有知识依据的回答。

前置条件​

  • 用于验证的客户端已安装 cURL。
  • 有一个正在运行且可使用 ai-proxy 和 ai-rag 插件的 API7 网关实例。
  • 在 Microsoft Foundry 中有一个 Azure OpenAI 资源，并已创建聊天和嵌入部署。记录资源名称、API Key 和两个部署的名称。
  • Azure AI Search 服务有一个已填充数据的索引，索引向量字段的名称和维度与请求一致。示例使用 1,024 维的 contentVector，与 Microsoft 的基本向量搜索流程一致。
  • 如果使用 ADC 配置，请确认 ADC 已安装并连接到目标网关组。

配置 RAG 插件​

在同一个路由上配置 ai-rag 和 ai-proxy，使检索和生成在同一条请求路径中完成。

从控制台获取 Token，将它与目标网关组及现有服务 ID 一同导出为环境变量。快速入门使用的网关组为 default。如有需要，请先创建或复用服务。

export API_KEY=replace-with-dashboard-token
export GATEWAY_GROUP_ID=default
export SERVICE_ID=replace-with-service-id

通过 Admin API 创建路由：

curl -k "https://localhost:7443/apisix/admin/routes/rag-azure?gateway_group_id=${GATEWAY_GROUP_ID}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
  {
    "name": "rag-azure",
    "service_id": "$SERVICE_ID",
    "paths": ["/v1/chat/completions"],
    "plugins": {
      "ai-proxy": {
        "provider": "openai-compatible",
        "auth": {
          "header": {
            "api-key": "YOUR_AZURE_OPENAI_KEY"
          }
        },
        "options": {
          "model": "YOUR_CHAT_DEPLOYMENT"
        },
        "override": {
          "endpoint": "https://YOUR-RESOURCE.openai.azure.com/openai/v1/chat/completions"
        }
      },
      "ai-rag": {
        "embeddings_provider": {
          "azure_openai": {
            "endpoint": "https://YOUR-RESOURCE.openai.azure.com/openai/v1/embeddings",
            "api_key": "YOUR_AZURE_OPENAI_KEY"
          }
        },
        "vector_search_provider": {
          "azure_ai_search": {
            "endpoint": "https://YOUR-SEARCH.search.windows.net/indexes/YOUR-INDEX/docs/search?api-version=2024-07-01",
            "api_key": "YOUR_AZURE_SEARCH_KEY"
          }
        }
      }
    }
  }
EOF

❶ 将 provider 设置为 openai-compatible，以便在 Azure OpenAI v1 请求体中保留聊天部署名称。

❷ 设置 Azure OpenAI v1 Chat Completions 端点。

❸ 配置 ai-rag，使用 Azure OpenAI 生成向量嵌入，并使用 Azure AI Search 执行向量检索。嵌入端点使用同一 Azure OpenAI 资源的 /openai/v1/embeddings 路径。

完整配置说明请参阅 ai-rag 和 ai-proxy。

验证配置​

发送一个包含 ai_rag 字段的请求。本示例请求生成 1,024 维的向量嵌入。请将维度调整为 Azure AI Search 向量字段的维度。如果该字段使用嵌入部署的默认维度，可以省略 dimensions。

curl "http://127.0.0.1:9080/v1/chat/completions" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_DEPLOYMENT",
    "messages": [
      {
        "role": "user",
        "content": "Based on our internal docs, what are the main capabilities of API7 AI Gateway?"
      }
    ],
    "ai_rag": {
      "vector_search": {
        "fields": "contentVector"
      },
      "embeddings": {
        "model": "YOUR_EMBEDDING_DEPLOYMENT",
        "input": "API7 AI Gateway capabilities overview",
        "dimensions": 1024
      }
    }
  }'

❶ 使用一个需要查询已索引知识库才能回答的问题，以便确认回答是否基于检索到的内容。

❷ ai_rag.vector_search.fields 指定用于检索的向量字段。

❸ ai_rag.embeddings 指定嵌入部署，并提供用于向量检索的文本和维度。维度必须与搜索索引中的向量字段一致。

你应收到标准聊天补全响应，回答基于索引中的文档。与不使用 ai_rag 的请求相比，回答应更具体，并与内部知识库内容一致。

最佳实践​

  • 及时更新知识库和索引。过时文档会降低回答质量。
  • 确保嵌入维度与 Azure AI Search 向量字段的维度一致。
  • 密切监控 Token 用量。新增上下文会增加提示词 Token 和成本。

后续步骤​