4. 开发环境搭建：Python 3.10+ 安装、虚拟环境与依赖管理

反洗钱推理链路涉及大量数据处理、规则引擎调用与模型推理，一个干净、可复现的开发环境是保障链路稳定性的基石。本节将指导你完成从 Python 解释器安装到依赖锁定的全流程，确保团队协作时“一次搭建，到处运行”。

4.1 Python 版本选择与安装

反洗钱 SDK（如 aml-engine-sdk）及主流机器学习框架（如 scikit-learn、xgboost）已全面支持 Python 3.10+ 的类型注解增强与性能优化。推荐使用 Python 3.10.11 或 3.11.5 长期稳定版本。

4.2 虚拟环境：隔离反洗钱推理上下文

每个反洗钱项目（如“对公账户可疑交易推理”、“跨境汇款链路分析”）都应拥有独立的虚拟环境，避免依赖冲突。我们提供两种主流方案：

方案 A：venv（Python 内置，轻量首选）

# 创建虚拟环境（在项目根目录执行）
python -m venv .venv

# 激活环境
# Linux / macOS:
source .venv/bin/activate

# Windows (CMD):
.venv\Scripts\activate

# 验证：终端出现 (.venv) 前缀
(.venv) $

方案 B：conda（适合包含 C++ 扩展的推理组件）

# 创建环境并指定 Python 版本
conda create -n aml_inference python=3.10

# 激活环境
conda activate aml_inference

# 验证
(aml_inference) $ python --version

4.3 依赖管理：从 requirements.txt 到 pyproject.toml

反洗钱推理链路通常包含三类依赖：核心推理（规则引擎、特征计算）、数据接入（数据库驱动、消息队列）、测试/文档。我们采用分层管理策略。

4.3.1 传统方式：requirements.txt

适用于快速原型或小型团队。按层级分组，用注释标明用途：

# 反洗钱推理链路 - 核心依赖
# 版本锁定日期：2025-03-01
aml-engine-sdk==2.1.0
pandas==2.1.4
numpy==1.26.2
scikit-learn==1.3.2

# 数据接入层
psycopg2-binary==2.9.9
kafka-python==2.0.2

# 开发与测试
pytest==7.4.3
black==23.12.0

安装命令：

pip install -r requirements.txt

4.3.2 现代方式：pyproject.toml（推荐）

反洗钱推理链路作为正式项目，建议采用 PEP 621 标准的 pyproject.toml，支持依赖分组与元数据声明：

[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "aml-inference-chain"
version = "0.4.0"
description = "反洗钱推理链路API接口开发实战"
requires-python = ">=3.10"
dependencies = [
    "aml-engine-sdk>=2.1.0,<3.0.0",
    "pandas>=2.1.0",
    "numpy>=1.26.0",
    "scikit-learn>=1.3.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4",
    "black>=23.12",
    "mypy>=1.7",
]
db = [
    "psycopg2-binary>=2.9",
    "sqlalchemy>=2.0",
]
kafka = [
    "kafka-python>=2.0",
]

安装命令：

# 安装核心依赖
pip install .

# 安装全部依赖（含开发与数据库）
pip install .[dev,db,kafka]

4.4 环境搭建流程总览

下图展示了从 Python 安装到依赖锁定的完整链路，以及各环节的产出物：

4.5 快速搭建清单

按照以下步骤，你可以在 10 分钟内完成反洗钱推理链路的开发环境搭建：

1. 安装 Python 3.10+ — 从 python.org 下载安装包，勾选“Add Python to PATH”。
2. 创建项目目录 — mkdir aml-inference-chain && cd aml-inference-chain
3. 初始化虚拟环境 — python -m venv .venv 并激活。
4. 编写依赖文件 — 创建 pyproject.toml 或 requirements.txt，按 4.3 节模板填写。
5. 安装依赖 — pip install -e .（可编辑模式）或 pip install -r requirements.txt。
6. 锁定版本 — pip freeze > requirements-lock.txt，提交到版本控制。
7. 验证 — 执行 python -c "import aml_engine_sdk; print('环境就绪')"。