第 10 章 · 快速开始

10.1 概览

本章帮助你在 30 分钟内 完成 ADAP 的端到端体验：从准备测试数据源，到创建第一个分析项目，到查看 AI 自动生成的 QuickSight 仪表盘。

前提

已完成第 9 章的基础设施部署（推荐使用一键部署脚本 scripts/deploy.sh）
已完成 Cognito 用户初始化，能够登录前端
有一个可访问的 MySQL 数据源（或使用本章提供的本地 Demo 模式）

10.1.1 一键部署（推荐）

如尚未完成部署，可使用 ADAP 提供的一键部署脚本：

bash

# 克隆项目
git clone <repo-url>
cd agentic-data-platform

# 运行一键部署脚本（约 20~30 分钟）
bash scripts/deploy.sh \
  --account-id <YOUR_AWS_ACCOUNT_ID> \
  --qs-user <RoleName/SessionName>

脚本将自动完成：

环境检查（aws cli、python3、node、cdk 版本校验）
CDK 部署所有 Stack（IAM → S3 → Auth → AgentCore → Compute → API → Orchestration 等）
提取 CDK Output，写入 .deploy-outputs.json
构建 Lambda 部署包
自动生成前端 .env.production 配置
部署 AgentCore Agents（7 个 Agent）
构建并部署前端（Nginx 或 S3/CloudFront）
验证部署结果并输出摘要

常用参数：

参数	说明
`--account-id`	AWS 账号 ID（必填）
`--qs-user`	QuickSight 用户名，格式 `RoleName/SessionName`（用于创建仪表盘权限）
`--region`	AWS Region，默认 `us-east-1`
`--skip-cdk`	跳过 CDK 部署（仅重新部署 Agent 或前端）
`--skip-agentcore`	跳过 AgentCore Agent 部署
`--skip-frontend`	跳过前端构建和部署
`--ec2-host`	EC2 公网 IP（前端部署到 Nginx 时使用）
`--ec2-key`	EC2 SSH 密钥文件路径
`--dry-run`	仅检查环境，不实际部署

10.2 准备测试数据源

10.2.1 选项 A：生成电商 Demo 数据（推荐）

ADAP 内置了一份电商业务的模拟数据集，包含：

表名	行数	说明
customers	50,000	注册用户（含城市、省份、VIP 等级）
products	1,000	商品（多级分类、品牌、成本/售价）
orders	100,000	过去 1 年的订单（含状态、收货地址）
order_items	~300,000	订单明细（平均 3 件/单）
payments	~95,000	支付记录（95% 支付率）

步骤 1：创建数据库结构

bash

mysql -h <your-rds-host> -u admin -p < scripts/setup_mysql.sql

步骤 2：生成并写入模拟数据

bash

source .venv/bin/activate

python scripts/generate_mock_data.py \
  --host <your-rds-host> \
  --port 3306 \
  --database ecommerce \
  --username admin \
  --password <your-password>

数据生成约需 3~5 分钟，进度条会实时显示写入进度。

步骤 3：验证数据

bash

mysql -h <your-rds-host> -u admin -p ecommerce -e "
  SELECT 'customers' AS tbl, COUNT(*) AS cnt FROM customers
  UNION ALL
  SELECT 'products', COUNT(*) FROM products
  UNION ALL
  SELECT 'orders', COUNT(*) FROM orders
  UNION ALL
  SELECT 'order_items', COUNT(*) FROM order_items
  UNION ALL
  SELECT 'payments', COUNT(*) FROM payments;
"

预期输出：

+-------------+--------+
| tbl         | cnt    |
+-------------+--------+
| customers   | 50000  |
| products    |  1000  |
| orders      | 100000 |
| order_items | 301234 |
| payments    |  95012 |
+-------------+--------+

10.2.2 选项 B：使用已有 MySQL 数据源

任何 MySQL 5.7+ / 8.0 的数据库均可直接接入，无需预先准备。ADAP 的「数据产品经理 Agent」会自动探索表结构并识别业务背景。

确保 ADAP Lambda 的 VPC / 安全组能够访问目标数据库，或使用公网 RDS Endpoint。

10.2.3 获取 JDBC 连接串

jdbc:mysql://<host>:<port>/<database>?useSSL=false&serverTimezone=Asia/Shanghai

示例：

jdbc:mysql://mydb.us-east-1.rds.amazonaws.com:3306/ecommerce?useSSL=false&serverTimezone=Asia/Shanghai

10.3 登录 ADAP

10.3.1 访问前端

在浏览器打开 ADAP 前端地址：

EC2 Nginx 部署：http://<ec2-public-ip>
S3 + CloudFront 部署：https://<cloudfront-domain>

10.3.2 注册 / 登录

首次访问会看到登录页面。使用在第 9.8 节创建的账号登录，或点击「注册」创建新账号（如果 Cognito 开启了自注册）。

登录成功后进入项目列表页，初始为空。

10.4 创建第一个分析项目

10.4.1 点击「新建项目」

在项目列表页右上角点击 「新建项目」 按钮，打开新建项目对话框。

10.4.2 填写数据源信息

字段	示例值	说明
JDBC URL	`jdbc:mysql://mydb.us-east-1.rds.amazonaws.com:3306/ecommerce?useSSL=false`	MySQL 连接串
用户名	`admin`	数据库用户名
密码	`yourpassword`	明文密码（传输加密，后端存入 SSM）
项目描述（可选）	`电商业务数据分析`	给 AI 的提示，可为空

💡 提示：项目描述是可选的。填写业务背景（如"这是一个跨境电商平台的订单和用户数据"）可以帮助 AI 更快识别行业背景，生成更贴切的分析方向。

10.4.3 提交并等待分析

点击「创建」后，系统会：

立即返回 project_id，页面跳转到项目详情页
后台启动 Step Functions 状态机，开始 AI 分析流程
通过 WebSocket 实时推送执行进度到前端

你可以在项目详情页看到实时的阶段进度：

● PRD 生成中...          ← 数据产品经理 Agent 正在探索数据
○ 数据建模
○ 数据接入
○ 查询构建
○ 可视化

10.5 观察 AI 分析过程

10.5.1 PRD 生成阶段（约 3~5 分钟）

「数据产品经理 Agent」（Claude Opus）会：

连接 MySQL，探索所有表的 Schema（列名、类型、样本值）
识别业务背景（电商 / 零售 / 金融等）
设计四层数仓架构（ODS / DWD / DWS / ADS）
生成结构化 PRD（JSON 格式），包含：
- 行业识别结果
- 数仓表设计（含表名、字段、分区、质量规则）
- 推荐分析指标和仪表盘方向

Human-in-the-Loop（HitL）：PRD 生成完毕后，系统暂停等待人工审批。前端会显示 PRD 预览，你需要选择：

「批准」：继续执行后续阶段
「修改」：编辑 PRD 后再批准
「拒绝」：终止流程

10.5.2 数据建模与接入阶段（约 5~10 分钟）

HitL 批准后，后续阶段自动执行：

阶段	Agent	说明
数据接入	Data Integration	运行 Glue Job，MySQL → S3 ODS（Parquet）
数据建模	Chief Architect	生成四层 SQL 脚本，Athena 执行建表
数据治理	Data Governance	评估数据质量，注册 Glue Catalog
查询构建	Query Builder	验证 ADS 层指标 SQL 准确性
可视化	Visualization	在 QuickSight 创建数据集和仪表盘

每个阶段完成后，前端进度条会更新并展示关键日志。

10.5.3 实时事件日志

在项目详情页的「执行日志」面板，可以看到每个 Agent 发出的关键事件：

[10:23:15] PRD Agent: 探索到 5 张表，识别业务类型：电商零售
[10:24:02] PRD Agent: 设计四层架构，ADS 层包含 8 个指标主题
[10:26:33] HitL: 等待用户审批 PRD...
[10:27:01] 用户批准 PRD，继续执行
[10:27:05] Data Integration: 开始接入 customers 表...
[10:28:40] Data Integration: 已写入 50,000 行到 S3 ODS
[10:34:12] Chief Architect: 数仓建模完成，创建了 12 张 Athena 表
[10:36:45] Visualization: QuickSight 仪表盘创建成功

10.6 查看分析结果

10.6.1 在 ADAP 前端查看指标

项目完成后，「监控」页面展示：

成本明细：本次运行的 AWS 各服务费用（Bedrock、Glue、Athena、QuickSight）
执行耗时：各阶段的时间分布
资源清单：已创建的 Glue 数据库、Athena 表、S3 路径

10.6.2 查看数据画像报告

在项目详情页的「数据画像」标签，可以看到 Analytics Advisor Agent 自动生成的画像报告，包括：

整体评分（0–100）：综合数据质量、维度丰富度、时间跨度等六个维度
关键洞察：如「orders 表 10 万条记录横跨 62 个月，适合趋势分析」
表结构统计：每张表的行数、字段数、null 率、高频值
表间关联关系：自动探测到的关联字段（置信度 ≥ 0.5 的才显示）
分析方向建议：面向 DWS/ADS 层设计的建模提示

10.6.3 在 QuickSight 查看仪表盘

对于电商数据集：

仪表盘	指标示例
销售概览	日/月 GMV 趋势、订单量、客单价
用户分析	新增用户趋势、省份分布、VIP 等级分布
商品分析	分类销售排行、库存周转率、毛利率分布
支付分析	支付成功率、支付渠道分布

10.6.4 直接用 Athena 查询

ADAP 在 Glue Catalog 中创建了四层数据库，可以直接在 Athena 控制台查询：

sql

-- 查询 ADS 层：近 30 天各省份 GMV
SELECT
    province,
    SUM(order_amount) AS gmv,
    COUNT(DISTINCT order_id) AS order_cnt
FROM adap_<project_id>_ads.ads_province_sales_daily
WHERE stat_date >= DATE_ADD('day', -30, CURRENT_DATE)
GROUP BY province
ORDER BY gmv DESC
LIMIT 10;

10.7 API 快速体验

如果你希望通过 API 集成 ADAP，以下是最常用的 3 个接口：

10.7.1 获取 JWT Token

bash

API_URL="https://<rest-api-id>.execute-api.us-east-1.amazonaws.com/prod"
CLIENT_ID="<cognito-client-id>"

TOKEN=$(aws cognito-idp initiate-auth \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=admin@example.com,PASSWORD=YourPassword \
  --client-id "$CLIENT_ID" \
  --query 'AuthenticationResult.IdToken' \
  --output text)

echo "Token: ${TOKEN:0:50}..."

10.7.2 创建分析项目

bash

curl -X POST "$API_URL/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jdbc_url": "jdbc:mysql://mydb.us-east-1.rds.amazonaws.com:3306/ecommerce?useSSL=false",
    "username": "admin",
    "password": "yourpassword",
    "description": "电商业务数据分析"
  }'

响应示例：

json

{
  "project_id": "proj-20240506-a1b2c3",
  "status": "running",
  "message": "项目已创建，分析流程已启动",
  "created_at": "2024-05-06T10:23:00Z"
}

10.7.3 查询项目状态

bash

PROJECT_ID="proj-20240506-a1b2c3"

curl -s "$API_URL/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

响应示例：

json

{
  "project_id": "proj-20240506-a1b2c3",
  "status": "completed",
  "phases": {
    "prd": "completed",
    "data_ingestion": "completed",
    "data_modeling": "completed",
    "visualization": "completed"
  },
  "cost_usd": 0.47,
  "duration_seconds": 823,
  "quicksight_dashboard_url": "https://us-east-1.quicksight.aws.amazon.com/..."
}

10.8 WebSocket 实时监听

如果你要在自己的应用中监听执行进度，可以通过 WebSocket 订阅事件流：

python

import asyncio
import websockets
import json

async def watch_project(ws_url, token, project_id):
    uri = f"{ws_url}?token={token}"
    async with websockets.connect(uri) as ws:
        # 订阅指定项目的事件
        await ws.send(json.dumps({
            "action": "subscribe",
            "project_id": project_id
        }))
        print(f"已订阅项目 {project_id} 的实时事件...")

        async for message in ws:
            event = json.loads(message)
            phase = event.get("phase", "")
            msg   = event.get("message", "")
            status = event.get("status", "")
            print(f"[{phase}] {status}: {msg}")

            if event.get("status") in ("completed", "failed"):
                print("流程结束，断开连接")
                break

# 运行
WS_URL = "wss://<ws-api-id>.execute-api.us-east-1.amazonaws.com/prod"
asyncio.run(watch_project(WS_URL, TOKEN, PROJECT_ID))

10.9 常见问题（Quick Start FAQ）

Q：创建项目后一直显示「PRD 生成中」，超过 10 分钟没有进展？

A：检查以下几点：

Bedrock 模型访问权限是否开通（Claude Sonnet 4.6 / Opus）
Lambda 执行角色是否有 Bedrock 调用权限
查看 Lambda 日志：aws logs tail /aws/lambda/adap-agent-runner --follow

Q：PRD 生成完成但 HitL 审批按钮没出现？

A：WebSocket 连接可能断开。刷新页面重新连接，或直接调用 HitL API：

bash

curl -X POST "$API_URL/projects/$PROJECT_ID/hitl/approve" \
  -H "Authorization: Bearer $TOKEN"

Q：Glue Job 失败，错误提示「Access Denied」？

A：IAM Role ADAP-GlueServiceRole 缺少对目标 S3 Bucket 的权限。检查 infra/cdk/iam_stack.py 中的 S3 Policy，确认 Bucket 名称与 adap-prototype-* 模式匹配。

Q：QuickSight 仪表盘显示空白？

A：QuickSight 需要额外的 IAM 权限和 S3 访问授权。确认：

QuickSight 账号已订阅（Console → QuickSight → Sign up）
QuickSight 可以访问 Athena 和对应的 S3 Bucket

Q：如何重新运行某个项目？

A：目前每次请求会创建新项目。如需复用已有的 ODS 数据，可在创建时传入 "reuse_ods": true（需要数据接入 Agent 支持，当前版本按 project_id 隔离 ODS）。

Q：单次分析大概花多少钱？

A：以 5 张表、约 50 万行数据为例，典型成本约 $0.30~$0.80：

服务	费用估算
Bedrock（Claude Opus/Sonnet）	~$0.20~$0.50
Glue ETL（接入 + 建模）	~$0.05~$0.15
Athena（查询验证）	~$0.01~$0.05
Step Functions	~$0.01
其他（DynamoDB、S3、Lambda）	< $0.05

10.10 下一步

完成第一个项目后，可以探索以下进阶功能：

功能	参考章节
了解各 Agent 的详细工作原理	第 4 章 Agent 架构
查看数仓分层设计规范	第 5 章数据仓库与数据治理
配置监控告警	第 8 章监控与成本
生产环境部署与多环境管理	第 9 章部署指南
REST API 完整接口文档	docs/api-reference.md
E2E 测试与质量验证	docs/e2e-test-guide.md

本章参考来源：scripts/generate_mock_data.py、scripts/setup_mysql.sql、scripts/deploy_frontend.sh、api/handlers/agent_runner.py、docs/api-reference.md、docs/e2e-test-guide.md

第 10 章 · 快速开始 ​

10.1 概览 ​

前提 ​

10.1.1 一键部署（推荐） ​

10.2 准备测试数据源 ​

10.2.1 选项 A：生成电商 Demo 数据（推荐） ​

10.2.2 选项 B：使用已有 MySQL 数据源 ​

10.2.3 获取 JDBC 连接串 ​

10.3 登录 ADAP ​

10.3.1 访问前端 ​

10.3.2 注册 / 登录 ​

10.4 创建第一个分析项目 ​

10.4.1 点击「新建项目」 ​

10.4.2 填写数据源信息 ​

10.4.3 提交并等待分析 ​

10.5 观察 AI 分析过程 ​

10.5.1 PRD 生成阶段（约 3~5 分钟） ​

10.5.2 数据建模与接入阶段（约 5~10 分钟） ​

10.5.3 实时事件日志 ​

10.6 查看分析结果 ​

10.6.1 在 ADAP 前端查看指标 ​

10.6.2 查看数据画像报告 ​

10.6.3 在 QuickSight 查看仪表盘 ​

10.6.4 直接用 Athena 查询 ​

10.7 API 快速体验 ​

10.7.1 获取 JWT Token ​

10.7.2 创建分析项目 ​

10.7.3 查询项目状态 ​

10.8 WebSocket 实时监听 ​

10.9 常见问题（Quick Start FAQ） ​

10.10 下一步 ​

第 10 章 · 快速开始

10.1 概览

前提

10.1.1 一键部署（推荐）

10.2 准备测试数据源

10.2.1 选项 A：生成电商 Demo 数据（推荐）

10.2.2 选项 B：使用已有 MySQL 数据源

10.2.3 获取 JDBC 连接串

10.3 登录 ADAP

10.3.1 访问前端

10.3.2 注册 / 登录

10.4 创建第一个分析项目

10.4.1 点击「新建项目」

10.4.2 填写数据源信息

10.4.3 提交并等待分析

10.5 观察 AI 分析过程

10.5.1 PRD 生成阶段（约 3~5 分钟）

10.5.2 数据建模与接入阶段（约 5~10 分钟）

10.5.3 实时事件日志

10.6 查看分析结果

10.6.1 在 ADAP 前端查看指标

10.6.2 查看数据画像报告

10.6.3 在 QuickSight 查看仪表盘

10.6.4 直接用 Athena 查询

10.7 API 快速体验

10.7.1 获取 JWT Token

10.7.2 创建分析项目

10.7.3 查询项目状态

10.8 WebSocket 实时监听

10.9 常见问题（Quick Start FAQ）

10.10 下一步