依赖管理

依赖管理概述

Keras 3 设计用于支持多个后端（TensorFlow、JAX、PyTorch、NumPy 和 OpenVINO），每个后端都有一套自己的依赖项。Keras 中的依赖管理系统确保在这些后端之间进行正确的安装和兼容性。

来源：requirements.txt1-24 requirements-jax-cuda.txt1-15 requirements-torch-cuda.txt1-16 requirements-tensorflow-cuda.txt1-13 pyproject.toml1-111

需求文件结构

Keras 将其依赖项组织到多个需求文件中，以处理不同的后端和配置。

主要需求

主要的 requirements.txt 文件包含所有支持的后端在 CPU 模式下的依赖项，适用于开发和测试。

- TensorFlow CPU (~2.18.0)
- PyTorch (2.6.0+cpu)
- JAX CPU (0.5.0)
- Pre-commit hooks
- Common dependencies via requirements-common.txt

后端特定 GPU 需求

为了支持 GPU，Keras 为每个后端提供了单独的需求文件。

需求文件	目的	关键依赖项
requirements-tensorflow-cuda.txt	带 GPU 的 TensorFlow	tensorflow[and-cuda] ~= 2.18.0
requirements-jax-cuda.txt	带 GPU 的 JAX	jax[cuda12] == 0.4.28
requirements-torch-cuda.txt	带 GPU 的 PyTorch	torch == 2.5.1+cu121
requirements-openvino.txt	OpenVINO 后端	openvino

pyproject.toml 中的基本依赖项

Keras 所需的核心依赖项，无论后端如何，都在 pyproject.toml 中定义。

- absl-py
- numpy
- rich
- namex
- h5py
- optree
- ml-dtypes
- packaging

来源：requirements.txt1-24 requirements-tensorflow-cuda.txt1-13 requirements-jax-cuda.txt1-15 requirements-torch-cuda.txt1-16 requirements-tensorflow-cuda.txt1-13 pyproject.toml28-38

安装依赖项

基本安装

安装 Keras 及其依赖项

克隆仓库
使用 pip 安装依赖项
```
pip install -r requirements.txt
```
配置后端（请参阅后端配置）

对于开发环境，建议也运行

pre-commit install

后端特定安装

带 GPU 的 TensorFlow 后端

pip install -r requirements-tensorflow-cuda.txt

带 GPU 的 JAX 后端

pip install -r requirements-jax-cuda.txt

带 GPU 的 PyTorch 后端

pip install -r requirements-torch-cuda.txt

来源：CONTRIBUTING.md96-100 CONTRIBUTING.md104-108 .github/workflows/actions.yml49-57

GPU 支持

Keras 支持 TensorFlow、JAX 和 PyTorch 后端的 GPU 加速，每个后端都有特定的需求。

TensorFlow GPU 支持

TensorFlow GPU 支持通过 tensorflow[and-cuda] 包启用，该包包含 CUDA 和 cuDNN 依赖项。

JAX GPU 支持

对于 JAX，GPU 支持通过以下方式提供

--find-links https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
jax[cuda12]==0.4.28

PyTorch GPU 支持

PyTorch GPU 支持需要

--extra-index-url https://download.pytorch.org/whl/cu121
torch==2.5.1+cu121
torch-xla==2.5.1

GPU 环境检测

在集成测试和 CI/CD 流水线中，Keras 检查每个后端可用的 GPU 设备。

TensorFlow: tf.config.list_physical_devices("GPU")
JAX: jax.default_backend()
PyTorch: torch.cuda.is_available()

来源：requirements-tensorflow-cuda.txt1-13 requirements-jax-cuda.txt1-15 requirements-torch-cuda.txt1-16 .kokoro/github/ubuntu/gpu/build.sh26-79 keras/src/utils/module_utils.py47-57

开发环境设置

预提交钩子

Keras 使用 pre-commit 钩子来自动化 API 生成、代码格式化和 linting。这些通过以下方式安装：

pip install pre-commit
pre-commit install

`.pre-commit-config.yaml` 中的 pre-commit 钩子配置包括：

API 生成脚本
用于代码格式化和 linting 的 Ruff

测试依赖项

为了运行测试，您需要安装相应的后端依赖项。

# Install backend-specific dependencies
pip install -r requirements.txt

# Run tests
pytest keras

若要使用特定后端进行测试

KERAS_BACKEND=jax pytest keras

来源：CONTRIBUTING.md110-130 .pre-commit-config.yaml1-32 CONTRIBUTING.md173-221

CI/CD 依赖管理

Keras 使用 GitHub Actions 来测试多个后端，并采用特定的依赖项配置。

GitHub Actions 配置

`.github/workflows/actions.yml` 中的主要 CI 工作流配置了：

要测试的 Python 版本和后端矩阵
相应后端依赖项的安装
运行每个后端的测试
代码格式化检查

使用 Kokoro 进行 GPU 测试

对于 GPU 测试，Keras 使用 Kokoro 基础设施，其中包含：

CUDA 环境检测
后端特定 GPU 依赖项的安装
在运行测试前验证 GPU 可用性

来源：.github/workflows/actions.yml1-139 .github/workflows/nightly.yml1-123 .kokoro/github/ubuntu/gpu/build.sh1-80

模块懒加载

Keras 通过 keras/src/utils/module_utils.py 中的 LazyModule 类实现了可选依赖项的懒加载机制。

该系统

推迟导入可选模块直到需要时
为缺失的依赖项提供清晰的错误消息
根据可用后端启用条件代码路径

懒加载的关键模块包括

tensorflow
jax
torch_xla
tf2onnx
scipy

使用示例

来源：keras/src/utils/module_utils.py1-61

后端特定依赖项处理

不同的优化器和层可能根据后端具有特定的依赖项。例如，在 keras/src/optimizers/muon.py 中，优化器的实现会根据后端而异。

在实现使用后端特定功能的组件时，请考虑：

检查所需依赖项
提供备用实现
对后端特定代码使用条件导入

对于 PyTorch 中如 LSTM 等 GPU 特定操作，Keras 会检查 CUDA 的可用性。

来源：keras/src/optimizers/muon.py1-287 keras/src/backend/torch/rnn.py524-527

依赖项问题排查

常见的依赖项问题及其解决方案

问题	解决方案
缺少后端	确保安装了相应的后端包（tensorflow、jax、torch 等）
未检测到 GPU	检查 CUDA 安装及其与后端版本的兼容性
导入错误	检查错误消息以查找缺失的包并安装它们
版本冲突	为不同项目使用隔离环境（venv、conda）
torch-xla 问题	按照 `LazyModule` 错误消息中的特定安装步骤操作

欲了解更多详细的故障排除信息

检查您的后端版本是否与 requirements.txt 中的需求相匹配。
验证 CUDA/cuDNN 版本是否与您的后端需求相匹配
对于开发，请确保所有依赖项都通过 pip install -r requirements.txt 安装。

来源：keras/src/utils/module_utils.py47-57 integration_tests/import_test.py1-130