# sorting_brain

**Repository Path**: mwdb996/sorting_brain

## Basic Information

- **Project Name**: sorting_brain
- **Description**: 机械臂抓取的智能大脑
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-14
- **Last Updated**: 2025-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

项目总览

名称与目标：Sorting Brain Console（前后端分离）用于“看-听-想-做”全链路原型，覆盖目标检测/分割（YOLO）、场景分类（YOLO-CLS）、语音转写（FunASR 2pass），通过一个流式 ReAct 智能体（LLM）把工具编排起来。
技术栈：
后端：Python 3，FastAPI + Uvicorn（REST + WebSocket），websockets，opencv-python，onnxruntime，ultralytics，Pillow，requests，dotenv，openai 兼容客户端（Qwen）。
前端：Vite + React（TypeScript），WebAudio（采集），WebSocket（双向），Canvas（叠加层）。
ASR：FunASR WebSocket 2pass server（独立进程，modelscope 模型）。
模型：YOLOv8 分割 ONNX（80 类，DFL 解码 + proto 分割）、YOLOv8 分类 ONNX（ImageNet 风格）、Ultralytics .pt（best.pt，实例分割/检测）。
目录与模块

后端服务：brain_console/backend/main.py:1
FastAPI 路由与长连接（REST + WS），调用核心能力（YOLO/分类/相机/实时分析/LLM）。
感知核心：
YOLO（ONNX 分割）：brain_console/backend/core/yolo_onnx.py:1
YOLO（Ultralytics .pt）：brain_console/backend/core/yolo_pt.py:1
YOLO-CLS（ONNX 分类）：brain_console/backend/core/yolo_cls_onnx.py:1
统一图像输入：brain_console/backend/core/image_fetcher.py:1
相机（本地采集 + MJPEG 预览）：brain_console/backend/core/camera.py:1
实时流分析（RTSP/HTTP 视频流，服务端渲染）：brain_console/backend/core/realtime.py:1
智能体（ReAct + 流式，含日志净化/OVERLAY 信道）：brain_console/backend/core/brain.py:1
ASR 上游（独立）：FunASR-main/runtime/python/websocket/funasr_wss_server.py:1
前端（Vite/React）：
v1（Canvas 前端叠加，已淘汰）：brain_console/frontend/src/App.tsx:1
v2（后端渲染、前端仅展示，推荐）：brain_console_v2/frontend/src/App.tsx:1
旧版 Gradio 演示（不属于主链路）：brain_console/app.py:1 与 brain_console/core/*
GUI 脚本（OpenCV + Ultralytics）：brain_console/GUI/gui_brain.py:1
开发脚本：brain_console/dev.sh:1、brain_console/dev-stop.sh:1
环境变量示例：brain_console/backend/.env:1（含模型路径/摄像头抓拍 URL/Qwen 配置）
关键技术与实现细节

统一图像来源 fetch_image（强约定）
输入支持 PIL.Image / numpy / 本地路径 / http(s) URL / 摄像头抓拍（CAMERA_API_URL）/ 场景回退（_SCENE_IMAGE_PATH）。
失败时抛异常；工具层透传错误，便于排查。brain_console/backend/core/image_fetcher.py:1
YOLOv8 分割（ONNX）
自研解码：DFL 距离回归 + 多尺度分类图 + 原型 proto 组合系数 → mask；支持 NMS、去 letterbox 还原到原图尺寸；生成 mask_png（RGBA base64）与粗轮廓点集。brain_console/backend/core/yolo_onnx.py:1
环境：YOLO_MODEL_PATH 指定 onnx 路径；推理接口 run_yolo(image, conf, mask_thr, only_class)。
输出模式统一：objects[{label,score,bbox[x1,y1,x2,y2], mask_png?, mask_size?}], image_size[W,H]。
YOLO（Ultralytics .pt）
懒加载 YOLO(best.pt)，支持 PIL 直接推理；提取 boxes/masks；将 mask 多边形绘到透明 RGBA 生成 mask_png。brain_console/backend/core/yolo_pt.py:1
业务后处理（环境变量可配）：
类别白名单：YOLO_PT_ALLOWED_CLASSES（默认三类法兰）
ROI：YOLO_PT_ROI（像素或比例）；未配置走边距比例 YOLO_PT_MARGIN_RATIO（默认 0.05）
尺寸/面积阈值：YOLO_PT_MIN_W/MIN_H、YOLO_PT_MIN_AREA_RATIO（默认 0.002）
高 IoU 去重：YOLO_PT_MERGE_IOU（默认 0.8）
边界剔除：YOLO_PT_DROP_BORDER
默认置信度：YOLO_PT_CONF（默认 0.5，可入参覆盖）。
输出严格统一到同一 schema，前端可以与 ONNX 分割通用处理。
YOLO-CLS（ONNX 分类）
简单预处理（等比到 imgsz），选择 2D logits tensor → softmax → TopK；支持自定义标签文件（YOLO_CLS_LABELS）。brain_console/backend/core/yolo_cls_onnx.py:1
默认模型路径：YOLO_CLS_MODEL_PATH 或 /data/sorting_brain/yolov8n-cls.onnx。
输出：classes[{index,label,score}], image_size。
实时视频流分析（远程）
采集线程：OpenCV VideoCapture（HTTP/RTSP/MJPEG），写入最新帧；推理线程周期性取帧 → YOLO 推理（默认 onnx，可选 pt）；结果扇出到订阅者（asyncio 队列）。brain_console/backend/core/realtime.py:1
后端提供 /api/rt/ws 推送 rendered_image_url（服务端渲染后的图像）与 summary，前端直接展示，不再做前端叠加。
与 CAMERA_API_URL 协同：/api/rt/start 若传入 stream_url 且包含 /stream，自动推断其 /capture 并注入 CAMERA_API_URL（供 fetch_image 无缝抓拍）。
本地相机（Linux/Windows）
选择后端（V4L2/DirectShow/MSMF），配置分辨率/FPS，后台线程持续采集；提供 MJPEG 预览 /api/camera/stream 和一次性抓拍 /api/camera/snapshot。brain_console/backend/core/camera.py:1
ReAct 智能体（LLM 编排 + 流式）
System prompt 约定 ACTION/FINAL 协议：工具调用通过单行 ACTION: {...}，结束用 FINAL: …。brain_console/backend/core/brain.py:1
循环：流式输出一轮 → 解析 ACTION/FINAL → 调用工具（yolo_pt/yolo_cls/ocr/ros）→ 注入 OBSERVATION → 继续下一轮，直至 FINAL 或无动作。
LLM 客户端：OpenAI 兼容（Qwen），环境 QWEN_API_KEY/QWEN_BASE_URL/QWEN_MODEL，按需流式。失败时在流中返回错误提示，不崩溃。
ASR（FunASR 2pass）
上游服务：funasr_wss_server.py（端口缺省 10095）；支持 2pass-online（临时）与 2pass-offline（稳定），支持 VAD/热词；仅支持单客户端并发。FunASR-main/runtime/python/websocket/funasr_wss_server.py:1
后端 WS 代理：/api/v1/ws 把浏览器的 WS 桥接到 FunASR 上游（带重试/超时）；/asr/status 用于连通性快速自检。brain_console/backend/main.py:340
前端：WebAudio 采 16k PCM，通过 WS 发送二进制音频与握手 JSON（chunk_size、look_back、itn 等），双缓冲聚合 online/offline 文本，稳定结果回填输入框并可自动触发执行。brain_console/frontend/src/App.tsx:156
（v2）前端仅展示
右侧结果区两个元素：
- 场景图像：原始摄像头流或上传图片
- 分析结果：后端渲染好的图像 rendered_image_url（包含掩码/边框/类别/分数），无需前端叠加
流式日志中：
- [工具返回] 行为“摘要”（不含 base64）
- OVERLAY: 行包含 rendered_image_url，前端据此更新“分析结果”图像
场景一致性与图源约定（AGENTS）
推荐工具入口统一使用 fetch_image(image, use_camera_env=True, scene_path=_SCENE_IMAGE_PATH)
无上传时：优先 CAMERA_API_URL 抓拍 → 否则回退 _SCENE_IMAGE_PATH（由 /api/scene/upload 或抓拍“设为场景”维护）
远程预览推荐 /stream，分析推荐 /capture 单张，保证时序一致。AGENTS.md:1
服务接口（后端 FastAPI）

健康检查
GET /health → {status: ok}
GET /asr/status → 触上游 FunASR，一次握手探活
智能体（文本到流式日志）
POST /api/command/text → StreamingResponse（纯文本流），服务端运行 ReAct 回合，期间向流里追加：
普通思考文本
[系统] 检测到工具调用：{...}
[工具返回] {...}（净化后的摘要：objects_found/top_label/labels 等）
OVERLAY: {...}（包含 rendered_image_url，用于前端展示）
OBSERVATION: {...}（供下轮 LLM 消化的精简摘要，无 base64）
✅ 任务完成：… 或 ℹ️ 未检测到进一步的ACTION或FINAL…
场景图管理
POST /api/scene/upload（multipart file）→ 保存并设置为当前场景（yolo_cls 与 yolo_pt 均更新）
GET /api/scene/yolo_debug → ONNX 输出调试（PT-only 模式返回占位）
POST /api/scene/yolo_infer → 使用 yolo_pt 对当前场景或指定 image_url 推理
POST /api/scene/yolo_cls_infer → 使用 yolo_cls 对当前场景分类
本地相机
POST /api/camera/start | /stop | GET /status
GET /api/camera/stream（MJPEG 预览）
GET /api/camera/snapshot?set_scene=true → 抓拍并保存为文件，set_scene=true 将其设为当前场景
已修复：抓拍“设为场景”会同时设置分类与检测两侧（set_scene_image_cls + set_scene_image_pt）。brain_console/backend/main.py:327-334
远程流实时分析（后端渲染）
POST /api/rt/start { stream_url, capture_url?, engine } → 启动后台采集/推理/渲染；若未给 capture_url 且 stream_url 含 /stream，将自动推断 /capture 并写入 CAMERA_API_URL
POST /api/rt/stop、GET /api/rt/status
WS /api/rt/ws → 连续推送 { rendered_image_url, summary }，前端直接展示“分析结果”
ASR 代理
WS /api/v1/ws → 与 FunASR 上游桥接（text frame 透传 JSON，binary 透传 PCM）
数据协议（v2）

- 抓拍/场景推理：
  - POST /api/scene/yolo_infer { image_url? } → { ok, result: { rendered_image_url, summary, image_size }, used_image_data_url? }
  - used_image_data_url：后端用于推理的原始帧（data URL），前端将“场景图像”切换为该帧以确保像素对齐
- 实时推理：
  - WS /api/rt/ws → { rendered_image_url, summary }
- 智能体流：
  - [工具返回] 行：仅摘要（objects_found/top_label/labels）
  - OVERLAY: 行：包含 rendered_image_url（前端显示），不写入日志
  - OBSERVATION: 行：给 LLM 的精简摘要（无 base64）
运行与联调（conda 虚拟环境 defect_detection）

准备环境（建议在 conda env: defect_detection）
Python 依赖：brain_console/backend/requirements.txt:1
Node 依赖：brain_console/frontend（npm install）
模型文件：
Ultralytics .pt：/data/sorting_brain/best.pt（已存在）
YOLO 分割 ONNX：/data/sorting_brain/yolov8seg_onnx/yolov8nseg_relu_80class_dfl.onnx（.env 已指向）
YOLO-CLS ONNX：/data/sorting_brain/yolov8n-cls.onnx
关键环境变量（可在 defect_detection 环境内 export，或使用 .env 加载）
YOLO_MODEL_PATH（分割 ONNX）/ YOLO_CLS_MODEL_PATH（分类 ONNX）
CAMERA_API_URL（远程抓拍接口 /capture）
YOLO_PT_MODEL_PATH（可不设，默认使用 /data/sorting_brain/best.pt）
YOLO_PT_* 后处理阈值（见 yolo_pt.py 内部说明）
QWEN_API_KEY/QWEN_BASE_URL/QWEN_MODEL（用于 ReAct 智能体流式）
FUNASR_WS_URL（默认 ws://127.0.0.1:10095）
一键开发脚本
./brain_console/dev.sh
启动 FunASR WS（CPU/GPU 可选）、后端（默认 8765）、前端（5173）
日志输出在 brain_console/dev-logs
停止：./brain_console/dev-stop.sh
手动启动（仅示例）
后端：
conda activate defect_detection
pip install -r brain_console/backend/requirements.txt
python -m uvicorn brain_console.backend.main:app --host 0.0.0.0 --port 8765
前端（v2 推荐）：
cd brain_console_v2/frontend
npm install
npm run dev
FunASR 上游（CPU 示例）：
cd FunASR-main/runtime/python/websocket
python funasr_wss_server.py --port 10095 --certfile "" --keyfile "" --ngpu 0 --device cpu
端到端链路（v2：从“指令/语音”到“后端渲染结果”）

文本 → ReAct 智能体 → 工具 → 后端渲染图
前端 POST /api/command/text（流式）→ 后端 process_command_stream 开启一回合
LLM 输出 ACTION → 视觉工具推理并在后端用 OpenCV 渲染 → OVERLAY 行给出 rendered_image_url → [工具返回] 输出摘要 → 继续回合直至 FINAL
语音 → ASR（2pass）→ 文本 → ReAct 智能体
浏览器采集 16k PCM → WS /api/v1/ws（后端代理）→ FunASR 上游
online 片段实时填充输入框，offline 稳定片段覆盖；到达稳定结果后可自动触发“发送”，进入上面的 ReAct 链路。
远程流实时检测
前端 POST /api/rt/start（填写 stream_url 与 capture_url）→ 后端线程采集+推理+渲染 → WS /api/rt/ws 持续推送 rendered_image_url → 前端直接显示“分析结果”。
场景图片工作流
上传 /api/scene/upload 或本地相机抓拍 /api/camera/snapshot?set_scene=true → 设置 _SCENE_IMAGE_PATH
之后 yolo_pt/yolo_cls 可在 image=None 时自动使用 CAMERA_API_URL 抓拍或场景回退；保证 LLM 连续回合使用同一帧。
注意与已知事项

安全：brain_console/backend/.env 示例文件包含敏感键位，请改为运行环境注入；勿提交到仓库。
小问题：/api/camera/snapshot 中 set_scene_image_det 名称未定义（应改为 set_scene_image_pt 或同时设置分类/检测两者）。brain_console/backend/main.py:225
Ultralytics 依赖 PyTorch/torchvision，确保 defect_detection 环境已安装（requirements 已含 ultralytics，但不同 CUDA/CPU 组合需匹配 wheel）。
onnxruntime 若无 GPU，将自动 CPU 运行，已实现 providers 顺序回退。
FunASR 上游“仅支持单客户端”，前端已在 stopMic 时延时静音和 is_speaking=false，降低断句丢尾词风险。
文件与配置速览（关键路径）

后端入口与路由：brain_console/backend/main.py:1
ReAct 智能体流式：brain_console/backend/core/brain.py:1
图像来源统一入口：brain_console/backend/core/image_fetcher.py:1
YOLO（PT）：brain_console/backend/core/yolo_pt.py:1（允许类/ROI/尺寸/面积/去重/边界等过滤）
YOLO（ONNX 分割）：brain_console/backend/core/yolo_onnx.py:1（DFL 解码 + proto 分割）
YOLO-CLS（ONNX）：brain_console/backend/core/yolo_cls_onnx.py:1
实时流分析：brain_console/backend/core/realtime.py:1
本地相机：brain_console/backend/core/camera.py:1
前端页面：brain_console/frontend/src/App.tsx:1
ASR 上游：FunASR-main/runtime/python/websocket/funasr_wss_server.py:1
开发脚本：brain_console/dev.sh:1
运行依赖：brain_console/backend/requirements.txt:1
环境变量示例：brain_console/backend/.env:1（请勿泄露实际 key）
这份文档覆盖了技术路径、各模块所用技术、统一约定与数据协议，以及端到端如何串联与运行的具体细节，便于你在 defect_detection 环境中快速上手与联调。