企业官网建设流程全解析

1. 黑芝麻BST感知模型从BSNN编译到板端执行到底难在哪

黑芝麻BST（Black Sesame Technologies）平台的感知模型落地，核心链路可以概括成一句话：BSNN 编译产物 + app 可执行文件 → 板端同目录部署 → 执行验证。听起来简单，但真正上手时，大部分工程师卡在三个地方：编译环境版本对不上、模型文件放错位置、执行权限没给全。这篇就按我实际跑通的顺序，把 BSNN 编译、部署目录结构、执行验证命令完整拆一遍，最后再讲怎么用 TaoToken 统一管理模型服务调用，让整条链路有一个可复用的 Key/API 通道。

先说清楚这套流程适合谁：如果你在做车载感知算法，手里有黑芝麻 BST 的开发板（比如华山系列），需要把训练好的感知模型（YOLO 系列、BEV、分割网络等）通过 BSNN 工具链转成板端可执行格式，然后跑通一次完整推理，那这篇就是给你写的。BSNN 是黑芝麻的神经网络编译工具链，负责把 ONNX 等中间格式转成芯片能吃的.lib/.meta/weights.bin；而 app 文件是你自己写的 C++ 推理程序编译出来的 bin。两者缺一不可，且必须放在同一路径下。

我试过最省事的做法，是直接复用 SDK 容器里自带的 bsnn 环境，而不是自己从 Release 包里重新搭一套。原因很现实：SDK 容器里的环境变量、sysroot、库版本都是和板端固件对齐过的，你自己拼一套，十有八九会在链接阶段报找不到符号。所以下面的步骤，默认你已经在 SDK 容器里操作。

整条链路我拆成六段：先讲清楚问题场景和目录约定，再讲 TaoToken 的前置准备（因为后面验证服务调用要用），然后是可直接复制的编译配置、部署结构、执行命令，接着是常见报错排查，最后给一个语义一致的 CTA 收尾。每一段都尽量给到能直接粘贴的命令和配置，而不是泛泛而谈。

2. TaoToken 前置准备：统一 Key 与 API 通道管理模型服务调用

在讲编译之前，先把 TaoToken 这条线铺好，因为后面执行验证阶段，我们会用它来统一管理模型服务的调用通道。很多团队的问题是：模型在板端跑推理是一套流程，但模型版本管理、远程服务调用、多模型切换又是另一套散落的脚本，Key 到处硬编码，换个人接手就找不到入口。TaoToken 在这里的角色，是提供一个统一的 API 通道，把模型对话、Coding Plan、API Keys 这些能力收敛到一个入口。

你需要先拿到自己的 API Key。访问 https://taotoken.net/api 对应的控制台，在 API Keys 页面创建一个 Key。这个 Key 后面会用在两个地方：一是本地验证脚本里调用模型服务，二是如果你要把板端推理结果回传做二次分析，也可以通过同一个 Key 走统一通道。创建完 Key 之后，建议单独存一个环境变量文件，不要写死在代码里。

# 保存到本地环境变量文件，注意不要提交到 git export TAOTOKEN_API_KEY="sk-你的实际key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

这里有个细节：Base URL 用https://taotoken.net/api，不要带任何多余路径。很多 401 报错就是因为把 Base URL 写成了带/v1或者带具体端点的形式，导致鉴权头拼错。Key 的权限范围在控制台里可以按需勾选，如果你只是做模型对话验证，勾选对话权限即可；如果要做长期编码或 Agent 任务，建议单独建一个 Key 走 Coding Plan，权限隔离更清晰。

模型 ID 这块，不同任务用的模型不一样。做感知结果的自然语言描述、日志分析，用通用对话模型就够；做代码生成、编译脚本补全，用编码能力强的模型。你可以在模型对话页面先手动试几个模型，确认哪个响应质量符合预期，再把它写进配置。这一步别省，因为后面板端执行验证时，如果模型服务调用失败，你很难判断是编译问题还是 Key 问题。

注意：TaoToken 是统一的 API 通道，不是让你把板端推理本身搬到云端。板端推理仍然在 BST 芯片上本地执行，TaoToken 负责的是模型服务调用、版本管理、以及推理结果的后处理分析这类周边能力。两者是配合关系，不是替代关系。

把 Key 和 Base URL 准备好之后，先做一次最小验证，确认通道是通的：

curl -s -X POST "$TAOTOKEN_BASE_URL/v1/chat/completions" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "你的模型ID", "messages": [{"role": "user", "content": "ping"}] }'

如果返回里有正常的choices字段，说明 Key 和通道都没问题。这一步过了，再往下走编译部署，心里就有底了。

3. 可复制配置：BSNN 编译环境与 CMake 片段

现在进入编译环节。核心原则是：能复用 SDK 容器里的 bsnn 环境，就不要自己从 Release 包重新搭。SDK 容器里 samples 自带的 bsnn 路径通常在：

/opt/bstos/2.2.2.5/sysroots/aarch64-bst-linux/usr/share/samples/coreip-samples-src/bsnn

这个路径里的版本号2.2.2.5要和你的板端固件版本对齐。对齐的方式是检查env_setup.sh：

vim script/env_setup.sh

重点看里面SDK_VERSION或类似的变量，确认和你板端固件一致。版本不一致是后面undefined reference和version mismatch报错的头号原因。确认无误后，执行环境初始化：

source script/env_setup.sh

这一步会把交叉编译工具链、sysroot、库路径都注入当前 shell。执行完可以用echo $CC和echo $CXX确认编译器指向的是 aarch64 版本，而不是宿主机的 gcc。

接下来创建编译目录并进入：

mkdir build cd build

然后是 CMake 配置和编译。这里给一个可直接复制的 CMakeLists.txt 关键片段，重点是 install 命令里自定义产物名，方便后面部署时识别：

cmake_minimum_required(VERSION 3.10) project(bst_perception_demo CXX) set(CMAKE_CXX_STANDARD 14) set(CMAKE_CXX_STANDARD_REQUIRED ON) # 指向 SDK 里的 bsnn 头文件和库 include_directories( ${SDK_ROOT}/sysroots/aarch64-bst-linux/usr/include ) link_directories( ${SDK_ROOT}/sysroots/aarch64-bst-linux/usr/lib ) add_executable(yolov5m yolov5m.cpp) target_link_libraries(yolov5m bsnn_runtime pthread dl ) # 关键：自定义 install 产物名，部署时 bin 文件名就是 yolov5m install(TARGETS yolov5m DESTINATION .)

配置和编译命令：

cmake .. make -j16 install

-j16表示最多 16 个编译任务并行，机器核多可以调大，核少就调小，别把内存打爆。install会把产物按 CMakeLists.txt 里的DESTINATION放到指定位置。编译完成后，你会得到一个不带后缀的 bin 文件，文件名默认和 cpp 源文件同名，如果 CMakeLists.txt 里改了install(TARGETS yolov5m ...)，那产物就叫yolov5m。

这里有个容易踩的坑：如果你只是替换模型文件、没有改调用模型的代码，那不需要重新编译，直接替换模型文件即可。只有当你改了 cpp 里的推理逻辑、输入输出张量处理、后处理代码时，才需要重新走一遍cmake .. && make -j16 install。这个判断能帮你省掉大量无谓的编译时间。

模型文件这边，需要三个文件，都是模型转换工具链在 1100 stage 产物里生成的：

这三个文件必须放在同一路径下，缺一个都跑不起来。部署时把它们和 app bin 放一起，目录结构建议这样组织：

deploy/ ├── yolov5m # app 可执行文件 ├── yolov5m.lib # 模型结构 ├── yolov5m.meta # 模型元信息 └── weights.bin # 权重

4. 部署与执行验证：权限、命令与成功结果

部署分两部分：app 文件和模型文件。app 文件就是上一步编译出来的 bin，模型文件就是.lib/.meta/weights.bin三件套。把它们放到板端的同一个目录下，比如/userdata/deploy/。

放好之后，第一件事是给整个文件夹赋权限：

sudo chmod 777 -R /userdata/deploy/

这一步别偷懒。板端默认权限比较严，bin 没有执行权限会直接报Permission denied，模型文件没有读权限会报failed to open model file。-R递归给整个目录，省得一个个改。

然后就是执行。你可以直接执行，也可以写个 sh 脚本。直接执行：

cd /userdata/deploy/ ./yolov5m

如果程序需要传参（比如指定模型路径、输入图片路径），按你 cpp 里的实现来：

./yolov5m --model ./yolov5m.lib --input ./test.jpg

写 sh 脚本的话，建议把环境变量也带上，避免板端库路径找不到：

#!/bin/sh export LD_LIBRARY_PATH=/userdata/deploy/lib:$LD_LIBRARY_PATH cd /userdata/deploy/ ./yolov5m --model ./yolov5m.lib --input ./test.jpg

执行成功的标志是什么？程序会打印模型加载信息、输入输出张量形状、推理耗时，最后输出检测结果（类别、置信度、框坐标）。如果看到类似下面的输出，说明整条链路通了：

[BSNN] model loaded: yolov5m.lib [BSNN] input shape: 1x3x640x640 [BSNN] output shape: 1x25200x85 [BSNN] inference time: 23.4 ms [RESULT] class=person score=0.91 bbox=[112, 88, 340, 520]

推理耗时和具体模型、芯片负载有关，YOLOv5m 在 BST 芯片上一般几十毫秒量级。如果耗时异常高（比如几百毫秒），先检查是不是跑在了 CPU 回退路径上，而不是 NPU。

到这里，板端本地推理就跑通了。接下来是 TaoToken 的接入验证：把推理结果通过统一 API 通道做一次后处理调用，确认 Key 和通道在真实任务里可用。写一个简单的 Python 脚本：

import os import requests api_key = os.environ["TAOTOKEN_API_KEY"] base_url = os.environ["TAOTOKEN_BASE_URL"] # 模拟板端推理输出的检测结果 detections = [ {"class": "person", "score": 0.91, "bbox": [112, 88, 340, 520]}, {"class": "car", "score": 0.87, "bbox": [400, 200, 620, 480]}, ] prompt = f"以下是车载感知模型的检测结果，请用一句话总结场景：{detections}" resp = requests.post( f"{base_url}/v1/chat/completions", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "model": "你的模型ID", "messages": [{"role": "user", "content": prompt}], }, timeout=30, ) data = resp.json() print(data["choices"][0]["message"]["content"])

如果这段脚本能正常返回场景描述，说明从 BSNN 编译、板端部署执行，到 TaoToken 统一通道调用，整条端到端链路就完整跑通了。这就是验收动作：一次完整推理 + 一次服务调用，两个都过，才算真正落地。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错来对。你在编译部署和执行阶段，大概率会遇到下面几类问题。

第一类：编译阶段undefined reference to bsnn_xxx

这是链接找不到 bsnn 库。原因通常是link_directories没指对，或者env_setup.sh没 source。排查顺序：先echo $SDK_ROOT确认环境变量在，再ls $SDK_ROOT/sysroots/aarch64-bst-linux/usr/lib | grep bsnn确认库文件存在。如果库在但还报错，检查 CMakeLists.txt 里target_link_libraries的库名拼写，bsnn_runtime和libbsnn_runtime.so是两个东西，CMake 里写前者。

第二类：执行阶段Permission denied

bin 没有执行权限。chmod 777 -R整个目录，或者至少chmod +x yolov5m。如果模型文件报failed to open，也是权限问题，同样用chmod解决。

第三类：version mismatch或model load failed

模型文件和板端固件版本不匹配。.meta文件里记录了编译时的工具链版本，板端 runtime 版本对不上就会拒绝加载。解决办法是确认模型转换用的工具链版本和板端固件版本一致，重新转换模型。

第四类：TaoToken 调用报 401

这是鉴权失败。排查顺序：先确认TAOTOKEN_API_KEY环境变量真的被 export 了，echo $TAOTOKEN_API_KEY看有没有值；再确认请求头是Authorization: Bearer sk-xxx，注意 Bearer 后面有空格；最后确认 Base URL 是https://taotoken.net/api，没有多余路径。401 基本都是这三处之一。

第五类：local proxy failed

这个报错通常出现在网络层，说明请求没到达服务端。检查你的网络配置是否能正常访问外部 API，以及是否有本地代理设置干扰了请求。如果你在容器里跑，确认容器的网络模式允许出站请求。

第六类：reading choices报错

这个报错说明响应体里没有choices字段，通常是请求体格式不对，或者模型 ID 写错了。检查messages是不是数组、model字段是不是控制台里真实存在的模型 ID。如果返回的是错误信息而不是正常响应，先打印完整resp.text看服务端到底返回了什么。

第七类：OAuth 相关报错

如果你用的是需要 OAuth 流程的接入方式，报错通常和 token 过期或 scope 不足有关。重新走一遍授权流程，确认 scope 包含了你需要的权限。如果只是普通 API Key 调用，一般不会碰到 OAuth 问题，碰到了说明你混用了两种鉴权方式。

提示：排查时养成先看完整错误信息的习惯。很多报错信息里已经写清楚了是文件找不到、版本不对还是鉴权失败，直接照着改就行，不用猜。

6. 把链路固化下来：从一次跑通到可复用

一次跑通只是开始，真正有价值的是把这条链路固化成可复用的流程。我的做法是：把编译、部署、执行三步写成脚本，模型文件用版本号管理，TaoToken 的 Key 和 Base URL 走环境变量注入，不写死在代码里。

编译脚本build.sh：

#!/bin/bash set -e source script/env_setup.sh mkdir -p build && cd build cmake .. make -j16 install echo "build done: $(ls -la yolov5m)"

部署脚本deploy.sh：

#!/bin/bash set -e TARGET=/userdata/deploy mkdir -p $TARGET cp build/yolov5m $TARGET/ cp models/yolov5m.lib $TARGET/ cp models/yolov5m.meta $TARGET/ cp models/weights.bin $TARGET/ sudo chmod 777 -R $TARGET echo "deploy done"

执行验证脚本run.sh：

#!/bin/bash cd /userdata/deploy/ ./yolov5m --model ./yolov5m.lib --input ./test.jpg

这三个脚本一套下来，换模型、换板子、换人都能快速复现。模型文件按版本号建目录，比如models/yolov5m_v1.2/，里面放三件套，部署时软链过去，回滚也方便。

TaoToken 这边，建议把 Key 按用途拆开：一个 Key 专门做模型对话验证，一个 Key 走 Coding Plan 做长期编码任务，权限隔离，出问题好定位。Base URL 统一用https://taotoken.net/api，所有脚本从环境变量读，不硬编码。

如果你要长期做车载感知模型的迭代，Coding Plan 会比按次调用更划算，尤其是需要频繁跑编译脚本补全、日志分析这类任务时。模型对话入口适合做单次验证和调试，API Keys 页面负责 Key 的创建和权限管理，接入文档里有各语言的最小示例，照着改就能用。

最后留一个实用技巧：板端执行时，如果推理结果不对但程序不报错，先检查输入图片的预处理（归一化、通道顺序、resize 方式）是否和训练时一致。感知模型落地，八成的精度问题都出在预处理对不上，而不是模型本身。编译部署链路再顺，预处理错了，结果也是错的。把预处理逻辑和模型文件一起版本管理，能省掉大量返工。