内容
# 洞察与演示代理，用于微软Fabric和Foundry的运营数据
### 端到端示例：自然语言洞察发现和演示生成
本项目演示了如何将 **微软Fabric结构化数据** 连接到 **微软Foundry代理**，从而实现对实时运营数据的自然语言对话和通过MCP工具自动生成符合模板的PowerPoint演示文稿。
> Fabric Lakehouse → **对话代理** 通过自然语言显示洞察 → **演示代理** 通过MCP生成PowerPoint演示文稿
> [!TIP]
> 📖 **深入了解：** [解耦数据和逻辑 — 使用Fabric数据代理和Foundry自动化演示生成](https://stochasticcoder.com/2026/06/22/decoupling-data-and-logic-using-fabric-data-agents-and-foundry-to-automate-presentation-generation/)。配套文章介绍了架构和分离数据检索与演示逻辑的理由。
---
## 目录
- [从这里开始](#从这里开始)
- [本项目演示的模式](#本项目演示的模式)
- [架构](#架构)
- [项目结构](#项目结构)
- [部署](#部署)
- [配置](#配置)
- [清理](#清理)
---
*示例场景：LONGHAUL 运营仪表盘。左侧 — 对话代理回答有关运营利润率的问题。中间 — KPI 汇总和分析图表。右侧 — 按需演示生成。*
<table>
<tr>
<td width="240" valign="middle">
<a href="samples/LONGHAUL-MBR-South-May2025.pptx"><img src="media/South-May2025-Page1.jpg" alt="生成的South区域2025年5月月度业务回顾演示文稿的标题幻灯片" width="220"></a>
</td>
<td valign="middle">
<b>示例输出</b><br>
LONGHAUL 南区 2025 年 5 月的月度业务回顾；由演示代理端到端生成。<br><br>
<a href="samples/LONGHAUL-MBR-South-May2025.pptx">⬇ 下载演示文稿 (.pptx)</a>
</td>
</tr>
</table>
---
## 从这里开始
如果您正在探索：
- 如何将 **微软Fabric Lakehouse** 数据连接到 **微软Foundry代理** 而无需在提示中编写 SQL
- 如何使用 **Fabric数据代理** 作为结构化运营数据的自然语言接口
- 如何编排 **多轮对话代理** 以实时数据为基础进行推理
- 如何通过MCP工具驱动 **符合模板的PowerPoint生成**
- 如何在Azure容器应用上构建 **全栈AI平台**，并使用托管身份
→ 本项目提供所有三种模式的完整、可行的参考实现。
> **场景是示例，不是产品。** 示例使用 **LONGHAUL** — 一个虚构的长途货运公司，拥有 13 个月的 5 个地区和 20 种车辆类型的运营 KPI 数据。领域是可互换的；模式才是最重要的。
---
## 本项目演示的模式
### 模式 1 — Fabric 数据代理作为 AI 数据接口
本项目使用 **Fabric数据代理** 而不是在代理提示中编写 SQL 或硬编码查询，作为Lakehouse的专用自然语言接口。Foundry代理像调用工具一样调用它 — 用纯英文提问并接收直接从实时数据中提取的结构化答案。代理不需要 SQL 知识；Fabric 处理翻译。
### 模式 2 — 代理在实时运营数据上进行编排推理
**对话代理** 维护多轮线程，允许用户探索趋势、比较维度并深入了解驱动因素 — 所有这些都基于实时 Fabric 数据而非静态上下文或预计算的汇总。Foundry 管理线程状态和工具路由。
### 模式 3 — MCP 驱动的演示生成
**演示代理** 编排一个两步工作流：从 Fabric 数据代理检索 KPI，然后调用 MCP 工具 (`fill_presentation_template`)，该工具使用 `python-pptx` 填充 PowerPoint 模板，将完成的演示文稿上传到 Azure Blob Storage，并返回下载 URL。代理驱动整个流程；MCP 工具强制模板一致性 — 每个生成的演示文稿都遵循相同的结构。
### 将其适应您的领域
LONGHAUL 货运场景是一个示例。相同的三种模式适用于任何具有结构化运营数据和定期报告需求的领域：
- **零售** → 销售业绩、库存 KPI、区域分解
- **医疗保健** → 运营指标、患者结果、每项程序的成本
- **金融服务** → 投资组合业绩、风险指标、客户报告
- **制造业** → 生产效率、停机时间分析、质量指标
要适应：用您的数据替换 Fabric Lakehouse 表，更新 Fabric 数据代理和 Foundry 代理系统提示，并替换您的 PowerPoint 模板。
---
## 架构
```mermaid
flowchart TD
KV["🔐 Azure Key Vault\n代理 ID · 机密"]
FABRIC["📊 微软Fabric\nlh_trucking_ops Lakehouse\nda_trucking_ops 数据代理"]
subgraph FOUNDRY["微软Foundry"]
Models["🤖 模型\n· GPT-4.1\n· GPT-4.1-mini"]
subgraph AGENTS["代理"]
CONV["💬 对话代理\n多轮 KPI 问题解答"]
PRES["📑 演示代理\n生成完成的 MBR 演示文稿"]
end
end
subgraph CONTAINER_APPS["Azure 容器应用"]
API["⚙️ insights-api\nFastAPI · REST 网关（外部）"]
MCP["🔧 presentation-tools\nFastMCP · PowerPoint 工具（内部）"]
UI["🖥️ insights-ui\nReact + Vite · 仪表盘 + 聊天"]
end
STORAGE["🗄️ Azure Blob 存储\n模板 · 演示文稿 · 缩略图\n对话 · 演示文稿元数据"]
UI -->|"REST /api/*"| API
API -->|"Foundry SDK"| CONV & PRES
Models --> AGENTS
CONV & PRES -->|"FabricDataAgentTool"| FABRIC
PRES -->|"MCP streamable-http (内部)"| MCP
MCP -->|"python-pptx + LibreOffice"| STORAGE
API --> STORAGE
KV -->|"运行时机密"| API & FOUNDRY
```
### 核心组件
| 组件 | 技术 | 角色 |
|---|---|---|
| **对话代理** | 微软Foundry代理 | 对Fabric KPI数据进行多轮问答 |
| **演示代理** | 微软Foundry代理 | 编排KPI检索和演示文稿生成 |
| **da_trucking_ops** | Fabric数据代理 | Lakehouse的自然语言接口 |
| **lh_trucking_ops** | 微软Fabric Lakehouse | 13个月的货运运营KPI数据 |
| **insights-api** | FastAPI，Python | REST网关 — 将UI请求路由到代理和存储 |
| **presentation-tools** | FastMCP，Python | MCP服务器 — PowerPoint模板填充，演示文稿管理 |
| **insights-ui** | React，Vite | 仪表盘，KPI汇总条，对话聊天，MBR库 |
---
## 项目结构
<details>
<summary>展开以查看存储库布局</summary>
```
Fabric-Foundry-Insight-Presentation-Agents/
├── deploy.ps1 # 完整的端到端部署编排器
├── README.md # 此文件
│
├── agents/ # Foundry代理定义 + 部署器
│ ├── deploy.py # 创建/更新两个代理，写入 IDs 到 agents/agent_ids.json
│ ├── conversational_agent.py # 对话代理定义
│ └── presentation_agent.py # MBR 演示代理定义
│
├── apps/
│ ├── insights-api/ # FastAPI REST 网关（外部 ACA）
│ │ └── src/
│ │ ├── main.py # 应用程序入口点，路由器注册
│ │ ├── config.py # 环境/设置
│ │ ├── fabric.py # Fabric SQL 连接 + KPI 查询
│ │ ├── models.py # Pydantic 请求/响应模型
│ │ └── routes/ # kpis, analytics, presentations, templates, conversations
│ │
│ ├── presentation-tools/ # FastMCP 服务器（内部 ACA — 仅限代理）
│ │ └── src/
│ │ └── tools/
│ │ └── powerpoint_tools.py # fill_presentation_template, get_deck_url, get_template_slides
│ │
│ └── insights-ui/ # React + Vite SPA
│ └── src/
│ ├── App.jsx # 周期/区域状态，路由
│ ├── components/ # KpiSummaryBar, PresentationPanel, AnalyticsPanel, ConversationPanel
│ ├── hooks/ # useKpis, useAnalytics, usePresentationGeneration, useConversation
│ └── pages/ # 仪表盘，演示文稿库，对话
│
├── infra/ # 基础设施即代码（Terraform）
│ ├── main.tf # 根模块
│ ├── variables.tf
│ ├── outputs.tf
│ ├── terraform.tfvars.tpl # 模板 — 由 deploy.ps1 填充
│ └── modules/
│ ├── ai_services/ # Foundry 账户 + 项目 + GPT-4.1 部署
│ ├── container_apps/ # insights-api, presentation-tools, insights-ui 容器应用
│ ├── container_registry/ # Azure 容器注册表
│ ├── identity/ # 用户分配的托管身份 + RBAC
│ ├── key_vault/ # Key Vault + 机密
│ ├── monitoring/ # Log Analytics + 应用程序洞察
│ └── storage/ # Blob 存储（模板，演示文稿，缩略图，对话）
│
├── scripts/
│ ├── Deploy-Infrastructure.ps1 # 阶段 1：Terraform 应用
│ ├── Deploy-Containers.ps1 # 阶段 2：ACR 镜像构建和推送
│ ├── Deploy-FabricWorkspace.ps1 # 阶段 3：创建 Lakehouse，发现 SQL 端点
│ ├── Deploy-FabricLakehouse.ps1 # 阶段 3：创建表，填充数据，上传模板
│ ├── Deploy-FabricDataAgent.ps1 # 阶段 3b：创建 da_trucking_ops + 工作区 RBAC
│ ├── Deploy-FoundryAgents.ps1 # 阶段 4：部署 Foundry 代理
│ ├── New-GitHubOidc.ps1 # GitHub Actions OIDC 设置
│ └── common/
│ └── DeploymentFunctions.psm1 # 共享 PowerShell 实用程序
│
├── data/
│ └── templates/ # mbr_template.pptx — PowerPoint 模板
│
└── docs/
└── fabric-setup.md # Fabric 工作区、Lakehouse 和数据代理设置指南
```
</details>
---
## 部署
Fabric 工作区和 Lakehouse 必须在运行部署脚本之前存在 — 部署脚本会自动创建所有其他资源。
```powershell
az login
az account set --subscription "您的订阅名称或ID"
.\deploy.ps1 `
-Subscription "您的订阅名称或ID" `
-FabricWorkspaceId "<工作区GUID>"
```
`deploy.ps1` 自动运行六个阶段 — 基础设施、容器、Lakehouse 数据填充、Fabric 数据代理创建和 Foundry 代理部署（约 20-30 分钟）。脚本完成后，Fabric 门户中需要两个手动步骤。
→ **参见 [docs/deployment_steps.md](docs/deployment_steps.md) 以获取完整的操作指南**：前提条件、Fabric 工作区设置、所有部署阶段、部署后门户步骤、验证检查清单、GitHub Actions 和清理。
---
## 配置
<details>
<summary>展开以查看环境变量参考</summary>
### insights-api
| 变量 | 来源 | 描述 |
|---|---|---|
| `AZURE_CLIENT_ID` | 托管身份 | 用户分配的托管身份的客户端ID |
| `FOUNDRY_PROJECT_ENDPOINT` | Terraform 输出 | Foundry 项目端点 URL |
| `CONVERSATIONAL_AGENT_NAME` | 容器应用环境变量 | `ca-insights-api` 上由 `Deploy-FoundryAgents.ps1` 设置的代理名称 |
| `PRESENTATION_AGENT_NAME` | 容器应用环境变量 | `ca-insights-api` 上由 `Deploy-FoundryAgents.ps1` 设置的代理名称 |
| `FABRIC_SQL_SERVER` | Terraform 变量 | Fabric SQL 分析端点主机名 |
| `FABRIC_SQL_DATABASE` | Terraform 变量 | `lh_trucking_ops` |
| `STORAGE_ACCOUNT_URL` | Terraform 输出 | `https://<account>.blob.core.windows.net` |
### presentation-tools
| 变量 | 来源 | 描述 |
|---|---|---|
| `AZURE_CLIENT_ID` | 托管身份 | 用户分配的托管身份的客户端ID |
| `STORAGE_ACCOUNT_URL` | Terraform 输出 | `https://<account>.blob.core.windows.net` |
### Fabric 数据代理（`da_trucking_ops`）
| 设置 | 值 |
|---|---|
| 数据源 | `lh_trucking_ops` Lakehouse |
| Foundry 连接名称 | `da_trucking_ops` |
| 表 | `dim_month`, `dim_region`, `dim_vehicle_type`, `fact_monthly_kpis`, `fact_vehicle_kpis` |
| 数据范围 | 2024 年 5 月 – 2025 年 5 月（13 个月，5 个地区，20 种车辆类型） |
</details>
---
## 清理
测试完成后或不再需要时，拆除所有已部署的资源：
```powershell
.\deploy.ps1 -Subscription "您的订阅名称或ID" -Destroy
```
这会在所有 LONGHAUL Insight 资源上运行 `terraform destroy`。Terraform 状态存储帐户 (`rg-tfstate-ins`) **不会** 被销毁，如果不再需要，必须手动删除。
Fabric 工作区和 Lakehouse 不由 Terraform 管理，必须在 [Fabric 门户](https://app.fabric.microsoft.com) 中单独删除。
---
## 许可证
该项目根据 [MIT 许可证](LICENSE.md) 授权。
---
## 免责声明
**此代码仅用于教育和演示目的。**
此示例代码不适用于生产环境，提供时不附带任何形式的保证，包括但不限于适销性、特定用途适用性和非侵权保证。在任何情况下，作者或版权所有者均不承担因软件或软件使用或交易中的任何索赔、损害或其他责任而产生的任何责任，无论是在合同、侵权或其他情况下。
**关键点：**
- 这是一个 **演示项目**，展示 Fabric + Foundry AI 代理集成模式
- **不适用于生产环境**，除非进行大量额外的开发、测试和合规性审查
- 用户负责确保遵守适用的法规和安全要求
- 微软Azure和微软Fabric服务会产生费用 — 监控您的使用情况，并在完成后清理资源
- 不提供有关准确性、可靠性或适用于任何目的的保证或担保
使用此代码，即表示您理解这些限制并接受使用此代码所带来的全部责任。
