📚 课程目录第2章 Python环境与依赖安装

2. Python 环境与依赖安装

金融图谱批流一体链路对 Python 版本、依赖隔离和核心库的兼容性有严格要求。本章从环境配置、虚拟环境搭建到核心依赖安装，提供一套可复现的标准化流程，确保后续章节的代码在开发、测试和生产环境行为一致。

2.1 Python 3.10+ 环境配置

推荐使用 Python 3.10.12 或 3.11.x 版本。PyFlink 1.16+ 对 3.10 支持最稳定，3.12 部分依赖（如 grpcio）可能存在预编译轮子缺失问题。

版本	PyFlink 兼容性	pandas 兼容性	推荐场景
3.9.x	✅ 1.14-1.18	✅ 1.3-2.0	存量项目迁移
3.10.x	✅ 1.16-1.19	✅ 1.5-2.2	本课程首选
3.11.x	✅ 1.17-1.19	✅ 2.0-2.2	新项目推荐
3.12.x	⚠️ 部分预编译缺失	✅ 2.1+	实验性

💡 版本检查命令：

python3 --version
# 输出示例：Python 3.10.12

如果系统默认版本低于 3.10，建议通过 deadsnakes PPA（Ubuntu）或 brew（macOS）安装指定版本。

2.2 虚拟环境搭建

使用 venv 创建隔离环境，避免依赖冲突。以下步骤在项目根目录下执行：

创建虚拟环境
```
python3.10 -m venv .venv
```

激活环境

# Linux / macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

验证环境隔离

which python
# 输出应指向 .venv/bin/python

升级 pip 与 setuptools

pip install --upgrade pip setuptools wheel

⚠️ 避坑提示： 不要使用 conda 混合管理 PyFlink 依赖。Conda 的默认通道中 PyFlink 版本滞后，且与 apache-flink 官方轮子存在冲突。本课程统一使用 pip + venv 方案。

2.3 核心依赖安装

本课程依赖分为四层：数据处理层、流计算层、图存储层、消息中间件层。以下为 requirements.txt 完整内容：

# requirements.txt
# 数据处理
pandas==2.1.4
numpy==1.26.2

# 流计算（PyFlink）
apache-flink==1.18.0

# 图数据库驱动
neo4j==5.18.0

# 消息队列
kafka-python==2.0.2

# 工具库
python-dateutil==2.8.2
pyyaml==6.0.1

执行安装命令：

pip install -r requirements.txt

  📦 安装耗时参考（网络良好，首次安装）：
  pandas + numpy：约 30-60 秒
apache-flink：约 2-5 分钟（需下载预编译 Java 依赖）
neo4j + kafka-python：约 20-40 秒

2.4 依赖验证脚本

安装完成后，运行以下脚本验证所有核心库可正常导入：

# verify_deps.py
import sys
import pandas as pd
import pyflink
from neo4j import GraphDatabase
from kafka import KafkaProducer, KafkaConsumer

print(f"Python 版本: {sys.version}")
print(f"pandas 版本: {pd.__version__}")
print(f"PyFlink 版本: {pyflink.__version__}")
print("✅ 所有核心依赖导入成功！")

预期输出：

Python 版本: 3.10.12 (main, Nov 22 2023, 14:57:46) [GCC 11.4.0]
pandas 版本: 2.1.4
PyFlink 版本: 1.18.0
✅ 所有核心依赖导入成功！

2.5 依赖关系与数据流架构

下图展示了本课程中四个核心依赖之间的数据流转关系，以及它们在批流一体链路中的角色：

2.6 常见安装问题与解决方案

错误现象	根因	解决方案
`No matching distribution found for apache-flink`	Python 版本过高或过低	切换到 Python 3.10 或 3.11
`grpcio 编译失败`	缺少 C++ 编译工具链	安装 `build-essential`（Linux）或 Xcode CLI（macOS）
`neo4j 连接超时`	Neo4j 服务未启动或端口未开放	检查 `neo4j status` 及防火墙规则
`kafka-python 消费无数据`	Kafka 集群地址配置错误	确认 `bootstrap_servers` 与 `group_id` 正确

🔧 快速诊断命令：

# 检查已安装包版本
pip list | grep -E "pandas|pyflink|neo4j|kafka"

# 检查 Java 环境（PyFlink 依赖 JDK 11+）
java -version

2.7 环境快照与复现

完成安装后，建议导出精确的依赖快照，确保团队或 CI/CD 环境可复现：

pip freeze > requirements-lock.txt

requirements-lock.txt 会记录所有依赖（包括传递依赖）的精确版本号。后续环境重建时直接使用：

python3.10 -m venv .venv
source .venv/bin/activate
pip install -r requirements-lock.txt