文章目录一、为什么要用问句来测文档二、测量口径三、十个问题逐一验Q1 不接摄像头屏为什么全黑板子到底起没起来 —— **D**Q2 怎么把画面拉出来看RTSP 拉不到视频 —— **B**Q3 画面很糊是不是镜头没对上焦 —— **D**Q4 怎么换成我自己的检测模型 —— **Ddocs 域真答案在第三棵树**Q5 不用那个 UI怎么直接拿到检测结果 —— **D**Q6 板子的 IP 是多少为什么每次开机都变 —— **D**Q7 编译环境怎么搭ATC 在哪下载 —— **B拆成 7a / 7b**Q8 能不能接第二个摄像头双摄怎么搞 —— **B**Q9 怎么改推流的分辨率 / 帧率 —— **B**Q10 板子上的喇叭能不能响 —— **C**四、汇总0 个 A 级五、三个结构性发现5.1 FAQ 是唯一按问题组织的位置但它选错了问题5.2 同一个能力写了四份放在四个地方互相不通5.3 文档把本地已有的东西指向了在线仓库六、一个必须说清的方法学陷阱七、如果我是厂商我会改这五处八、如果我是老师我这样自救九、复现方法这是一次按问句测文档的实验。我不看目录结构、不按模块翻阅只准备 10 个学生真正会问的问题然后去官方资料里找答案记录找到没有、藏在第几层、要不要跨目录树、读完之后能不能照做。结论有点刺眼10 个问题里独立可解的是 0 个。但这不是文档写得差——恰恰相反有几处写得好得可以直接当范文。问题出在组织方式这套文档是按软件分层组织的不是按任务组织的。一、为什么要用问句来测文档官方文档有 83 篇 markdown、约 5.1 GB 的 SDK、28 个 AI skill。打开目录你会看到get-started/software-guide/api-reference/hardware-guide/tools/FAQ—— 全部按软件分层命名。这个结构对我要查ss_mpi_venc_set_chn_attr的参数是高效的。但学生不会这样问。学生问的是“屏怎么不亮”“画面好糊是不是坏了”“怎么换成我自己训练的模型”“板子的 IP 是多少为什么每次都不一样”这些问句里没有一个 API 名字也没有一个模块名。用自然语言问句去找一套按模块命名的文档命中率会骗人解决率才是真相。所以这次测量分两步机器部分可复现脚本按三组递进关键词搜索记录首命中轮次、命中文件、路径深度、机器耗时。脚本在文末给出。人工部分不可替代打开排名最高的页面读完判断照这篇做能不能解决问题然后定级。第 2 步是关键。第 1 步的结果会严重高估——这点后面有数据。二、测量口径项定义搜索域DOCSdocs/zh-CN/**83 篇 mdCODEapps/components/vendor/1460 个文本文件SKILL.agents/28 个官方 AI skill319 个文本文件关键词轮次round1 学生最自然的说法产品功能名round2 换个说法round3 想到模块名/代码符号路径深度命中文件相对所在域根的路径段数DOCS 根 docs/zh-CN定级A 有专页照做即通B 有片段但需拼接、或需离开 docs 树C 只有接口参考没有任务路径D 文档里没有答案资料规模基线域内容规模docs/zh-CN官方文档正文83 篇 md含图约 58 MB.agents/skills官方 AI skills第三棵树28 个 skill319 个文本文件appscomponentsvendor各工程 README 与源码1460 个文本文件三、十个问题逐一验Q1 不接摄像头屏为什么全黑板子到底起没起来 ——Ddocs 里搜未接 | 未检测 | 摄像头失败0 条相关。命中的是 I2C “未接设备”、SD 卡未检测、人脸录入失败。唯一沾边的是get-started/first-project/README.md的「四、验证结果」表5 项判据烧写成功 / 串口进~ #//root/hello存在 / 手动执行有输出 / 重启后不自动执行。它能判板子活着不能解释屏为什么黑。而真实的因果链是不接 sensor → hi_fw_media_vi_init 失败 → goto cleanup → 进程退出 → ui_module_init 从未执行 → 屏全黑ui_module_init()在main()里排在倒数第二位VI 一失败就直接goto cleanup_eventhub。串口只有两行[mpp] hi_fw_media_vi_init failed [main] Bye.但学生不一定想到去插那根线。他看到的只有一块黑屏而黑屏同时意味着没接摄像头 / 排线没插紧 / sensor 型号不符 / 板子坏了。四种原因一个现象。Q2 怎么把画面拉出来看RTSP 拉不到视频 ——Bsoftware-guide/api-reference/framework/api_liveserver.md写得相当好默认端口 554、播放地址格式rtsp://:554/livestream/、直连与 IPC 两种模式、事件回调模型一应俱全。但没有一句PC 端用什么命令拉也没有拉到了只有声音没有画面怎么办。实测中必须加-rtsp_transport tcpffplay-rtsp_transporttcp-x1280-y720rtsp://192.168.1.142:554/livestream/0不加的话窗口全黑状态行长这样35.30 A-V: nan fd 0 aq 32KB vq 0KB sq 0B这一行的信息量其实很大音频时钟走了 35 秒音频通、A-V: nan视频时钟没建立、vq0KB视频包没到、aq32KB网络与 RTSP 会话正常。结论是UDP 下 2560×1440 的大包被丢小包音频能过。定级 B地址能查到故障排除查不到。Q3 画面很糊是不是镜头没对上焦 ——D全 docs 树里对焦 | 调焦 | 焦距只命中1 处hardware-guide/periph-standards/sensor/sensor-image-test-items.md:21原文是完成对焦后查看…画面是否有左右或上下清晰度不一样。这是一条测试项不是怎么调。而实测事实是模组是定焦 可螺纹手动调焦出厂焦点不对着你的使用距离官方建议检测距离约1 米景深只有几十厘米镜头外面还有一层保护膜没撕的话怎么调都糊。这三条文档里一处都没有。学生的结论必然是镜头是坏的——而实际上转两圈镜头就好了。Q4 怎么换成我自己的检测模型 ——Ddocs 域真答案在第三棵树先看关键词ATC | 模型转换 | 模型量化 | svp_acl在 docs 里 14 处命中过滤掉SVAC3之后剩 0 处。为什么因为 14 处全是HI_MAPI_VENC_SVAC3_NALU_..._PATCH里的 “Audio/Transport/Channel” 之类的撞词。这是本次测量最大的坑关键词命中数会骗人。api_aidetect.md只有接口签名*_create/*_process/*_listen没有一句模型从哪来、怎么转换、放哪、有没有容量限制。真答案在一个你想不到的地方.agents/skills/hi-aiot-cv610-ai-algorithm-apply/。它的SKILL.md里写着 aidetect 的完整流程、错误码0xa05f8007、MMZ leak处置、ss_mpi_aidetect_process的常见报错。这是给人看的文档但它只服务于 AI 编码助手。docs 里没有任何一处指向它。Q5 不用那个 UI怎么直接拿到检测结果 ——D这个问题对应fw_cli。数据很干脆位置出现次数docs/zh-CN83 篇0.agents/skills28 个0apps/cv610_ev_board/references/factory_demo/ws73_lcd/唯一出现处相对apps深度5 层而且目录名叫ws73_lcdWi-Fi 屏的出厂 demo与命令行工具没有任何语义关联。也就是说实测中最适合教学的 NPU 入口文档零提及。这是全篇最刺眼的一条第 6 节会给改法。Q6 板子的 IP 是多少为什么每次开机都变 ——D4 处命中全部错位scenario-1/3讲的是把Windows 有线网卡设成静态 IPWSL 镜像网络不是板子scenario-4setenv ethaddr 12:34:56:78:9A:BCu-boot 里临时设 MAC不是板子固件行为openharmony-support.md:141ifconfig eth0 192.168.1.16OpenHarmony 侧的临时配置。没有怎么查板子 IP、没有MAC 为什么每次变、没有静态绑定方案。而实测确认/sys/class/net/eth0/addr_assign_type 1 # NET_ADDR_RANDOM内核自己标了这是随机地址同一块板四次启动IP 依次是.138 → .141 → .142 → .143严格递增、旧租约不回收。内核已经把答案写在一个文件里了只是没人告诉用户去看这个文件。Q7 编译环境怎么搭ATC 在哪下载 ——B拆成 7a / 7b7a 环境搭建A。software-guide/environment-setup/四个场景WSL / Ubuntu Server / WSLDocker / UbuntuDocker每个都带独立的「常见问题」锚点FAQ/compilation另有 3 条实打实的报错处置交叉编译器不在 PATH、AI 非交互 SSH 下 PATH 不加载、切案例前要distclean。这是整套文档里最完整的一块照着做能成。它也是 11 个子项里唯一拿到 A 的。7b ATCD。0 命中。工具包既无下载入口也无章节环境搭建章节到能编应用就结束了。Q8 能不能接第二个摄像头双摄怎么搞 ——B硬件层写得很清楚板级文档明确场景二 / 场景三均支持双摄像头并用一张表列出了两种场景下板载开关的对应状态。这一点做得好接口复用与场景的对应关系一目了然。断点在操作层samples/cv610_dev_board/README.md里 sensor 那一行给了一个[双摄像头](https://gitcode.com/HiSpark/...)在线链接——而对应的 README 其实就在本地apps/cv610_ev_board/samples/sensor/dual/。Q9 怎么改推流的分辨率 / 帧率 ——Bdocs 里没有操作页只有api_vpss.md/api_venc.md的接口参考。答案在本地工程 READMEapps/cv610_ev_board/samples/sensor/single/README.md有 Sensor / 分辨率 / fps / MIPI Lane / RAW 的对照表并指出改分辨率走sample_single_sensor.h的编译宏。顺带得到一个重要结论改分辨率要重编译应用级全量 11.5 秒这直接是二次开发门槛的数据。Q10 板子上的喇叭能不能响 ——C7 篇提到喇叭 / 扬声器 / 放音全部是硬件描述板子上有什么或api_ao.md接口参考。没有一条验证路径。而实测背景更有意思/proc/umap/ao只有表头没有数据行说明 AO 设备从未被 enablefw_cli也没有音频命令。但/root/.ash_history开头 13 条是产线测试命令里面明明有OTT audio_play_start inner OTT audio_play_start external厂商验证过放音但OTT这个工具不在镜像里。用户无法复现厂商的验证。这一条对课堂尤其要命——老师需要一个30 秒确认硬件是好的手段。四、汇总0 个 A 级#问题定级答案实际位置深度Q1不接摄像头屏全黑D——Q2RTSP 拉不到视频Bsoftware-guide/api-reference/framework/api_liveserver.mdL4Q3画面糊 / 对焦D—仅 1 处测试项—Q4换成自己的模型D.agents/skills/hi-aiot-cv610-ai-algorithm-apply/域外Q5不用 UI 拿检测结果Dapps/.../references/factory_demo/ws73_lcd/5 层Q6板子 IP / 每次变D——Q7a编译环境Asoftware-guide/environment-setup/×4L3Q7bATC 在哪下D——Q8双摄怎么搞B板级文档硬件 本地samples/sensor/dualL4 / 域外Q9改分辨率 / 帧率Bapps/.../samples/sensor/single/README.md域外Q10喇叭能不能响Capi_ao.md仅接口L5口径数值独立可解A0 / 10需拼接或跨目录树B4 / 10仅有接口参考C1 / 10文档中无答案D5 / 10五、三个结构性发现5.1 FAQ 是唯一按问题组织的位置但它选错了问题FAQ/合计 7 条位置条目FAQ/compilation交叉编译器未找到 · AI 执行时找不到编译命令 · 切换案例编译不干净FAQ/develop产出文件系统镜像 · 应用开机自启 · 文件传输 · 增量编译烧写FAQ/environment无独立条目跳转到 4 个 scenario 的「常见问题」锚点7 条 100% 落在编译 / 烧录 / 环境 / 文件传输域对上面 10 问的覆盖是 0/10。不是写得不好是选错了问题这 7 条全是程序跑不起来的问题而学生卡住的地方是跑起来了但看不到、看不懂、改不动。5.2 同一个能力写了四份放在四个地方互相不通以 NPU 检测为例版本位置写给谁有没有换模型接口参考docs/zh-CN/software-guide/api-reference/framework/api_aidetect.md查函数签名的人✗AI 向导.agents/skills/hi-aiot-cv610-ai-algorithm-apply/4 个 referencesAI 编码助手✓含错误码表可跑样例apps/cv610_ev_board/samples/ai_component/README.md想跑通的人部分出厂 demoapps/cv610_ev_board/references/factory_demo/ws73_lcd/README.md想看真实产品的人✓fw_cli从任意一份出发都走不到另外三份docs 不引用.agents/samples 页链到在线仓出厂 demo 的 README 埋在references/factory_demo/ws73_lcd/第 5 层。这条比文档缺失更准确能力是完整的、甚至写了四个版本问题只在入口没有连起来。5.3 文档把本地已有的东西指向了在线仓库docs/zh-CN/samples/cv610_dev_board/README.md列了一整张案例表24 个跳转链接全部是https://gitcode.com/HiSpark/hi_aiot_solution_cv610_ev_board/...的绝对 URL。而对应的 README 就在本地apps/cv610_ev_board/samples/sensor/single/README.md、.../dual/、.../ai_component/全都在内容还更详细有 Sensor/分辨率/fps 表、目录树、mermaid 数据流图。后果离线环境、内网、GitCode 访问慢的时候学生的下一步直接断掉。六、一个必须说清的方法学陷阱关键词命中率与解决率严重脱节。10 个问题在 docs 树里共命中136 处文件真正能回答问题的约8 处噪声率约94%。几个典型问句撞到哪为什么撞上屏为什么黑tools/BurnTool.md因为里面写了上电ATC 在哪下HI_MAPI_VENC_SVAC3_NALU_..._PATCH因为它含 “ATC” 三个字母板子 IPscenario-1/3因为里面确实有静态 IP但讲的是 Windows 网卡所以第几轮搜到不能当指标10 问里有 9 问在第一轮就命中了。机器耗时平均 124 ms也不能当指标那是 grep 的速度。学生的瓶颈不是搜索快是不知道往哪棵树找。唯一有效的指标是读完最高排名页面之后还有没有答案——这正是 A/B/C/D 定级做的事。这段建议原样保留在报告里因为它恰好说明问句找不到答案不是学生不会搜。七、如果我是厂商我会改这五处优先级改法成本收益P0FAQ 增补五问摄像头 / 屏 / 模型 / IP / 音频。每问三段现象、怎么判断、怎么解决一天FAQ 是唯一按问题组织的位置改造成本最低、收益最高P0fw_cli进 README 首屏加一节不做 UI 也能验证的 5 条命令半小时把有 NPU从宣传语变成学生 30 秒能验证的事实P1补一页光学准备定焦、工作距离 1 m、螺纹可调、保护膜半天消掉最高频的镜头是坏的误判P2samples 页的 24 个绝对 URL 改相对路径十分钟断网/内网环境下下一步不断P2从 skills 抽 1 页给人看如ai-algorithm-apply的错误码表半天已经写好的高质量内容不该只对 AI 可见八、如果我是老师我这样自救每台配一根串口线。屏黑时它是唯一能看见真相的通道能省掉 80% 的板子坏了。把这三个问题的答案印在工位卡上摄像头必须先接、拉流要加-rtsp_transport tcp、板子自带 Type-C 调试口。课前查好 IP 并贴标签。MAC 每次启动随机重启就变。第一节课别讲编译。出厂镜像开箱即跑15 分钟能出图把编译放到第二次课且由老师预先搭好环境。fw_cli值得你花十分钟找出来。它在apps/cv610_ev_board/references/factory_demo/ws73_lcd/是这块板上最好的教学入口用法见我另一篇。九、复现方法脚本只回答能不能搜到、要试几次、藏在哪里搜到的是不是真答案必须人工读页面后定级。# 在装了 SDK 的 Linux / WSL 里python3 doc_survey.pysurvey.txt21python3 doc_survey.py--jsonsurvey.json脚本做了三件事三个搜索域、10 组问题每组三档关键词、记录首命中轮次 / 路径深度 / 耗时。原始输出已归档结论可逐条核对。一句话总结这套文档不缺内容缺的是从问题到入口的那条路。10 个问题里 5 个在 83 篇文档里彻底没有答案4 个要靠翻工程目录去拼1 个只有接口没有路径——而唯一一个 A 级环境搭建说明只要按任务组织他们是写得好的。
