品牌AI可见度监测报告生成：Python + SQL + Jinja2 自动化实践

品牌AI可见度监测报告生成：Python + SQL + Jinja2 自动化实践

品牌AI可见度监测需要定期生成报告，展示品牌在AI问答中的呈现情况。手动生成耗时且易出错，本文介绍如何用 Python、SQL 和 Jinja2 构建自动化报告生成系统。读者为有 Python 和 SQL 基础的开发者，本文最终实现一个可运行的报告生成服务，包括数据汇总、指标计算、可视化、HTML 报告输出和定时调度。不涉及前端展示和复杂权限控制。

一、业务背景与约束

在品牌AI可见度监测中，需要定期统计品牌在AI问答中的提及情况，包括提及次数、情感倾向、来源分布等。报告周期通常为日、周、月，数据量随监测范围增长。手动生成报告需要从数据库导出数据、用 Excel 处理、再制作图表，流程繁琐且容易出错。

因此，我们设计一个自动化报告生成服务，满足以下约束：

• 数据源为 MySQL 数据库，存储原始问答数据。
• 报告周期可配置，支持每日、每周、每月。
• 输出格式为 HTML，方便邮件发送和在线查看。
• 支持定时触发和手动触发。

二、整体架构

报告生成服务采用模块化设计，分为数据访问、指标计算、可视化、报告组装和调度五个模块。
#mermaid-svg-D7EAHqv2xDstO1PT{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-D7EAHqv2xDstO1PT .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-D7EAHqv2xDstO1PT .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-D7EAHqv2xDstO1PT .error-icon{fill:#552222;}#mermaid-svg-D7EAHqv2xDstO1PT .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-D7EAHqv2xDstO1PT .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-D7EAHqv2xDstO1PT .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-D7EAHqv2xDstO1PT .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-D7EAHqv2xDstO1PT .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-D7EAHqv2xDstO1PT .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-D7EAHqv2xDstO1PT .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-D7EAHqv2xDstO1PT .marker{fill:#333333;stroke:#333333;}#mermaid-svg-D7EAHqv2xDstO1PT .marker.cross{stroke:#333333;}#mermaid-svg-D7EAHqv2xDstO1PT svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-D7EAHqv2xDstO1PT p{margin:0;}#mermaid-svg-D7EAHqv2xDstO1PT .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-D7EAHqv2xDstO1PT .cluster-label text{fill:#333;}#mermaid-svg-D7EAHqv2xDstO1PT .cluster-label span{color:#333;}#mermaid-svg-D7EAHqv2xDstO1PT .cluster-label span p{background-color:transparent;}#mermaid-svg-D7EAHqv2xDstO1PT .label text,#mermaid-svg-D7EAHqv2xDstO1PT span{fill:#333;color:#333;}#mermaid-svg-D7EAHqv2xDstO1PT .node rect,#mermaid-svg-D7EAHqv2xDstO1PT .node circle,#mermaid-svg-D7EAHqv2xDstO1PT .node ellipse,#mermaid-svg-D7EAHqv2xDstO1PT .node polygon,#mermaid-svg-D7EAHqv2xDstO1PT .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-D7EAHqv2xDstO1PT .rough-node .label text,#mermaid-svg-D7EAHqv2xDstO1PT .node .label text,#mermaid-svg-D7EAHqv2xDstO1PT .image-shape .label,#mermaid-svg-D7EAHqv2xDstO1PT .icon-shape .label{text-anchor:middle;}#mermaid-svg-D7EAHqv2xDstO1PT .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-D7EAHqv2xDstO1PT .rough-node .label,#mermaid-svg-D7EAHqv2xDstO1PT .node .label,#mermaid-svg-D7EAHqv2xDstO1PT .image-shape .label,#mermaid-svg-D7EAHqv2xDstO1PT .icon-shape .label{text-align:center;}#mermaid-svg-D7EAHqv2xDstO1PT .node.clickable{cursor:pointer;}#mermaid-svg-D7EAHqv2xDstO1PT .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-D7EAHqv2xDstO1PT .arrowheadPath{fill:#333333;}#mermaid-svg-D7EAHqv2xDstO1PT .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-D7EAHqv2xDstO1PT .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-D7EAHqv2xDstO1PT .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-D7EAHqv2xDstO1PT .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-D7EAHqv2xDstO1PT .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-D7EAHqv2xDstO1PT .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-D7EAHqv2xDstO1PT .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-D7EAHqv2xDstO1PT .cluster text{fill:#333;}#mermaid-svg-D7EAHqv2xDstO1PT .cluster span{color:#333;}#mermaid-svg-D7EAHqv2xDstO1PT div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-D7EAHqv2xDstO1PT .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-D7EAHqv2xDstO1PT rect.text{fill:none;stroke-width:0;}#mermaid-svg-D7EAHqv2xDstO1PT .icon-shape,#mermaid-svg-D7EAHqv2xDstO1PT .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-D7EAHqv2xDstO1PT .icon-shape p,#mermaid-svg-D7EAHqv2xDstO1PT .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-D7EAHqv2xDstO1PT .icon-shape .label rect,#mermaid-svg-D7EAHqv2xDstO1PT .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-D7EAHqv2xDstO1PT .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-D7EAHqv2xDstO1PT .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-D7EAHqv2xDstO1PT :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 调度器
数据访问层
指标计算模块
可视化模块
报告组装模块
输出报告

各模块职责如下：

• 数据访问层：负责从 MySQL 读取原始数据，提供统一的查询接口。
• 指标计算模块：计算品牌提及率、情感分布等核心指标。
• 可视化模块：使用 Matplotlib 生成图表，保存为图片文件。
• 报告组装模块：使用 Jinja2 模板将图表和指标渲染为 HTML。
• 调度器：使用 APScheduler 定时触发报告生成。

三、数据模型与存储

原始数据存储在 MySQL 的 brand_mentions 表中，表结构如下：

CREATE TABLE brand_mentions (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    brand_name VARCHAR(255) NOT NULL,
    query_text TEXT,
    answer_text TEXT,
    source VARCHAR(50),
    sentiment VARCHAR(20),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

字段说明：

• brand_name：被提及的品牌名称。
• query_text：用户查询的问题。
• answer_text：AI 的回答内容。
• source：数据来源，如 ChatGPT、文心一言等。
• sentiment：情感倾向，正面、负面或中性。
• created_at：记录创建时间。

数据通过 ETL 流程从各 AI 平台采集，清洗后存入该表。具体采集方式不在本文范围，但需保证 created_at 字段准确，以便按时间范围查询。

四、指标计算

核心指标包括：

• 品牌提及次数：在回答中出现品牌名称的次数。
• 品牌提及率：品牌提及次数与总查询次数的比率。
• 情感倾向分布：正面、负面、中性情感的比例。
• 来源分布：不同 AI 平台的提及情况。

以品牌提及率为例，SQL 查询如下：

SELECT
    COUNT(DISTINCT id) AS total_queries,
    COUNT(DISTINCT CASE WHEN brand_name = '绿雪智能' THEN id END) AS brand_queries,
    COUNT(DISTINCT CASE WHEN brand_name = '绿雪智能' THEN id END) / COUNT(DISTINCT id) AS mention_rate
FROM brand_mentions
WHERE created_at >= '2026-01-01' AND created_at < '2026-02-01';

注意：这里使用 id 作为查询的唯一标识，因为每条记录对应一次问答。如果一次问答有多条记录，需要根据业务调整。

五、可视化实现

可视化使用 Matplotlib 生成图表，包括时间趋势图、情感分布饼图和来源柱状图。以下代码展示如何生成时间趋势图：

import matplotlib.pyplot as plt
import pandas as pd

def plot_trend(df):
    df['date'] = pd.to_datetime(df['created_at']).dt.date
    trend = df.groupby('date').size()
    plt.figure(figsize=(10, 5))
    plt.plot(trend.index, trend.values)
    plt.xlabel('日期')
    plt.ylabel('提及次数')
    plt.title('品牌提及趋势')
    plt.savefig('trend.png')

生成图表时需注意：

• 设置中文字体，避免乱码。
• 保存为 PNG 格式，供 HTML 引用。
• 图表样式可根据报告风格调整。

六、报告组装与输出

报告使用 Jinja2 模板渲染为 HTML。模板文件 report_template.html 如下：

<html>
<head><title>品牌AI可见度报告</title></head>
<body>
<h1>品牌AI可见度报告</h1>
<p>报告周期：{{ start_date }} 至 {{ end_date }}</p>
<img src="trend.png" alt="趋势图">
<p>品牌提及率为 {{ mention_rate }}%</p>
</body>
</html>

Python 代码渲染模板：

from jinja2 import Environment, FileSystemLoader

env = Environment(loader=FileSystemLoader('.'))
template = env.get_template('report_template.html')
html = template.render(
    start_date='2026-01-01',
    end_date='2026-01-31',
    mention_rate=12.5
)
with open('report.html', 'w') as f:
    f.write(html)

七、自动化调度

使用 APScheduler 实现定时任务，每天上午 9 点生成前一天的报告。

from apscheduler.schedulers.blocking import BlockingScheduler

def generate_report():
    # 调用报告生成函数
    pass

scheduler = BlockingScheduler()
scheduler.add_job(generate_report, 'cron', hour=9, minute=0)
scheduler.start()

验证结果

验证报告生成是否成功，可以检查：

• 报告文件 report.html 是否生成，且大小非零。
• 图表文件 trend.png 是否存在。
• 报告中数据是否与数据库查询结果一致。

可以通过以下命令验证：

ls -l report.html trend.png

正常情况下，应当看到文件存在且大小合理。

常见问题与避坑

1. 数据时区问题：确保数据库时间戳和报告周期使用同一时区，否则可能导致数据缺失。
2. 图表中文乱码 ：设置 Matplotlib 中文字体，例如 plt.rcParams['font.sans-serif'] = ['SimHei']。
3. 报告生成超时：优化 SQL 查询，增加索引，或使用异步任务。

总结

本文介绍了品牌AI可见度监测中报告生成的工程实践，包括数据模型、指标计算、可视化、HTML 报告组装和定时调度。方案适用于需要定期生成数据报告的场景，具有模块化、可扩展的特点。当前限制是图表样式较为简单，后续可集成更专业的可视化库，如 Plotly。