1. 从一张照片到人脸框OpenCVFlask 人脸检测 API 到底能做什么人脸检测这件事说穿了就是让程序在一张图里找到「哪里有人脸」并给出坐标框。它不负责认出这是谁只负责回答「有没有脸、脸在哪、有几张」。这个能力听起来简单却是很多视觉应用的第一块砖相册自动按人脸分组、门禁抓拍裁剪、直播美颜定位、考勤签到预处理背后都先跑一遍人脸检测。我这次要带你跑的是用 Claude Code 辅助、从零搭一个 OpenCV Flask 的人脸检测 API。选 Flask 而不是 FastAPI是因为它足够轻几十行就能起服务小白调试时心智负担小选 OpenCV 而不是纯深度学习框架是因为它自带 Haar 级联和 DNN 模块装完就能用不需要单独下权重文件也能先跑通链路。适合谁适合刚学完 Python 基础、想做一个「能上传图片、能返回 JSON」的完整小项目的人也适合已经会写脚本、但没把脚本封装成 HTTP 接口的人。整个流程分四步装依赖、写检测脚本、用 Flask 包成接口、本地用 curl 验证。每一步我都会给出可直接复制的代码和命令你照着敲就能看到结果。核心检索词先记住OpenCV 人脸检测、Flask 上传图片接口、Haar 级联检测、人脸框坐标返回。下面正式开始。2. 前置准备TaoToken 接入 Claude Code 与项目依赖安装在动手写代码前先把「AI 辅助」这条线接上。Claude Code 是一个跑在终端里的编码助手能读你的项目文件、按你的描述生成和修改代码。要让它稳定工作需要给它配一个可用的模型接入点。我用的是 TaoToken 提供的接入方式官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。配置 Claude Code 时核心是三件套Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api API Key 在控制台的 API Keys 页面生成Model ID 按你选的模型填。如果你用的是 Claude Code 的 settings 配置可以写成这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这段 JSON 放在 Claude Code 的 settings 文件里路径按你系统的约定来。配好之后在终端里跑一次对话测试能正常返回就说明接入通了。如果你更习惯用 Codex 的 auth.json写法类似把 base_url 和 api_key 对应填进去即可。需要生成 Key 的话直接去 https://taotoken.net/api-keys 操作。接入通了之后回到项目本身。新建目录并初始化mkdir face-detection cd face-detection python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate然后写 requirements.txtFlask3.0.3 opencv-python4.10.0.84 numpy1.26.4 Werkzeug3.0.3安装pip install -r requirements.txt这里有个坑要提前说opencv-python 在服务器无图形界面时可能报 libGL 相关错误如果你在纯命令行环境跑可以换成 opencv-python-headless。本地开发用带界面的版本没问题。装完后验证一下python -c import cv2, flask; print(cv2.__version__, flask.__version__)能打印出版本号前置就齐了。这一步别跳过很多人后面报错其实是依赖没装全。3. 可复制配置Flask 路由与 OpenCV 人脸检测代码现在写核心代码。项目结构建议这样face-detection/ ├── app.py ├── detector.py ├── requirements.txt └── uploads/先写 detector.py把检测逻辑独立出来方便复用和测试import cv2 import numpy as np class FaceDetector: def __init__(self): cascade_path cv2.data.haarcascades haarcascade_frontalface_default.xml self.face_cascade cv2.CascadeClassifier(cascade_path) if self.face_cascade.empty(): raise RuntimeError(级联分类器加载失败检查 OpenCV 安装) def detect(self, image_bytes): nparr np.frombuffer(image_bytes, np.uint8) img cv2.imdecode(nparr, cv2.IMREAD_COLOR) if img is None: raise ValueError(图片解码失败确认上传的是有效图片) gray cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) gray cv2.equalizeHist(gray) faces self.face_cascade.detectMultiScale( gray, scaleFactor1.1, minNeighbors5, minSize(30, 30) ) results [] for (x, y, w, h) in faces: results.append({ x: int(x), y: int(y), width: int(w), height: int(h) }) return { face_count: len(results), faces: results, image_width: img.shape[1], image_height: img.shape[0] }再写 app.py把检测包成 HTTP 接口from flask import Flask, request, jsonify from detector import FaceDetector app Flask(__name__) detector FaceDetector() app.route(/api/detect, methods[POST]) def detect(): if file not in request.files: return jsonify({error: 缺少 file 字段}), 400 file request.files[file] if file.filename : return jsonify({error: 文件名为空}), 400 try: image_bytes file.read() result detector.detect(image_bytes) return jsonify(result), 200 except ValueError as e: return jsonify({error: str(e)}), 400 except Exception as e: return jsonify({error: 服务内部错误: str(e)}), 500 app.route(/api/health, methods[GET]) def health(): return jsonify({status: ok}), 200 if __name__ __main__: app.run(host0.0.0.0, port5000, debugTrue)关键参数说明scaleFactor1.1 表示每次图像缩放比例值越小检测越细但越慢minNeighbors5 控制误检值越大越严格minSize(30,30) 过滤太小的区域。这三个参数是人脸检测调优的核心后面排障会用到。启动服务python app.py看到 Running on http://0.0.0.0:5000 就成功了。注意 debugTrue 只用于本地开发上线要关掉。4. 验证请求上传图片返回人脸框的完整动作服务起来后用 curl 验证。先准备一张有人脸的图片比如 test.jpg放在项目目录下curl -X POST http://127.0.0.1:5000/api/detect \ -F filetest.jpg正常返回类似{ face_count: 1, faces: [ {x: 120, y: 80, width: 180, height: 200} ], image_width: 640, image_height: 480 }face_count 是检测到的人脸数faces 数组里每个对象就是一张人脸的框x、y 是左上角坐标width、height 是框的宽高。你可以拿这个坐标在原图上画矩形验证import cv2 img cv2.imread(test.jpg) for f in result[faces]: cv2.rectangle(img, (f[x], f[y]), (f[x]f[width], f[y]f[height]), (0, 255, 0), 2) cv2.imwrite(output.jpg, img)打开 output.jpg能看到绿框套在人脸上说明整条链路通了。如果返回 face_count 为 0先换一张正脸清晰、光线均匀的图再试Haar 级联对侧脸和暗光比较敏感。再测一下健康检查接口curl http://127.0.0.1:5000/api/health返回 {status:ok} 说明服务活着。这两个接口跑通你的第一个 AI 视觉接口就算立起来了。想继续用 AI 辅助改代码可以在 Claude Code 里描述需求比如「给 detect 接口加一个返回人脸置信度的字段」它会基于你现有文件改。5. 本篇常见错排查401、local proxy failed、reading choices 等真实报错第一个高频错误是 401 Unauthorized。如果你在 Claude Code 里调用模型时报 401多半是 API Key 没配对或过期。检查 settings 里的 ANTHROPIC_API_KEY 是否和 https://taotoken.net/api-keys 生成的一致Base URL 是否是 https://taotoken.net/api 注意结尾不要多加斜杠。改完重启终端再试。第二个是 local proxy failed。这个报错通常出现在网络配置层面说明请求没发出去。先确认你的 Base URL 填对了再确认本机没有残留的代理环境变量干扰。可以临时清掉 HTTP_PROXY、HTTPS_PROXY 再跑一次。如果用的是公司网络确认能正常访问 https://taotoken.net/api 。第三个是 reading choices 相关报错一般出现在模型返回结构解析阶段说明返回体不是预期的 JSON。常见原因是 Model ID 填错或者请求被中间层改写。核对 Model ID 拼写确认没有多余空格。第四个是 OpenCV 的级联分类器加载失败报错类似「!empty() in function detectMultiScale」。这是 haarcascade 文件路径不对。用 cv2.data.haarcascades 拼接是标准做法如果你手动指定路径确认文件真实存在。opencv-python-headless 和 opencv-python 混装也会导致路径异常卸载重装一个即可。第五个是 Flask 上传大图报 413。默认没有限制但如果你加了 MAX_CONTENT_LENGTH 又设太小就会触发。检查 app.config 里的配置或者直接去掉限制。上传前也可以在前端压缩图片。第六个是 OAuth 相关报错。如果你在 Claude Code 里看到 OAuth 字样说明它在尝试走账号登录流程而不是 API Key。确认你用的是 API Key 模式settings 里不要同时存在冲突的认证字段。清掉旧的登录缓存再试。排查顺序建议先看 HTTP 状态码401 查 Key400 查请求体500 查服务端日志。Flask 的 debug 模式会把堆栈打出来照着堆栈定位最快。6. 继续往下走把接口用起来与长期编码方案接口跑通只是起点。你可以在这个基础上加功能返回人脸裁剪图、支持批量上传、加一个简单的前端页面拖拽上传。这些都可以让 Claude Code 帮你改描述清楚输入输出即可。想验证模型对话效果可以去 https://taotoken.net/models 试试需要看接入文档在 https://taotoken.net/doc 有说明。如果你打算长期用 AI 辅助写这类视觉项目单次对话不够建议上 Coding Plan能覆盖更连续的编码和 Agent 场景入口在 https://taotoken.net/coding-plan 。配置里记得三件套齐全Base URL 用 https://taotoken.net/api Key 用你生成的Model ID 按需选。最后留个实用技巧把 detector.py 里的 scaleFactor 和 minNeighbors 做成接口参数这样不用改代码就能调检测灵敏度。上传一张合影把 minNeighbors 从 5 调到 3看检测数量变化你会对这两个参数有直观感受。这个接口虽小但它是你后面做人脸识别、人脸比对的地基先把地基踩实。