AI经营报告项目——项目记录

从零到一：用 Python + 大模型构建多业务线经营分析报告系统

前言

你是否曾经面对一堆杂乱无章的 Excel/JSON 数据，需要每周/每月为领导制作格式统一、分析深入、排版精美的经营分析报告？手工制作不仅耗时，而且容易出错。本文分享一个完整项目实战，我们将手把手搭建一个基于 Python 和大语言模型的经营分析报告自动生成系统。你只需准备好数据，运行一条命令，就能得到一份带表格、文字分析和可视化图表的 Markdown/HTML 报告。

项目支持单地区、多地区横向对比，并可灵活扩展主机、宽带、5G 等不同业务线。代码清晰分层，即使你是初级开发者，也能按步骤复现。

项目背景与目标

• 输入：各业务系统导出的 JSON/CSV 数据（主机、宽带、5G 等）。
• 输出：结构化的 Markdown 报告，并可进一步转换为带图表的精美 HTML 报告。
• 核心能力：调用大模型（如 OpenAI GPT）进行数据分析和报告撰写，而非硬编码规则。
• 扩展性：新增业务线只需增加数据加载、提示词模板和报告生成函数，无需改动核心框架。

整体架构与项目结构

operational-report-ai/ ├── config/ │ ├── settings.py # 全局配置，API密钥、文件路径等 │ └── prompts/ # 各种报告的系统提示词和用户提示词模板 ├── data/ # 原始数据文件存放（示例和实际数据） │ ├── daily/ │ └── monthly/ │ ├── output/ # 生成的报告输出目录 ├── src/ │ ├── data_loader.py # 统一数据加载 │ ├── data_processor.py # 数据处理，生成分析快照 │ ├── ranking_processor.py # 排名计算、表格生成 │ ├── prompt_builder.py # 使用 Jinja2 组装提示词 │ ├── llm_client.py # 调用大模型 API │ ├── report_generator.py # 报告生成主流程 │ ├── host_data_processor.py# 主机业务专用重塑 │ ├── broadband_data_processor.py │ ├── broadband_ranking_processor.py │ └── md_to_html.py # Markdown 转 HTML（通过大模型） ├── tests/ # 单元测试 ├── main.py # 程序入口 ├── requirements.txt └── .env # 敏感配置（不上传 Git）

项目采用分层模块化架构：

• 配置层：.env和settings.py管理所有可变参数。
• 数据层：data_loader.py负责从文件或 API 加载原始数据。
• 处理层：各种processor将原始数据转换为标准快照字典。
• 服务层：prompt_builder.py将快照注入提示词，llm_client.py封装 API 调用。
• 编排层：report_generator.py按顺序调度各模块，最终输出报告。

环境准备

1. 创建 Python 虚拟环境

建议使用 Conda 或 venv：

conda create-ncreatemdpython=3.13-yconda activate createmd

2. 安装依赖

创建requirements.txt文件：

openai>=1.0 pandas>=2.0 python-dotenv>=1.0 jinja2>=3.1 tabulate markdown

然后执行pip install -r requirements.txt。

3. 配置 .env 文件

在项目根目录新建.env，填入你的大模型 API 密钥和 Base URL（若使用代理或自定义端点）：

OPENAI_API_KEY=sk-your-key LLM_BASE_URL=https://api.playground.ai.gcable.cc/v1 LLM_MODEL=gpt-4o REPORT_MODE=single # 可选 single/multi/host_monthly/broadband_monthly/5g_monthly_html

核心模块开发

数据加载器 (data_loader.py)

封装从不同来源读取数据的功能。例如从本地 JSON 加载：

defload_data(file_path:str)->dict:withopen(file_path,'r',encoding='utf-8')asf:returnjson.load(f)

对于需要读取多个文件的场景（如月度主机数据），可扩展为load_host_data、load_broadband_monthly_data等，返回元组或字典。

数据处理与快照 (data_processor.py)

“快照”是整个系统的核心抽象。它将原始数据转成标准结构字典，供 LLM 消费。例如，将日数据中的 KPI 完成情况、新装、流失等指标聚合起来。这一层同时负责指标计算、异常标记、单位转换，确保 LLM 拿到的是干净、可直接理解的数据。

提示词构建 (prompt_builder.py)

利用 Jinja2 模板引擎将快照数据注入提示词。系统提示词定义角色和分析框架；用户提示词包含实际数据（Markdown 表格和 JSON 统计量）。

示例：

defbuild_prompts(snapshot,sys_path,usr_path):system_prompt=load_template(sys_path)user_template=load_template(usr_path)template=Template(user_template)user_prompt=template.render(snapshot_json=json.dumps(snapshot,ensure_ascii=False,indent=2))returnsystem_prompt,user_prompt

LLM 调用 (llm_client.py)

封装 OpenAI SDK，支持自定义 base_url 和代理：

importopenaidefgenerate_report(system_prompt,user_prompt):client=openai.OpenAI(api_key=OPENAI_API_KEY,base_url=LLM_BASE_URL)response=client.chat.completions.create(model=LLM_MODEL,messages=[{"role":"system","content":system_prompt},{"role":"user","content":user_prompt}],temperature=0.3)returnresponse.choices[0].message.content

报告生成器 (report_generator.py)

按顺序编排流程：加载数据 → 处理为快照 → 构建提示词 → 调用 LLM → 保存 Markdown。

对于多地区或月度报告，会引入ranking_processor预先计算表格和排名，再注入提示词。这种方式能保证表格排序、合计行等复杂格式的准确性。

单地区日报告实战

以日维度主机数据为例，说明完整流程。

1. 准备模拟数据：data/raw_data_20260506.json，可以自定义数据结构。
2. 编写 data_processor 的 process_to_snapshot()，将原始扁平 JSON 转成含有kpi_completion、user_acquisition、user_churn、card_activation、fiber_upgrade的字典。
3. 系统提示词定义报告章节：考核指标全景、用户新装与流失等等，并要求 Markdown 格式。
4. 运行 main.py，输出output/report_20260506_xxx.md。

这是最简单但完整的端到端流程。

多地区横向对比报告

当数据包含多个分公司时，我们希望生成一份排名对比报告。

1. 数据准备：在data/regions/下放置每个地区的 JSON 文件，文件名即地区名。
2. 新增ranking_processor.py：计算各指标排名、生成预警列表，返回包含rankings和alerts的字典。
3. 提示词：系统提示词要求生成排名表格和预警分析；用户提示词注入排名 JSON。
4. 配置 REPORT_MODE=multi启用多地区对比。

月度主机经营分析报告

与日报告不同，月度数据通常来自多个文件。

1. 数据加载：load_host_data支持传入多个文件路径，返回元组。
2. 专用重塑函数reshape_host_json合并多个数据源，统一别名，计算衍生指标（如理论月净增、预警）。
3. 表格生成compute_host_monthly_table根据重塑后的数据动态生成转置表格，可分离“合计”等特殊行并按完成率排序。
4. 提示词包含三个分表，系统提示词要求对每个表进行深度分析。

宽带分析报告与速率区间图表

宽带业务数据的特点是按速率区间（100M以下、100M-200M 等）细分。我们既要生成表格，还要在 HTML 中绘制分组柱状图。

1. 重塑函数：将每个速率区间的字段组合成复合键，如300M_本月宽带数。
2. 表格函数：生成“缴费宽带完成情况”和五个速率区间分表。
3. HTML 转换：在md_to_html.py中，我们让大模型承担了生成柱状图的任务——在系统提示词中明确要求使用 Chart.js 绘制两个图表：
   • 各速率区间总净增数对比柱状图
   • 各分公司分组柱状图（5个区间，不同颜色）
4. 提示词中还包含“宽带升级方向分析”，要求大模型对图表进行解读，指出各经营体升级趋势。

这种方式完全绕过了本地绘图库，非常灵活。

5G 月度 HTML 报告：纯靠大模型

5G 业务我们采用了最激进的方案：跳过所有本地处理步骤，直接将原始 JSON 注入提示词，让大模型完成数据解析、指标计算、表格构建和 HTML 渲染。

1. 数据加载：读取三个 JSON 文件，合并为一个字典。
2. 提示词设计：
   • 系统提示词详细描述了数据字段含义、报告结构（三个完成情况表格 + 开卡销户表 + 套餐统计表）、表格排序规则、预警颜色、HTML 样式。
   • 用户提示词仅包含三个 JSON 数据块。
3. 执行：run_5g_monthly_report_html()构建提示词后直接调用大模型，获取 HTML 字符串并保存。

这种方法虽然消耗 token 较多，但消除了所有业务计算代码，极大简化了流程，非常适合需求多变、快速上线的场景。

Markdown 转 HTML 的美化方式

我们提供了两种 MD→HTML 转换：

• 基于本地库markdown：生成静态 HTML，样式固定，适用于离线环境。
• 基于大模型：编写系统提示词要求大模型生成带有内联样式、响应式设计、数据高亮和 Chart.js 图表的完整 HTML。可自由定制样式。

实际项目中，我们推荐在关键报告（如宽带、5G）上采用大模型转换，以获得更佳的视觉效果和动态图表。

Git 安全：彻底清除 .env 文件

.env包含密钥，一旦误提交到 Git 就会造成安全风险。本文提供了一套完整的处理流程：

1. 立即吊销泄露的密钥并生成新 Key。
2. 将.env加入.gitignore并提交。
3. 使用git filter-repo从历史记录中彻底清除.env文件。
4. 强制推送并通知协作者重新克隆仓库。

我们给出了每一步的详细命令和注意事项，确保小白也能安全操作。

总结与展望

通过这套项目，你可以：

• 快速接入多业务线数据，自动生成格式统一的报告。
• 通过修改提示词灵活调整分析角度和报告结构，无需重写代码。
• 渐进式地将报表从手动制作过渡到全自动生成。

未来，你可以继续扩展：

• 定时任务：用 cron 每天自动生成日报告。
• API 接收数据：用 FastAPI 封装，让上游系统实时推送 JSON 并触发报告生成。
• 多模型支持：将 LLM 调用抽象为接口，轻松切换模型。

完整的项目代码和示例数据可在我的 GitHub 仓库中找到（链接待补充）。希望本文能帮助所有运营分析人员从重复劳动中解放出来，让数据自动“说话”。

原文发表于 CSDN，转载请注明出处。