Vertex AI Agent部署失败：ModuleNotFoundError找不到data_science模块

背景 #

使用Google ADK/Agent Builder在Vertex AI Reasoning Engine部署自定义多Agent应用，代码封装在data_science包下的.whl文件中。通过unzip -l验证wheel结构正确，包含data_science/agent.py及data_science/sub_agents/下的所有模块；本地执行pip install dist/*.whl可正常安装并使用该模块。

部署配置 #

• 调用agent_engines.create(...)部署，设置extra_packages = [whl_uri]，其中whl文件存储路径为gs://otm_chatbot_bucket/wheels/data_science-0.1-py3-none-any.whl
• 通过AdkApp.from_module("data_science.agent", "root_agent")创建应用实例
• 已确认Vertex AI服务账号service-<PROJECT_NUMBER>@gcp-sa-aiplatform.iam.gserviceaccount.com拥有存储桶的Storage Object Viewer权限

错误信息 #

远程部署时触发如下错误：

Pickle load failed: Missing module. Service terminating. ModuleNotFoundError: No module named 'data_science'

已验证项：

• whl_uri路径正确，未硬编码
• GCS存储桶权限正常，Vertex AI可访问目标文件
• 本地安装wheel后可正常导入data_science模块

可能的原因及解决方案 #

1. Wheel包打包配置不规范 #

若setup.py或pyproject.toml未正确声明data_science包结构，即使wheel包含文件，pip安装后也无法识别为可导入的Python模块：

• 若使用setup.py，需确保包声明正确：

  from setuptools import setup, find_packages
  
  setup(
      name="data_science",
      version="0.1",
      packages=find_packages(),  # 自动发现所有子包，或显式指定["data_science", "data_science.sub_agents"]
      python_requires=">=3.10"  # 匹配Vertex AI环境的Python版本
  )
  

• 若使用pyproject.toml（推荐），需配置正确的包列表：

  [project]
  name = "data_science"
  version = "0.1"
  packages = ["data_science", "data_science.sub_agents"]
  requires-python = ">=3.10"
  

2. ADK部署的模块加载时机冲突 #

AdkApp.from_module()在本地执行时会直接导入模块，但远程部署时，Vertex AI会先序列化应用对象，再在远程环境反序列化。若序列化时依赖的模块未在远程环境完成安装，会触发模块找不到的错误：

• 确保部署代码中未在agent_engines.create()执行前提前导入data_science模块，所有导入逻辑应放在Agent类定义内部，或仅在wheel安装完成后触发导入。
• 尝试将AdkApp.from_module()的调用封装在延迟加载函数中，避免本地序列化时提前绑定模块路径。

3. Extra Packages安装顺序问题 #

Vertex AI部署时会先安装requirements中的包，再处理extra_packages。若google-adk版本与代码依赖不兼容，可能干扰模块加载：

• 尝试将wheel包的依赖直接声明在requirements中，或调整extra_packages的优先级（可先在本地测试依赖顺序，再对应调整远程配置）。

4. Python版本不兼容 #

确认wheel包的Python版本与Vertex AI Reasoning Engine使用的版本一致（默认多为3.10），打包时需指定兼容版本（参考上述打包配置中的python_requires字段）。

调试方法 #

1. 开启部署调试日志：
   在agent_engines.create()中添加logging_level="DEBUG"参数，查看详细的安装、加载日志，确认wheel包是否被正确下载、安装，以及模块导入时的完整错误栈。

2. 远程环境验证：
   创建临时Vertex AI自定义训练作业，使用相同服务账号和环境，安装目标wheel包并尝试导入data_science模块，验证环境是否能正常识别该模块。

3. 检查安装路径：
   在临时作业中执行pip show data_science，查看安装路径，确认模块文件是否存在于Python的site-packages目录下。

内容的提问来源于stack exchange，提问作者cryptickey