API结构

相关源文件

• api_gen.py
• keras/__init__.py
• keras/api/__init__.py
• keras/api/_tf_keras/keras/__init__.py
• keras/src/backend/common/remat.py
• keras/src/backend/common/remat_test.py
• requirements-common.txt

本文全面概述了 Keras 3 的 API 结构，包括其组织和生成方式。本页面侧重于 API 本身的技术架构，而非其中的特定组件。有关模型、层和优化器等特定 API 组件的详细信息，请参阅核心 API 组件。

Keras API 设计概述

Keras API 在设计时考虑了两个关键原则：

1. 后端无关性：相同的 API 适用于多个后端（TensorFlow、JAX、PyTorch、NumPy、OpenVINO）。
2. 兼容性：包含一个 TensorFlow 兼容层，使 Keras 3 能够作为 tf.keras 的直接替代品。

API 是从源代码自动生成的，确保了公共接口的一致性，同时保持了实现细节的灵活性。

来源：keras/__init__.py1-80 keras/api/__init__.py1-60 keras/api/_tf_keras/keras/__init__.py1-58

API 生成过程

Keras 使用自动化流程生成其公共 API。这种方法提供了多项优势：

1. 源代码与公共 API 之间的一致性
2. 实现细节与公共接口之间更清晰的分离
3. TensorFlow 兼容层的自动化生成

API 生成由 api_gen.py 脚本处理，该脚本使用 namex 库将源代码转换为公共 API 文件。

来源：api_gen.py1-202

生成的 API 结构

Keras API 结构遵循清晰的层次组织，所有公共接口都通过 keras.api 包暴露。主要组件包括：

主要 API 组件

生成的 API 包含以下主要组件：

• 顶层类：核心类，如 Model、Layer、Optimizer 等。
• 模块命名空间：逻辑分组，如 layers、models、optimizers 等。
• 后端接口：通过 backend 和 ops 模块暴露的底层操作。
• 工具：支持功能，如 callbacks、utils 等。

来源：keras/api/__init__.py1-60 keras/__init__.py1-80

目录结构

生成的 API 位于 keras/api/ 目录中，其组织结构如下：

组件	位置	目的
主要 API	keras/api/	主要的公共接口
TF 兼容性	keras/api/_tf_keras/	TensorFlow 兼容层
源代码	keras/src/	实现细节

keras/__init__.py 文件导入并重新导出来自生成的 keras/api/ 目录的所有符号，使其在顶层可访问。

来源：keras/__init__.py1-80 keras/api/__init__.py1-60

TensorFlow兼容层

Keras API 结构的一个关键部分是 TensorFlow 兼容层，它使得 Keras 3 可以作为 tf.keras 的直接替代品。这个层在 API 生成过程中自动生成。

兼容层：

1. 位于 keras/api/_tf_keras/keras/
2. 镜像了主 API 的结构，但进行了 TensorFlow 特定的调整
3. 使现有 TensorFlow 用户能够以最少的代码更改过渡到 Keras 3

兼容层在 API 生成过程中通过以下方式创建：

1. 复制主 API
2. 调整导入路径
3. 集成旧版 TensorFlow 特定功能

来源：api_gen.py36-134 keras/api/_tf_keras/keras/__init__.py1-58

API 生成实现

API 生成过程依赖于两个关键组件：

1. namex 库：一个 Python 库，用于分析源代码并生成公共 API 文件。
2. api_gen.py 脚本：负责协调生成过程的脚本。

api_gen.py 脚本：

1. 创建一个临时构建目录
2. 将源代码复制到此目录
3. 使用 namex 生成 API
4. 创建 TensorFlow 兼容层
5. 更新包的 init 文件
6. 将生成的文件复制回仓库

该脚本从公共 API 中移除了实现细节，确保用户只与预期的接口交互，同时允许开发人员在不破坏向后兼容性的情况下重构内部。

来源：api_gen.py1-202 requirements-common.txt1-25

公共 API 访问和命名空间

用户通过顶层暴露的公共 API 访问 Keras 功能：

这些导入通过 keras/__init__.py 解析，该文件从生成的 keras/api/ 目录导入。keras/src/ 中的内部实现细节不直接暴露给用户。

API 导航保护

Keras API 结构包含针对意外访问实现细节的保护：

这可以防止用户在自动补全中看到或意外使用 keras.src 或 keras.api，引导他们使用正确的公共接口。

来源：keras/__init__.py67-72 keras/__init__.py75-80

总结

Keras API 结构旨在提供：

1. 清晰、一致且组织良好的用户接口
2. 跨多个 ML 框架的后端无关操作
3. 与现有 TensorFlow 代码的兼容性
4. 实现细节与公共接口之间的清晰分离

自动化 API 生成过程确保公共 API 与实现保持同步，同时保护用户免受可能影响向后兼容性的内部更改的影响。