RAG MCP Server (Lambda + OpenSearch Serverless)

RAG MCP 服务（Lambda + OpenSearch Serverless）

此项目实现了一个 RAG（检索增强生成）服务，作为 MCP（模型上下文协议）工具，并使用 AWS 无服务器架构进行部署。

它使用 AWS Lambda 进行计算，使用 API Gateway（HTTP API）提供请求接口，使用 OpenSearch Serverless 进行向量存储和搜索，使用 OpenAI 生成嵌入和内容，并使用 AWS S3 持久存储原始文档。

基础设施使用 Python 编写的 AWS Cloud Development Kit（CDK）进行管理。

前提条件

开始之前，请确保已安装以下组件：

• Node.js 和 npm： AWS CDK 所需。（下载）
• AWS CDK Toolkit： 通过 npm 全局安装：npm install -g aws-cdk
• AWS CLI： 已安装并配置。CDK 和 Makefile 通过它与 AWS 账户交互。
  • 配置： 需要配置凭证，通常通过以下方式进行：
    • IAM Identity Center（SSO）：运行 aws configure sso 或 aws sso login。这是推荐的现代方式。
    • IAM 用户：运行 aws configure 并提供访问密钥 ID 和秘密访问密钥（出于安全考虑，不太推荐）。
  • 请参阅 AWS CLI 配置指南。
  • 重要： 确保配置的 AWS 配置文件（或默认配置文件）具有足够的权限（请参阅“设置”部分）。
• Python： 版本 3.9 或更高（与 Lambda 运行时一致）。
• Pip： 通常随 Python 一同安装。用于管理 Python 依赖项。
• Make： 使用 Makefile 自动化目标所需。（Linux/macOS 上通常已预装；Windows 上可能需要安装）。

项目结构

/
├── Makefile             # Automation commands (build, deploy, test, etc.)
├── pyproject.toml       # Application dependencies & project metadata
├── pytest.ini           # Pytest configuration (ensures tests find modules)
├── .env.example         # Example environment variables for local testing/config
├── README.md            # This file
├── src/                 # Application source code (Lambda handler, services, utils)
├── stack/               # CDK Stack definition (Python)
├── infrastructure/      # AWS CDK app definition and config
│   ├── app.py           # CDK App entrypoint
│   ├── cdk.json         # CDK configuration
└── tests/               # Application and infrastructure tests
    ├── test_lambda_handler.py
    └── test_infrastructure.py
└── example_payloads/    # Example JSON payloads for API requests
    ├── payload_add.json
    ├── payload_query.json
    └── payload_list.json

设置与配置

1. 安装依赖项： 在项目根目录中安装 Python 依赖项。

   make deps
   

2. AWS 凭证与权限：（确保拥有 AdministratorAccess 或同等权限以进行部署）。

3. 在 AWS Secrets Manager 中创建密钥（目标区域）：

   • OpenAI API 密钥：
     • 名称： AI/MCP_SERVERS/RAG_SERVER（或更新 stack/rag_mpc_stack.py）
     • 类型： 其他类型的密钥
     • 密钥/值： 添加一个名为 OPENAI_API_KEY 的密钥，并将你的 sk-... 密钥作为其值。
   • 应用程序 API 密钥：
     • 用途： 对客户端向已部署 API 发出的请求进行身份验证。
     • 名称： App/RagMcp/ApiKey（或更新 stack/rag_mpc_stack.py）
     • 类型： 其他类型的密钥
     • 密钥值： 选择 纯文本，并输入一个强随机 API 密钥值，供客户端应用程序（Agentic AI 框架）使用。（例如，生成 UUID 或使用密码生成器。）不要将其保存为键值对，只保存密钥字符串本身。

4. 环境变量（本地使用）：（测试和部署不需要）。

通过 Makefile 部署和管理

Makefile 提供了用于管理应用生命周期的便捷目标。如有需要，你可以通过环境变量覆盖默认的 AWS 区域和配置文件（例如，AWS_REGION=us-east-1 make deploy）。

典型工作流：

1. make deps
2. make bootstrap
3. 在 AWS Secrets Manager 中创建两个密钥（OpenAI 密钥、应用 API 密钥）。
4. make deploy
5. make invoke / make logs / 通过 API 终端节点使用应用（包括 API 密钥）。
6. make destroy

Makefile 目标：

• make build：构建 Lambda 部署包（从 pyproject.toml 安装依赖并复制 src/），并将其放入 build/lambda_package/ 目录。执行 make deploy 和 make test 时会自动运行此目标。

• make bootstrap：（每个 AWS 账户/区域运行一次）为 CDK 部署准备 AWS 环境。

  • 为什么需要？：CDK 需要某些 AWS 资源（例如 S3 存储桶）来存储部署资产并管理部署。引导操作会创建这些共享资源。

  # Example using the default region from Makefile/AWS config
  make bootstrap
  # Example overriding region
  make bootstrap AWS_REGION=us-east-1
  

• make deploy：构建 Lambda 部署包，并使用 cdk deploy 部署整个堆栈（RagMcpStack）。

  • **前提条件：**有效的 AWS 凭证、在 Secrets Manager 中正确配置的 OpenAI 密钥，以及已为目标区域完成 CDK 引导。
  • **流程：**CDK 会将堆栈定义合成为 CloudFormation 模板并进行部署，从而创建或更新所有必要的 AWS 资源。此过程可能需要几分钟，尤其是在首次部署或创建/更新 OpenSearch 资源时。
  • **输出：**成功完成后，堆栈输出中会显示 API Gateway 终端节点 URL。

  make deploy
  # Example overriding region and profile
  make deploy AWS_REGION=us-east-1 AWS_PROFILE=my-dev-profile
  

• make test：按需构建部署包，并使用 pytest 运行单元测试和基础设施测试。

• make logs：实时跟踪已部署 Lambda 函数的 CloudWatch 日志。需要成功部署堆栈。按 Ctrl+C 停止。

• make destroy：通过 CloudFormation 销毁 CDK 堆栈创建的所有 AWS 资源。请谨慎使用，此操作不可撤销。

• make clean：删除本地构建产物（build/、cdk.out 等）。不会影响已部署的 AWS 资源。

• make invoke：显示用于与已部署 API 交互的示例 curl 命令。

  • 首先，按照命令输出设置 API_KEY 和 API_URL 环境变量。
  • 然后，运行示例 curl 命令。
  • 请注意，POST 请求使用 example_payloads/ 目录中的示例 JSON 文件。
  • 已部署 URL 示例（来自上一次成功部署）： https://9h8ob953ge.execute-api.eu-west-3.amazonaws.com/（注意：当前部署请始终使用 make invoke 输出或 CloudFormation 输出中的 URL）。

架构概述

1. **API Gateway（HTTP API）：**接收发往 /mcp 的 HTTP 请求（GET 用于发现，POST 用于执行）。
2. **Lambda 函数：**处理来自 API Gateway 的请求。解析 MCP 调用、获取密钥、生成嵌入向量（使用 OpenAI）、与 OpenSearch Serverless 和 S3 交互，并可能调用 OpenAI 进行生成。
3. **OpenSearch Serverless：**存储文档嵌入向量和元数据，并为 RAG 检索步骤提供 k-NN 向量搜索能力。
4. **S3 存储桶：**存储已添加文档的原始文本内容。
5. **Secrets Manager：**安全存储 OpenAI API 密钥。
6. **IAM：**定义 Lambda 函数访问其他 AWS 服务（S3、Secrets Manager、OpenSearch、CloudWatch Logs）的权限。
7. **CloudWatch：**收集 Lambda 函数的日志。

开发说明

• 测试： 使用 make test，通过模拟 AWS/OpenAI/OpenSearch 依赖项来运行单元测试。真正的端到端测试通常需要部署到 AWS 开发环境。
• 依赖项： 将 Python 依赖项添加到 pyproject.toml，然后运行 make deps。
• 基础设施： 编辑 stack/rag_mpc_stack.py 以修改 AWS 资源。
• 应用逻辑： 编辑 src/ 目录中的文件以修改 Lambda 行为。

运行示例脚本

示例 Python 脚本（example.py）演示了如何与已部署的 API 交互：

1. 部署堆栈： 确保已部署堆栈（make deploy）。

2. 设置环境变量： 需要将已部署的 API URL 和你的 App API Key 设置为环境变量。可以通过 make invoke 获取，也可以从 CloudFormation 堆栈输出中获取。

   # 获取 URL（示例）
   export API_URL=$(aws cloudformation describe-stacks --stack-name RagMcpStack --query "Stacks[0].Outputs[?OutputKey=='ApiGatewayEndpoint'].OutputValue" --output text --profile <YOUR_PROFILE> --region <YOUR_REGION>)
   
   # 设置你的密钥（替换为 Secrets Manager 中的实际密钥）
   export API_KEY="<YOUR_APP_API_KEY>"
   

3. 运行脚本：

   python example.py
   

   脚本会调用发现端点，添加两份文档，列出文档并执行查询，同时打印请求和响应。 注意： 脚本需要 requests 库（如果尚未安装，请运行 pip install requests，不过通过 make deps 应该已安装）。

常见故障排除提示

• ExpiredToken / InvalidClientTokenId 错误： 刷新 AWS 凭证（aws sso login）。
• 部署失败并提示 Secrets Manager 相关问题： 检查：
  • CDK 中的密钥名称是否与 AWS 中的名称完全一致。
  • 密钥是否位于部署所在的_同一区域_。
  • 密钥值的格式是否正确（OpenAI 密钥需要包含 OPENAI_API_KEY 字段，App API Key 应为纯文本）。
  • 部署者凭证是否具有 secretsmanager:GetSecretValue 权限。
• 部署因 IAM 错误而失败： 检查部署者权限。
• API Gateway 返回 401 Unauthorized： 确保客户端在 X-API-Key 标头中发送了正确的 API 密钥值。
• API Gateway 返回 5xx 错误： 检查 Lambda 日志（make logs）。