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

在网关层实现 RAG

本指南介绍如何在 API7 AI 网关中配置检索增强生成（RAG），使请求在到达大语言模型前，先使用知识库中的上下文进行增强。

概览​

当前限制：API7 AI 网关的 RAG 目前仅支持 Azure。 你必须使用 Azure OpenAI 生成向量嵌入，并使用 Azure AI Search 执行向量搜索。对其他服务提供方的支持尚在规划中，当前并未实现。

RAG 会在请求处理期间从向量知识库检索相关上下文，并用其增强大语言模型提示词。在网关层实现 RAG，可以集中管理增强逻辑，无需每个服务都在应用侧编排 RAG。

架构流程如下：

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

前置条件​

  • 安装 Docker。

  • 安装 cURL，用于发送请求并验证服务。

  • 拥有一个正在运行且可使用 ai-proxy 和 ai-rag 插件的 API7 网关实例。

  • 从控制台获取令牌，并将其保存到环境变量：

    export API_KEY=your-dashboard-token   # 请替换为你的控制台令牌

  • 将 {gateway_group_id} 替换为网关组 ID。如果正在按照快速入门操作，请使用 default。

  • 如果使用 Admin API 示例，请在 API7 网关中创建或复用一个服务。如果尚无服务，请按照创建或复用服务操作，然后将其 ID 保存到环境变量：

    export SERVICE_ID=your-service-id         # 请替换为你的服务 ID

  • 为生成模型准备 Azure OpenAI 资源和 Deployment。

  • 拥有用于生成向量嵌入的 Azure OpenAI 访问权限。

  • 拥有 Azure AI Search 服务，并已使用知识库内容填充索引。

配置 RAG 插件​

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

curl -k "https://localhost:7443/apisix/admin/routes?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -d '{
    "id": "rag-azure",
    "service_id": "'"$SERVICE_ID"'",
    "paths": ["/v1/chat/completions"],
    "plugins": {
      "ai-proxy": {
        "provider": "azure-openai",
        "auth": {
          "header": {
            "api-key": "YOUR_AZURE_OPENAI_KEY"
          }
        },
        "options": {
          "model": "gpt-4o-mini"
        },
        "override": {
          "endpoint": "https://YOUR-RESOURCE.openai.azure.com/openai/deployments/YOUR-DEPLOYMENT/chat/completions?api-version=2024-10-21"
        }
      },
      "ai-rag": {
        "embeddings_provider": {
          "azure_openai": {
            "endpoint": "https://YOUR-RESOURCE.openai.azure.com/openai/deployments/text-embedding-3-large/embeddings?api-version=2023-05-15",
            "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"
          }
        }
      }
    }
  }'

❶ ai-proxy 负责生成，并且在此路由上必须使用 provider: "azure-openai"。

❷ ai-rag 使用仅限 Azure 的后端：Azure OpenAI 负责生成向量嵌入（embeddings_provider），Azure AI Search 负责向量检索（vector_search_provider）。

❸ 指定完整的 Azure OpenAI 端点，其中包括资源名称、Deployment 名称和 API 版本。

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

验证配置​

发送一个包含 ai_rag 字段的请求。请求必须提供 vector_search.fields 和 embeddings.input。

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

❶ ai_rag.vector_search.fields 映射检索期间使用的 Azure AI Search 文档字段。

❷ ai_rag.embeddings.input 是为向量搜索生成向量嵌入的文本，也是执行检索的必填字段。

❸ 使用一个依赖已索引知识库的问题，以便确认回答是否以检索内容为依据。

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

最佳实践​

  • 及时更新知识库和索引。过时文档会降低回答质量。
  • 根据数据特征调整 top_k。值过低可能遗漏上下文，值过高可能稀释提示词。
  • 密切监控 Token 用量。新增上下文会增加提示词 Token 和成本。

后续步骤​