2、环境搭建与项目初始化：TFX安装与依赖管理、虚拟环境配置、第一个TFX流水线项目结构

好，咱们正式开始动手了。

这一章，说白了就是「把枪擦亮，子弹上膛」。很多同学学TFX，上来就卡在环境上，装了半天跑不起来，心态直接崩了。我当年第一次搭TFX环境，也折腾了整整一个下午，最后发现是Python版本不对。嗯，这种坑，咱们今天一次性填平。

2.1 虚拟环境：给你的项目一个「干净的小房间」

我个人习惯，每个项目都开独立的虚拟环境。为什么？你想想看，今天装TFX 1.14，明天装个旧版TensorFlow 2.3，后天再跑个PyTorch项目——依赖全混在一起，迟早出问题。我曾经在一个生产服务器上，因为全局环境里装了冲突的protobuf版本，导致TFX流水线跑着跑着就崩了，排查了整整两天。

所以，第一步：创建虚拟环境。

# 我推荐用 Python 3.8 或 3.9，TFX 对这两个版本支持最稳
python3.9 -m venv tfx_env

# 激活环境
# Linux/Mac:
source tfx_env/bin/activate

# Windows:
# tfx_env\Scripts\activate
小技巧： 激活后，你会在终端前面看到 (tfx_env) 字样。如果没看到，说明没激活成功，别急着下一步。

2.2 TFX安装与依赖管理

环境激活后，就可以装TFX了。但注意，别直接 pip install tfx 就完事。我建议先升级pip，再安装，能省掉很多莫名其妙的报错。

# 先升级 pip，这一步我吃过亏
pip install --upgrade pip

# 安装 TFX
pip install tfx

# 验证安装
python -c "import tfx; print(tfx.__version__)"

如果看到版本号，比如 1.14.0，恭喜你，装上了。

但这里有个坑——TFX的依赖非常重。它会自动装上TensorFlow、Apache Beam、ML Metadata、Protobuf等等一大堆东西。我建议你装完后，用 pip list 看一眼，确认关键组件都在。

组件 作用 常见版本要求
TensorFlow 模型训练与推理 ≥2.9.0
Apache Beam 数据管道与分布式处理 ≥2.40.0
ML Metadata 记录流水线元数据 ≥1.14.0
Protobuf 序列化数据结构 ≥3.20.0
注意： 如果你在 macOS M1/M2 芯片上安装，可能会遇到 grpcio 编译失败的问题。解决方案是：pip install grpcio --no-binary grpcio。我上次在M1 MacBook上折腾了半小时，最后用这个命令搞定的。

2.3 第一个TFX流水线项目结构

环境搭好了，咱们来建项目。别一上来就写代码，先把目录结构搭好。我见过太多人，代码写到一半，发现不知道把配置文件放哪，临时乱塞，最后自己都找不到了。

这是我个人比较推荐的项目结构：

my_tfx_pipeline/
├── pipeline/                # 流水线定义
│   ├── __init__.py
│   ├── pipeline.py          # 定义流水线组件
│   └── configs.py           # 配置参数
├── components/              # 自定义组件（如果有）
│   └── __init__.py
├── data/                    # 原始数据
│   └── sample.csv
├── models/                  # 模型输出目录
├── metadata/                # ML Metadata 存储
├── runner.py                # 流水线运行入口
└── requirements.txt         # 依赖清单

为什么要这么分？说白了，就是「各司其职」。

  • pipeline/ 放流水线的「骨架」，定义组件怎么连。
  • components/ 放「血肉」，比如你自定义的数据处理逻辑。
  • data/ 和 models/ 是输入输出，一目了然。

来，咱们写一个最简单的 pipeline.py，感受一下：

# pipeline/pipeline.py
import tfx
from tfx.components import CsvExampleGen, StatisticsGen, SchemaGen

def create_pipeline(pipeline_name: str, pipeline_root: str, data_path: str):
    # 读取CSV数据
    example_gen = CsvExampleGen(input_base=data_path)

    # 生成数据统计
    statistics_gen = StatisticsGen(examples=example_gen.outputs['examples'])

    # 推断数据Schema
    schema_gen = SchemaGen(
        statistics=statistics_gen.outputs['statistics'],
        infer_feature_shape=True
    )

    return tfx.dsl.Pipeline(
        pipeline_name=pipeline_name,
        pipeline_root=pipeline_root,
        components=[example_gen, statistics_gen, schema_gen]
    )

这段代码干了三件事：读数据、算统计、推Schema。你看，TFX的组件就像搭积木，一个的输出是另一个的输入。

然后，写个 runner.py 来跑它：

# runner.py
from pipeline.pipeline import create_pipeline

pipeline = create_pipeline(
    pipeline_name='my_first_pipeline',
    pipeline_root='./metadata',
    data_path='./data'
)

# 本地运行（使用DirectRunner）
pipeline.run()
核心要点： 第一个流水线，别追求复杂。能跑通 CsvExampleGen → StatisticsGen → SchemaGen 这三步，你就已经入门了。我当年第一次跑通时，看到终端里打出 Pipeline run succeeded，那种成就感，比调通一个模型还爽。

2.4 避坑指南：我踩过的三个坑

最后，分享几个我实际项目中遇到的坑，你遇到了别慌：

  1. Python版本不对： TFX 1.14 要求 Python 3.8-3.9。我用 Python 3.10 装，直接报 No matching distribution found。老老实实降版本。
  2. protobuf版本冲突： 如果你之前装过TensorFlow，再装TFX，protobuf可能打架。解决方案：先 pip uninstall protobuf，再 pip install tfx，让它自动装匹配的版本。
  3. 路径问题： pipeline_root 一定要用绝对路径或相对于项目根目录的路径。我试过用 ./metadata 在某个IDE里跑，结果它把元数据写到了奇怪的地方，找都找不到。

好了，环境搭好了，项目结构也建起来了。下一章，咱们开始真正动手，写一个完整的TFX流水线——从数据读取到模型导出，一步到位。

记住：环境搭得好，后面没烦恼。别急，慢慢来。

← 上一章 📖 返回目录 下一章 →