Openvision MCP

OpenVision FastAPI 推理服务器

欢迎来到这款小巧、以Docker为先的FastAPI推理服务器——现在增添了更多✨乐趣✨和清晰度。本README文件重点介绍 Makefile 助手，这样您就可以使用简单的命令来构建、运行、测试、检查代码规范以及清理项目 make 命令。

专业提示：你实际上只需要 Docker + docker-compose 来运行环境，以及 Python 来进行代码检查/测试。

🧭 快速参考 — Makefile 目标

从仓库根目录中使用这些目标。每个都是一个围绕（某个功能或目的的）小型辅助工具 docker-compose 或本地工具。

• 帮助 — 显示可用目标

  make help

• 构建 — 建造 app Docker镜像

  make build

• 跑 — 开始 app 服务（分离的）

  make run
  # then visit http://localhost:8000

• 停止 — 停止正在运行的服务

  make stop

• 日志 — 跟随 app 服务日志

  make logs

• 干净 — 删除为（某用途）创建的容器、镜像和卷 app

  make clean

• lint（在中文中，这个词通常不直接翻译，因为它是一个特定领域或技术术语，但可以解释为“棉絮”或“绒屑”，具体取决于上下文。在计算机编程中，lint 通常指的是一种用于检查代码错误的工具或过程，但在日常中文中，我们可能更倾向于使用更通用的表述。） — 跑 isort， black， ruff， flake8

  make lint

• 测试 — 安装CI依赖（如果存在）并运行 pytest

  make test

🎯 快速图表（当你运行时会发生什么） make run)

flowchart LR
  A[Developer 🧑‍💻] -->|make build| B[Docker image 🧩]
  B -->|make run| C[docker-compose ⛴️]
  C --> D[app service ▶️]
  D --> E{Endpoints}
  E --> E1[/health]
  E --> E2[/v1/predict]
  E --> E3[/v1/statistics]

🛠️ 典型的工作流程

• 快速开发循环（构建 → 运行 → 查看日志）：

  make build && make run && make logs

• 清理由（该）助手创建的一切 app 服务：

  make clean

• 预提交审查（格式与代码规范检查）：

  make lint

• 在本地运行测试：

  make test

• 微调模型（示例）：

# prepare data in ImageFolder layout: data/train//* and data/val//*
make train
# or run directly:
python scripts/train_finetune.py --data-dir ./data --model efficientnet_b4 --epochs 10 --batch-size 32 --output ./checkpoints --export-torchscript

训练后，将（某物）指向 AppConfig.trained_model_path （或者 APP_TORCHSCRIPT_MODEL_PATH 将（env）添加到导出的TorchScript中 .pt 保存文件并重启服务器以运行微调后的模型。

⚙️ 环境与配置

在运行之前复制示例环境文件（可选）：

cp .env.example .env
# edit .env to set MODEL_PATH or other overrides

配置由以下驱动 app/config.py 以及环境变量。

🔌 端点（超级快速）

• GET /health — 健康检查
• POST /v1/predict — 推理（多部分 file）
• GET /v1/statistics — 运行时统计信息
• GET /metrics — Prometheus 指标（如果已启用）
• 提示访问交互式API文档： http://localhost:8000/docs 以便在您的浏览器中轻松探索和测试API。

示例推理：

curl -X POST "http://localhost:8000/v1/predict" -F "file=@myphoto.jpg"

📦 Docker 笔记

该项目以Docker为优先； make build / make run 它们是轻量级的辅助工具。如果你更喜欢使用原生 Docker：

docker build -t openvision-inference .
docker run -p 8000:8000 openvision-inference

🔎 可观测性 & 日志

• 结构化JSON日志发送至 application.log 以及标准输出（stdout）。
• 当……时启用Prometheus指标 prometheus-fastapi-instrumentator 已安装。

🙌 贡献与礼仪

• 按照项目布局进行 app/ 对于路由器、服务和实用工具。
• 跑 make lint 和 make test 在提交拉取请求（PR）之前。
• 保持更改的小而集中——每个拉取请求（PR）只包含一个逻辑批次的更改。

______________________________________________________________________

如需更深入的设计说明和操作指南，请参阅 docs/DESIGN.md， docs/ASSIGNMENT.md 并且 docs/REMARKS.md.