企业官网建设流程全解析

1. 先把“要不要用”想清楚：场景、硬件与方案取舍

OpenVINO 这套东西，很多人第一次接触是在一台没有独立显卡的 Ubuntu 机器上——手上有个训练好的模型，想让它跑起来，又不想为了推理专门买卡。它本质上是模型推理运行时加一套配套工具链，把训练框架产出的模型转成中间表示（IR），再针对 CPU、集成显卡、专用加速单元做图优化、算子融合和低精度计算，最终换来的是一段稳定的、可嵌入的推理代码和一份可复现的性能数据。这篇内容面向的是已经有一台 Ubuntu 机器、想把它真正用起来的人，从环境确认、安装、模型转换、量化、写推理代码，一路写到压测和排错，中间会把我自己踩过的坑全部摊开讲。

先给结论：如果你只是偶尔跑一次模型、图个新鲜，那直接用训练框架自带的推理接口就够了，多装一层东西纯属给自己找事。但当你的模型需要反复在相同硬件上跑、需要把推理逻辑嵌到某个桌面程序或者边缘盒子里、需要把延迟从几百毫秒压到几十毫秒、需要在不掉精度的前提下把模型体积砍掉一半，这时候再引入一个专门的推理运行时才有意义。判断标准其实很简单：有没有“部署”这两个字的需求，而不是“实验”。

1.1 它解决的到底是哪类问题

训练框架的推理模式，设计目标是“能跑”，不是“跑得快、跑得稳”。它默认带着一堆训练期残留，算子实现是通用实现，内存分配策略也比较随意，每换一个输入尺寸就可能重新做一次图重排。推理运行时干的事情正好相反：它把模型当成一个固定的计算图去编译，把能合并的算子合并掉，把能提前算的常量提前算掉，把连续的卷积、归一化、激活拼成一个执行单元，再根据目标硬件的缓存层级和向量宽度安排数据布局。

举个我实际遇到的例子：一个检测模型在训练框架里 CPU 单张推理大概 60 毫秒，转成 IR 之后不走量化是 38 毫秒左右，走完训练后量化是 22 毫秒上下。这个提速不是靠玄学，主要来自三处——算子融合减少了内存往返，权重从浮点压到低精度减少了带宽占用，以及编译期就确定了内存池大小，避免了推理过程中的反复申请释放。理解了这条链路，你就知道为什么“转个格式”能带来这么大差别，也就知道后面参数该怎么调。

1.2 和常见几类方案的横向比较

表格里最右边那列才是关键。绝大多数人的真实处境是“有几十台到几百台同型号的机器，模型固定，输入尺寸固定”，这种场景下专门推理运行时的收益最大，因为编译期优化和量化收益可以一次性摊薄到所有机器上。反过来，如果你的模型每周都在变、输入分辨率每次都不一样，那么编译缓存和静态 shape 带来的优势会打折扣，这时候要更谨慎地评估收益。

1.3 什么机器、什么场景值得上

硬件这块我建议你分成三档来看。第一档是普通的办公本或者开发机，只有集成显卡，内存 16G 起步，这一档用 CPU 推理配合低精度量化是最省事的组合，不需要额外驱动，也不会因为显卡争用导致桌面卡顿。第二档是带有独立显卡的机器，但要特别注意，这类硬件在本方案里的支持度跟具体型号强相关，能不能加速、加速多少，必须先跑一遍设备枚举再决定，别预设结论。第三档是带专用加速单元的迷你主机和边缘设备，这类硬件往往是为了低功耗常驻推理设计的，价值最高，但环境配置也最挑版本，后面会专门讲。

场景上，我总结出三类收益最明显的：一是“单模型高并发”，比如一路摄像头做检测加跟踪，需要同时跑多路；二是“低延迟刚性需求”，比如交互式应用，卡一帧用户就能感知到；三是“资源受限常驻”，比如一台小盒子 7×24 跑着，你不能让它占满所有 CPU 导致系统失去响应。这三类场景里，本方案的性能提示参数和流数控制能发挥很大作用，后面第 5 章会具体到参数。

2. 版本匹配与环境摸底：比安装本身更重要

装这类工具链，九成的失败都不是命令敲错了，而是版本没对齐。我见过太多次“照着某篇教程一步步来，结果第一步就报错”，最后发现是教程写于两年前，Python 版本、系统版本、运行时版本三个都变了。所以这一章我会把“装之前该确认什么”讲透，你按顺序走一遍，后面能省掉大量试错。

2.1 硬件与驱动信息的确认方法

先摸清楚机器上到底有什么。CPU 型号、核心数、指令集支持情况，这些决定了后面性能提示该怎么设：

lscpu | grep -E "Model name|^CPU\(s\)|Thread|Core|Flags"

重点看 Flags 里有没有向量指令集相关的标记，有的话低精度计算才能走得快。再看显卡和加速单元：

lspci -nn | grep -Ei "vga|display|accel" ls /dev/dri/

/dev/dri/下面出现renderD128这类节点，说明渲染设备节点已经就绪，这是集成显卡能被推理运行时识别的前提。如果这个目录是空的，那大概率是内核模块没加载或者被安全启动策略拦住了，这时候先别往下走，先把设备节点搞定。

还有一个很多人忽略的点：当前用户属不属于render组和video组。没有这个权限，程序能编译模型但在真正提交推理任务时会失败，报错信息还特别含糊。用groups看一下，没有的话补上：

sudo usermod -aG render,video $USER

改完必须重新登录才会生效，newgrp只在当前 shell 里临时生效，很多人误以为生效了，换个终端又不行了。

2.2 Python 与系统库的版本对齐

Python 这块的坑集中在两个地方。一是版本太新，运行时的预编译包还没跟上，pip install会尝试从源码编译，然后在某个 C++ 头文件上炸掉；二是数组计算库版本冲突，新版数组库改了若干接口，老版本运行时直接导入失败，报一个看起来跟数组毫无关系的符号错误。

我自己的做法是固定一套经过验证的组合：Python 3.10 或 3.11，数组库锁在 1.x 的最后一个稳定小版本，运行时用当前年度的长期支持版本。写进requirements.txt里锁死，不要用>=：

openvino==2025.x.x numpy==1.26.4 opencv-python==4.10.0.84

版本号具体填哪个，去官方发布的版本说明里查“支持的 Python 版本”和“依赖矩阵”，不要凭感觉。我一般会把这一行注释写在文件里，标注“此组合在 Ubuntu 22.04 上验证通过”，半年后自己回头看能救命。

系统库方面，最常缺的是图形库和 OpenMP 运行库。桌面版 Ubuntu 一般都有，服务器版精简安装往往没有，表现就是导入时抛一个找不到共享库的错误：

sudo apt update sudo apt install -y libgl1 libgomp1 libglib2.0-0

2.3 虚拟环境的隔离策略

不要往系统 Python 里装。Ubuntu 从较新版本开始对系统级 pip 安装有保护，硬装会污染系统包管理，后面出问题很难回滚。用虚拟环境隔离，一个项目一个环境：

sudo apt install -y python3-venv python3-dev build-essential cmake python3 -m venv ~/envs/ov-lab source ~/envs/ov-lab/bin/activate python -m pip install --upgrade pip setuptools wheel

python3-dev和build-essential这两个别省，虽然大部分时候用预编译包不需要编译，但一旦需要用到模型优化器里的某些组件，没有头文件会直接失败，而且失败信息出现在很后面，排查起来浪费时间。

注意：不要在同一台机器上同时用 pip 和系统包管理器装两个版本的运行时。两者会往不同路径写库文件，环境变量一改就可能加载到错误版本，症状是“昨天还好好的，今天突然报符号未定义”。真要两个版本共存，用不同的虚拟环境，别用系统级安装。

3. 三条安装路线的完整实操

安装路线没有优劣，只看你的使用场景。我下面按“最快能跑通”“系统级集成”“完全离线”三种需求分别写，你可以只挑一条走，但第 3.4 节的自检建议不管走哪条都做一遍。

3.1 pip 路线：最快跑通的选择

开发机上我基本都用这条。它把运行时和 Python 绑定一起装好，升级也方便：

source ~/envs/ov-lab/bin/activate pip install openvino

装完之后有个变化需要特别注意：早期版本里模型转换工具是单独一个包，从某个版本起被合并进了主包，同时转换命令的名称也换了。你如果搜到的是老教程，里面那条命令可能已经不存在了。现在的转换入口是ovc，压测工具仍然叫benchmark_app，这两个都随主包一起装上。确认一下：

python -c "import openvino as ov; print(ov.__version__)" ovc --help | head -20 benchmark_app -h | head -10

三条命令都能正常输出，说明基础安装 OK。如果ovc提示命令不存在，多半是 PATH 没刷新，用python -m openvino.tools.ovc --help试试，能跑通就是 PATH 问题，hash -r或者重开终端即可。

3.2 系统包仓库路线：适合多用户和长期维护

如果是团队共用的工作站，或者你需要把推理能力做成系统服务，pip 装到某个用户的环境里就不合适了。这时候用系统包管理器，好处是全局可用、依赖由系统统一管理、卸载干净。

流程是三步：导入软件源签名公钥、把仓库地址写进源列表、刷新后安装。具体的仓库地址和公钥文件请以官方发布的安装说明为准，我这里不贴具体地址，因为这类地址会随版本调整，照抄旧地址是最常见的失败原因。装完之后，系统里会多出一批命令行工具和 C++ 头文件，Python 绑定需要另外装对应的系统包。

这条路线有两个坑。第一个是系统版本与仓库版本必须对应，仓库是按发行版代号分目录的，写错代号会得到一个空的包列表，apt install提示找不到包。第二个是它可能与已有仓库产生依赖冲突，特别是图形相关的库，装完可能导致某些桌面组件行为异常。我一般会先apt-cache policy看一眼候选版本，确认要装的东西和现有系统不打架再动手。

3.3 离线包路线：内网和边缘设备的唯一选择

目标机器不能上外网的时候，只能走离线。流程是在一台同架构、同系统版本的联网机器上下载完整包，拷过去解压，然后设置环境变量。

# 联网机器上执行，把运行时包装到本地目录 pip download openvino --dest ./ov_pkgs --only-binary=:all: pip install --no-index --find-links ./ov_pkgs openvino --target ./ov_runtime

--target会把所有文件平铺到一个目录里，拷到目标机后：

export PYTHONPATH=/opt/ov_runtime:$PYTHONPATH export LD_LIBRARY_PATH=/opt/ov_runtime:$LD_LIBRARY_PATH

这两个变量都要设，只设PYTHONPATH能在import阶段通过，但一编译模型就会因为找不到底层动态库而失败，报错是“无法加载插件”这类含糊信息。我吃过这个亏，定位了整整一个下午。稳妥的做法是把这两行写进/etc/profile.d/下的一个脚本，所有用户自动生效。

包体积这块提醒一句：完整包不小，解压后可能到几百兆，边缘设备存储紧张的话要提前规划分区，别装到一半空间不足，留下一个不完整的目录，后面怎么都跑不起来。

3.4 安装自检与最小验证

装完不要急着上自己的模型，先用一个最简流程验证整条链路通不通。我习惯分四步走：

第一步，版本与设备枚举：

import openvino as ov core = ov.Core() print("runtime:", ov.__version__) print("devices:", core.available_devices)

available_devices里至少应该有CPU。如果连 CPU 都没有，是安装本身出了问题，别往下查。

第二步，用官方示例模型跑一次转换，验证工具链完整：

ovc --help

第三步，跑压测工具，验证推理引擎能真正加载模型并出结果。这一步用的是任意一个现成的 IR 模型，如果没有，可以用工具链自带的示例。

第四步，写三五行的推理脚本，验证 Python 绑定的数据流正确。这四步全过，说明环境是干净的，后面出问题基本都在模型和参数上，排查范围大大缩小。

4. 模型转换与量化：从原始模型到 IR

这是整个流程里最容易翻车的一环。转换本身不复杂，复杂的是转换前的形状确认、转换中的参数选择，以及转换后的精度验证。我把它拆成四节，按顺序走。

4.1 模型来源与目录约定

原始模型可能来自多种格式，常见的是训练框架导出的计算图加权重、通用交换格式，以及直接保存的序列化模型。转换工具对不同来源的支持程度不一样，有些格式需要额外依赖。

我给自己定了一条硬规矩：所有模型的目录结构必须统一。

models/ raw/ # 原始模型，只读，永不修改 detector_v3/ ir/ # 转换产物 detector_v3/ fp32/ fp16/ int8/ calib/ # 校准数据 detector_v3/ *.jpg

这么做的理由是版本可追溯。模型一多，你很快就会忘记某个 IR 文件是从哪来的、用什么参数转的。我还会在ir/detector_v3/下放一个build.txt，记录转换命令全文、工具版本、日期。后来同事接手的时候，这份记录比任何文档都有用。

raw/目录设为只读。听起来多余，但我真的遇到过转换脚本写错了输出路径，把原始模型覆盖掉的情况，重下一遍花了半天。

4.2 转换命令逐参数拆解

新版转换入口是ovc，最简形式只要一个输入：

ovc model.onnx --output_dir ./ir/detector_v3/fp32

但实际用起来，参数得按要求配。逐个说：

--input_shape，指定输入张量的形状。这个参数必须和模型实际接受的一致，写错了要么转换失败，要么转出来的模型一推理就报维度不匹配。对于图像模型，一般是[1,3,H,W]这种四维形式，注意通道顺序，训练时用的什么顺序，这里就必须是什么顺序，不要想当然。

--mean_values和--scale_values，把预处理参数写进模型。这两个参数是后面第 5.2 节要讲的“预处理下沉”的基础。图像模型常见配置是把像素值归一化到 0 到 1，再按通道减均值除标准差。写成--mean_values "[123.675,116.28,103.53]"这种形式，注意引号和逗号都要对，shell 里少个引号会把参数拆散。

--compress_to_fp16，把权重压到半精度。这个开关对体积和速度都有好处，代价是极小的精度损失，绝大多数视觉模型完全无感。我一般 FP32 和 FP16 各转一份，跑同一批测试图对比输出差异，差异在阈值内就只用 FP16。

--output_dir，产物路径。工具会生成一个.xml描述文件和一个.bin权重文件，两个必须放在一起，且文件名保持一致，只拷.xml过去是跑不起来的，这是新手常犯的错误。

转换成动之后，第一件事不是写代码，而是看图结构有没有被简化。用工具链自带的模型信息查看命令，看算子数量、看有没有奇怪的自定义算子残留。

4.3 静态 shape 与动态 shape 的取舍

这是一个需要认真权衡的点，很多人在这里做错选择然后抱怨性能不行。

静态 shape 的模型，输入尺寸在转换时就固定了，编译器可以做极致的布局优化和内存规划，推理速度最快，内存占用最低。缺点是换个尺寸就得重新转一个模型。

动态 shape 的模型，输入尺寸在推理时指定，灵活但代价明显：编译器不能确定缓冲区大小，每次推理前要做额外的形状推导和内存重分配，CPU 上影响还好，加速硬件上影响可能相当大。

我的经验是：如果业务里输入尺寸是固定的（比如摄像头分辨率固定、预处理统一缩放到 640×640），毫不犹豫用静态。如果尺寸确实要变，先用动态 shape 跑通功能，然后在实际使用的高频尺寸上各转一个静态版本，运行时按尺寸选择模型。这个策略听起来笨，但在边缘设备上是性价比最高的做法——多占几十兆存储，换取稳定的延迟表现，非常划算。

# 动态 batch，固定空间尺寸 ovc model.onnx --input "[1..8,3,640,640]" --output_dir ./ir/detector_v3/fp16_dyn # 固定尺寸的静态版本 ovc model.onnx --input "[1,3,640,640]" --compress_to_fp16 --output_dir ./ir/detector_v3/fp16

4.4 训练后量化与精度回归

量化是收益最大的一步，也是最容易出问题的一步。它把权重和激活值从浮点压到低精度整数，模型体积能小到原来的四分之一，CPU 上的推理速度通常有明显提升。

流程分三步：准备校准数据、执行量化、精度回归。

校准数据最关键的是“代表性”。数量上，一两百张到三百张足够，但必须覆盖实际场景的分布——白天、夜间、远景、近景、拥挤、稀疏，都要有。我见过用同一段视频抽帧做校准的，结果模型在另一种光照下精度暴跌，因为校准集根本没覆盖那种情况。数据来源建议直接从真实业务数据里抽，不要用公开测试集凑数。

import nncf import openvino as ov core = ov.Core() model = core.read_model("./ir/detector_v3/fp32/model.xml") def transform_fn(data_item): # 这里必须和推理时的预处理完全一致 return {0: preprocess(data_item)} calibration_dataset = nncf.Dataset(calib_loader, transform_fn) quantized = nncf.quantize( model, calibration_dataset, subset_size=200, preset=nncf.QuantizationPreset.PERFORMANCE, model_type=nncf.ModelType.DETECTION, ) ov.save_model(quantized, "./ir/detector_v3/int8/model.xml", compress_to_fp16=False)

几个关键点。transform_fn里的预处理必须和推理时逐位一致，通道顺序、归一化方式、缩放插值算法都要对，这个不一致是最隐蔽的精度下降原因。subset_size不用给太大，200 左右足够，给多了只是浪费时间。model_type这个参数对检测类模型很有用，它会采用对精度更友好的量化策略，代价是速度略慢一点，通常值得。

量化之后必须做精度回归，不能只看速度。我的做法是准备一个固定的小测试集（比如 100 张带标注的图），用 FP32 模型和 INT8 模型各跑一遍，比较最终指标的绝对差值。检测任务看平均精度，分类任务看 Top-1。经验阈值是：指标下降不超过 1 个百分点可以接受，超过就得回头查校准集或者调整量化参数。

如果精度掉得厉害，优先尝试三件事：增大校准集覆盖面、把量化 preset 换成精度优先、检查transform_fn是否和推理完全一致。这三件事能解决八成以上的量化精度问题。

5. 推理代码的骨架与提速手段

环境通了、模型有了，接下来是把它变成能用的程序。这一章我按“先能跑、再跑快”的顺序写，最后给出压测方法。

5.1 最小可运行推理脚本

先给一个骨架，能跑通就行，别一上来就追求性能：

import numpy as np import openvino as ov core = ov.Core() model = core.read_model("./ir/detector_v3/fp16/model.xml") compiled = core.compile_model(model, "CPU") input_layer = compiled.input(0) output_layer = compiled.output(0) # 关键：查询模型期望的输入形状与布局，不要硬编码 print("input shape:", input_layer.shape) print("input layout:", input_layer.layout) infer_request = compiled.create_infer_request() tensor = np.random.rand(1, 3, 640, 640).astype(np.float32) result = infer_request.infer({0: tensor}) output = result[output_layer] print(output.shape)

这段代码里有几个值得说的细节。core.read_model只读模型结构，不占推理资源；compile_model才是真正按硬件编译，这一步耗时较长（几百毫秒到几秒），所以必须放在循环外面，绝不能每次推理都编译一次。我见过有人在 Flask 的路由处理函数里调compile_model，单请求延迟直接上秒级，还以为是模型太大。

compiled.input(0)拿到的输入对象里带shape和layout信息，用它做校验能提前发现预处理顺序错误。.layout尤其有用，如果模型期望的是通道在前的布局而你的数据是通道在后，打印出来一眼就能看出来。

5.2 把预处理塞进模型

预处理放在 Python 里做，是常见的性能浪费。一次双线性缩放、一次归一化，在 Python 层面可能就吃掉几毫秒，而且和推理是串行的。

前面转换时用--mean_values和--scale_values写进模型的参数，这时候就生效了——运行时只需要把原始像素喂进去，均值和缩放在图内部完成。更进一步，还能把缩放、颜色空间转换、甚至通道重排都塞进模型：

import openvino as ov model = core.read_model("./ir/detector_v3/fp16/model.xml") ppp = ov.preprocess.PrePostProcessor(model) ppp.input().tensor() \ .set_element_type(ov.Type.u8) \ .set_layout(ov.Layout("NHWC")) \ .set_color_format(ov.preprocess.ColorFormat.BGR) ppp.input().preprocess() \ .convert_element_type(ov.Type.f32) \ .mean([123.675, 116.28, 103.53]) \ .scale([58.395, 57.12, 57.375]) \ .resize(ov.preprocess.ResizeAlgorithm.RESIZE_LINEAR) ppp.input().model().set_layout(ov.Layout("NCHW")) model = ppp.build() core.compile_model(model, "CPU")

这么改完，Python 端只需要把摄像头读到的原始数据直接传进去，一次拷贝都不用。实测在一个 640×640 输入的检测模型上，端到端延迟能降 3 到 5 毫秒，占整体延迟的比例不小。而且代码更干净，预处理逻辑和模型绑在一起，不会出现“某天有人改了前处理但忘了同步模型”的意外。

注意：resize的插值算法必须和训练时一致。训练用双线性就填RESIZE_LINEAR，训练用最近邻就换对应的枚举。算法不一致会带来系统性的精度偏差，而且很难通过看输出来发现，只能靠对比指标。

5.3 异步流水线与多设备并行

单请求串行推理是最慢的用法。真实场景里，数据读取、预处理、推理、后处理是可以重叠的，异步接口就是干这个的。

infer_request = compiled.create_infer_request() # 先启动一次，不阻塞 infer_request.start_async({0: tensor_0}) for i in range(1, N): # 在等上一次结果的同时准备下一批数据 next_tensor = load_and_prepare(i) infer_request.wait() result = infer_request.get_output_tensor(0).data.copy() postprocess(result) infer_request.start_async({0: next_tensor})

核心在于start_async之后立刻去做下一批的准备工作，wait只是等这一次算完，中间那段时间是被利用起来的。在 IO 开销占比高的场景里，这套写法能把吞吐提高不少。

再往前一步是多流。CPU 上可以开多个推理流，让多个请求并行：

compiled = core.compile_model( model, "AUTO", {ov.properties.streams.num: "4", ov.properties.hint.performance_mode: "THROUGHPUT"} )

streams.num设置成物理核心数是个不错的起点，超线程核心不算数。设太大反而会互相抢缓存，性能下降。performance_mode选吞吐模式时，运行时会倾向于用满所有核心做批处理；选延迟模式时，会优化单次请求的响应速度。这两个目标是对立的，必须按业务选，不能既要又要。

多设备并行也值得一提。AUTO会自动挑一个最优设备，MULTI则会同时在多个设备上跑，适合批处理吞吐场景：

compiled = core.compile_model(model, "MULTI:CPU,GPU", {ov.properties.hint.performance_mode: "THROUGHPUT"})

不过真要用MULTI，得先确认数据搬运本身不是瓶颈，否则多设备反而因为拷贝开销变慢。

5.4 benchmark_app 压测与指标解读

写完代码必须压测，但要压得对。压测工具的参数很多，我常用的组合是这样的：

benchmark_app -m ./ir/detector_v3/int8/model.xml \ -d CPU \ -api async \ -niter 200 \ -hint throughput \ -nstreams 4

参数的含义：-d指定设备，-api async用异步接口压，-niter指定迭代次数保证稳定，-hint和-nstreams和代码里的配置保持一致。压出来的结果里，重点看两个数：吞吐（每秒处理多少张）和延迟中位数。平均值会被偶发的长尾拖偏，中位数更真实。

还有一个必做的操作：首次运行和后续运行的差异。运行时会做编译缓存，第一次包含编译时间，数字会难看很多。设置缓存目录之后，第二次开始才是真实的稳态性能：

benchmark_app -m model.xml -d CPU -cd ./ov_cache -niter 200

-cd指定缓存目录，生产环境里这个配置一定要加上，否则每次服务重启都要重新编译，启动时间会很难看。

压测里我还会做一组对照：同一模型，INT8 和 FP16 各压一遍，看实际提速比例。如果 INT8 只快了 5%，那说明瓶颈不在计算而在内存带宽或者数据拷贝，这时候花力气继续优化量化参数是白费，应该去看预处理和后处理。这种对照能帮你把优化精力放对地方。

6. 踩坑速查与现场排查记录

前面讲的都是顺利路径，这一章讲不顺利的时候怎么办。我把这些年遇到的典型问题整理成表，再挑三个有代表性的现场展开。

6.1 报错速查表

6.2 三个真实排查现场

第一个现场：某台工控机上，模型能编译，设备列表里也有集成显卡，但一提交推理任务就失败，报错信息只说“执行失败”，没有任何细节。我先确认了程序确实选到了显卡设备，又跑了官方示例，示例能跑通，说明环境没问题。差别在哪？示例用的是小模型、单线程，业务代码是多线程。最后定位到是多个线程同时提交任务到同一个编译好的模型上，请求对象没有做隔离。改成每个线程各自create_infer_request，问题消失。这类问题的教训是：编译产物可以共享，请求对象不能共享，这条规则值得写在代码注释里。

第二个现场：一台边缘盒子，转换好的模型在开发机上跑得好好的，拷过去就报版本不支持。查了半天，发现开发机上装的是当年新版，盒子上是随系统预装的老版，IR 格式向前不兼容。解决方案有两个：要么在盒子上装同版本运行时，要么用盒子上那版工具重新转换一次。我选了后者，因为盒子已经批量部署，统一升级运行时的风险更大。这件事之后，我在转换脚本里加了一行，把工具版本号写进产物旁边的build.txt，部署前第一件事就是对比版本。

第三个现场：一个检测模型量化后精度掉了 4 个百分点，怎么调参都不行。最后发现校准集是从一段白天视频里抽的，而业务场景里有大量夜间画面。补了夜间样本重新量化，精度损失降到 0.6 个百分点。这件事让我形成了一个习惯：做量化之前，先花十分钟看看真实数据的分布，比调一百次参数有用。

6.3 长期维护的几点心得

第一，把环境做成可复现的。写一个setup.sh，把系统依赖、虚拟环境、运行时版本、模型转换命令全部串起来，新机器上跑一遍就到位。这件事的收益在半年后你会深有体会，尤其是当你要在第五台机器上重现第一台的环境时。

第二，把性能数据存档。每次转换模型、每次调参，都把压测结果记下来，模型、参数、版本、硬件、吞吐、延迟，做成一张表。时间长了这张表会告诉你很多规律——比如某类模型量化收益高、某类几乎没有，下次就能提前判断值不值得做。

第三，别在生产环境里做实验。转换、量化、调参这些事情全部在开发机或者测试机上完成，产物（也就是.xml和.bin）连同build.txt一起打包发布。生产机上只做两件事：装运行时、加载产物。这条规矩能避免绝大部分“线上突然跑不起来”的事故，因为线上根本没有变量。

第四，版本升级要当成一次发布来做。运行时升级往往伴随默认参数变化、性能特征变化，甚至个别接口的废弃。我一般会保留旧版本环境，新版本先在旁路跑一遍完整回归：精度对比、性能对比、长稳测试，三项都过了再切。

这套流程跑顺之后，从拿到新模型到部署上线，我通常两三个小时能搞定，其中大部分时间花在精度回归上。真正花时间的从来不是敲命令，而是想清楚每个参数为什么这么设、每个结果为什么是这个数。把这些想明白了，换个场景、换个硬件、换个模型，你依然能快速上手，而不是又从头搜一遍教程。