一、写在前面
之前在「人在途中」系列里，聊过一些工具链使用过程中的经验与踩坑笔记。今天这篇，算是补个缺：不讲算法、不讲优化，只讲那些基础但极其影响效率的使用方式。
很多问题其实不是能力问题，而是使用方式的问题。
古人说得直接：工欲善其事，必先利其器。希望这篇文章能帮你把“器”用顺。
二、工具链发布包到底包含什么（必须搞清楚）
这是很多人第一步就忽略的点，但说实话，这就是根本问题。
每次工具链发布，本质上是一个完整的软件套件（Toolchain Suite），通常包含：
- Docker 镜像：提供工具链使用和运行的基本环境，方便快速部署。为了适应不同用户的使用需求，Docker 内的组件比较多，可用于模型量化和模型训练、部署编译等，该镜像即为 GPU 镜像。但也有不少伙伴因为工作分工不同，不需要模型训练等环境。为了减小镜像体积，移除不必要的组件，官方也提供了轻量的 CPU 版本镜像。两个镜像客户可按需取用，如果刚开始不确定自己将来做什么，推荐直接安装 GPU 版本即可。
- OE 包：该包为示例包，提供了工具链基本使用流程（PTQ/QAT/部署等方面）的开发示例。配套 Docker 的 -v 参数挂载后，可以在 Docker 环境中快速使用这些示例。
- 文档（docs）：指导大家在工具链使用过程中的基本使用流程和基本功能、工具、配置方法、模型约束和工具链 API 的说明。
- 文档：release_note 变动说明和使用须知.pdf
本质理解：如果你只会用其中一部分，你的效率一定上不去。
三、拿到发布包，如何最快“跑起来”
不要一上来就研究算子支持、精度问题，这是典型误区。
正确的顺序是“先走后跑”。
Step 1：先看文档（重点：环境部署）
不要全看，重点看：
- 环境要求
- Docker 使用方式
- 示例入口
Step 2：把环境跑起来（优先 Docker）
只要环境没问题，后面一切都好说。
Step 3：按顺序走一遍链路（非常关键）
建议顺序：
- PTQ 快速入门
- QAT 快速入门
- UCP / 示例工程
- 完整推理流程
核心目标不是理解细节，而是“先跑通”。
四、环境部署：为什么强烈建议 Docker
如果你是新手，这里可以给出一个非常明确的结论：永远优先选择 Docker 部署。
原因很现实，都是实战中踩过的坑：
优点
- 环境隔离：不受宿主机污染，不怕依赖冲突。
- 多版本共存：J5 / J6 / X5 可以同时存在，不用反复重装。
- 快速恢复：环境搞坏了，直接删容器重建。
- 并行使用：多个容器互不影响。
什么时候不建议 Docker？
只在两种情况下：原始工程本身就在 Docker 中（避免套娃），或者需要强依赖宿主机硬件能力（如某些加速）。
五、不要用 run_docker.sh 脚本，直接手动构建容器
OE 包里提供的 run 脚本有个 -rm 参数，这在实际开发中非常不好——容器关了，修改就没了。
推荐方式
手动 docker run，长期复用容器。如下是构建容器时的完整模板，可供参考（以 J6 GPU 为例）：
docker run -dit --gpus all --shm-size="15g" \
-v $HOME/work/docker-data/AiToolchain/j6:/data \
-v $HOME/work/docker-data/AiToolchain/dataset:/data_set \
--privileged=true --name j6-3500 --hostname=j6-3500 \
openexplorer/ai_toolchain_ubuntu_22_j6_gpu:v3.5.0_rc3这些命令在附件中已经整理得很全。
六、Docker 挂载（-v）设计：这是效率关键点
这一点，大概是经验价值最高的部分之一。目录结构设计不好，后面全是弯路。
推荐目录结构
docker-data/
├── AiToolchain/
│ ├── j5/
│ ├── j6/
│ ├── x5/
│ └── dataset/
├── common/挂载策略
-v /xxx/j6:/data
-v /xxx/dataset:/dataset
-v /xxx/common:/common这样设计的好处
- 命令统一：每次构建新的容器只换 image 和 name。
- 跨版本复用：不同 OE 版本共享数据，可以随时查看和使用不同版本 OE 包内的内容。
- 数据集统一管理：数据集是共用的，不重复复制。
- 模型可迁移：老版本模型直接复用。
一个细节（很多人会踩坑）
容器默认路径是 /open_explorer，但你现在挂载在 /data。解决方案：
rm -rf /open_explorer
ln -s /data/horizon_j6_open_explorer_vxxx /open_explorer本质是恢复原有使用习惯，但脚本就能继续保持兼容。
七、建议增加一个 Common 挂载目录（强烈推荐）
-v /xxx/common:/common用途
可以放：SSH key（复用宿主机权限）、常用脚本、DSP 安装包、debug 工具、内部工具等。
价值：一次配置，所有容器都能用，而且数据统一管理，不用到处找。
八、远程调试
附件里已经给出了完整流程，这里提炼核心步骤：
-
容器内使用 HOST 的 pub_key
mkdir ~/.ssh cp /common/ssh/* ~/.ssh -
VSCode Remote 连接
VSCode 中安装“Dev Containers”后，先通过 SSH 与服务器建立连接，然后通过开发容器便可以查看和新构建的容器环境。
一旦打通，效率提升是质变。
-
配置本地的 pub key
细心的用户可能发现，Windows 下使用 SSH 连接远程服务器，每次都要输入密码，非常麻烦。这里提供一组命令解决该问题：
核心步骤：生成 key 直接在 VSCode 控制台（实际就是 PowerShell）执行：
ssh-keygen -t rsa -C 'xxxx@xxx.com'然后将公钥添加到远程服务器并配置 authorized_keys：
function ssh-copy-id([string]$userAtMachine, $args){ $publicKey = "$ENV:USERPROFILE" + "/.ssh/id_rsa.pub" if (!(Test-Path "$publicKey")){ Write-Error "ERROR: failed to open ID file '$publicKey': No such file" } else { & cat "$publicKey" | ssh $args $userAtMachine "umask 077; test -d .ssh || mkdir .ssh ; cat >> .ssh/authorized_keys || exit 1" } } ssh-copy-id -p 22 root@server_ip这样处理后，再次登录同一个服务器的 SSH 和 Docker，都不会要求输入密码了。
九、一些额外但很实用的习惯
- 不要在容器里乱改环境：改了环境就不可复现。
- 每个版本单独容器：不要混用，混淆版本。
- 所有重要操作脚本化：比如
sh build_env.sh、sh run_ptq.sh。 - 数据与代码分离：代码放在容器里，数据挂载出来，避免污染。
十、总结（核心就三句话）
- 先跑通整条链路，而不是盯着一个点。
- 环境稳定比什么都重要，Docker 优先。
- 目录结构和挂载设计决定你的效率上限。
结尾
这篇内容不复杂，但都是实战里反复验证过的经验。如果你刚开始用工具链，这些能帮你少走很多弯路；如果你已经在用，建议对照看看有没有可以优化的地方。
