fg-data-profiling命令行使用指南:终端批量生成CSV数据画像报告
fg-data-profiling命令行使用指南:终端批量生成CSV数据画像报告
fg-data-profiling 是一个开源的数据画像(data profiling)工具,它的命令行工具 data_profiling 让你无需编写任何 Python 代码——在终端输入一条命令,就能把 CSV 文件转换成一份包含数据质量警报、缺失值分析和变量统计的 HTML 画像报告,还可以批量处理整个目录的 CSV 文件。本指南带你从安装到批量生成,5 步上手。
为什么选择命令行生成数据画像 🚀
相比在 Python 脚本里调用 ProfileReport 类,命令行方式对新手更友好:
- 零代码:不需要会写 Python,输入一条命令即可出报告
- 速度快:支持多核并行(
--pool_size),处理大 CSV 文件效率更高 - 易集成:一条命令就能写进 CI 任务、定时脚本或 Makefile,实现自动化批量画像
- 输出即交付:默认生成单文件 HTML 报告,直接发给同事就能看
命令行功能的核心实现在 console.py,安装后会在系统中注册 data_profiling 可执行命令(见 pyproject.toml,同时还保留了 pandas_profiling 兼容别名)。
第一步:一键安装 fg-data-profiling
使用 pip 安装最新版即可:
pip install -U data-profiling
安装完成后,在终端运行 data_profiling --version 能打印版本号,说明命令行工具已就绪。详细安装方式(含 conda 方式)见 installation.md。
第二步:一条命令生成 CSV 数据画像报告
最简用法只需两个参数:输入 CSV 文件和输出 HTML 文件:
data_profiling data.csv report.html
执行完成后,系统会自动用浏览器打开生成的 HTML 报告。报告内容涵盖数据集概览、每个变量的分布直方图、缺失值热力图、相关性矩阵和数据质量警报。
💡 小提示:输出文件名可以省略,此时会默认使用输入文件名 + .html 扩展名(如 data.csv → data.html),逻辑见 console.py。
常用命令行参数速查表(新手必看)
运行 data_profiling -h 可以查看全部参数,效果如下:
| 参数 | 简写 | 作用 |
|---|---|---|
--title TITLE |
— | 设置报告标题(默认为 "YData Profiling Report") |
--silent |
-s |
只生成报告、不自动打开浏览器(批处理时必备) |
--minimal |
-m |
极简配置,关闭大部分分析,适合大数据集 |
--explorative |
-e |
探索模式,额外包含 Unicode、文件、图像等深度分析 |
--pool_size N |
— | 指定使用的 CPU 核心数(0 = 自动使用全部核心) |
--config_file FILE |
— | 指定 YAML 配置文件,精细控制报告行为 |
--infer_dtypes / --no-infer_dtypes |
— | 是否推断 DataFrame 字段类型(默认按 pandas 读取的类型) |
--version |
— | 打印版本号 |
--help |
-h |
显示帮助信息 |
官方文档中的完整说明见 quickstart.md。
三种分析模式怎么选:默认 / -m 极简 / -e 探索 🎯
- 默认模式:均衡配置,日常数据质量检查首选
-m极简模式:关闭缺失值图表、相关性计算等高开销分析,几秒内完成超大 CSV 的快速体检-e探索模式:开启 Unicode 文本、文件路径、图像哈希等深度分析,适合对数据一无所知时的首次探查
⚠️ 注意:--minimal 与 --config_file 不能同时使用,会报互斥错误(测试用例见 test_console.py)。
用 YAML 配置文件自定义报告行为
当命令行参数不够用时,可以把完整配置写进一个 YAML 文件,例如关闭相关性分析、修改标题和元数据信息:
data_profiling --config_file my_config.yaml --title "销售数据画像" sales.csv sales_report.html
仓库自带两份可直接参考的示例配置:
- 完整默认配置:config_default.yaml —— 所有选项的起点模板
- 极简配置:config_minimal.yaml —— 大数据集调优参考
可自定义的内容非常丰富,包括标题、数据集元信息(作者、版权、描述)、每种变量类型的统计口径、缺失值图表样式、相关性阈值、重复值展示、HTML 主题配色等,详细说明见 available_settings.md。
生成的 HTML 报告长什么样 👀
概览页:一眼看清变量数量、观测行数、缺失值比例和变量类型分布:
数据质量警报面板:自动标记常量列、重复行、高基数、高相关性等 20 多种潜在问题,数据质量问题无处遁形:
单变量分析:每个字段都有分布直方图、分位数、极值和样本值展示,快速定位异常数据:
批量生成多个 CSV 的画像报告(脚本技巧)📦
结合 -s(静默模式)和 shell 循环,一条脚本就能把目录里所有 CSV 全部画像:
mkdir -p reports
for f in data/*.csv; do
data_profiling -s --title "画像: $f" "$f" "reports/$(basename "${f%.csv}").html"
done
几秒钟后,reports/ 目录里就会生成与每个 CSV 一一对应的 HTML 报告。这个模式非常适合接入定时任务或数据管道的质量检查环节。
常见问题 FAQ
问:报告默认输出什么格式? 答:HTML 单文件报告(内嵌全部资源,可离线打开)。
问:处理大 CSV 太慢怎么办?
答:加 -m 使用极简配置,或用 --pool_size 调整并行核心数,参考 big_data.md。
问:生成的报告数据能导出吗?
答:可以。通过 Python API 的 to_json() 可导出 JSON 格式数据(CLI 目前聚焦 HTML 输出)。
问:支持 CSV 以外的文件吗? 答:只要是 pandas 能直接读取的格式(如标准表格文件)都可以作为输入。
从一条命令到批量自动化,fg-data-profiling 的命令行工具让数据画像真正做到了"开箱即用"。现在就可以找一份 CSV 试一试,30 秒内看到你的第一份数据质量报告!



