DataHub Vertex AI 元数据接入指南：模型、训练任务、流水线与跨平台血缘的全量采集实践

DataHub Vertex AI 元数据接入指南模型、训练任务、流水线与跨平台血缘的全量采集实践【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本指南面向需要将 Google Cloud Vertex AI 的 ML 资产模型、数据集、训练任务、端点、实验、模型评估与流水线纳入 DataHub 元数据治理体系的数据工程师与 ML 平台团队。文章以仓库 metadata-ingestion/docs/sources/vertexai/vertexai_pre.md 与 vertexai_post.md 为核心骨架结合vertexaisource 的实际实现代码与示例配方完整讲解多项目/多区域接入、GCP 权限配置、限流与性能调优、状态化增量采集、CustomJob 血缘以及跨平台GCS、BigQuery、S3、Snowflake、ABS血缘打通等实战要点。读完后你将能够独立编写一份生产可用的 Vertex AI 采集 recipe并理解每个关键参数在源码中的底层行为。一、能力总览Vertex AI 中哪些资产会被采集vertexaisource实现位于 metadata-ingestion/src/datahub/ingestion/source/vertexai/vertexai.py平台标识为vertexai当前支持状态为 BETA负责把 Vertex AI 中的以下七类 ML 资产摄入 DataHubVertex AI 资产DataHub 实体说明Model / Model VersionMlModelGroup/MlModel模型组对应 Vertex 模型名称模型版本命名为{model_name}_{model_version}如my_vertexai_model_1DatasetDataset支持 Text、Tabular、Image、Video、TimeSeries 五类托管数据集Training JobDataProcessInstance支持 AutoML 各类型与 CustomJob / CustomTrainingJob / CustomContainerTrainingJob / CustomPythonPackageTrainingJobEndpointMlModel已部署到端点的模型版本Experiment / Experiment RunContainer/DataProcessInstanceExperiment 作为逻辑分组映射为容器Run 记录参数、指标与工件Model Evaluation评估实体包含评估指标关联模型与测试数据集PipelineJob / Task / Task RunDataFlow/DataJob/DataProcessInstance一个流水线模板对应一个稳定的 DataFlow任务嵌套在父流水线下完整的实体映射关系可参考 vertexai/README.md 中的 Concept Mapping 表。从源码常量看资源在 DataHub UI 中还会按Models、Training Jobs、Datasets、Endpoints、Pipelines、Experiments、Evaluations等分类容器组织见 vertexai_constants.py。二、多项目、多区域与多实例隔离2.1 用project_ids取代已弃用的project_idsource 支持同时采集多个 GCP 项目可通过project_ids显式列表、project_labels按标签发现或project_id_pattern正则匹配三种方式指定目标项目。需要区分不同环境时通过env如PROD、DEV、STAGING标记可选的platform_instance字段则为资源加命名空间避免从多套 Vertex AI 环境采集时产生 URN 冲突。重要单数形式的project_id配置项已被弃用未来版本将移除。请使用列表形式# 已弃用 project_id: my-project # 推荐写法 project_ids: - my-project仓库中的迁移行为在配置类中有着明确的实现vertexai_config.py只设置了project_id、未设置project_ids时值会被自动搬移到project_ids并打印弃用告警日志两者同时设置且值相同时project_id被静默忽略两者同时设置但值冲突时采集会直接以校验错误失败提示移除弃用字段。因此无需手动迁移只需在方便的时候更新 recipe 以消除告警。2.2 项目校验规则与正则语法检查配置加载阶段会执行严格校验vertexai_config.pyproject_ids中的每个 ID 必须为 6~30 位、小写字母/数字/连字符、以字母开头并以字母或数字结尾非法格式会直接抛出校验错误重复项会被去重保持顺序project_labels必须是key:value形式仅允许小写字母、数字、下划线与连字符project_id_pattern的 allow/deny 正则会在启动时用re.compile预编译语法错误会立即报错而不是在运行中途才暴露若显式配置的project_ids全部被project_id_pattern过滤掉也会在启动时提前失败避免空跑。2.3 多区域regions与discover_regions单数region同样已弃用推荐改用列表或自动发现# region: us-west2 # [已弃用] 优先使用 regions 或 discover_regions regions: - us-west2 - us-central1 discover_regions: true # 枚举该项目的可用区域并全部扫描配置类要求三者至少指定其一require_region_source校验见 vertexai_config.py否则启动即报错。discover_regions: true会在每个项目下自动发现可用区域适合区域众多且经常变动的环境。三、前置条件网络、认证与最小权限3.1 GCP 认证ADC 或服务账号密钥采集前需保证与目标区域的网络连通、具备合法认证凭据与元数据 API 的读权限。推荐使用 Application Default CredentialsADC完成认证。两种提供凭据的方式方式一环境变量指向密钥文件$ export GOOGLE_APPLICATION_CREDENTIALS/path/to/keyfile.json方式二在 recipe 中内联 credential 配置内容取自服务账号 JSON 密钥文件credential: private_key_id: d0121d0000882411234e11166c6aaa23ed5d74e0 private_key: -----BEGIN PRIVATE KEY-----\nMIIyourkey\n-----END PRIVATE KEY-----\n client_email: testsuppproject-id-1234567.iam.gserviceaccount.com client_id: 123456678890服务账号密钥文件形如{ type: service_account, project_id: project-id-1234567, private_key_id: d0121d0000882411234e11166c6aaa23ed5d74e0, private_key: -----BEGIN PRIVATE KEY-----\nMIIyourkey\n-----END PRIVATE KEY-----, client_email: testsuppproject-id-1234567.iam.gserviceaccount.com, client_id: 113545814931671546333, auth_uri: https://accounts.google.com/o/oauth2/auth, token_uri: https://oauth2.googleapis.com/token, auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs, client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/test%suppproject-id-1234567.iam.gserviceaccount.com }创建服务账号并在所有目标项目上授予角色后下载密钥文件即可。默认推荐角色为roles/aiplatform.viewer可覆盖下表全部权限。3.2 权限清单服务账号需要在所有目标项目上被授予以下权限PermissionDescriptionaiplatform.models.list查看并列出项目中的所有 ML 模型aiplatform.models.get查看特定 ML 模型的详情aiplatform.endpoints.list查看并列出项目中的所有预测端点aiplatform.endpoints.get查看特定预测端点的详情aiplatform.trainingPipelines.list查看并列出项目中的所有训练流水线aiplatform.trainingPipelines.get查看特定训练流水线的详情aiplatform.customJobs.list查看并列出项目中的所有自定义任务aiplatform.customJobs.get查看特定自定义任务的详情aiplatform.experiments.list查看并列出项目中的所有实验aiplatform.experiments.get查看项目中特定实验的详情aiplatform.metadataStores.list查看并列出项目中的所有元数据存储aiplatform.metadataStores.get查看特定元数据存储的详情aiplatform.executions.list查看并列出项目中的所有执行记录aiplatform.executions.get查看特定执行记录的详情aiplatform.datasets.list查看并列出项目中的所有数据集aiplatform.datasets.get查看特定数据集的详情aiplatform.pipelineJobs.list查看并列出项目中的所有流水线任务aiplatform.pipelineJobs.get查看特定流水线任务的详情关于 ML Metadata 权限默认开启的 ML Metadata 提取用于增强血缘追踪依赖上述aiplatform.metadataStores.*与aiplatform.executions.*权限。若服务账号缺少这些权限连接器会优雅降级并输出告警若不需要 ML Metadata 功能可显式关闭use_ml_metadata_for_lineage: false、extract_execution_metrics: false、include_evaluations: false。关于项目自动发现的权限使用project_labels或project_id_pattern自动发现项目时服务账号还必须在每个候选项目上具备resourcemanager.projects.get通过roles/browser授予否则 Cloud Resource Manager 的search_projectsAPI 无法返回该项目。若显式指定project_ids则无需任何 Resource Manager 权限。从源码看项目解析通过resolve_gcp_projects与GcpProjectFilterConfig完成vertexai.py。四、完整 Recipe 与关键参数详解仓库提供的官方示例配方 vertexai_recipe.yml 完整如下source: type: vertexai config: project_ids: - acryl-poc # project_id: acryl-poc # [已弃用] 仍可用——会自动迁移到 project_ids 并输出告警 # region: us-west2 # [已弃用] 优先使用 regions 或 discover_regions # regions: # - us-west2 # - us-central1 # discover_regions: true # 枚举可用区域并全部扫描 # project_labels: # - env:prod # project_id_pattern: # allow: # - .*-prod # 必须设置 GOOGLE_APPLICATION_CREDENTIALS 或按如下方式提供 credential # credential: # private_key: -----BEGIN PRIVATE KEY-----\\nprivate-key\\n-----END PRIVATE KEY-----\\n # private_key_id: project_key_id # client_email: client_email # client_id: client_id sink: type: datahub-rest config: server: http://localhost:80804.1 采集范围开关配置类vertexai_config.py提供了以下布尔开关控制采集范围默认全部为trueinclude_models是否采集模型注册表中的模型与模型版本include_training_jobs是否采集训练任务及相关运行事件include_experiments是否采集实验与实验运行include_pipelines是否采集流水线与任务include_evaluations是否采集模型评估与评估指标use_ml_metadata_for_lineage是否从 ML Metadata API 为 CustomJob 等非 AutoML 训练任务提取血缘extract_execution_metrics是否从 ML Metadata Executions 提取超参数与指标适用于不使用 Experiments、但向 ML Metadata 记录日志的训练任务。另有三个名称/类型过滤模式默认全部放行experiment_name_pattern实验名称的正则 allow/deny 过滤training_job_type_pattern训练任务类名如CustomJob的过滤model_name_pattern模型显示名称的过滤。4.2 性能与分页上限性能设计资源按更新时间倒序最近更新优先抓取配合各类上限参数控制每次运行的处理量。例如设置max_training_jobs_per_type: 1000时每种类型的训练任务只处理最近更新的 1000 个。各资源类型的默认值与硬上限定义在 vertexai_constants.py汇总如下配置项默认值硬上限说明max_models1000050000最多采集的模型数按 update_time 倒序max_training_jobs_per_type100010000每种类型CustomJob、AutoML 等最多采集的训练任务数max_experiments100010000最多采集的实验数max_runs_per_experiment1001000每个实验最多采集的实验运行数max_evaluations_per_model10100每个模型最多采集的评估数ml_metadata_max_execution_search_limit500—搜索训练任务时最多检索的 ML Metadata 执行数按最后更新时间倒序采集慢或超时可调低max_*均可设为None表示不限制官方明确不推荐。API 排序通过ORDER_BY_UPDATE_TIME_DESC/ORDER_BY_CREATE_TIME_DESC常量实现见 vertexai_constants.py这也是增量采集只拿最新的机制基础。4.3 限流配置如果在日志中看到429 Quota Exceeded错误请开启限流rate_limit: true requests_per_min: 600rate_limit默认false开启后放慢采集节奏避免命中 Vertex AI API 配额限制requests_per_min默认600开启限流后的每分钟最大请求数。600 正好匹配 Google 对资源管理类请求每项目每区域每分钟 600 次的标准配额如果同一项目同一区域内还有其他工作负载共享配额应调低如 300。限流由 vertexai.py 引入的RateLimiter工具实现。4.4 状态化采集Stateful Ingestion开启stateful_ingestion带来两个效果增量跳过自上次运行以来未更新的资源会被跳过减少后续运行的重复 API 调用自动软删除从 Vertex AI 删除的实体会在 DataHub 中自动软删除。若只想保留软删除能力、不要增量跳过行为设置stateful_ingestion.ignore_old_state: true即可。状态处理由VertexAIStateHandlervertexai_state.py与StatefulStaleMetadataRemovalConfig配置项承载。4.5 UI 组织优化模型版本归入各自的模型组文件夹流水线任务与任务运行嵌套在父流水线文件夹之下。源码中ResourceCategoryModels、Training Jobs、Datasets、Endpoints、Pipelines、Experiments、Evaluations即为这些 UI 分类容器的定义容器通过gen_containers与ProjectIdKey生成见 vertexai.py。五、血缘能力与 CustomJob 的 ML Metadata 血缘5.1 核心 Vertex AI 血缘连接器捕获以下血缘关系训练任务 → 模型AutoML 与 CustomJob数据集 → 训练任务AutoML 与基于 ML Metadata训练任务 → 输出模型ML Metadata Executions模型 → 训练数据集通过 TrainingData aspect 的直接上游血缘实验运行 → 模型输出模型评估 → 模型与测试数据集输入流水线任务运行 → 模型与数据集通过 DataProcessInstance aspects 记录输入/输出。5.2 跨平台血缘外部数据源当任务配置或 ML Metadata 工件中引用了外部数据集时连接器会自动把 Vertex AI 资源与外部数据集关联支持平台如下引用格式DataHub 平台gs://...gcsbq://project.dataset.table或projects/.../datasets/.../tables/...bigquerys3://...、s3a://...s3wasbs://...、abfss://...abssnowflake://...snowflake这些 URI 模式在 vertexai_constants.py 的URIPatterns中统一定义含输入/输出方向的启发式判断外部平台常量见ExternalPlatforms。5.3 CustomJob 血缘训练代码需向 ML Metadata 记录日志CustomJob 训练任务通过Vertex AI ML Metadata API提取血缘与指标从而获得完整血缘追踪输入数据集 → 训练任务 → 输出模型超参数与指标提取训练任务记录到 ML Metadata Executions 的内容模型评估摄入含评估指标及与模型的关联。这三项能力分别由use_ml_metadata_for_lineage、extract_execution_metrics、include_evaluations控制默认均开启。前提条件你的训练任务必须向 Vertex AI ML Metadata 记录日志——使用 Vertex AI Experiments SDK 会自动完成也可以手动记录工件与执行。仓库文档给出了一个标准的训练日志示例vertexai_post.mdfrom google.cloud import aiplatform aiplatform.init(projectyour-project, locationus-central1) dataset_artifact aiplatform.Artifact.create( schema_titlesystem.Dataset, urigs://your-bucket/data/train.csv, display_nametraining-dataset, ) with aiplatform.start_execution( schema_titlesystem.ContainerExecution, display_nameftraining-job-{job_name}, ) as execution: execution.assign_input_artifacts([dataset_artifact]) # ... 训练逻辑 ... model_artifact aiplatform.Artifact.create( schema_titlesystem.Model, urimodel_uri, display_nametrained-model, ) execution.assign_output_artifacts([model_artifact])源码中MLMetadataSchemas定义了系统级 schemasystem.Dataset、system.Model、system.ContainerExecution、system.Run、system.CustomJob、system.Experiment、system.PipelineRun等ML Metadata 的搜索、分页与重试参数集中在MLMetadataDefaults默认 metadata store 为default页大小上限 100执行搜索上限 500带指数退避重试。5.4 跨平台血缘的platform_instance_map配置为确保外部数据集与原生连接器生成的 URN 完全一致否则血缘连不通需要通过platform_instance_map为外部平台配置平台实例与环境source: type: vertexai config: project_ids: - my-project platform_instance_map: gcs: platform_instance: prod-gcs env: PROD bigquery: platform_instance: prod-bq env: PROD s3: platform_instance: prod-s3 env: PROD snowflake: platform_instance: prod-snowflake env: PROD convert_urns_to_lowercase: true # 必填 - Snowflake 默认使用小写 URN abs: platform_instance: prod-abs env: PROD各平台注意事项Snowflake必须设置convert_urns_to_lowercase: true以匹配 Snowflake 连接器的默认小写 URN 行为其他平台GCS、BigQuery、S3、ABS使用默认的convert_urns_to_lowercase: false。该配置项由PlatformDetail模型承载vertexai_config.py支持platform_instance、env、convert_urns_to_lowercase三个字段。六、进阶配置外部数据集路径归一化当任务引用的外部数据路径带有分区段Hive 分区、日期分区等时每个分区都会生成独立 URN导致血缘碎片化。配置类提供了路径归一化能力normalize_external_dataset_paths默认false开启后剥离外部数据集路径GCS/S3/ABS中的分区段以生成稳定的数据集 URN。例如gs://bucket/data/year2024/month01/会归一化为gs://bucket/data/分区级别的信息仍会通过 DataProcessInstance 保留。默认关闭是为保持向后兼容未来大版本将默认开启partition_pattern_rules用于识别并剥离分区段的正则列表默认按顺序应用三条规则vertexai_config.pypartition_pattern_rules: - /[^/]([^/]) # Hive 风格: /year2024/month01/ - /dt\\d{4}-\\d{2}-\\d{2} # 日期分区: /dt2024-01-15/ - /\\d{4}/\\d{2}/\\d{2} # 日期层级: /2024/01/15/七、限制与故障排查7.1 已知限制模块行为受源 API、权限及平台暴露的元数据范围约束。需要特别关注的能力条件超参数与指标的识别依赖启发式命名规则。源码中HyperparameterPatterns与MetricPatternsvertexai_constants.py基于常见 ML 框架scikit-learn、Keras/TensorFlow、PyTorch、XGBoost的命名约定维护了精确匹配表、前缀/后缀集合不在这些集合内的自定义参数名可能无法被识别CustomJob 血缘依赖训练代码向 ML Metadata 记录日志见上文流水线实体在 1.4.0 版本有破坏性变更此前每次流水线运行会生成独立的 DataFlow 实体新版本改为每个流水线模板对应一个稳定的 DataFlow旧版本产生的实体在新版本采集后会呈现为独立实体建议开启状态化采集配合陈旧实体清理。7.2 故障排查步骤若采集失败按以下顺序排查验证凭据确认GOOGLE_APPLICATION_CREDENTIALS或内联credential有效、密钥未过期验证权限对照第三节权限清单逐项核对服务账号角色注意 ML Metadata 与项目自动发现所需的额外权限验证连通性确认与目标区域 Vertex AI API 的网络连通以及regions/discover_regions配置正确验证范围过滤检查project_ids、project_labels、project_id_pattern是否把目标项目全部过滤掉该情况会在启动时直接报错检查采集日志针对日志中的具体错误调整配置——429配额错误开启rate_limit并降低requests_per_min超时问题可调低ml_metadata_max_execution_search_limit权限缺失则按告警补充角色。八、结语Vertex AI 连接器将 ML 资产的元数据全貌以标准 DataHub 实体形态接入治理平台多项目/多区域接入解决组织级覆盖问题platform_instance与platform_instance_map解决多环境隔离与跨平台血缘对齐问题状态化采集解决增量效率与删除同步问题ML Metadata 血缘则把 CustomJob 等非 AutoML 任务也纳入完整的数据 → 训练 → 模型链路。结合本文给出的权限清单、recipe 模板与参数语义均有 vertexai_config.py 与 vertexai_constants.py 源码佐证你可以直接落地一套生产级的 Vertex AI 元数据采集方案并与 DataHub 中原生的 BigQuery、Snowflake、S3 等数据源血缘无缝衔接。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考