企业官网建设流程全解析

某天上午领导临时通知，下午三点前要交一份销售汇总：分区域、分销售、分产品，还要把异常订单单独标出来。很多人的第一反应是打开 Excel 手工筛选、复制、求和，再凭经验找几条金额异常的数据。真正做过的人都知道，这项工作本身并不难，难的是明细数据不干净、统计口径不统一、时间又紧。这个场景非常适合用 AI 辅助完成：让代码先做确定性的读取、清洗和聚合，让大模型负责生成汇总口径、识别并解释异常记录，最后输出一份带汇总表和异常清单的 Excel 文件。本文会完整演示这样一套小工具的开发过程，包括环境准备、核心代码、运行验证、常见问题排查和工程化建议，读者可以照着实现，也可以把思路迁移到月度经营分析、库存异常检查等场景。

1. 销售汇总的真正难点：数据杂、口径乱、时间紧

1.1 手工汇总为什么慢，慢在哪里

大多数销售明细表会包含订单号、销售日期、区域、销售员、客户、产品、数量、单价、金额等字段。表面上看，用 Excel 数据透视表几分钟就能完成统计，但真实业务中至少有三类问题会让手工汇总速度明显下降。

第一类是数据不干净。日期列存在2024/6/1、2024-06-01、2024.06.01混用，金额列出现文本或负数，客户名称留有空格，甚至整行记录缺失。数据透视表遇到脏数据会直接报错，或者合计结果明显不对，操作者只能逐行排查。

第二类是统计口径不一致。领导可能要求“按区域和销售员双维度汇总”，也可能要求“把退货订单剔除”“不计入未回款的订单”“单笔超过 50 万的单独列出来”。每次需求变化，手工操作都要重新调整筛选条件，容易遗漏。

第三类是时间紧。下午就要数据时，往往没有时间慢慢核对。手工做出来的结果如果被人问一句“这个数怎么算出来的”，回答不上来，就很容易返工。

1.2 AI 在销售汇总链路中的边界

在动手设计工具之前，先要明确 AI 在这里承担什么角色。大模型擅长的是语言理解、结构化文本生成、按规则描述异常，它并不擅长对大规模数据做精确计算。如果把十万行明细直接丢给模型，让它“计算一下总销售额”，结果不可控，算错了也没有可靠的校验方式。

更合理的方式是把任务拆成两层：

• 数据层由代码做确定性强的事情，包括读取文件、字段校验、缺失值检查、重复值检查、分组聚合、金额求和。
• 判断层由大模型做需要业务经验的事情，包括把聚合结果整理成易读的汇总说明、根据预设阈值筛选重点异常、为异常记录补充可读的原因描述。

这样分工之后，AI 不负责算数，只负责“看数说话”。算数的部分由 pandas 完成，结果可复现、可核对；AI 输出的部分用于辅助决策，即使某个判断不够准确，也不会导致基础数据错误。

1.3 一条可行的自动化处理主线

整套流程按下面这条主线设计：

1. 读取销售明细文件，只保留需要的列，统一日期格式。
2. 用代码做确定性校验，找出日期缺失、金额为负、订单号重复等异常候选。
3. 对清洗后的明细按指定维度分组聚合，得到汇总数据。
4. 把汇总数据和异常候选整理成紧凑的 JSON 结构，放入提示词。
5. 调用大模型 API，让模型输出结构化结果，包括汇总分组说明和异常清单。
6. 将结果写入 Excel，同时生成一个 Markdown 摘要，方便直接粘贴进消息。

这个流程的好处是：数据问题有迹可循，每个人的判断都记录在案，领导追问时可以解释每一步的逻辑。

2. 环境准备与项目结构设计

2.1 技术选型：pandas 做计算，大模型 API 做判断

示例采用 Python 作为主语言，理由并不是 Python 本身有多特殊，而是它在数据处理生态上最省事。pandas 可以处理 Excel、CSV 的读写和分组聚合，openpyxl 负责 Excel 底层写入，大模型 API 负责生成结构化判断结果。

大模型调用部分推荐使用 OpenAI 兼容接口。当前很多大模型服务商都提供 OpenAI 兼容格式，代码只需要关注base_url、api_key、model三个配置，替换服务商时改动成本很低。下面的代码会以这种通用接口为例，实际部署时替换成自己使用的模型名称和地址即可。

2.2 环境依赖与版本确认

建议使用 Python 3.10 或更高版本。依赖使用 pip 安装：

pip install pandas openpyxl openai python-dotenv

安装完成后可以执行下面命令确认版本：

python -c "import pandas; print(pandas.__version__)" python -c "import openai; print(openai.__version__)"

如果组织内部无法直接安装依赖，可以考虑使用离线安装包，或者把环境切换到 conda 等本地方案。这里要特别提醒：不要只装了库就直接进入代码，先确认 pandas 版本和 openpyxl 版本匹配。实际项目里遇到过 pandas 2.x 搭配老版本 openpyxl 写入 Excel 时样式异常的问题，先统一版本能省很多事。

2.3 项目目录与数据样例

推荐按下面的目录结构组织项目：

sales_ai_summary/ ├── .env ├── config.json ├── data/ │ ├── sales_detail.xlsx │ └── output/ └── src/ ├── prompts.py └── summary_runner.py

.env文件存放 API 密钥，不进入版本库：

LLM_API_KEY=你的密钥

config.json存放模型配置和业务规则。下面是示例结构：

{ "api": { "base_url": "https://your-llm-endpoint.example.com/v1", "model": "your-model-name", "temperature": 0.1, "max_tokens": 3000 }, "fields": { "order_id": "订单号", "date": "销售日期", "region": "区域", "sales": "销售", "customer": "客户", "product": "产品", "quantity": "数量", "amount": "金额" }, "group_by": ["区域", "销售"], "thresholds": { "amount_upper": 500000, "amount_lower": 0, "top_n": 5 } }

参数说明如下：

data/sales_detail.xlsx建议使用符合真实业务的样例数据，至少包含下面这些列：

订单号 销售日期 区域 销售 客户 产品 数量 单价 金额 SO20240601001 2024-06-01 华东 张伟 客户A 办公椅 10 680 6800 SO20240601002 2024-06-01 华东 李娜 客户B 办公桌 5 1200 6000

为了测试异常识别，最好在样例中故意放几条问题数据，例如日期为空、金额为负数、订单号重复、客户名称为空。

3. 核心实现：明细读取、汇总计算与 AI 异常识别

3.1 用 pandas 读取销售明细，先做确定性校验

工具的第一步是读取文件。支持 Excel 和 CSV 两种格式，根据文件后缀自动选择读取方式。

import pandas as pd def load_details(file_path): if file_path.endswith(".csv"): df = pd.read_csv(file_path) else: df = pd.read_excel(file_path) print(f"[info] 读取明细 {len(df)} 条") return df

读取之后不要急着发给 AI，先做字段完整性检查和数据类型统一。

def validate_details(df, cfg): fields = cfg["fields"] required_cols = [fields["order_id"], fields["date"], fields["amount"]] missing_cols = [c for c in required_cols if c not in df.columns] if missing_cols: raise ValueError(f"明细缺少必填列: {missing_cols}") df = df.copy() # 日期统一解析，无法解析的置为 NaT df[fields["date"]] = pd.to_datetime(df[fields["date"]], errors="coerce") # 金额统一转成数值，无法转换的置为 NaN df[fields["amount"]] = pd.to_numeric(df[fields["amount"]], errors="coerce") anomalies = [] date_col = fields["date"] amount_col = fields["amount"] order_col = fields["order_id"] customer_col = fields["customer"] upper = cfg["thresholds"]["amount_upper"] lower = cfg["thresholds"]["amount_lower"] date_bad = df[df[date_col].isna()] for idx in date_bad.index: anomalies.append({ "row": int(idx) + 2, "type": "日期无效", "order_id": _safe_value(df, idx, order_col), "reason": "销售日期为空或格式无法解析" }) amount_bad = df[df[amount_col].isna()] for idx in amount_bad.index: anomalies.append({ "row": int(idx) + 2, "type": "金额缺失", "order_id": _safe_value(df, idx, order_col), "reason": "金额为空或非数值" }) negative = df[df[amount_col] < lower] for idx in negative.index: anomalies.append({ "row": int(idx) + 2, "type": "金额异常", "order_id": _safe_value(df, idx, order_col), "reason": f"金额小于下限 {lower}" }) high = df[df[amount_col] > upper] for idx in high.index: anomalies.append({ "row": int(idx) + 2, "type": "金额偏高", "order_id": _safe_value(df, idx, order_col), "reason": f"金额超过上限 {upper}" }) dup_mask = df.duplicated(subset=[order_col], keep=False) dup_df = df[dup_mask].sort_values(order_col) for idx in dup_df.index: anomalies.append({ "row": int(idx) + 2, "type": "订单重复", "order_id": _safe_value(df, idx, order_col), "reason": "同一订单号出现多次" }) if customer_col and customer_col in df.columns: empty_customer = df[df[customer_col].isna() | (df[customer_col].astype(str).str.strip() == "")] for idx in empty_customer.index: anomalies.append({ "row": int(idx) + 2, "type": "客户缺失", "order_id": _safe_value(df, idx, order_col), "reason": "客户名称为空" }) print(f"[info] 确定性校验发现 {len(anomalies)} 条异常候选") return df, anomalies

def _safe_value(df, idx, col): if col in df.columns and pd.notna(df.loc[idx, col]): return str(df.loc[idx, col]) return ""

这段代码背后有一个关键设计：异常分两类。一类是绝对错误，比如日期无法解析、金额为负；另一类是业务重点关注，比如单笔金额超过阈值、订单号重复。绝对错误后续要回归修正，重点关注则会交给 AI 编排成可读的异常清单。

3.2 构造提示词：把数据切片传给模型

很多第一次做 AI 汇总的人会陷入一个误区，把整个明细 DataFrame 转成字符串塞进提示词，希望模型自己找出所有问题。十万行数据对应的 token 量可能高达几百万，既耗时又费钱，模型也无法在超长上下文里稳定聚焦。

正确做法是传给模型两样东西：

1. 分组聚合后的汇总数据，一般不超过 100 行。
2. 确定性校验发现的异常候选，一般不超过几十条。

这两样数据量很小，模型可以快速做出判断。

import json def build_prompt(df, anomalies, cfg): group_cols = cfg["group_by"] amount_col = cfg["fields"]["amount"] grouped = ( df.groupby(group_cols, dropna=False)[amount_col] .agg(["sum", "count", "mean"]) .reset_index() ) grouped.columns = group_cols + ["总金额", "订单数", "平均金额"] grouped = grouped.sort_values("总金额", ascending=False) # 控制传给模型的条数，避免上下文过长 grouped_block = grouped.head(100).to_json(orient="records", force_ascii=False) # 异常候选去掉 DataFrame 无关信息，只保留可读内容 anomaly_block = json.dumps(anomalies[:100], ensure_ascii=False, indent=2) user_prompt = f""" 销售明细已经完成数据读取和初步清洗。以下内容用于辅助生成汇总说明和异常清单。 一、按 {group_cols} 汇总后的数据： {grouped_block} 二、代码检测出的异常候选： {anomaly_block} 请基于以上信息完成工作，输出 JSON。 """.strip() return user_prompt, grouped

这个设计把“精确计算”和“智能解读”分离了。聚合结果由 pandas 计算，模型只是站在聚合结果之上描述现象，省 token，结果也更可靠。

系统提示词单独放在prompts.py中，方便后续调优：

SYSTEM_PROMPT = """ 你是一名销售运营分析助手。你会收到一份经过清洗的销售汇总数据和一份异常候选清单。 你的任务：根据这些信息，生成便于管理者阅读的汇总总结和异常清单。 要求： 1. 只输出 JSON，不要输出 JSON 以外的解释。 2. JSON 格式必须严格如下： { "summary": [ { "name": "华东-张伟", "总金额": 68200, "订单数": 12, "平均金额": 5683.33, "解读": "本组销售额最高，主要贡献来源..." } ], "anomaly_summary": "整体数据中发现了3条需要关注的异常记录，主要集中在日期和金额字段。", "anomalies": [ { "row": 5, "type": "金额偏高", "order_id": "SO20240601005", "reason": "单笔金额78万元，明显高于同组平均水平" } ] } 3. summary 中的 name 用维度拼接，例如 区域-销售。 4. anomaly_summary 不超过 120 字。 5. 如果没有任何异常，anomalies 为空数组，anomaly_summary 写“未发现明显异常”。 """.strip()

3.3 调用模型并解析结构化输出

调用模型使用 OpenAI 兼容接口。密钥从环境变量读取，避免硬编码到代码里。

import os from openai import OpenAI def call_llm(system_prompt, user_prompt, cfg): client = OpenAI( base_url=cfg["api"]["base_url"], api_key=os.getenv("LLM_API_KEY"), ) resp = client.chat.completions.create( model=cfg["api"]["model"], messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}, ], temperature=cfg["api"]["temperature"], max_tokens=cfg["api"]["max_tokens"], ) return resp.choices[0].message.content

模型返回的内容不一定每次都是干净 JSON。常见表现是首尾多出 ```json 标记、解释性文字、甚至因为达到 max_tokens 被截断。解析时需要做容错处理。

import json import re def parse_llm_json(text): if not text: raise ValueError("模型返回内容为空") text = text.strip() # 去掉可能的 Markdown 代码块标记 text = re.sub(r"^```(?:json)?|```$", "", text.strip()).strip() try: return json.loads(text) except json.JSONDecodeError: # 尝试提取第一个 { 到最后一个 } 之间的内容 start = text.find("{") end = text.rfind("}") if start != -1 and end != -1 and end > start: candidate = text[start : end + 1] try: return json.loads(candidate) except json.JSONDecodeError as e: raise ValueError(f"模型输出不是合法 JSON，原因为: {e}") from e raise

注意：解析容错只能解决边界标记问题，解决不了模型真正算错的问题。因此，summary 里的金额不要直接作为最终报表结果，最终报表的合计金额必须以 pandas 聚合结果为准。

3.4 生成汇总表 Excel 与异常清单

拿到了模型输出之后，把结果写入 Excel。这里有一个原则：Excel 里的汇总数据使用 pandas 计算的精确结果，模型的解读放在附加列中。这样既能保证数字准确，又能保留 AI 的分析价值。

def save_outputs(grouped, llm_data, anomalies, output_dir): import pathlib output_dir = pathlib.Path(output_dir) output_dir.mkdir(parents=True, exist_ok=True) summary_text = llm_data.get("summary", []) if summary_text: model_df = pd.DataFrame(summary_text) # 合并：先按 name 关联，再把模型解读补到汇总表 group_keys = list(grouped.columns[:len(grouped.columns)-3]) grouped["name"] = grouped[group_keys].astype(str).agg("-".join, axis=1) merged = grouped.merge( model_df[["name", "解读"]], on="name", how="left" ) merged = merged.drop(columns=["name"]) else: merged = grouped anomaly_df = pd.DataFrame(anomalies, columns=["row", "type", "order_id", "reason"]) llm_anomalies = llm_data.get("anomalies", []) if llm_anomalies: llm_anomaly_df = pd.DataFrame(llm_anomalies) anomaly_df = pd.concat([anomaly_df, llm_anomaly_df], ignore_index=True) sheet_name = "汇总表" out_path = output_dir / "summary_output.xlsx" with pd.ExcelWriter(out_path, engine="openpyxl") as writer: merged.to_excel(writer, sheet_name=sheet_name, index=False) anomaly_df.to_excel(writer, sheet_name="异常清单", index=False) md_lines = ["# 销售汇总摘要", ""] md_lines.append(f"### 汇总说明") md_lines.append(llm_data.get("anomaly_summary", "")) md_lines.append("") md_lines.append("### 分组汇总") for _, row in merged.head(10).iterrows(): md_lines.append(f"- {row[group_keys[0]]}-{row[group_keys[1]]}: 订单数 {row['订单数']}, 总金额 {row['总金额']}") md_path = output_dir / "summary.md" md_path.write_text("\n".join(md_lines), encoding="utf-8") print(f"[info] 输出汇总文件: {out_path}") print(f"[info] 输出摘要文件: {md_path}") return str(out_path)

这里要说明一下：anomaly_df同时写入两类异常，一类是代码确定性检测出来的，另一类是模型根据业务经验补充的。两类的来源在导出时应保留type或备注字段区分，避免后续误判责任方。实际生产项目中还可以加一列source，值为rule或llm。

4. 运行验证：从命令行产出两份结果文件

4.1 主入口脚本

把上述函数串起来，通过命令行参数控制输入输出。

import argparse import json import os from dotenv import load_dotenv from prompts import SYSTEM_PROMPT def main(): load_dotenv() parser = argparse.ArgumentParser(description="AI 销售汇总工具") parser.add_argument("--input", required=True, help="销售明细 Excel/CSV 路径") parser.add_argument("--config", default="config.json", help="配置文件路径") parser.add_argument("--output", default="data/output", help="输出目录") args = parser.parse_args() with open(args.config, "r", encoding="utf-8") as f: cfg = json.load(f) df = load_details(args.input) df, anomalies = validate_details(df, cfg) user_prompt, grouped = build_prompt(df, anomalies, cfg) llm_text = call_llm(SYSTEM_PROMPT, user_prompt, cfg) llm_data = parse_llm_json(llm_text) output_path = save_outputs(grouped, llm_data, anomalies, args.output) print(f"[done] {output_path}") if __name__ == "__main__": main()

运行命令：

cd sales_ai_summary python src/summary_runner.py --input data/sales_detail.xlsx --config config.json --output data/output

正常的输出大致如下：

[info] 读取明细 120 条 [info] 确定性校验发现 4 条异常候选 [info] 调用大模型接口完成 [info] 输出汇总文件: sales_ai_summary/data/output/summary_output.xlsx [info] 输出摘要文件: sales_ai_summary/data/output/summary.md [done] sales_ai_summary/data/output/summary_output.xlsx

4.2 检查汇总表和异常清单

打开 Excel 后，至少检查三件事：

1. 汇总表的总金额是否和明细列求和一致。可以新增一列用sum()交叉验证。
2. 异常清单里的row是否对应明细文件里的真实行号。注意 pandas 从 0 开始索引，Excel 从 1 开始，所以代码里做了+2偏移，其中 +1 表示标题行，+1 表示索引从 0 到 Excel 行号从 1 的转换。
3. 模型生成的“解读”是否与数字矛盾。例如某组总金额最高，解读却写成“金额较低”，这种情况通常是提示词里没有说明排序规则，需要补充。

summary.md可以直接复制到 IM 工具里，作为给领导的第一版汇报素材。

4.3 边界场景验证

除了正常数据，建议用三类数据测试工具：

空文件场景需要在main()里加一个提前退出逻辑，避免向模型发送空提示词。字段缺失场景依赖第 3.1 节的列校验。

5. 必须掌握的排查链路：AI 汇总脚本报错看哪里

5.1 读不到文件或者 Excel 报错

现象：运行脚本后提示文件不存在，或者Sheet2不存在，或者编码报错。

排查顺序：

1. 确认文件路径是相对路径还是绝对路径，当前工作目录是不是sales_ai_summary。
2. 确认文件扩展名和实际格式一致。有些同事把 CSV 内容另存为.xlsx，pandas 会读取失败。
3. 确认 Excel 里是否存在多个 Sheet。默认读取第一个 Sheet，如果目标数据在第二个 Sheet，需要传入sheet_name。

解决方案：

df = pd.read_excel(file_path, sheet_name=0) df = pd.read_csv(file_path, encoding="utf-8")

Windows 环境下建议显式指定encoding="utf-8"，否则 CSV 文件可能因为本地编码而乱码。

5.2 模型返回内容无法解析

现象：脚本报模型输出不是合法 JSON，或者输出的 Excel 里缺少某些字段。

常见原因有三个：

1. 模型没有遵守“只输出 JSON”的指令，额外输出了解释性文字。
2. max_tokens太小，JSON 被截断。
3. 模型自身能力有限，多行 JSON 里出现换行或转义错误。

处理建议按顺序执行：

1. 增加max_tokens，例如从 3000 调到 5000。
2. 在系统提示词里追加“不要使用 Markdown 代码块包裹 JSON”。
3. 把temperature调到 0，降低随机性。
4. 在parse_llm_json里增加日志输出，保存原始响应，便于分析。

with open("data/last_llm_response.txt", "w", encoding="utf-8") as f: f.write(llm_text)

5.3 汇总结果与明细对不上

现象：分组汇总的金额和 Excel 数据透视表不一致。

优先检查数据清洗步骤。最常见原因是金额列里混入了文本，例如"6,800"、"6800元"、"6800 "，pd.to_numeric会把它们变成 NaN，直接导致汇总金额偏小。需要先做文本替换：

df[amount_col] = ( df[amount_col] .astype(str) .str.replace(",", "", regex=False) .str.replace("元", "", regex=False) .str.strip() ) df[amount_col] = pd.to_numeric(df[amount_col], errors="coerce")

如果样本里包含了被排除的订单，也会导致对不上。建议在导出汇总表时额外保留“清洗前记录数”和“清洗后记录数”，方便核对。

5.4 API 调用超时或费用失控

现象：明细数据量一大，脚本长时间不返回；或者一次运行消耗了大量 token。

这里有两个层面要注意：

时间层面：API 调用需要增加超时配置：

client = OpenAI( base_url=cfg["api"]["base_url"], api_key=os.getenv("LLM_API_KEY"), timeout=cfg["api"].get("timeout", 60), )

成本层面：严格控制放入提示词的数据条数。grouped_block限制前 100 行，异常候选限制前 100 条，而不是把整个明细全部传进去。如果业务必须分析完整数据，更好的做法是分页处理，把 10 万条明细拆成多个批次，每个批次只做局部汇总，最后合并。不过对于销售汇总场景，先做 pandas 聚合再传给模型，通常已经足够。

注意：大模型 API 是按 token 计费的。提示词越长，单次成本越高。不要让模型重复读取原始明细，它并不需要这些原始记录，也不需要重新计算总额。

6. 让这套工具真正用得住的工程化建议

6.1 提示词版本管理

提示词是这套 AI 工具效果的核心，但提示词变更非常频繁。建议把系统提示词单独放在prompts.py或独立文本文件中，并在文件头部记录变更信息。

# prompts.py - 版本 1.2 # 2025-01-15: 增加"异常清单中保留 row 字段"的约束 # 2025-01-16: 修复 summary.name 拼接规则，改为 区域-销售

每次修改提示词后，至少用同一份样例数据回归一次，对比新增输出和旧版输出。不要在生产环境中直接改提示词，容易引入不可控变化。

6.2 把确定性计算和生成式判断分离

这套工具最核心的工程原则是：能用规则解决的问题，不要交给模型；模型只做规则难以覆盖的判断和文本生成。

在销售汇总场景里：

• 求和、计数、平均值、排序，全部由 pandas 处理。
• 日期格式、缺失值、负金额、重复订单号，全部由规则检查。
• 模型只负责“从多个异常候选中挑选最值得关注的几项”“把汇总结果改写成领导能看懂的话”。

如果完全依赖模型输出汇总数字，一旦模型“发挥不稳定”，整个报表的数据可信度都会受影响。而数字一旦不可信，AI 辅助办公这个工具就失去了价值。

6.3 生产环境还需要补哪些能力

学习和开发环境跑通只是开始，真正部署到日常使用时，建议补齐以下能力：

学习环境可以全流程快速跑通，但生产环境要把“模型不可用”当作常态设计。

6.4 后续扩展：定时任务、消息推送、Web 页面

在沉淀成稳定工具后，可以往三个方向扩展：

方向一：接入定时任务。使用 cron 或 CI 计划任务，每周定时读取最新明细，自动生成汇总表，发送到指定邮箱或 IM 群。

方向二：做成 Web 页面。上传 Excel 后自动调用处理流程，页面展示汇总表和异常清单，用户可以下载结果文件。需要额外增加文件上传安全校验和任务状态管理。

方向三：从“销售汇总”扩展到“经营日报”。同一套“明细读取 + 确定性校验 + 模型解读 + 结构化输出”的架构，可以复用到库存异常、渠道对账、客户回款提醒等场景。只要把config.json里的字段映射和规则阈值换掉，就能适配新的业务。

对刚接触 AI 应用开发的读者，建议不要一上来就写复杂平台，先用这个项目跑通一条最小链路。把一个 Excel 明细变成汇总表和异常清单的过程中，你会接触到数据清洗、提示词工程、结构化输出、容错解析、文件导出这些在实际项目中都会用到的能力。把一个场景做扎实，比一次性堆很多功能更有价值。