API生成

目的和概述

本文详细介绍了 Keras 3 中的 API 生成系统，该系统能够从源代码自动构建公共 API 结构。该系统确保了清晰、一致的接口，同时允许开发人员在实现细节和公共 API 之间保持分离。有关生成 API 结构的信息，请参阅核心 API 组件。

API 生成系统负责：

在 keras/api/ 目录中创建主要的 Keras API 结构
在 keras/api/_tf_keras/ 中生成 TensorFlow 兼容层
使用适当的导入更新顶层 __init__.py 文件

API 生成过程

Keras API 通过 api_gen.py 脚本自动生成，该脚本通常通过 api_gen.sh shell 脚本运行。此过程将 keras/src/ 中的源代码转换为 keras/api/ 中清晰、组织良好的 API 结构。

来源： api_gen.py163-198

`namex` 库

API 生成依赖于 namex 库（在 requirements-common.txt 中指定），该库分析 Keras 源代码并生成相应的 API 文件。此库在代码中查找导出注解，并创建仅公开预期接口的公共 API 结构。

来源： api_gen.py182-183 requirements-common.txt1

生成的 API 结构

API 生成创建了多个组件，这些组件共同构成了完整的 Keras 公共 API。

主 API 结构

主 API 结构在 keras/api/ 目录中生成，包括：

从源文件直接导入顶层类和函数
用于组织相关功能的模块结构
版本信息及其他元数据

来源： keras/api/__init__.py1-61

TensorFlow兼容层

API 生成的一个关键组件是 TensorFlow Keras 兼容层的创建，该兼容层允许 Keras 3 作为 tf.keras 的直接替代品使用。这由 api_gen.py 中的 create_legacy_directory() 函数处理。

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

兼容层生成包括：

创建目录结构 keras/api/_tf_keras/keras/
复制和调整主 API 结构
处理旧模块以确保与 TensorFlow Keras 的兼容性

顶层包初始化生成

update_package_init() 函数更新顶层 keras/__init__.py 文件，以导入所有来自生成 API 的公共符号

来源： api_gen.py145-160 keras/__init__.py1-80

API 生成工作流程

API 生成过程通常通过以下方法触发：

开发工作流

来源： api_gen.py1-7

CI/CD集成

API 生成也是持续集成过程的一部分，以确保 API 与源代码保持一致。

来源： api_gen.py199-202

技术实现细节

临时构建目录

API 生成会创建一个临时构建目录，以避免在生成过程中修改原始源文件。

功能	目的
`copy_source_to_build_directory()`	创建临时目录并复制源文件
`export_version_string()`	将版本字符串添加到生成的 API 中
`create_legacy_directory()`	生成 TensorFlow 兼容层
`update_package_init()`	更新顶层包初始化文件

来源： api_gen.py20-33 api_gen.py137-143

特殊 API 功能

API 生成确保了以下几个特殊功能：

命名空间清理：顶层 __init__.py 包含代码，以防止 .src 和 .api 出现在自动补全中，或在使用 from keras import * 时出现。
版本信息：API 生成从 keras.src.version 中添加版本信息。
模块搜索路径：该包将 API 目录添加到模块搜索路径中，以实现直接导入。

来源： keras/__init__.py58-80

结论

Keras 3 中的 API 生成系统在实现细节和公共 API 之间提供了清晰的分离。这使得开发人员能够专注于实现，同时确保用户拥有一个一致、结构良好的接口可供使用。此过程的自动化性质减少了公共 API 中出现错误和不一致的可能性。