内容
# 雪花Cortex代理 + AWS基岩知识库 通过MCP
跨平台AI代理编排的参考架构 - 使用模型上下文协议（MCP）将Snowflake Cortex代理连接到AWS基岩知识库。
本项目演示了如何构建一个统一的AI代理，该代理在单个对话中查询两个平台的数据，代理智能地将问题路由到正确的数据源。
## 前提条件
### 雪花
- 具有 **ACCOUNTADMIN** 角色（或具有创建数据库、创建代理、创建语义视图权限的角色）的Snowflake账户
- 一个仓库（XS足够）- 脚本使用 `DEMO_WH`
- 在您的账户中启用Cortex代理（AI＆ML > 代理应在Snowsight中可见）
- 启用跨区域推理以访问模型：
```sql
ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';
```
### AWS
- 具有访问 **us-east-1** 区域权限的AWS账户
- 配置了具有凭证的AWS CLI（`aws configure`），凭证具有以下权限：
- S3：CreateBucket，PutObject
- 基岩：CreateKnowledgeBase，Retrieve
- Lambda：CreateFunction，UpdateFunctionCode
- API网关：CreateApi，CreateRoute
- Cognito：CreateUserPool，CreateUserPoolClient
- IAM：CreateRole，PutRolePolicy
- 安装了 `boto3` 的Python 3.10+
- 启用了亚马逊基岩模型访问（至少Titan Embed Text v2）
### 本地开发
- Python 3.10+
- Git
- SnowSQL CLI（或使用Snowsight SQL工作表运行 `.sql` 文件）
- 用于安装Python依赖的 `pip`
### 网络
- Snowflake账户必须能够访问AWS API网关端点（无网络策略阻止出站到 `*.execute-api.*.amazonaws.com`）
- 无VPN/防火墙阻止Cognito托管UI（ `*.auth.*.amazoncognito.com`）
## 本项目演示的内容
| 集成模式 | 实现 |
|---|---|
| 雪花Cortex代理作为编排器 | 使用基于LLM的规划在多个工具上路由查询 |
| Cortex分析师（文本到SQL） | 通过语义视图进行结构化数据查询 |
| Cortex搜索（RAG） | 通过向量搜索进行非结构化文档检索 |
| AWS基岩知识库作为MCP工具 | 通过MCP协议可访问的外部数据 |
| OAuth2到IAM桥 | Lambda + API网关 + Cognito在身份验证系统之间转换 |
| 跨平台编排 | 单个查询在雪花和AWS上触发工具 |
## 架构
有关详细的技術文档，包括身份验证流程、MCP协议细节、安全模型和延迟特性，请参阅 [diagrams/architecture.md](diagrams/architecture.md)。
```
┌─────────────────────────────────────────────────────────┐
│ 雪花Cortex代理（编排器） │
│ 模型：自动 | 预算：60秒 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │
│ │ Cortex │ │ Cortex │ │ 外部MCP │ │
│ │ 分析师 │ │ 搜索 │ │ 服务器 │ │
│ │ （文本到SQL）│ │ （RAG） │ │ （AWS基岩） │ │
│ └──────┬───────┘ └──────┬───────┘ └───────┬────────┘ │
└─────────┼────────────────┼──────────────────┼───────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌────────────────────┐
│ 语义视图 │ │ Cortex搜索 │ │ AWS API网关 │
│ （结构化 │ │ 服务 │ │ + Cognito（OAuth2） │
│ 表格） │ │ （非结构化 │ │ │ │
└──────────────┘ │ 文档） │ │ Lambda MCP服务器 │
└──────────────┘ │ （实现MCP） │
│ │ │
│ 基岩托管 │
│ 知识库 │
│ │ │
│ S3文档 │
└────────────────────┘
```
## 集成挑战
雪花外部MCP服务器 **仅支持OAuth2身份验证**。AWS基岩服务使用 **IAM/SigV4身份验证**。这些是根本不同的身份验证系统：
- **OAuth2**：以用户为中心、基于令牌、云无关的标准
- **SigV4/IAM**：AWS特定、请求签名、机器到机器
本项目通过一个Lambda函数解决了这一差距：
1. 接受OAuth2身份验证的请求（由API网关 + Cognito验证）
2. 实现MCP协议（工具/列表，工具/调用）
3. 使用其IAM执行角色调用基岩知识库检索API
4. 以MCP格式将结果返回给雪花
## 示例用例：供应链制造
包含的示例使用制造供应链场景来演示与现实数据的集成：
| 数据位置 | 数据类型 | 内容 |
|---|---|---|
| 雪花（结构化） | 表格与语义视图 | 供应商、材料、生产订单、工厂位置、物联网遥测数据 |
| 雪花（非结构化） | Cortex搜索服务 | 供应商电子邮件通信、质量审计报告 |
| AWS S3 + 基岩知识库 | 文档通过MCP | 运费、客户退货/RMA、合规/ISO认证 |
Cortex代理跨所有源编排 - 一个问题，如 *"对于质量有问题的供应商，他们所在地区的运费是多少，客户是否抱怨过？"* 在一次调用中触发分析师（结构化查询）、Cortex搜索（电子邮件）和MCP工具（基岩知识库）。
## 设置步骤
### 雪花侧
```bash
# 1. 创建数据库、表格和合成数据
snowsql -f snowflake/01_data_setup.sql
# 2. 创建Cortex搜索服务（非结构化数据的向量索引）
snowsql -f snowflake/02_cortex_search.sql
# 3. 创建语义视图（Cortex分析师文本到SQL的模式）
snowsql -f snowflake/03_semantic_view.sql
# 4. 创建具有雪花原生工具的Cortex代理
snowsql -f snowflake/04_cortex_agent.sql
```
### AWS侧
```bash
cd aws
pip install -r requirements.txt
# 5. 上传文档到S3并创建基岩托管知识库
python setup_knowledge_base.py
# 6. 部署Lambda MCP服务器 + API网关 + Cognito
python deploy_oauth_proxy.py --kb-id <KB_ID>
```
### 连接平台
```bash
# 7. 在雪花中创建指向Lambda的外部MCP服务器
# 编辑05_mcp_connection.sql并使用步骤6中的值，然后：
snowsql -f snowflake/05_mcp_connection.sql
# 8. 在雪花CoWork中认证
# 进入代理 > 连接器 > 连接 > 使用Cognito凭证登录
```
## 关键组件
### 创建的雪花对象
| 对象 | 类型 | 目的 |
|---|---|---|
| `MFG_OPERATIONS_AGENT` | Cortex代理 | 编排器，带有3个原生工具 + 1个MCP工具 |
| `MFG_OPERATIONS_SV` | 语义视图 | 在结构化表格上启用文本到SQL |
| `SUPPLIER_COMMS_CSS` | Cortex搜索服务 | 供应商电子邮件的向量搜索 |
| `QUALITY_REPORTS_CSS` | Cortex搜索服务 | 质量报告的向量搜索 |
| `AWS_LOGISTICS_MCP` | 外部MCP服务器 | 通过OAuth2连接到AWS Lambda |
| `aws_logistics_mcp_integration` | API集成 | OAuth2配置（Cognito端点） |
### 创建的AWS资源
| 资源 | 服务 | 目的 |
|---|---|---|
| S3存储桶 + 文档 | S3 | 知识库的源数据 |
| 托管知识库 | 基岩 | 文档的RAG检索 |
| Lambda函数 | Lambda | MCP服务器实现（工具/列表 + 工具/调用） |
| HTTP API | API网关 | 带有JWT授权器的HTTPS端点 |
| 用户池 + 应用程序客户端 | Cognito | 为雪花颁发OAuth2令牌 |
### MCP协议实现
Lambda实现了这些MCP方法：
| 方法 | 功能 |
|---|---|
| `tools/list` | 返回工具模式（`retrieve_logistics_docs`带有查询 + numberOfResults参数） |
| `tools/call` | 调用 `bedrock-agent-runtime:Retrieve` 并返回格式化结果 |
| `initialize` | 返回服务器功能 |
## 示例问题
在下面的 [示例问题](#sample-questions-1) 部分中查看 35 个示例问题的完整列表，按以下类别组织：
- **类别A** （15个问题）：仅限雪花 - 使用Cortex分析师和/或Cortex搜索
- **类别B** （10个问题）：仅限AWS - 通过MCP使用基岩知识库
- **类别C** （10个问题）：跨平台编排 - 跨雪花和AWS编排
## 文件结构
```
├── README.md ← 您在这里
├── snowflake/
│ ├── 01_data_setup.sql ← 数据库 + 表格 + 合成数据
│ ├── 02_cortex_search.sql ← Cortex搜索服务
│ ├── 03_semantic_view.sql ← 语义视图，用于Cortex分析师文本到SQL
│ ├── 04_cortex_agent.sql ← 具有雪花原生工具的代理
│ └── 05_mcp_connection.sql ← 外部MCP服务器 + ALTER代理
├── aws/
│ ├── requirements.txt
│ ├── setup_knowledge_base.py ← S3上传 + 基岩知识库创建指南
│ ├── deploy_oauth_proxy.py ← Lambda + API网关 + Cognito部署
│ ├── test_gateway.py ← 端到端MCP服务器测试
│ ├── lambda/
│ │ └── mcp_proxy_handler.py ← MCP服务器实现
│ └── sample_documents/ ← 基岩知识库文档
│ ├── freight_costs/
│ ├── customer_returns/
│ └── compliance/
├── demo/
│ ├── requirements.txt
│ └── run_demo.py ← 代理REST API演示客户端
└── diagrams/
└── architecture.md ← 详细的技術架构
```
## 适应您的用例
这是参考架构。要适应您的领域：
1. **替换雪花数据** - 用您自己的结构化/非结构化数据替换供应链表格
2. **替换S3文档** - 将您自己的文档上传到基岩知识库
3. **更新语义视图** - 构建表格的事实、维度、指标模型
4. **更新代理指令** - 更改工具的编排路由规则
5. **保持MCP桥接器不变** - Lambda/API网关/Cognito基础设施适用于任何基岩知识库
集成模式（雪花和AWS之间的OAuth2桥接器）是领域无关的。
---
## 示例问题
### 类别A：仅限雪花（Cortex分析师 + Cortex搜索）
| # | 问题 | 使用的工具 |
|---|----------|-----------|
| A1 | 哪些供应商的质量评级低于3.5，他们发送了哪些通信？ | 分析师 + 供应商通信搜索 |
| A2 | 显示产量低于94%的生产订单和任何相关的质量审计发现 | 分析师 + 质量报告搜索 |
| A3 | 按工厂计算平均生产产量，哪些工厂的缺陷最多？ | 分析师 |
| A4 | 查找所有关于不可抗力事件或生产中断的供应商通信 | 供应商通信搜索 |
| A5 | 我们的工厂中有哪些关键质量审计发现仍然存在？ | 质量报告搜索 |
| A6 | 什么是关键材料的总库存价值，哪些材料低于补货点？ | 分析师 |
| A7 | 哪些来自中国的供应商发送了价格上涨通知？ | 分析师 + 供应商通信搜索 |
| A8 | 显示按缺陷计数排序的汽车类别生产订单 | 分析师 |
| A9 | 深圳电子厂发现了哪些纠正措施？ | 质量报告搜索 |
| A10 | 哪些材料的库存水平低于最低库存水平，哪些是他们的供应商？ | 分析师 |
| A11 | 整个工厂的按时完成率是多少？ | 分析师 |
| A12 | 查找关于质量问题的通信，并将其与供应商质量评级相关联 | 分析师 + 供应商通信搜索 |
| A13 | 显示与焊接相关的质量发现以及受影响的生产订单 | 质量报告搜索 + 分析师 |
| A14 | 我们的最高成本生产订单是什么，哪些工厂生产了它们？ | 分析师 |
| A15 | 是否有供应商就产能限制或交货时间变化进行沟通？ | 供应商通信搜索 |
### 类别B：仅限AWS（通过MCP的基岩知识库）
| # | 问题 | 使用的工具 |
|---|----------|-----------|
| B1 | 上海到洛杉矶的当前海运费率是多少？ | MCP |
| B2 | 斯图加特到德克萨斯州奥斯汀的空运费率是多少？ | MCP |
| B3 | 显示与电子产品或焊料缺陷相关的客户退货投诉 | MCP |
| B4 | 我们的制造工厂持有哪些ISO认证，哪些处于监管之下？ | MCP |
| B5 | 对铝进口到中国征收哪些关税（Section 232关税）？ | MCP |
| B6 | 是否有潜在监管影响的保修索赔？ | MCP |
| B7 | 从蒙特雷墨西哥到奥斯汀的陆运费率是多少？ | MCP |
| B8 | 显示环氧树脂和液压油的材料安全数据表信息 | MCP |
| B9 | 我们的墨西哥供应商适用哪些USMCA优惠关税率？ | MCP |
| B10 | 液压阀体客户退货的财务影响是什么？ | MCP |
### 类别C：跨平台编排（雪花 + AWS）
| # | 问题 | 使用的工具 |
|---|----------|-----------|
| C1 | 对于质量评级低于3.5的供应商，他们所在地区的运费是多少，客户是否投诉过他们的产品？ | 分析师 + MCP |
| C2 | 底特律制造中心出现焊接质量问题 - 显示受影响的生产订单、质量审计发现和关于这些产品的任何客户退货投诉 | 分析师 + 质量报告搜索 + MCP |
| C3 | 比较亚太地区和北美地区供应商的总到岸成本（材料成本 + 运费 + 关税） | 分析师 + MCP |
| C4 | 哪些生产订单有高缺陷率，并导致客户保修索赔？ | 分析师 + MCP |
| C5 | 深圳QuickParts的完整风险概况是什么 - 质量评级、关于问题的通信、工厂的质量审计发现、使用他们的材料、客户退货？ | 分析师 + 供应商通信搜索 + 质量报告搜索 + MCP |
| C6 | 对于我们的航空航天产品类别，生产收益率是多少，哪些质量审计相关，合规认证是什么？ | 分析师 + 质量报告搜索 + MCP |
| C7 | 哪些供应商就价格上涨进行沟通，他们所在地区的运费是多少，这对我们的总生产成本有何影响？ | 供应商通信搜索 + MCP + 分析师 |
| C8 | 显示电动汽车电池生产的整个供应链风险 - 材料库存水平、供应商可靠性、奥斯汀工厂的质量问题、亚洲的运费和客户退货 | 分析师 + 供应商通信搜索 + 质量报告搜索 + MCP |
| C9 | 日本的海运费率是多少，日本钢的交付表现和质量评级是多少？ | MCP + 分析师 |
| C10 | 对于有客户保修索赔的产品，追溯到哪些工厂生产了它们，存在哪些质量发现，供应商沟通了什么 | MCP + 质量报告搜索 + 供应商通信搜索 + 分析师 |
