Files

zaiun xu 9df21f80ef Initial commit: FishServer monorepo (FishAction, FishMeasure, fish_api)

Made-with: Cursor

2026-04-08 19:32:23 +08:00

4.5 KiB

Raw Blame History

Fish API

FastAPI 网关：分块接收 SVO2（FishMeasure）与 MP4（FishAction），在后台调用现有脚本；对外提供文档约定的 GET 轮询接口，并托管预览视频 URL。

依赖环境

Python 3.11+（uv 可管理 3.13 等版本）
FishMeasure：需与本机 FishMeasure/ 一致的环境（ZED SDK、pyzed、CUDA、YOLO/SAM 权重等）
FishAction：需可运行 FishAction/predict_video_x3d_3class.py（PyTorch、PyTorchVideo、checkpoint）

若 FishMeasure 与 FishAction 使用不同虚拟环境，可设置：

PYTHON_FISH_MEASURE — 运行 predict_weigth_from_svo2.py 的解释器路径
PYTHON_FISH_ACTION — 运行 predict_video_x3d_3class.py 的解释器路径

单一 Conda 环境：若 FishMeasure 与 FishAction 已与网关停在同一个 env（例如仓库根目录 packaging/conda-fishserver.yaml 定义的 fishserver），则不要设置上述两个变量，子进程会使用当前 uvicorn 的 Python。可用 scripts/run_fishserver.sh 启动。

配置（环境变量）

变量	说明	默认
`PUBLIC_BASE_URL`	返回 JSON 中 `video_left` / `video_right` 的前缀（勿带末尾 `/`）	`http://127.0.0.1:8000`
`INGEST_API_KEY`	非空时，`/api/v1/ingest/*` 需请求头 `X-API-Key`	空（不校验）
`STREAM_TMP_DIR`	分块上传临时目录	`<repo>/fish_api/.data/ingest`
`MEDIA_ROOT`	对外托管的 `latest_left.mp4` / `latest_right.mp4`	`<repo>/fish_api/.data/media`
`FISH_MEASURE_ROOT`	`FishMeasure` 根目录	自动相对仓库
`FISH_ACTION_ROOT`	`FishAction` 根目录	自动相对仓库
`MEASURE_OUTPUT_ROOT`	传给 `--save-output` 的目录	`FishMeasure/output_weight_estimator`
`YOLO_MODEL` / `WEIGHT_CHECKPOINT` / `ACTION_CHECKPOINT`	模型路径	与仓库内脚本默认一致
`SAM_DEVICE`	`cuda` 或 `cpu`	`cuda`
`DEFAULT_FISH_SPECIES`	GET 中 `result[].type`	`大黄鱼`

可在 fish_api/.env 中填写上述变量（pydantic-settings 会读取）。

安装与启动

cd fish_api
uv sync
# 可选：包含 httpx，便于本地用 FastAPI TestClient 做冒烟测试
# uv sync --group dev
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

OpenAPI：http://127.0.0.1:8000/docs

对外 GET（由其它系统轮询）

GET /api/v1/biomass/real/camera/ — 双目 / 称重结果（最新一次成功快照）
GET /api/v1/biomass/health/result/ — 行为 / 健康（最新一次成功快照）

失败时返回 code: 500，msg 为错误信息，data 为空结构。

流式输入（分块上传）

POST /api/v1/ingest/svo/session 或 POST /api/v1/ingest/mp4/session → session_id
PUT /api/v1/ingest/{svo|mp4}/session/{session_id}?offset=0（多次）
- 追加语义：offset 必须等于当前已写入字节数（从 0 开始顺序上传）
POST /api/v1/ingest/{svo|mp4}/session/{session_id}/finalize → 202 Accepted，后台开始跑对应算法

示例（小文件一次性，$API_KEY 可选）：

BASE=http://127.0.0.1:8000
H=()
# H=(-H "X-API-Key: your-secret")

sid=$(curl -sS "${H[@]}" -X POST "$BASE/api/v1/ingest/svo/session" | jq -r .session_id)
curl -sS "${H[@]}" -T sample.svo2 -X PUT "$BASE/api/v1/ingest/svo/session/$sid?offset=0"
curl -sS "${H[@]}" -X POST "$BASE/api/v1/ingest/svo/session/$sid/finalize"
curl -sS "$BASE/api/v1/biomass/real/camera/"

MP4 将 svo 换成 mp4，本地文件换成 clip.mp4，轮询 GET /api/v1/biomass/health/result/。

说明：curl -T 发送 PUT 时 offset 为 0 且一次性传完整文件适合单块场景；多块时请自行递增 offset。

行为与健康映射

X3D 输出 feeding / normal / scared → 中文吃饵 / 正常游行 / 惊吓
健康：scared → 不健康，其余 → 健康（启发式，可后续换专用模型）

视频 URL

FishMeasure 跑完后在输出目录查找 *preview*.mp4，复制到 MEDIA_ROOT/latest_left.mp4 与 latest_right.mp4（仅一个文件时左右 URL 可能相同）。确保 PUBLIC_BASE_URL 与前端/文档中的域名端口一致（例如 http://192.168.3.33:8888另起反向代理时，应把该值配成对外可达的 API 根）。

演进建议

RTSP：用 ffmpeg 切段写入 MP4 后调用现有 finalize 逻辑
任务状态：finalize 返回 job_id，增加 GET /jobs/{id} 查询进度

4.5 KiB Raw Blame History Unescape Escape