先看成果：做完之后你会得到什么
假设手上有一份季度销售明细 CSV，字段是订单日期、地区、渠道、产品、数量、单价。做完这套流程之后，你会得到一个网页形态的分析报告：
- 顶部一排筛选控件：日期范围、地区下拉、渠道多选；
- 中间几张联动图表：月度收入趋势折线、地区收入排名条形图、渠道占比图；
- 拖动筛选器时，所有图表和数字跟着变；
- 旁边一段由模型起草、你核对过的结论文字；
- 一个链接，同事点开就能自己筛数据看，不需要装任何客户端。
整个流程拆成三段：把 CSV 变成一张干净的表 → 让 GPT-6 Astra 在 Hex 里帮你写分析代码 → 把结果做成带控件的可交互报告并发布出去。
前置条件清单
开始之前，确认这几件事：
1. 一个 Hex 账号，并且所在工作区已经开启了 AI 助手功能。不同套餐对 AI 能力的开放程度不一样，具体以 Hex 官方页面为准。
2. 一份 CSV 文件，建议控制在几十万行以内。文件越大，后面的交互响应越慢。
3. 基础的 SQL 或 Python 阅读能力。你不需要自己从零写代码，但要能看懂模型写的代码在做什么。
4. 一份数据字典或业务口径说明（哪怕只是几句话）。比如"每行是一张订单""金额单位是元""退款单也在这个文件里"。这一段信息对模型输出质量的帮助，比任何提示词技巧都大。
5. 浏览器。Hex 是纯 Web 工具，本地不需要装环境。
步骤一：先在本地把 CSV 看一眼
不要直接把文件丢进去。先花两分钟做基础检查，能省掉后面半小时的排错。
```bash
看编码是否是 UTF-8（Windows 导出的 CSV 常见 GBK）
file -I sales.csv
看前几行有没有多余的表头行、分隔符是不是逗号
head -5 sales.csv
```
重点确认三件事：编码、分隔符、日期格式。这三项有任何一项不对，后面所有代码都会翻车。
步骤二：在 Hex 里新建项目并导入 CSV
登录 Hex 后新建一个项目，找到数据导入入口，把 CSV 上传进去。上传完成后，Hex 通常会把这个数据集注册成一个可以直接引用的表或 DataFrame，变量名以界面上显示的为准（例如 sales 或 df_sales），后面代码里的名字要和它保持一致。
如果文件不大，也可以直接在一个 Python 单元格里读取，方便本地先调试：
```python
import pandas as pd
编码正常的情况
df = pd.read_csv("sales.csv")
如果文件是 GBK 编码，改用
df = pd.read_csv("sales.csv", encoding="gbk")
print(df.shape)
print(df.dtypes)
df.head()
```
步骤三：做一个数据体检单元格
在清洗之前，先让数据自己交代问题。把下面这段放进一个单元格，输出一张体检表：
```python
profile = pd.DataFrame({
"类型": df.dtypes.astype(str),
"缺失数": df.isna().sum(),
"缺失率": df.isna().mean().round(3),
"唯一值数": df.nunique(),
})
profile
```
看到结果后，重点扫两类行：缺失率偏高的列，以及"唯一值数等于 1"的列（这种列对分析没有贡献）。
步骤四：清洗与类型转换
常见问题无非是大写数字、千分位逗号、货币符号、日期被当成字符串。统一处理一遍：
```python
import pandas as pd
df["订单日期"] = pd.to_datetime(df["订单日期"], errors="coerce")
df["数量"] = pd.to_numeric(
df["数量"].astype(str).str.replace(",", "", regex=False),
errors="coerce",
)
df["单价"] = pd.to_numeric(
df["单价"].astype(str).str.replace(r"[^\d.]", "", regex=True),
errors="coerce",
)
丢弃日期无法解析的行，并打印丢了多少
before = len(df)
df = df.dropna(subset=["订单日期"])
print(f"丢弃无法解析日期的行：{before - len(df)}")
df["收入"] = df["数量"] * df["单价"]
```
这里一定要把"丢弃了多少行"打印出来。分析报告里数字对不上时，这是第一个要回看的地方。
步骤五：把数据字典交给 GPT-6 Astra
打开 Hex 的 AI 助手面板，把下面这类信息一次性给它。关键在于：把真实的列名、真实的类型、几行真实样本贴进去，模型的输出质量会明显不同。
```text
你在帮我做数据分析。数据情况如下：
变量名：df
列名与类型：
订单日期 datetime64[ns]
地区 object
渠道 object
产品 object
数量 float64
单价 float64
收入 float64
前 5 行样本：
<粘贴 df.head() 的输出>
（可以先删掉客户姓名这类敏感字段）
业务背景：每行是一张订单。同一个订单号可能有多行明细。
地区包含华东、华北、华南、西南。渠道包含线上、门店、分销。
请写一段 pandas 代码，完成：
1. 按月聚合收入，输出 month、收入 两列，month 为月份起始日；
2. 按地区聚合收入，按收入降序；
3. 按渠道计算收入占比，保留两位小数；
4. 每步结果都 print 形状和前几行。
要求：只输出一个代码块，不要解释；不要修改 df 本身，全部用中间变量。
```
把返回的代码粘进新单元格运行。先看数字，再看图。 建议手动核对一次总量：把聚合结果加总，和 df["收入"].sum() 对比，两者对不上说明聚合口径有问题（比如重复计数）。
步骤六：从表格到图表
如果聚合结果已经是一张规整的表，用 Hex 的图表单元格最省事：选中数据源，拖字段到 X 轴、Y 轴，选折线或条形即可。
想更精细地控制样式，就用代码画：
```python
import plotly.express as px
fig = px.line(
monthly,
x="month",
y="收入",
markers=True,
title="月度收入趋势",
)
fig.update_layout(margin=dict(l=10, r=10, t=50, b=10))
fig
```
```python
fig2 = px.bar(
by_region.sort_values("收入", ascending=True),
x="收入",
y="地区",
orientation="h",
title="各地区收入排名",
)
fig2
```
步骤七：加筛选控件，让图表联动
在 Hex 里添加输入控件（日期范围、下拉、多选），每个控件会生成一个变量，比如 date_range、region_filter。然后在查询里引用它们。
SQL 版本大致长这样（不同数据连接器的参数写法有差异，以 Hex 官方文档为准）：
```sql
select
date_trunc('month', 订单日期) as month,
sum(收入) as 收入
from orders
where 订单日期 between {{ date_range.start }} and {{ date_range.end }}
and 地区 in ({{ region_filter }})
group by 1
order by 1
```
Python 版本则是先筛选再聚合：
```python
mask = (
(df["订单日期"] >= date_range[0])
& (df["订单日期"] <= date_range[1])
& (df["地区"].isin(region_filter))
)
filtered = df.loc[mask]
```
把每张图的源数据都接到这层筛选后的结果上，控件就能同时驱动所有图表。
步骤八：让模型写一段结论文字
把已经聚合好的几张表交给模型，让它起草一段人话总结：
```text
下面是本月报告的三张汇总表：月度收入趋势、地区收入排名、渠道占比。
请写一段 150 字以内的中文结论，包含：整体趋势方向、表现突出的地区、
需要关注的变化。只陈述数据支持的事实，不要推测原因，不要使用夸张措辞。
```
生成的文字放进 Hex 的文本单元格，再自己改一遍。模型负责起骨架，事实判断仍然要由你来做。
步骤九：发布与分享
确认图表和控件都正常联动后，用项目右上角的发布/分享入口生成链接。有几点需要确认：
- 权限：链接是工作区内可见还是公开访问，按需设置；
- 缓存刷新：数据源更新后报表是否需要手动刷新，看数据连接的配置；
- 变量默认值：控件要有合理的默认值，别人点开就能看到完整数据，而不是空白页。
常见坑与排错
1. 中文乱码：CSV 是 GBK 编码时，加 encoding="gbk"；不确定就先转成 UTF-8 再上传。
2. 列名带空格或换行：先 df.columns.tolist() 打印出来，必要时 df.columns = df.columns.str.strip()。
3. 日期解析失败：errors="coerce" 会把解析不了的值变成 NaT，所以要统计丢了多少行，而不是默认全部成功。
4. 数值里混着货币符号：用正则去掉非数字字符，再用 to_numeric 转换。
5. 模型编造列名：模型看不到你的真实数据时容易猜。解决办法是每次都把列名和样本贴进提示词。
6. 聚合口径不一致：同一订单多行明细时，直接按行数统计会重复计数，要明确按订单号去重还是按行汇总。
7. 单元格依赖顺序：下游单元格引用了还没运行的变量会报错，按从上到下的顺序逐个运行一遍。
8. 大文件卡顿：先聚合出小表再画图，不要用原始明细直接渲染几十万个点。
9. 坐标轴被极值压扁：出现异常大值时考虑用对数轴，或者单独标注。
10. 分享后数字没更新：确认数据源刷新策略和报表缓存设置。
下一步建议
跑通一遍之后，可以往这几个方向走：
- 接数据仓库：把 CSV 换成直连数据库或数仓，报表就能自动更新，不用每次手动传文件。
- 沉淀提示词模板：把验证过好用的提示词存成团队模板，同一个业务口径反复用。
- 加数据校验单元格：在报表顶部放一行"总行数、总金额、日期范围"，数字异常时一眼能看出来。
- 拆成多个页面：总览放趋势和占比，明细页放下钻表格，避免单页信息过载。
- 用版本历史：改动前后留个记录，方便回滚。
整套流程的核心其实只有两条：把数据洗干净，把数据字典讲清楚。模型负责把代码写出来，判断数字对不对这件事，始终在你手上。