python-visuals

Power BI 中的 Python 可视化（PBIR）

所有报表修改都必须使用 pbir。 仅将 PBIR 元数据用于诊断。如果 pbir 不可用或缺少所需操作，请停止并报告缺失项；绝不要直接编辑报表 JSON。

Python 可视化通过执行 matplotlib/seaborn 脚本，在 Power BI 画布上呈现静态 PNG 图像。优先使用 seaborn，而非原始 matplotlib，这样语法更简洁，默认设置也更好——它只需更少代码即可处理大多数图表类型。

可视化标识

• visualType： pythonVisual
• 数据角色： Values（列和度量值，可添加多个）
• 数据变量： dataset（自动注入的 pandas DataFrame）
• 行数上限： 150,000 行
• 输出： 72 DPI 静态 PNG——不支持交互

工作流：创建 Python 可视化

步骤 1：添加可视化

pbir add visual pythonVisual "Report.Report/Page.Page" --name PythonChart \
  --data "Values:Sales.Date" --data "Values:Sales.Revenue"

步骤 2：编写脚本

import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(8, 4))
ax.bar(dataset["Date"], dataset["Sales"], color="#5B8DBE")
ax.spines["top"].set_visible(False)
ax.spines["right"].set_visible(False)
plt.tight_layout()
plt.show()  # MANDATORY

关键规则：

• 最后一行必须是 plt.show()——没有它就不会呈现任何内容
• dataset 会自动注入为 pandas DataFrame；不要创建它
• 列名与字段绑定中的 nativeQueryRef（显示名称）一致
• 只有最后一次 plt.show() 调用会呈现内容；不支持多个图形

步骤 2b：审核

在向用户提供脚本之前，调用 python-reviewer Agent 验证正确性并提供设计反馈。

步骤 3：注入脚本

pbir visuals python "Report.Report/Page.Page/PythonChart.Visual" \
  --script-file chart.py

CLI 会处理 PBIR 字符串转义。

步骤 4：验证

pbir visuals bind "Report.Report/Page.Page/PythonChart.Visual" --show
pbir validate "Report.Report" --all

PBIR 格式

用于只读诊断时，脚本存储在 visual.objects.script[0].properties 中：

{
  "source": {"expr": {"Literal": {"Value": "'import matplotlib.pyplot as plt\\n...\\nplt.show()'"}}},
  "provider": {"expr": {"Literal": {"Value": "'Python'"}}}
}

CLI 会自动处理所有转义。

支持的库

Power BI Service（Python 3.11）

Package	Version	用途
matplotlib	3.8.4	主要绘图
seaborn	0.13.2	统计可视化
numpy	2.0.0	数值计算
pandas	2.2.2	数据处理
scipy	1.13.1	科学计算
scikit-learn	1.5.0	机器学习
statsmodels	0.14.2	统计模型
pillow	10.4.0	图像处理

不支持： plotly、bokeh、altair（Service 中的网络访问受阻）。

完整的软件包列表：https://learn.microsoft.com/power-bi/connect-data/service-python-packages-support

桌面端

任何本地安装的软件包均可不受限制地使用。

最佳实践

1. 始终调用 plt.show()——这是必需的，且必须位于最后一行
2. 使用 figsize=(w, h) 使图形与容器宽高比匹配（输出为 72 DPI）
3. 移除图表装饰——例如 ax.spines["top"].set_visible(False)
4. 使用与报表主题匹配的十六进制颜色
5. 保持脚本简单——桌面端超时为 5 分钟，Service 超时为 1 分钟
6. 尽量减少转换操作——应改用 DAX/Power Query 执行繁重计算
7. 使用 try/except，提高生产脚本的健壮性
8. 先复制数据——操作数据前先执行 data = dataset.copy()

限制

限制项	桌面端	Service
输出	72 DPI 静态 PNG	72 DPI 静态 PNG
超时	5 分钟	1 分钟
行数上限	150,000	150,000
负载	--	30 MB
网络访问	不受限制	受阻
网关	仅个人网关	仅个人网关
发起交叉筛选	不支持	不支持
接收交叉筛选	支持	支持
发布到 Web	不支持	不支持
嵌入（应用拥有数据）	不支持	不支持

脚本结构模板

import matplotlib.pyplot as plt
import numpy as np

# 1. Guard against empty data
if dataset.empty:
    fig, ax = plt.subplots(1, 1, figsize=(6, 4))
    ax.text(0.5, 0.5, "No data available", ha='center', va='center', fontsize=14, color='#888888')
    ax.axis('off')
    plt.show()
else:
    # 2. Data preparation (dataset is auto-injected)
    data = dataset.copy()

    # 3. Create figure with explicit size
    fig, ax = plt.subplots(figsize=(8, 4))

    # 4. Plot
    ax.plot(data["X"], data["Y"], color="#5B8DBE", linewidth=2)

    # 5. Style
    ax.spines["top"].set_visible(False)
    ax.spines["right"].set_visible(False)
    ax.grid(axis="y", alpha=0.3)

    # 6. Layout and render
    plt.tight_layout()
    plt.show()

何时使用脚本视觉对象

只有在以下所有条件都满足时，才使用 Python 视觉对象：

• 图表没有原生等效项，也没有合理的 Deneb 规范
• 其价值在于必须在渲染时运行的统计计算（模型拟合、核密度、预测区间），而不只是绘制 Vega 能绘制的形状
• 该视觉对象不需要作为交叉筛选源、悬停工具提示、发布到 Web，或 app-owns-data 嵌入
• 报表部署在 Pro/PPU 或更高容量上，且所在区域已启用 Fabric

如果交互或交叉筛选很重要，请使用 Deneb（静态 PNG 无法作为选择源）。如果只需要小型内嵌标记（迷你图、条形图、状态标签），请使用 SVG 度量值（无行数上限、无超时、无许可或区域限制，并且可在发布到 Web 后渲染）。脚本视觉对象的适用范围很窄：用于内部或组织内使用、在渲染时计算的统计图表。

**确定使用脚本视觉对象后，如何选择 Python 或 R：**当计算依赖 scikit-learn、statsmodels 或 scipy，或报表周边逻辑已使用 Python 时，使用 Python。对于出版级统计默认值，以及没有 Python 对应包的 R 包（forecast、corrplot、pheatmap、山脊图/小提琴图），使用 R。如果两者都合适，默认选择报表中其他脚本所用的语言；混用语言会使发布时需要验证的包范围翻倍。

不要仅仅因为某种图表类型“看起来有统计性”就默认使用脚本视觉对象。箱线图、棒棒糖图或哑铃图应使用 SVG 度量值或 Deneb；脚本只用于确实需要计算的图表。

参考资料

• references/data-model.md —— 说明 dataset 分组机制、行数/字节数上限，以及如何强制逐行输入
• references/community-examples.md —— 按图表类型整理的 seaborn 示例集，以及 matplotlib 和 Python Graph Gallery 链接
• references/chart-patterns.md —— 常见的 matplotlib/seaborn 图表模式（条形图、热图、环形图、KPI、面积图）
• examples/script/ —— 独立的 Python 脚本（bar-chart、trend-line）；转义后即可注入 visual.json
• examples/visual/bar-chart.json —— PBIR visual.json：横向堆叠条形图，包含 PY 对比线和变化百分比标签
• examples/visual/kpi-card.json —— PBIR visual.json：基于文本的 KPI，包含数值、变化百分比指示器和 PY 对比
• examples/visual/trend-line.json —— PBIR visual.json：包含折线图和按月 x 轴的面积图

获取文档

若要查找最新的 Python 视觉对象/包支持文档，请搜索 https://learn.microsoft.com 并获取相关页面。根据用户的请求进行搜索，并按需多次搜索，以确保在继续操作前获得充分的上下文。

相关技能

• pbi-report-design —— 布局和设计最佳实践
• r-visuals —— R 脚本视觉对象（概念相同，语言不同）
• deneb-visuals —— Vega/Vega-Lite 视觉对象（交互式、基于矢量的替代方案）
• svg-visuals —— 通过 DAX 度量值实现 SVG（轻量级内嵌图形）
• pbir-format（pbip 插件）—— PBIR JSON 格式参考