qsr-voice-assistant-agentcore

# QSR 全渠道语音助手，由 Amazon Bedrock AgentCore 提供支持 <!-- 核心框架和语言 --> [](https://aws.amazon.com/cdk/) [](https://www.python.org/) [](https://aws.amazon.com/bedrock/) [](https://aws.amazon.com/bedrock/) [](https://modelcontextprotocol.io/) [](https://aws.amazon.com/location/) [](https://nextjs.org/) [](https://aws.amazon.com/dynamodb/) [](https://aws.amazon.com/api-gateway/) [](https://aws.amazon.com/cognito/)  该项目演示了一个功能齐全、高度对话式的 **全渠道语音点餐助手**，适用于快餐（QSR）连锁店。这意味着相同的 AI 后端可以无缝部署在网页应用、移动应用、店内自助终端或 Drive-Thru 扬声器上，同时保持统一的客户状态。由 **Amazon Nova Sonic v2**、**Amazon Bedrock AgentCore** 和 **MCP 协议** 提供支持，助手与客户进行自然、实时的语音对话，以接受订单、推销商品和查找最近的分支，使用 AWS 位置服务。 --- ## 🎥 观看实际操作 想亲眼看看整个平台的运行情况吗？观看快速演示： [](https://youtu.be/SagiW7cQ8xA) **点击观看：** 2 分钟内实时数据流、机器学习预测、网页仪表盘和 AI 聊天机器人 --- ## 📦 该项目解决了哪些商业问题？ 传统的 QSR 点餐体验（Drive-Thru 扬声器、移动应用和店内自助终端）通常无摩擦但非常不个性化。它们缺乏智能推销、记住过去的客户偏好或动态调整到客户的实时物理环境的能力。 **这个 AI 助手作为一个超级个性化的“数字收银员”。** 客户只需自然地说话。助手知道客户是谁，记得他们的过去订单，准确知道他们的物理位置，并无缝地协调整个结账过程。 如果客户说： > *"我饿了，我就想要昨天的常用订单，但再加一份大薯条。* AI 立即使用其后端工具来查找客户的订单历史，获取当前菜单价格，根据最近的商店位置计算税费，将商品添加到购物车，并在不到一秒的时间内通过极其真实的语音做出响应。 --- ## 🌟 深入探讨：企业架构和 IT 解决方案 在生产环境中部署实时语音转语音 AI 引入了巨大的 IT 障碍。这种架构解决了最关键的企业问题： **🛡️ 1. 双层安全（Cognito JWT + SigV4）** 系统使用 Amazon Cognito 用户池来管理身份验证。而不是直接将安全的后端 API 公开给公共浏览器，前端使用临时 IAM 凭证通过 **SigV4** 直接与 Bedrock AgentCore 运行时建立 WebSocket 连接。同时，`AuthInterceptor` 验证 **Cognito JWT** 在 WebSocket 流中。专门的 **Post-Confirmation Lambda** 在电子邮件验证后自动分配唯一的 `customerId`，严格将 Cognito 与 DynamoDB 表解耦。 <br> <br> **🔗 2. 零代码遗留集成（OpenAPI 和 MCP 网关）** AI 不需要编写自定义的 Python/Node.js “工具”。AgentCore 网关直接从 API 网关摄取标准的 OpenAPI 模式。这意味着这个 AI 代理可以放在任何现有的后端 REST API（甚至是遗留系统）上，AI 将动态发现并使用端点作为工具，通过模型上下文协议（MCP）。 **🧠 3. 无状态 AI（无向量数据库或内存同步问题）** 维护用户“内存”通常需要昂贵的向量数据库或将大量聊天历史记录注入 LLM 上下文。这个 AI 完全 **无状态**。当它需要记住过去的订单或偏好时，它使用工具实时查询生产 DynamoDB。这保证了 100% 的准确性，消除了幻觉，并大大降低了 token 成本。 **⚡ 4. 超低延迟语音转语音** 使用新的 **Amazon Nova Sonic v2**，系统绕过了传统的“语音转文本 -> LLM -> 文本转语音”管道。它直接理解和生成音频，从而实现超低延迟、类似人类的对话，捕捉语气和情感。 **📈 5. 无限可扩展性和零闲置成本（100% 无服务器）** 构建在纯 **无服务器架构** 上（AgentCore、API 网关、Lambda、DynamoDB）。无论您有 10 个或 10,000 个客户同时订购，它都会自动扩展。甚至 Next.js 前端也无服务器托管在 **Amazon S3 和 CloudFront** 上（通过 OAC 安全）。当系统空闲时（例如商店关闭），计算成本将精确降至零。 **📊 6. 完全可观察性和可审计性** 企业系统需要严格的审计。AgentCore 与 AWS CloudWatch 完全集成（可通过 GenAI Observability > Bedrock AgentCore 访问）。AI 调用的每个工具、读取的每个数据库响应及其内部“思维链”推理都已记录。管理员可以准确追踪 AI 为什么和如何得出其结论。 <br> --- ## 🛠️ 使用的 AWS 架构和服务 该项目实施了一个完全托管、可扩展且安全的架构，使用以下核心 AWS 服务： * **Amazon Bedrock（Nova Sonic v2）：** 核心 AI 模型，原生处理与超低延迟的直接语音转语音交互。 * **Amazon Bedrock AgentCore：** 托管 WebSocket 网关和运行时容器，自动编排 MCP 工具和 SigV4 身份验证。由最先进的 **AWS Strands 框架（`strands.experimental.bidi`）** 提供支持，以实现 WebSocket 上的真正双向（Bidi）音频流。 * **AWS Lambda 和 API 网关：** 无服务器计算层，执行业务逻辑（AddToCart、PlaceOrder、GeocodeAddress 等）。 * **Amazon DynamoDB：** 高可扩展的 NoSQL 数据库，托管 5 张表（`Customers`、`Locations`、`Menu`、`Orders`、`Carts`）。 * **Amazon Cognito：** 通过处理用户身份验证、授权和安全 JWT 令牌管理来保护 Web UI。 * **AWS 位置服务（Geo Places）：** 提供路由、地理编码和最近位置计算。 * **Amazon S3 和 CloudFront：** 托管 React/Next.js 前端应用程序。 * **AWS CodePipeline 和 CodeBuild：** 提供一个全自动的 CI/CD 管道，无缝部署前端和后端更新。 * **AWS CDK（云开发工具包）：** 在 Python 中定义整个基础设施即代码，确保可复制的部署。 --- ## 🧱 基础设施即代码（CDK）栈 该项目由多个 CDK 栈组成，通过 AWS CodePipeline 部署：  <br> <br> 1. **AgentCoreStack**：托管 AgentCore 网关、Bidi 代理运行时，并编排 WebSocket 层。 2. **ApiGatewayStack**：公开所有后端业务逻辑的 REST API。 3. **CognitoStack**：用户池和身份池，用于身份验证用户和授予临时 AWS 凭证。 4. **LambdaStack**：多个 AWS Lambda 函数，处理特定领域的工具执行。 5. **LocationStack**：配置 AWS 位置服务（Geo Places）进行空间查询。 6. **DynamoDBStack**：定义模式并提供 5 个核心表。 7. **S3CloudfrontStack**：使用 S3 和 CloudFront 交付安全的前端。 --- ## 📂 项目结构概述 ```text 📦 qsr-voice-assistant-agentcore/ ├── 📁 backend/ # 无服务器后端和 AgentCore │ ├── 📁 agent_core/ # Bedrock AgentCore WebSocket 运行时和 MCP 配置 │ ├── 📁 cdk_pipeline/ # 后端 CI/CD CodePipeline 定义 │ ├── 📁 lambda_funcs/ # 无服务器工具处理程序（菜单、购物车、位置） │ ├── 📁 scripts/ # 后端实用脚本 │ └── 📁 stacks/ # 后端 AWS CDK 基础设施定义 ├── 📁 frontend/ # Next.js 前端应用程序 │ ├── 📁 cdk_pipeline/ # 前端 CI/CD CodePipeline 定义 │ ├── 📁 qsr-app/ # Next.js 源代码 │ ├── 📁 scripts/ # 合成数据播种和配置生成器 │ └── 📁 stacks/ # 前端 AWS CDK 基础设施定义 ├── 📄 app.py # CDK 应用程序入口点 ├── 📄 cdk.json # CDK 配置 ├── 📄 Makefile # 部署命令 └── 📄 README.md # 文档 ``` --- ## 🔄 用户请求流程（幕后） 整个架构建立在高度安全、实时的流媒体管道上： 1. 用户通过 **Amazon S3 和 CloudFront** 从浏览器或移动设备访问 Web 应用程序。 2. 用户使用用户名和密码通过 **Amazon Cognito** 进行身份验证，并接收 JWT 令牌（访问令牌和 ID 令牌）。 3. 前端用 ID 令牌交换 Cognito 身份池的临时 AWS 凭证（访问密钥、密钥、会话令牌）。 4. 前端建立与 **AgentCore 运行时** 的安全、**SigV4 签名 WebSocket 连接**（外部传输安全），并立即将 **Cognito JWT 访问令牌**（身份有效载荷）作为第一个帧注入。这种双层安全确保了 AWS 基础设施授权和应用程序级客户身份。 5. AgentCore 运行时托管在 AgentCore 运行时中，验证访问令牌，通过调用 Cognito GetUser API，并提取客户的验证姓名、电子邮件和 `customerId`。 6. AgentCore 运行时在 Amazon Bedrock 上初始化 **Nova 2 Sonic** 模型，并使用验证的客户上下文构建个性化系统。 7. AgentCore 运行时作为 **MCP（模型上下文协议）客户端** 连接到 **AgentCore 网关**，使用 SigV4 身份验证，并发现可用的工具。 8. 用户说出他们的订单。代理通过 Nova 2 Sonic 处理语音输入，并通过 AgentCore 网关使用 MCP 异步调用工具。 9. AgentCore 网关公开后端 REST API 作为 MCP 工具。当代理调用工具时，AgentCore 网关将请求转发为 REST API 调用到 **API 网关**，后者将其路由到适当的 **Lambda 函数**。 10. Lambda 函数查询 **DynamoDB** 表和 **AWS 位置服务**，并将响应返回给网关。 11. Nova 2 Sonic 生成一个上下文语音响应，结合工具结果，并通过 WebSocket 连接将其流式传输回用户。 --- ## 📍 AWS 位置服务的作用（位置感知） 该 AI 助手的关键功能是其 **位置感知**。由于 QSR 连锁店有数百个分支，助手需要准确知道将订单路由到哪个分支。AWS 位置服务实现了三个令人难以置信的功能： * **地理围栏（Drive-Thru 与店内）：** 如果客户在 Drive-Thru 队伍中打开应用程序，系统会立即检测到他们距离特定分支 10 米。AI 自动用以下内容问候他们： *"我看到您在我们的 Kadıköy 分支！我应该直接将您的订单发送到厨房吗？"* * **路线中/取货计算：** 如果客户正在驾驶，AI 可以计算路线并说： *"在您去工作的路上有一个分支，距离只有 2 分钟的绕路。我将把您的咖啡送到那里，这样您到达时就已经准备好了。* * **动态菜单和税费计算：** 不同的分支有不同的本地税费或菜单可用性。查找最近的分支可确保准确的定价。 ### 🧪 合成分支生成（`seed_data.py`） 为了在没有实际餐厅连锁店所有权的情况下使此演示极为现实，包含了一个特殊的 **`seed_data.py`** 脚本。 当执行时，该脚本提示输入城市和首选餐厅类型（例如“汉堡”）。它使用 **Amazon Geo Places API** 查找附近的真实汉堡店，并将它们保存到 DynamoDB 的 `Locations` 表中，以充当合成分支。这确保在测试期间，语音助手将无缝找到附近的真实街道和位置。 --- ## 🧠 语音助手代理系统和工具 该架构引入了一种高度动态和可扩展的 **代理工作流**，使用模型上下文协议（MCP）和 Amazon API 网关。 无需编写手动工具包装器，AgentCore 网关直接从 API 网关摄取 OpenAPI 模式。AI 代理无缝发现这些 REST API，并使用整个无服务器后端基础设施作为其工具集。当 AI 需要现实世界数据时，它通过 API 网关触发特定的 AWS Lambda 函数，以查询或改变 DynamoDB 中的状态：  * **获取菜单工具** ➡️ 查询 `QSR-菜单` 以获取当前商品和价格。 * **位置工具** ➡️ `地理编码地址`、`获取最近位置`、`查找路线沿线位置` ➡️ 使用 AWS 位置服务并查询 `QSR-位置`。 * **购物车工具** ➡️ `获取购物车`、`添加到购物车`、`更新购物车` ➡️ 管理临时 `QSR-购物车` 状态。 * **订单工具** ➡️ `下订单`、`获取以前的订单` ➡️ 编写并读取 `QSR-订单`。 * **客户资料** ➡️ `获取客户资料` ➡️ 从 `QSR-客户` 检索忠诚度数据。 --- ## 🗄️ DynamoDB 表 该项目部署了 5 个 DynamoDB 表，作为 QSR 连锁店的单一事实来源：    1. **`QSR-位置`**：存储餐厅分支的 GPS 坐标、地址和 ID。 2. **`QSR-菜单`**：存储可用商品、价格和允许的自定义（例如“无洋葱”、“额外奶酪”）。 3. **`QSR-客户`**：存储客户资料、忠诚度层和家庭位置。 4. **`QSR-购物车`**：一个临时表，保存结账前的活跃购物车。 5. **`QSR-订单`**：所有已完成订单的历史账本。 --- ## 💰 企业成本估算（每月） 该架构主要是 **无服务器**（按需付费），使其对原型设计和生产都具有极高的成本效益。 **假设和场景：** - **流量：** 每天 1,000 个语音订单（约 30,000 个订单/月）。 - **AI 模型：** Amazon Nova Sonic v2（语音）。 - **存储：** S3（前端资产）、DynamoDB（订单/菜单数据）。 | AWS 服务 | 成本因素和估算 | 近似每月成本 | |-------------|-------------------------|----------------------:| | **Amazon Bedrock（Nova Sonic v2）| 按需付费每令牌和音频秒。 | **~$45.00** | | **Amazon API 网关** | 100,000 REST API 调用（$1.20/1M）。 | **~$0.12** | | **AWS Lambda** | 100,000 次执行（免费层或便士）。 | **~$0.50** | | **Amazon DynamoDB** | 按需读取/写入（30k 个订单可忽略不计）。 | **~$1.50** | | **Amazon Cognito** | 1,000 MAU（免费层涵盖 50k MAU）。 | **$0.00** | | **Amazon CloudFront 和 S3** | 语音 UI 前端的标准流量。 | **~$2.00** | | **总估算成本** | | **~$49.12** | --- ## 🚀 部署说明 在部署此项目之前，请确保您的本地环境和 AWS 账户满足以下要求： ### 0. 先决条件 **本地环境：** * **Node.js（v20+）**：Next.js 15 和 AWS CDK 所需。 ([下载 Node.js](https://nodejs.org/)) * **AWS CLI（v2）**：与您的 AWS 账户交互所需。 ([安装 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)) * **Python（3.11+）**：CDK 部署脚本和 Lambda 函数所需。 * **Git**：版本控制和拉取存储库所需。 * **AWS CDK**：在终端中运行 `npm install -g aws-cdk` 安装。 **AWS 账户设置：** * **IAM 用户/角色**：您必须拥有具有 `AdministratorAccess`（或创建 IAM 角色、Lambda 函数、Bedrock 模型和 DynamoDB 表的足够权限）的 IAM 用户或角色。 * **AWS CLI 配置**：通过在终端中运行 `aws configure` 并提供您的访问密钥 ID 和秘密访问密钥来配置您的本地机器。 * **Amazon Bedrock 模型访问**：您 **必须** 在部署前在 AWS Bedrock 控制台（us-east-1）手动请求访问 **Amazon Nova Sonic v2** 模型，否则语音助手将失败。 . 配置 AWS CodeStar 连接到 GitHub 管道直接从 GitHub 拉取源代码。您必须配置 AWS CodeStar 连接： 1. 进入 **AWS 控制台** -> **开发工具** -> **设置** -> **连接**。 2. 点击 **创建连接**，选择 **GitHub**，并按照提示授权 GitHub 的 AWS 连接器。 3. 确保授予 **您的仓库**（例如 `<您的仓库名称>`）的访问权限。 4. 复制新创建的 **连接 ARN**。 5. 在项目根目录中打开 `cdk.json`。在 `"context"` JSON 块中，更新以下属性以匹配您的设置： ```json "context": { "githubConnectionArn": "arn:aws:codeconnections:eu-central-1:123456789012:connection/...", "githubRepo": "<您的用户名>/<您的仓库名称>", "githubBranch": "main" } ``` ### 3. 部署基础设施（零触摸部署） 系统使用 AWS CDK 自变管道。部署后端和前端栈： ```bash make bootstrap env=backend make deploy env=backend make bootstrap env=frontend make deploy env=frontend ``` ### 4. 获取实时应用 URL 当前端管道完成后，您可以通过运行以下命令轻松获取实时应用程序 URL： ```bash python frontend/scripts/get_cloudfront_url.py ``` ### 5. 创建用户账户 在登录前端之前，您必须在 Amazon Cognito 用户池中注册新用户。您可以通过导航到实时应用程序 URL（CloudFront）并点击 **注册** 按钮，或直接通过 AWS Cognito 控制台创建用户。确保使用与 `seed_data.py` 步骤中提供的相同电子邮件地址，以将您的合成订单历史记录链接到您的个人### 6. 生成合成数据 部署完成后，使用您附近的现实世界位置填充 DynamoDB 表： ```bash python frontend/scripts/seed_data.py ``` *（脚本将要求电子邮件地址，以便将测试数据绑定到您的 Cognito 账户，并使用 AWS Geo Places 查找您地址附近的实际位置）。* --- ## 🎯 测试 AI 助手（示例场景） 填充数据后，打开前端 Web 应用程序（CloudFront URL），登录，点击麦克风按钮，并尝试说出这些场景来测试各种后端工具和 DynamoDB 表：  **🧑‍💻 1. 客户资料（`QSR-Customers`）和过去订单（`QSR-Orders`）** > *"我到目前为止下了多少订单？顺便问一下，我有任何忠诚度积分和忠诚度等级吗？"* *（AI 将查询 DynamoDB 获取您的过去订单，计算它们，并检查您的个人资料中的忠诚度积分和等级）。* **🍔 2. 菜单价格和自定义（`QSR-Menu`）** > *"你们有什么样的汉堡？我想要豪华汉堡，但可以不要洋葱并添加额外奶酪吗？"* *（AI 将从 DynamoDB 获取菜单，验证“不加洋葱”是一种有效的自定义选项，并确认总价格）。* **🛒 3. 购物车管理（SR-Carts`）** > *"将那份豪华汉堡添加到我的购物车，再加一份大薯条。实际上，再加两份大薯条。"* *（AI 使用 API Gateway 工具创建购物车会话并动态更新 DynamoDB 中的商品）。* **📍 4. 位置感知和路由（`QSR-Locations`）** > *"我现在正在开车，离你们最近的分支在哪里？可以把我的订单送到那里吗？"* *（AI 将检测您的 GPS 位置，使用 AWS 位置服务查找最近的分支并路由最终订单）。## 🗑️ 要完全删除项目并停止费，您可以手动 控制台删除资源。 进入 **AWS CloudFormation 控制。 2. 删除所有 `Frontend 和 `Backend-*` 。 3. 自动3 存储桶（管道工件和 CDK 工具包）。 销毁 CDK 管道栈。 > ⚠️ **警告如果无法删除任何栈，请再点击一次删除，并为资源选中 **保留资源**）选项。这将成功。