入户门检测 FastAPI 服务

基于 export_entrance_position.py 的 HTTP API 服务，支持远程调用入户门检测功能。

快速开始

1. 启动服务器

# 激活环境
conda activate yolo26

# 启动服务
python server.py --host 0.0.0.0 --port 8000

# 或使用 uvicorn 直接启动
python -m uvicorn server:app --host 0.0.0.0 --port 8000

2. 访问 API 文档

浏览器打开：http://localhost:8000/docs

这是 Swagger UI 界面，可以交互式测试所有 API。

3. 使用客户端调用

# 健康检查
python client.py --health

# 检测场景
python client.py -s scene0001

# 带可视化输出
python client.py -s scene0001 --vis_ply

# 指定远程服务器
python client.py -s scene0001 --server http://192.168.1.100:8000

API 接口

健康检查

GET /health

响应示例：

{
  "status": "healthy",
  "model_loaded": true,
  "gpu_available": false,
  "timestamp": "2026-04-14T14:17:34.406460"
}

提交检测任务

POST /detect
Content-Type: application/json

{
  "scene_folder": "/path/to/scene0001",
  "conf": 0.35,
  "iou": 0.45,
  "voxel_size": 0.03,
  "imgsz": [1024, 2048],
  "vis_ply": true
}

响应：

{
  "task_id": "d36d7028-7b15-41bd-99b7-194647ef6656",
  "status": "pending",
  "message": "任务已提交，正在处理中"
}

查询任务状态

GET /status/{task_id}

响应示例：

{
  "task_id": "d36d7028-7b15-41bd-99b7-194647ef6656",
  "status": "processing",
  "progress": 0.3,
  "message": "正在检测门并识别入户门..."
}

状态说明：

pending: 等待处理
processing: 处理中
completed: 已完成
failed: 失败

获取检测结果

GET /result/{task_id}

响应： JSON 格式的入户门检测结果

下载可视化 PLY

GET /result/{task_id}/ply

响应： PLY 文件（二进制）

删除任务

DELETE /task/{task_id}

Python 客户端使用示例

from client import EntranceDoorClient

# 创建客户端
client = EntranceDoorClient(base_url="http://localhost:8000")

# 健康检查
health = client.health_check()
print(f"服务状态：{health['status']}")

# 提交检测任务并等待结果
result = client.detect(
    scene_folder="/path/to/scene0001",
    conf=0.35,
    iou=0.45,
    vis_ply=True,
    poll_interval=2.0  # 查询状态间隔（秒）
)

print(f"入户门位置：{result['result']['entrance_position']}")

# 保存结果到本地
result_data = client.detect_and_save(
    scene_folder="/path/to/scene0001",
    output_dir="results",
    vis_ply=True
)

# 仅查询状态（不等待）
task_id = "..."
status = client.get_status(task_id)
print(f"任务状态：{status['status']}")

# 获取结果
if status['status'] == 'completed':
    result = client.get_result(task_id)
    
# 下载 PLY 文件
client.download_ply(task_id, "output/vis.ply")

# 删除任务
client.delete_task(task_id)

cURL 使用示例

# 健康检查
curl http://localhost:8000/health

# 提交检测任务
curl -X POST http://localhost:8000/detect \
  -H "Content-Type: application/json" \
  -d '{
    "scene_folder": "/path/to/scene0001",
    "conf": 0.35,
    "vis_ply": true
  }'

# 查询状态
curl http://localhost:8000/status/{task_id}

# 获取结果
curl http://localhost:8000/result/{task_id}

# 下载 PLY
curl -o vis.ply http://localhost:8000/result/{task_id}/ply

部署说明

本地开发

python server.py --reload --port 8000

生产环境

使用 gunicorn + uvicorn workers：

pip install gunicorn

gunicorn server:app \
  -w 2 \
  -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --timeout 120

Docker 部署

FROM python:3.12-slim

WORKDIR /app

COPY requirements_server.txt .
RUN pip install -r requirements_server.txt

COPY export_entrance_position.py .
COPY camera_spherical.py .
COPY yoloe-26x-seg.pt .
COPY server.py .

EXPOSE 8000

CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000"]

配置选项

服务器参数

参数	默认值	说明
`--host`	`0.0.0.0`	监听地址
`--port`	`8000`	监听端口
`--reload`	`False`	开发模式（热重载）
`--workers`	`1`	工作进程数

客户端参数

参数	默认值	说明
`--server`	`http://localhost:8000`	服务器地址
`--conf`	`0.35`	检测置信度阈值
`--iou`	`0.45`	NMS IoU 阈值
`--voxel-size`	`0.03`	点云体素尺寸
`--imgsz`	`1024 2048`	YOLOE 输入图像尺寸
`--vis_ply`	`False`	是否生成可视化 PLY
`--timeout`	`600`	超时时间（秒）

文件保存位置

使用客户端调用时，结果文件保存在场景文件夹的 output/ 目录下：

scene0001/
└── output/
    ├── entrance_position.json    # JSON 结果
    └── vis.ply                   # 可视化 PLY 文件（如使用 --vis_ply）

这样每个场景的检测结果都保存在各自的场景目录下，更有针对性。

服务器使用内存存储任务状态，重启后任务信息会丢失。

任务生命周期

提交：POST /detect 创建任务，返回 task_id
处理：后台异步执行检测
查询：GET /status/{task_id} 查询进度
获取结果：GET /result/{task_id} 获取检测结果
清理：DELETE /task/{task_id} 删除任务和结果文件

临时文件清理

检测结果默认保存在 server_results/ 目录
客户端结果保存在 client_results/ 目录
使用 DELETE /task/{task_id} 会自动清理相关文件

错误处理

常见错误

400 Bad Request

场景文件夹不存在
任务尚未完成就获取结果

404 Not Found

任务 ID 不存在
结果文件已被删除

500 Internal Server Error

检测过程出错（查看错误信息）

TimeoutError

检测超时（默认 600 秒）

性能优化

提高检测速度

降低图像分辨率

python client.py -s scene0001 --imgsz 640 1280

提高体素尺寸（降低点云密度）

python client.py -s scene0001 --voxel-size 0.05

多进程部署

gunicorn server:app -w 4 -k uvicorn.workers.UvicornWorker

内存优化

检测过程会加载大量点云数据，建议：

单服务器最多处理 2-4 个并发任务
使用 --voxel-size 0.05 或更大值降低内存占用

安全注意事项

生产环境建议

添加认证 ```python from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key")

@app.post("/detect") async def detect(api_key: str = Depends(api_key_header)):

   # 验证 API key


2. **启用 HTTPS**
   使用 Nginx 反向代理：
   ```nginx
   server {
       listen 443 ssl;
       location / {
           proxy_pass http://localhost:8000;
       }
   }

限制请求大小 python app = FastAPI() app.config.max_upload_size = 100 * 1024 * 1024 # 100MB

故障排查

服务器无法启动

# 检查端口占用
lsof -i :8000

# 检查依赖
pip install -r requirements_server.txt

客户端连接失败

# 检查服务器是否运行
curl http://localhost:8000/health

# 检查防火墙
telnet localhost 8000

检测失败

查看服务器日志中的详细错误信息：

# 服务器日志会显示详细错误
# 检查 vision.txt 格式
# 检查图像文件是否存在

SERVER_README.md 7.6 KB Histórico Raw