AI导哈

RAG服务器

一个基于AWS Lambda和OpenSearch Serverless的检索增强生成（RAG）服务器，用于存储和检索文档内容。

  • by w3con
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 0x00000002/rag-mcp-server

使用说明

RAG MCP服务器（Lambda+OpenSearch无服务器）

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

它使用AWS Lambda进行计算，使用API网关（HTTP API）进行请求接口，使用OpenSearch Serverless进行矢量存储/搜索，使用OpenAI进行嵌入和生成，使用AWS S3进行持久原始文档存储。

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

先决条件

在开始之前，请确保已安装以下内容：

  • Node.js和npm： AWS CDK需要。 (下载)
  • AWS CDK工具包： 通过npm全局安装： npm install -g aws-cdk
  • AWS-CLI： 已安装并配置。这就是CDK和Makefile与您的AWS帐户交互的方式。
    • 配置： 您需要配置凭据，通常通过以下方式：
      • IAM身份中心（SSO）：运行 aws configure sso 或 aws sso login这是推荐的现代方法。
      • IAM用户：运行 aws configure 并提供访问密钥ID和秘密访问密钥（出于安全考虑不太推荐）。
    • 请参阅 AWS CLI配置指南.
    • 重要提示： 确保您配置的AWS配置文件（或默认配置文件）具有足够的权限（请参阅“设置”部分）。
  • python 版本3.9或更高（与Lambda运行时匹配）。
  • 匹普： 通常包含在Python中。用于管理Python依赖关系。
  • 制造商： 使用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密钥值。（例如生成UUID或使用密码生成器）。做 不 将其存储为键/值对，只存储键字符串本身。

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

通过Makefile进行部署和管理

这 Makefile 为管理应用程序生命周期提供了方便的目标。如果需要，您可以使用环境变量覆盖默认的AWS区域和配置文件（例如。， AWS_REGION=us-east-1 make deploy).

典型工作流程：

  1. make deps
  2. make bootstrap
  3. 创造两个秘密 AWS机密管理器中的（OpenAI密钥、应用程序API密钥）。
  4. make deploy
  5. make invoke / make logs /通过其API端点（包括API密钥）使用应用程序。
  6. make destroy

生成文件目标：

  • make build：构建Lambda部署包（从安装依赖项 pyproject.toml 以及复制 src/)进入 build/lambda_package/ 目录。这会自动发生，作为 make deploy 和 make test.

  • make bootstrap：（每个AWS帐户/区域运行一次）引导AWS环境以进行CDK部署。

    • 为什么？: 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包并部署整个堆栈(RagMcpStack)使用 cdk deploy.

    • 先决条件： 有效的AWS凭据、Secrets Manager中正确配置的OpenAI Secret以及目标区域的CDK引导已完成。
    • 流程： CDK将堆栈定义合成到CloudFormation模板中并进行部署。这将创建/更新所有必要的AWS资源。这可能需要几分钟的时间，尤其是第一次或创建/更新OpenSearch资源时。
    • 输出： 成功完成后，API网关端点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：销毁CDK堆栈通过CloudFormation创建的所有AWS资源。请谨慎使用，因为这是不可逆转的。

  • make clean：删除本地生成工件(build/, cdk.out等等）。不会影响已部署的AWS资源。

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

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

架构概述

  1. API网关（HTTP API）： 接收传入的HTTP请求 /mcp （GET用于发现，POST用于执行）。
  2. Lambda函数： 处理来自API网关的请求。解析MCP调用，获取机密，生成嵌入（使用OpenAI），与OpenSearch Serverless和S3交互，并可能调用OpenAI进行生成。
  3. OpenSearch无服务器： 存储文档嵌入和元数据。为RAG检索步骤提供k-NN向量搜索功能。
  4. S3铲斗： 存储添加文档的原始文本内容。
  5. 保密经理： 安全地存储OpenAI API密钥。
  6. 国际机械师协会： 定义Lambda函数访问其他AWS服务（S3、Secrets Manager、OpenSearch、CloudWatch Logs）的权限。
  7. 云观察： 从Lambda函数收集日志。

开发说明

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

运行示例脚本

Python脚本示例(example.py)演示了如何与已部署的API进行交互：

  1. 部署堆栈： 确保堆栈已部署(make deploy).

  2. 设置环境变量： 您需要提供已部署的API URL和应用程序API密钥作为环境变量。你可以用 make invoke 或来自CloudFormation堆栈输出。

    # Get the URL (example)
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>)

# Set your key (replace with the actual key from 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 字段，应用程序API密钥应为纯文本）。
    • 部署者凭据具有 secretsmanager:GetSecretValue 许可。
  • 部署失败，出现IAM错误： 检查部署程序权限。
  • API网关返回401未授权： 确保客户端在中发送正确的API密钥值 X-API-Key 头球
  • API网关返回5xx错误： 检查Lambda日志(make logs).

相关 MCP