EmbedAI — 边缘 AI 的嵌入式发行版

English | 中文

以硬件为核心：让 AI 模型在板卡上稳定、高性能地跑起来。

项目定位

以硬件为核心的边缘 AI 发行版：围绕特定板卡（当前为 NVIDIA Jetson Orin Nano Super DevKit NVMe）对整条硬件栈做调优，目标是让模型稳定、高性能地运行（见 docs/12-positioning.md）。

• 精简系统：无 GUI / 无桌面栈，只留 SSH 管理入口
• 自建 distro 与 image：embedai / embedai-image
• 资源极限留给 AI：GPU/CUDA 计算能力保留，其余能省则省，把资源留给模型
• 整栈定版：内核 / 驱动 / CUDA 版本经 KAS 锁定，换机器与 CI 结果一致

详细文档见 docs/（分章节：硬件、KAS、内核、裁剪、CI、虚拟板、下载加速、定位）。

构建方式：KAS

本仓库用 KAS 管理整个 Yocto 构建，替代 tegra-demo-distro 的 git submodule 方式。

~/tegra-kas/
├── kas.yml                      # KAS 配置：仓库 + 层 + distro/machine/target
├── meta-embedai/                 # 自建层
│   ├── conf/
│   │   ├── layer.conf
│   │   └── distro/embedai.conf   # 自建 distro
│   ├── recipes-core/images/
│   │   └── embedai-image.bb      # 自建精简镜像
│   └── recipes-bsp/arm-trusted-firmware/
│       └── arm-trusted-firmware_%.bbappend   # Python 3.10 兼容补丁
└── build/                       # kas 生成的构建目录（不入库）

依赖

• kas（5.3+，pip install kas）
• 磁盘：构建 Jetson 镜像约需 ~60G+（可复用旧缓存）

快速开始

kas checkout kas.yml      # 拉取并锁定各层
kas build kas.yml         # 构建 embedai-image
kas shell kas.yml         # 进入 bitbake 环境
kas dump kas.yml          # 查看最终展开配置

首次构建生成 kas.lock 固定各仓库版本。

国内首次构建慢？ 先把下载和编译拆开：bitbake --runall=fetch embedai-image 只拉源码（可中断重跑），完成后再 kas build。详见 docs/07-local-build.md。

虚拟开发板（QEMU，无需 Jetson）

没有硬件也能验证发行版（启动/systemd/网络；无 GPU/CUDA/TensorRT）：

kas build kas.yml:kas-qemu.yml
kas shell kas.yml:kas-qemu.yml -c "runqemu qemuarm64 nographic"

详见 docs/11-qemu.md。

复用旧构建缓存（零复制，只读镜像）

旧构建（tegra-demo-distro/build/）的产物可直接当只读源复用，磁盘不够时不用复制：

DL_DIR ?= "/旧路径/build/downloads"                        # 源码包（版本锁定一致→全命中）
SSTATE_DIR ?= "${TOPDIR}/sstate-cache"                      # 自己的新缓存
SSTATE_MIRRORS = "file://.* file:///旧路径/build/sstate-cache/PATH"  # 编译产物只读镜像

CI 构建缓存：sstate 存进 Release（突破 Actions 10GB）

GitHub Actions 的缓存每仓库上限 10GB，而本项目的 Yocto sstate 缓存有 15–30GB—— 用 actions/cache 必然超限、save 静默失败，导致 CI 每次从零重编。

改用 GitHub Release 持久化（单文件 <2GiB、每 release ≤1000 资产、总大小不限）：

• CI 编译产物按 1.9GB 分卷上传到 Release（sstate-jetson / sstate-qemu）
• 版本化、非覆盖：先传完整套，最后原子切换 LATEST 指针 → 中断也不会丢旧缓存
• 还原时读 LATEST → 下载该套 → sha256sum -c 校验 → 解压进 build/sstate-cache
• CI 内网拉取 15GB 约 3 分钟

本地复用（可选，慢网慎用）：

scripts/pull-sstate.sh          # 拉 sstate-jetson → build/sstate-cache
scripts/pull-sstate.sh qemu     # 拉 sstate-qemu（qemuarm64）

原则：CI 编全量、本地只增量。详见 docs/17-dev-loop.md。

已解决的坑

问题	原因	解决
KAS 5.3 layers schema 报错	新版本不再支持 path/priority	改为 <repo.path>/<layer名> + prio；bitbake 需 layers: {'': disabled}
tegra_distro_update_bblayersconf 崩溃（sanity_conf_read 未定义）	版本号不匹配才走更新逻辑	bblayers_conf_header 补 TD_BBLAYERS_CONF_VERSION = "embedai-7"
GitHub 超时拉不到仓库	网络不稳定	从本地已有 clone 预置仓库目录，kas 检测存在即跳过
ImportError: cannot import name 'UTC' from 'datetime'	meta-tegra 的 TF-A 配方需 Python 3.11+，宿主是 3.10	meta-embedai 里用 timezone.utc 等价替换（bbappend）

下一步（资源精简清单）

• 确认 meta-tegra 实际包名后，在 embedai-image.bb 追加 AI 包：cudnn、tensorrt-core、tegra-libraries-cuda 等
• 自建 ollama recipe（ARM64 原生部署，无需 docker）
• 按需去掉 pam / virtualization distro 特性（embedai.conf 里有注释开关）
• 构建通过后删除旧 build/tmp、build/cache 腾空间

License

MIT