123 lines
4.8 KiB
Markdown
123 lines
4.8 KiB
Markdown
# 使用 Conda 单环境部署 FishServer（方案 A）
|
||
|
||
本文说明在另一台 **Linux x86_64** 机器上，用 **一个 conda 环境** 安装 Fish API、FishMeasure、FishAction 所需依赖并启动服务。子进程与 uvicorn 共用同一 Python 解释器，**无需**在 `fish_api/.env` 中设置 `PYTHON_FISH_MEASURE` / `PYTHON_FISH_ACTION`（保持为空即可）。
|
||
|
||
---
|
||
|
||
## 前置条件
|
||
|
||
- 已克隆本仓库，目录中包含 `fish_api/`、`FishMeasure/`、`FishAction/`。
|
||
- **模型权重**：将原机器上的 `models/` 及 `.env` 中引用的 checkpoint 拷贝到新机器；空目录会导致推理失败。
|
||
- **GPU（可选）**：若使用 `SAM_DEVICE=cuda` 或 PyTorch CUDA，需安装与 PyTorch 版本匹配的 **NVIDIA 驱动与 CUDA**。
|
||
- **ZED SDK（处理 `.svo2` 时）**：在新机器安装 **Stereolabs ZED SDK** 及 Python API，版本尽量与现有开发/生产环境一致。
|
||
- **ffmpeg**：用于视频转码；可用系统包（`apt install ffmpeg` 等），或使用仓库内 `scripts/setup_ffmpeg.sh`（需将脚本中的 `PROJECT_ROOT` 改为本机仓库路径）。
|
||
|
||
---
|
||
|
||
## 1. 创建并激活 conda 环境
|
||
|
||
Fish API 要求 **Python ≥ 3.11**（见 `fish_api/pyproject.toml`）。
|
||
|
||
```bash
|
||
conda create -n fishserver python=3.11 -y
|
||
conda activate fishserver
|
||
```
|
||
|
||
后续所有 `pip`/`python` 命令均在该环境中执行。
|
||
|
||
---
|
||
|
||
## 2. 安装 Fish API（FastAPI 网关）
|
||
|
||
```bash
|
||
cd /path/to/FishServer/fish_api
|
||
pip install -e .
|
||
# 或：pip install -r requirements.txt
|
||
```
|
||
|
||
可选开发依赖（本地冒烟测试等）：
|
||
|
||
```bash
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 在同一环境中安装 FishMeasure / FishAction 依赖
|
||
|
||
**方案 A 的核心**：测量与行为脚本由 API 以子进程调用，默认使用 **当前 `python`（与 uvicorn 相同）**，因此 PyTorch、OpenCV、ZED、X3D 等必须**全部**装进 **`fishserver`** 这一环境。
|
||
|
||
本仓库未提供单一的 `FishMeasure/requirements.txt`，请按以下方式之一对齐依赖：
|
||
|
||
1. **从已有机器导出**（推荐）：在已能跑通测量的环境中执行 `pip freeze > requirements-frozen.txt`，在新环境中用 `pip install -r requirements-frozen.txt`（注意需人工剔除/替换与平台、CUDA 不兼容的包）。
|
||
2. **按模块 README 与脚本逐步安装**：参考 `FishMeasure/README.md`、各子目录说明，以及 `FishAction/predict_video_x3d_3class.py` 的实际 import；至少安装 `FishAction/requirements.txt` 中的依赖，并补齐 PyTorch、torchvision、与 ZED 文档匹配的包。
|
||
|
||
安装完成后，在 **`conda activate fishserver`** 下验证：
|
||
|
||
```bash
|
||
python -c "import torch; print(torch.__version__)"
|
||
# 若使用 ZED：按 Stereolabs 文档验证 pyzed 等
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 配置 `fish_api/.env`
|
||
|
||
从旧机器复制 `fish_api/.env` 到新机器，**全部路径改为本机绝对路径**，例如：
|
||
|
||
- `PUBLIC_BASE_URL`：客户端可访问的 API 根地址，**不要**末尾 `/`。
|
||
- `ACTION_WATCH_DIR`、`MEASURE_WATCH_DIR`：若启用目录监控，填本机目录。
|
||
- `YOLO_MODEL`、`WEIGHT_CHECKPOINT`、`ACTION_CHECKPOINT` 等：指向本机真实文件。
|
||
- `SAM_DEVICE`：`cuda` 或 `cpu`。
|
||
|
||
**方案 A 下不要填写** `PYTHON_FISH_MEASURE`、`PYTHON_FISH_ACTION`（留空），让子进程使用当前环境的 `python`。
|
||
|
||
启动前请 **`conda activate fishserver`**，使 `which python` / `which uvicorn` 指向该环境。`fish_api/start_fresh.sh` 使用环境变量 **`PYTHON`**（可选）覆盖解释器，默认 **`python3`**。
|
||
|
||
---
|
||
|
||
## 5. 启动服务
|
||
|
||
在**仓库根目录**执行：
|
||
|
||
```bash
|
||
conda activate fishserver
|
||
cd /path/to/FishServer
|
||
bash scripts/start_fresh.sh
|
||
```
|
||
|
||
默认监听 `0.0.0.0:8000`。可覆盖：
|
||
|
||
```bash
|
||
HOST=0.0.0.0 PORT=8000 bash scripts/start_fresh.sh
|
||
```
|
||
|
||
可选环境变量（见 `fish_api/start_fresh.sh` 注释）：
|
||
|
||
- `CLEAR_SQLITE_DATABASE=1`：清空 SQLite（谨慎）。
|
||
- `CLEAR_MEASURE_OUTPUT=1` / `CLEAR_ACTION_OUTPUT=1`：清空中间输出目录。
|
||
|
||
浏览器访问：`http://<主机>:8000/docs`。
|
||
|
||
---
|
||
|
||
## 6. 自检清单
|
||
|
||
| 检查项 | 说明 |
|
||
|--------|------|
|
||
| 环境 | `conda activate fishserver` 后 `python -V` 为 3.11+ |
|
||
| API 包 | 在 `fish_api` 目录下 `python -c "import app"` 无报错 |
|
||
| 可执行文件 | `which uvicorn` 指向 `fishserver` 的 `bin` |
|
||
| 权重 | `.env` 中模型路径在本机存在 |
|
||
| 测量（SVO） | ZED 与 PyTorch 在同一 conda 环境中可用 |
|
||
| ffmpeg | `ffmpeg -version` 成功（若走视频转码路径） |
|
||
|
||
---
|
||
|
||
## 7. 参考
|
||
|
||
- 根目录 `README.md`、`fish_api/README.md`：环境变量表与启动说明。
|
||
- `fish_api/start_fresh.sh`：启动前 `prestart_fresh` 与 uvicorn 参数。
|
||
|
||
若需将 FishMeasure / FishAction 拆到**独立 conda 环境**，请在 `fish_api/.env` 中填写 `PYTHON_FISH_MEASURE` 与 `PYTHON_FISH_ACTION`（不在本文「方案 A」范围内）。
|