Autoware 模型制品（Artifacts）下载指南：基于 Ansible 从 Hugging Face 获取感知模型 Bundle-平芜编程栈

自动驾驶

【免费下载链接】autoware

Autoware - the world's leading open-source software project for autonomous driving

项目地址：https://gitcode.com/GitHub_Trending/au/autoware

导读

Autoware 的感知（Perception）栈依赖一系列经过训练的深度学习模型来完成推理，这些模型以“模型 Bundle”的形式托管在 Hugging Face 上，并通过仓库内的artifactsAnsible 角色统一拉取到本地。本文以ansible/roles/artifacts/README.md为核心，完整讲解该角色的下载流程、提交哈希（commit hash）选择逻辑、数据目录布局（~/autoware_data/ml_models）、权限模型以及从旧版布局迁移的方法，并结合ansible/roles/artifacts/下的角色源码（tasks、defaults、meta）和 install_dev_env.yaml 进行源码级印证。读完本文，你将能够独立、正确地运行--tags artifacts完成全部模型下载，并理解每个任务为何以当前用户身份运行、为何通常需要保留--ask-become-pass。

背景：artifacts 角色解决什么问题

Autoware 感知栈（perception stack）在推理阶段需要使用多种模型，例如激光雷达目标检测、BEV 融合、交通灯识别、轨迹预测等。这些模型体积大、版本多、更新频繁，不适合直接纳入 Autoware 源码仓库，因此统一托管在 Hugging Face 的AutowareFoundation组织下。

仓库内的artifacts角色通过一条命令完成全部模型的下载：

ansible-playbook autoware.dev_env.install_dev_env --tags artifacts

其设计要点如下：

每个模型 Bundle 都固定（pin）到一个版本标签（tag），而非跟随main分支漂移，保证可复现性；
默认下载到~/autoware_data/ml_models，这是 asset 类型化的~/autoware_data/布局的一部分；
下载以运行 playbook 的用户身份执行，整个角色不使用 sudo，模型文件的所有权始终归属于该用户（详见后文“权限模型”一节）。

在 install_dev_env.yaml 中，artifacts 角色被赋予universe与artifacts两个标签，并排在 CUDA、TensorRT、spconv 等运行时依赖之后，注释明确说明其职责是“ONNX models and other artifacts”。

下载前：确认当前提交哈希（commit hash）

模型标签与 Autoware 源码版本之间存在对应关系，下载前需要先确认当前代码所处的版本状态，必要时切换到最新发布标签。原文档提供了如下决策图：

决策规则可概括为三条分支：

当前处于某个发布标签（release tag）：无需改动提交哈希，直接继续后续步骤；
当前位于main分支，且已拉取autoware-nightly.repos：同样无需改动，继续执行；
当前位于main分支，但只拉取了autoware.repos：需要切换到最新发布标签。

如果需要切换到最新标签，执行以下命令：

cd ~/autoware git fetch --tags && git checkout $(git describe --tags $(git rev-list --tags --max-count=1))

命令含义拆解：

git rev-list --tags --max-count=1：按提交时间取最新一个带标签的提交；
git describe --tags <commit>：为该提交解析出最近的标签名；
git checkout <tag>：切换到该标签。

模型制品下载完成后，可以再切回自己想要的任意分支或提交哈希，下载行为与源码版本无关。

说明：autoware.repos与autoware-nightly.repos分别位于仓库根目录的 repositories/autoware.repos 与 repositories/autoware-nightly.repos，是拉取 Autoware 各功能包仓库清单的文件。

前置要求：安装 Ansible

下载模型依赖 Ansible，安装步骤在 ansible 安装指南中有完整说明。核心流程如下（基于 ansible/README.md）：

# 移除 apt 安装的旧版 ansible（Ubuntu 22.04 自带版本过旧） sudo apt-get purge ansible # 安装 pipx sudo apt-get -y update sudo apt-get -y install pipx # 将 pipx 加入系统 PATH python3 -m pipx ensurepath # 通过 pipx 安装指定大版本范围的 ansible pipx install --include-deps --force "ansible==10.*"

这里使用 pipx 而非 pip，是为了将 Ansible 隔离在独立的虚拟环境中，避免污染系统 Python；--force确保重复安装时收敛到指定版本。

下载 Artifacts：分步操作

步骤 1：安装 Ansible Collections

在仓库根目录执行：

cd ~/autoware # 克隆仓库的根目录 ansible-galaxy collection install -f -r "ansible-galaxy-requirements.yaml"

其中ansible-galaxy-requirements.yaml位于仓库根目录，是定义autoware.dev_envcollection 依赖的清单文件。

注意：当有新 playbook 加入时，此步骤需要重新执行，以确保本地 collection 与仓库定义保持一致。

步骤 2：运行 playbook 下载制品

ansible-playbook autoware.dev_env.install_dev_env --tags artifacts -e "data_dir=$HOME/autoware_data/ml_models" --ask-become-pass

各参数的作用：

参数	作用
`autoware.dev_env.install_dev_env`	由 collection 提供的入口 playbook（对应仓库 ansible/playbooks/install_dev_env.yaml）
`--tags artifacts`	只执行被标记为`artifacts`的角色，跳过其余开发环境安装任务
`-e "data_dir=$HOME/autoware_data/ml_models"`	通过 extra vars 覆盖默认的`data_dir`，指定模型下载的目标目录
`--ask-become-pass`	请求 sudo 密码；只要后文提到的两个依赖条件任一可能成立，就应保留该参数

下载行为说明（原文档要点）：

每个模型 Bundle 都固定到 Hugging Face 上的一个版本标签；
制品完整性依赖 Hugging Face Hub 与传输层（HTTPS）保证，而不是依赖本角色内固定的校验和（checksum）——也就是说，角色本身不携带并校验每个文件的哈希值，信任模型由平台侧背书。

步骤 3（可选）：验证下载结果

下载完成后，data_dir下应出现与每个模型仓库对应的子目录（如bevfusion、lidar_centerpoint、tensorrt_yolox等），具体清单见下一节。可通过ls -la或du -sh查看目录结构与占用空间，确认所有权归属当前用户（ls -l的属主列应为你自己的用户名而非 root）。

源码级解析：artifacts 角色内部实现

本节结合 ansible/roles/artifacts/ 下的实际源码，说明“一条命令背后到底发生了什么”。

下载任务与模型清单

角色的全部下载逻辑集中在 tasks/main.yaml，核心任务是对清单逐项执行 Hugging Face CLI：

- name: Download the model bundles from Hugging Face ansible.builtin.command: cmd: >- hf download AutowareFoundation/{{ item.repo }} --revision {{ item.revision }} --local-dir "{{ data_dir }}/{{ item.dest | default(item.repo) }}" environment: PATH: "{{ ansible_facts.env.PIPX_BIN_DIR | default(ansible_facts.env.HOME ~ '/.local/bin', true) }}:{{ ansible_facts.env.PATH }}" HF_TOKEN: "{{ lookup('env', 'HF_TOKEN') }}" changed_when: false

要点解读：

hf download：调用 Hugging Face CLI（由huggingface_cli依赖角色安装）从AutowareFoundation组织下的指定仓库下载模型；
--revision：指定标签（tag）作为版本；
--local-dir：dest相对于data_dir，未指定dest时默认为仓库名；
environment.PATH：优先将pipx的 bin 目录（$HOME/.local/bin）前置到 PATH 中，确保能定位到hf命令；
environment.HF_TOKEN：透传宿主环境变量HF_TOKEN（若已设置，可用于私有或受限模型仓库的鉴权）；
changed_when: false：该任务不参与 Ansible 的“变更”判定，重复运行不会误报 changed 状态。

完整的模型清单（仓库名 / 标签 / 目标子目录）如下，与 tasks/main.yaml 逐行对应：

模型仓库（AutowareFoundation/…）	版本标签（revision）	目标子目录（相对于 data_dir）	用途/备注
`yabloc_pose_initializer`	`v1.0`	`yabloc_pose_initializer`	YabLoc 视觉定位初始化
`bevfusion`	`v2.0`	`bevfusion`	BEV 融合 3D 目标检测
`camera_streampetr`	`v1.0`	`camera_streampetr`	相机端到端 3D 检测（StreamPETR）
`tensorrt_bevdet`	`v1.0`	`tensorrt_bevdet`	BEVDet 的 TensorRT 版本
`image_projection_based_fusion`	`v5.0`	`image_projection_based_fusion`	基于图像投影的融合检测
`lidar_apollo_instance_segmentation`	`v1.0`	`lidar_apollo_instance_segmentation`	Apollo 实例分割模型
`lidar_centerpoint`	`v4.1`	`lidar_centerpoint`	CenterPoint 点云 3D 检测
`lidar_transfusion`	`v2.1`	`lidar_transfusion`	TransFusion 点云 3D 检测
`tensorrt_yolox`	`v1.0`	`tensorrt_yolox`	YOLOX 的 TensorRT 版本；同时承载 whole_image_traffic_light_detector 模型
`traffic_light_classifier`	`v4.0`	`traffic_light_classifier`	交通灯状态分类
`diffusion_planner`	`v3.0`	`diffusion_planner/v3.0`	轨迹规划器（扩散模型），多版本并存
`diffusion_planner`	`v3.1`	`diffusion_planner/v3.1`	同上
`diffusion_planner`	`v4.0`	`diffusion_planner/v4.0`	同上
`diffusion_planner`	`v5.0`	`diffusion_planner/v5.0`	同上
`tensorrt_vad`	`v0.1`	`vad/v0.1`	VAD 模型；本地目录刻意命名为`vad`（节点读取`$(var data_path)/vad/v0.1`）
`traffic_light_fine_detector`	`v3.0`	`traffic_light_fine_detector`	交通灯精细检测
`simpl_prediction`	`v0.1`	`simpl_prediction`	轨迹预测（SimPL）
`ptv3`	`v4.0`	`ptv3`	Point Transformer V3 点云模型
`lidar_frnet`	`v2.0`	`lidar_frnet`	FRNet 点云检测
`calibration_status_classifier`	`v2.0`	`calibration_status_classifier`	标定状态分类

其中两处需要特别注意的设计：

diffusion_planner每个版本都是一个 tag：由于同一仓库的每个 tag 在仓库根目录持有相同文件名，若不分目录下载，后下载的版本会覆盖先下载的版本。因此清单为每个版本显式指定了独立的dest（如diffusion_planner/v3.0），实现多版本共存；
tensorrt_vad的本地目录名为vad：因为下游节点读取$(var data_path)/vad/v0.1，目录名必须与节点约定一致，而不能沿用仓库名。

data_dir 默认值

默认下载位置定义在 defaults/main.yaml：

data_dir: "{{ ansible_facts.env.HOME }}/autoware_data/ml_models"

即~/autoware_data/ml_models，它是 asset 类型化~/autoware_data/布局中的一类目录。该布局包含五类 asset 子目录：

子目录	内容
`assets/`	通用资产
`maps/`	地图数据
`ml_models/`	机器学习模型（artifacts 角色的下载目标）
`recordings/`	回放数据（rosbag 等）
`scenarios/`	仿真场景

这种按类型划分的布局，让地图、模型、回放、场景各归其位，便于多消费方（Ansible 角色、ROS 节点、Docker 容器）按约定路径访问。

依赖角色与权限模型

角色的依赖声明在 meta/main.yaml，共两个依赖角色，且仅在特定条件下才需要 sudo：

dependencies: - role: autoware.dev_env.autoware_data_ownership - role: autoware.dev_env.huggingface_cli

autoware_data_ownership：纠正“root 拥有安装目录”的历史遗留问题。该角色的任务（见 autoware_data_ownership/tasks/main.yaml）先解析真实路径，再查找目录树下不属于当前用户的路径，发现后以 root 身份执行chown -Rh将所有权归还给当前用户。早期版本以 root 下载制品，导致目录被 root 占用，进而阻塞所有消费方：Ansible 角色无法写入、ROS 节点无法写入 TensorRT 引擎文件、docker/容器中的非特权aw用户无法读取。该角色只在“目录下存在非当前用户所有路径”这一条件成立时才使用become。
huggingface_cli：在 pipx 缺失时安装 pipx。其任务（见 huggingface_cli/tasks/main.yaml）先检查/usr/bin/pipx是否存在，不存在则通过 apt 安装 pipx，再执行pipx install --force huggingface_hub==1.*安装 Hugging Face CLI（hf）。--force使每次运行收敛到该版本约束，修正越界版本；将huggingface_hub主版本约束在1.*是为了保持hfCLI 的命令面稳定。

总结权限模型（原文档核心结论）：artifacts 角色自身的每个任务都以运行 playbook 的用户身份下载，不使用 sudo，因此制品所有权始终属于该用户；只有上述两个依赖角色才可能触发 sudo，且各自都有明确的触发条件。因此：

只要“root 遗留所有权需要纠正”或“pipx 缺失”任一条件仍可能成立，就应保留--ask-become-pass。

从 autoware_data_ownership/README.md 还可以看到：当~/autoware_data不存在、或用户已拥有其下所有路径时，该角色什么都不做；干净安装通常无需密码。

从旧版布局迁移

早期版本的 artifacts 角色会直接下载到~/autoware_data/。为匹配新的 asset 类型化布局，需要将现有模型目录移动到~/autoware_data/ml_models/下（若之前使用过~/autoware_map/，则移入~/autoware_data/maps/）：

mkdir -p ~/autoware_data/ml_models shopt -s extglob mv ~/autoware_data/!(ml_models|maps|recordings|scenarios|assets) ~/autoware_data/ml_models/ # 仅当你也使用过 ~/autoware_map/ 时才需要： [ -d ~/autoware_map ] && mv ~/autoware_map ~/autoware_data/maps

命令要点：

shopt -s extglob：开启 bash 扩展通配符，使!(...)模式生效；
mv ~/autoware_data/!(ml_models|maps|recordings|scenarios|assets) ~/autoware_data/ml_models/：把~/autoware_data下除五个标准子目录之外的所有顶层条目（即旧版散落的模型目录）一次性移入ml_models/；
条件判断[ -d ~/autoware_map ]：仅在存在旧地图目录时执行迁移。

重新运行 playbook 也是安全的：它会向新的ml_models/目录填充模型，迁移完成后可以删除旧版顶层遗留的模型文件夹。

常见问题与注意事项

下载目录权限异常（Permission denied）：多为旧版 root 下载遗留。运行--tags artifacts时保留--ask-become-pass，让autoware_data_ownership依赖角色自动修复所有权；也可手工执行sudo chown -Rh "$USER:$USER" "$(readlink -f ~/autoware_data)"（该命令与角色内部执行的一致，readlink -f用于解析符号链接场景）。
hf: command not found：huggingface_cli依赖角色应已通过 pipx 安装huggingface_hub==1.*；若手动安装，可执行pipx install --force "huggingface_hub==1.*"（见 huggingface_cli/README.md）。
新增 playbook 后下载失败/行为不一致：记得重新执行ansible-galaxy collection install -f -r "ansible-galaxy-requirements.yaml"。
需要下载私有/受限模型：预先在环境中导出HF_TOKEN，任务会通过lookup('env', 'HF_TOKEN')透传给hfCLI。
模型完整性校验：本角色信任 Hugging Face Hub 与 HTTPS 传输，不固定校验和；如需更严格的可复现性，应在平台侧管理模型发布与审计。

结语

artifacts角色把“数十个模型、不同版本标签、统一目录布局”的复杂下载流程收敛为一条ansible-playbook ... --tags artifacts命令：通过hf download逐项拉取固定标签的模型 Bundle，默认落盘~/autoware_data/ml_models，并借助两个条件触发的依赖角色（所有权修复、pipx 安装）保证“制品归用户所有、命令可重复执行”。理解这份 README 与配套源码，是顺利搭建可复现的 Autoware 开发/运行环境的关键一步——既适用于首次安装，也适用于旧版布局的平滑迁移。