TensorFlow.js Converter 开发者指南Python 环境搭建、单元测试与 pip 打包发布全流程【免费下载链接】tfjsA WebGL accelerated JavaScript library for training and deploying ML models.项目地址: https://gitcode.com/gh_mirrors/tf/tfjs本篇指南以 tfjs-converter/DEVELOPMENT.md 为主体面向希望参与 TensorFlow.js Converter模型转换器Python 侧开发的工程师。TensorFlow.js Converter 是 tfjs 仓库中的核心子项目负责把 TensorFlow SavedModel、Keras H5、TF-Hub 模块、JAX/Flax 模型等转换成可在浏览器与 Node.js 中加载的 tfjs 格式tfjs_layers_model/tfjs_graph_model其 Python 工具链集中在python/目录下。读完本文你将掌握如何在虚拟环境中安装依赖并运行pylint代码检查、如何通过脚本或 Bazel 两种方式运行全部 Python 单元测试、如何构建并本地验证tensorflowjspip wheel 包以及如何使用debugpy对单测进行断点调试。一、先认清 Python 侧代码的分布tfjs-converter/python/是 converter 的 Python 实现所在目录包含库代码、二进制工具与测试。核心目录结构如下tensorflowjs/Python 包主体。其中converters/子目录承载转换逻辑关键模块包括converter.py命令行入口与转换主流程对应tensorflowjs_converter命令keras_h5_conversion.py/keras_tfjs_loader.pyKeras H5 与 tfjs layers model 的双向转换tf_saved_model_conversion_v2.pyTensorFlow SavedModel 到 tfjs graph model 的转换jax_conversion.pyJAX/Flax 模型的转换fold_batch_norms.py、fuse_depthwise_conv2d.py、fuse_prelu.py、normalize_bias_add.py等图重写优化Graph Rewrite模块wizard.py交互式转换向导tensorflowjs_wizard命令op_list/各类算子白名单 JSON如arithmetic.json、convolution.json、control.json用于校验与映射 TensorFlow 算子。run-python-tests.sh一键运行全部 Python 测试的脚本。setup.pypip 包构建配置。requirements.txt/requirements-dev.txt/extra-requirements.txt运行与开发依赖。每个核心模块都配套了同名的*_test.py单元测试如converter_test.py、tf_saved_model_conversion_v2_test.py、jax_conversion_test.py这是后面讨论测试策略的基础。二、搭建 Python 开发环境官方文档明确建议在 virtualenv 或 pipenv 等隔离的虚拟环境中进行 Python 开发与测试避免污染系统级 Python 环境——尤其是在后面构建和安装 pip 包时隔离环境能防止意外覆盖已安装的tensorflowjs或其他依赖。进入python/目录后先安装测试所需的依赖cd python pip install -r requirements.txt当前仓库的 requirements.txt 声明了转换器运行时的核心依赖主要包括tensorflow2.13.0,3与tf-keras2.16.0转换与模型加载所依赖的 TensorFlow 及 Keras 实现jax0.4.23、jaxlib0.4.23、flax0.7.5JAX/Flax 模型转换支持tensorflow-hub0.16.1TF-Hub 模块转换支持tensorflow-decision-forests1.9.0决策森林模型支持six1.16.0,2、packaging~23.1、importlib_resources5.9.0通用工具依赖。此外requirements-dev.txt 通过-r requirements.txt引入全部运行依赖并追加开发期依赖pylint代码检查、PyInquirer1.0.3wizard 交互、setuptools65.6.3与debugpy1.6.5调试。这些版本号以仓库内文件为准。需要说明开发文档写作时曾要求同时支持 Python 2 与 Python 3原文明确提示 Be sure to run the tests underbothPython 2 and Python 3而当前仓库的构建产物已是纯 Python 3 定位——python/BUILD.bazel 中py_wheel目标声明了python_tag py3。参与开发时请以仓库当前状态为准。三、代码检查pylint在提交代码前运行 Python linter 以保持代码风格一致cd python pylint tensorflowjspylint 可以直接通过系统包管理器安装如apt-get install -y pylint也可以依赖requirements-dev.txt中锁定的版本。run-python-tests.sh脚本内部也会在执行测试前先运行 pylint见下文因此即使忘记手动检查一键测试脚本也会替你把关。四、运行 Python 单元测试的两种方式DEVELOPMENT.md 提供了两条等价且可自行偏好的测试路径。方式一run-python-tests.sh脚本cd python ./run-python-tests.sh查看 run-python-tests.sh 的源码可知其内部执行流程安装virtualenv并创建临时虚拟环境激活使用find递归收集python/目录下所有*_test.py文件默认安装requirements-dev.txt也可传入一个自定义 requirements 文件作为唯一参数运行pylint --rcfile.pylintrc tensorflowjs设置PYTHONPATH.:${PYTHONPATH}后逐个执行python ${TEST_FILE}全部通过后输出 All tests passed. 并清理临时虚拟环境。脚本默认使用python解释器因此在运行前请确保当前环境的python指向目标版本。该方式不依赖 Bazel适合没有安装 Bazel 的开发机。方式二Bazel 测试如果已安装 Bazel参考官方安装指南可以在仓库根目录执行cd python bazel test tensorflowjs/...当前仓库的 Bazel 配置进一步演进更推荐从仓库根目录通过 yarn 封装运行yarn bazel test //tfjs-converter/python/...对应地也可以使用yarn run-python-tests触发上文的一键脚本。在 python/tensorflowjs/converters/BUILD.bazel 中每个转换模块都定义了对应的py_test目标例如converter_test、keras_h5_conversion_test、tf_saved_model_conversion_v2_test、jax_conversion_test、wizard_test等并显式声明了各自依赖的第三方库如expect_tensorflow_installed、expect_numpy_installed、expect_tf_keras_installedBazel 会负责依赖解析与隔离执行。只运行单个测试用例调试特定用例时Bazel 的--test_filter非常有用例如yarn bazel test //tfjs-converter/python/tensorflowjs/converters:tf_saved_model_conversion_v2_test --test_filterConvertTest.test_convert_saved_model_v1五、构建并验证 tensorflowjs pip 包5.1 构建 wheel在python/目录下调用build-pip-package.sh并传入一个用于存放 wheel 文件的目标目录cd python # 你需要指定一个存放 pip wheel 文件的文件夹例如 ./build-pip-package.sh /tmp/my_tensorflowjs_pip从 build-pip-package.sh 的实现来看脚本会检查并创建目标目录安装并激活python3的临时 virtualenv从 Bazel 产物目录dist/bin/tfjs-converter/python/*py3*.whl拷贝 wheel 到目标目录——因此执行该脚本前通常需要先通过yarn bazel build tfjs-converter/python:python3_wheel仓库中 scripts/create_python_pips.sh 的做法生成 wheel可选地执行 test-on-install见 5.2可选地通过twine上传到测试或正式 PyPI。wheel 的元数据由 python/BUILD.bazel 中的py_wheel目标定义发行名为tensorflowjs、python_tag py3并内置两个控制台脚本入口tensorflowjs_converter与tensorflowjs_wizard分别指向tensorflowjs.converters.converter:pip_main与tensorflowjs.converters.wizard:pip_main同时在requires中列出了运行时依赖集合。如果构建成功目标目录下会出现形如tensorflowjs-version-py3-none-any.whl的文件具体版本号以仓库 version.py 为准文档示例中的tensorflowjs-0.0.1-py2-none-any.whl属于早期示例当前仓库仅构建 py3 wheel。5.2 安装 wheel 并做 test-on-install构建完成后即可用pip install安装pip install --force-reinstall \ /tmp/my_tensorflowjs_pip/tensorflowjs-0.0.1-py2-none-any.whl强烈建议在 virtualenv 或 pipenv 中安装以免改动系统基础环境。build-pip-package.sh还提供了--test标志在构建完 pip 包后立即执行 test-on-install即在全新虚拟环境中安装该 wheel 并运行 test_pip_package.py 中的测试./build-pip-package.sh --test /tmp/my_tensorflowjs_pip从脚本源码看--test流程会依次执行卸载旧版tensorflowjs→ 在临时目录中以pip install ${WHEEL_PATH}[wizard]安装刚构建的 wheel → 运行python test_pip_package.py→ 清理临时目录。注意该测试文件会在运行时主动检查如果tensorflowjs源码目录出现在当前路径即从源码目录直接运行测试会直接失败Do not run this test from the Python source directory这是为了确保测试针对的是 pip 安装产物而非源码。5.3 pip 包测试覆盖了什么test_pip_package.py 是对 pip 包 Python API 与命令行二进制最直接的验证涵盖API 层tfjs.converters.save_keras_model()保存 Keras 模型并校验model.json的modelTopology、weightsManifest结构tfjs.converters.load_keras_model()读回模型并逐权重比对CLI 层通过子进程调用tensorflowjs_converter覆盖--input_format kerasH5、tf_saved_modelv1/v2、tf_frozen_model、tfjs_layers_model等多种输入格式的转换以及反向转换tfjs → keras H5 / keras_saved_model边界与报错非法--input_format值、缺少input_path、对 Keras 输入误传--signature_name等场景应报错并给出提示高级特性--split_weights_by_layer按层拆分权重、--weight_shard_size_bytes自定义权重分片大小、--quantization_bytes与--quantize_uint16权重量化uint16 量化后权重文件体积约为原来的 1/2测试对此有断言。这些用例同时覆盖了 python/BUILD.bazel 与 converters/BUILD.bazel 中定义的 Bazel 测试目标可作为理解转换器能力边界的最佳入口。六、进阶用 debugpy 断点调试测试Bazel 测试在沙箱中运行传统print调试不直观。当前仓库的 Python README见 python/README.md记录了基于debugpy的 VSCode 调试方案在要调试的测试文件顶部加入import debugpy debugpy.listen((localhost, 5724)) print(Waiting for debugger to connect. See tfjs-converter python README) debugpy.wait_for_client()若对应 Bazel 测试目标尚未依赖debugpy需要在 BUILD 文件中补充//tfjs-converter/python/tensorflowjs:expect_debugpy_installed用yarn bazel run --configdebugpy运行该测试并在 VSCode 中选择Python: Attach (Converter)连接调试器。七、结语与后续阅读至此你已掌握 TensorFlow.js Converter Python 侧从环境搭建、静态检查、单元测试到 pip 打包发布的完整开发闭环日常迭代使用run-python-tests.sh或yarn bazel test //tfjs-converter/python/...快速回归发布前用build-pip-package.sh --test验证 wheel 的可安装性与可用性遇到疑难用例则借助--test_filter与debugpy定点调试。若想进一步深入转换器的算子映射与图优化实现可从 op_list 目录的算子白名单 JSON 和tf_saved_model_conversion_v2.py入手而 python/README.md 与 tfjs-converter/README.md 也提供了与本文互补的安装、CLI 用法与开发说明。【免费下载链接】tfjsA WebGL accelerated JavaScript library for training and deploying ML models.项目地址: https://gitcode.com/gh_mirrors/tf/tfjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考