# Vision AI Local Deploy

> 视觉AI本地部署 Skill，用于在用户 Windows 主机（G 盘）上部署、运行、维护与排查视觉模型——LocateAnything-3B（VLM 定位）、YOLO11（实时检测）、TensorRT 引擎（加速），涵盖环境搭建、8GB 显存量化部署、屏幕识别悬浮工具、画框标注与本地训练、PyInstaller 打包分发。当用户需要部署/运行/加速/排查本地视觉 AI 模型时使用。

- Skill: `andersonlin4/vision-ai-local-deploy` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add andersonlin4/vision-ai-local-deploy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andersonlin4/vision-ai-local-deploy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: AndersOnLin4 (https://skillmd.com/u/andersonlin4)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/andersonlin4/vision-ai-local-deploy

---


# 视觉AI本地部署 Skill

在用户 Windows 主机上部署与维护本地视觉 AI 模型的操作手册。所有路径、依赖版本、硬件约束均已固定，直接复用，避免重复踩坑。

## 环境与硬件（固定事实，不可变）

- **硬件**：CPU 9700X ｜ GPU RTX 4060 Ti **8GB** ｜ 内存 DDR5 32GB
- **显示器**：双屏混合 DPI——主屏 4K(3840×2160@200%) + 副屏 1080p(1920×1080@100%)
- **系统**：Win11 ｜ 代理 FlClashX（127.0.0.1:7893）
- **主项目目录**：`G:\LocateAnything\`（Python、venv、模型、脚本、.bat 全在此）
- **TensorRT 方案目录**：`G:\YOLO-TensorRT\`
- **打包产物目录**：`G:\YOLO-Package\`

详见 [references/environment.md](references/environment.md)

## 关键约束（必须遵守）

1. **C 盘敏感**：一切安装到 G 盘；HF_HOME、pip cache、YOLO_CONFIG_DIR 必须重定向到 G，禁止写 C。
2. **8GB 显存约束**：LocateAnything-3B 权重 7.66GB，bf16 装不下，**必须 4-bit 量化**（bitsandbytes `load_in_4bit`）。
3. **分辨率上限 1280**：8GB 显存下 LocateAnything 检测分辨率最高 1280px；1600px 实测 68 秒/峰值 11.92GB（爆显存颠簸），1080p 及以上不可行。YOLO/TensorRT 无此限制。
4. **硬件超限先询问**：当部署超出用户硬件配置的模型/软件时，必须先询问用户；用户拒绝则选轻量化版本。
5. **许可证约束**：LocateAnything = NVIDIA 非商用（仅学术研究，用户大创可用，商用需换模型）；YOLO = AGPL-3.0（商用分发有开源义务）。打包分发前必须提示。

## 调用方式

本 skill 为知识型 skill，无需执行脚本。当用户提出视觉 AI 部署/运行/排查需求时：

1. 先读 [references/environment.md](references/environment.md) 确认环境与路径。
2. 按需求匹配对应功能域（见下方），读取对应 reference 执行。
3. 遇到报错/异常，先查 [references/pitfalls.md](references/pitfalls.md) 的踩坑记录，避免重复排查。

## 功能域

### 环境与依赖

Python 3.11、venv、torch cu124、pip 镜像、缓存重定向。详见 [references/environment.md](references/environment.md)

### 模型部署（三套）

- **LocateAnything-3B**：VLM 定位模型，4-bit 量化部署。详见 [references/deployment.md](references/deployment.md)
- **YOLO11**：实时检测，ultralytics，本地训练。详见 [references/deployment.md](references/deployment.md)
- **TensorRT**：YOLO 引擎加速（300 FPS），直接 TensorRT API。详见 [references/deployment.md](references/deployment.md)

### 工具与启动

网页版、悬浮框、标注工具、训练、打包分发。详见 [references/tools.md](references/tools.md)

### 踩坑与排查

编码、DPI、置顶、双重 sigmoid、类过滤、torch 降级等全部已踩坑记录。详见 [references/pitfalls.md](references/pitfalls.md)

## 踩坑速查（最高频）

1. torch 装成 CPU 版 → 走 CUDA 索引 cu124，装完 `torch.cuda.is_available()` 验证
2. 8GB 显存 OOM → 4-bit 量化
3. .bat 启动没反应 → 纯 ASCII + CRLF 换行
4. UI 跨屏大小错乱 → `SetProcessDpiAwareness(2)` + 手动按屏设 `tk scaling`
5. 悬浮框看不见 → 别用底层 API 写 `WS_EX_LAYERED`，用 Tk 原生 `-topmost`+`lift`
6. YOLO 置信度偏低+满屏 0.5 → 别再 sigmoid（TRT 输出已是概率）
7. 勾选类别无效 → 检查是否把 classes 用于过滤

## 注意事项

- **不重复安装**：环境已建好（`G:\LocateAnything\venv`、模型、.bat），优先复用，除非用户明确要求重建。
- **不碰 C 盘**：任何安装/缓存/下载先确认落盘位置为 G。
- **诚实告知利弊**：量化会略降精度、TensorRT 固定 640 输入、打包产物约 4GB（torch CUDA 库占大头）等事实必须如实说明，不做过度承诺。
- **许可证提示**：涉及分发/商用意图时，必须提示 LocateAnything 非商用、YOLO AGPL 条款。