适用场景
你有一个用户会自行上传图片的产品(头像、二手交易图、评论配图、社区发帖),需要在图片进到前台展示之前,判断它是否包含违规内容,并对边界样本安排人工复核、对用户申诉留痕。这套方案把“调用分类器 → 按分数分级 → 自动放行/自动拦截/进入人工队列 → 申诉回查”串成一条可落地的服务,适合 1~3 人的小团队先把链路跑通,再按数据反馈校准阈值。
需要提前说明:下文出现的模型标识统一由环境变量 MODERATION_MODEL 注入,接口具体支持哪些图像输入形式、返回哪些类别,以 OpenAI 官方文档和你的账号实际可用能力为准,换模型不用改业务代码。
环境与前置条件
- 操作系统:Linux(Ubuntu/Debian 等)或 macOS 均可,Windows 建议走 WSL2。
- Python:3.10 及以上(示例用到
str | None语法)。 - 内存:2 GB 起步,够跑 FastAPI + SQLite;如果要多进程或接 PostgreSQL,建议 4 GB。
- 磁盘:图片落盘按“平均单图 300 KB × 日上传量 × 保留天数”估算,先留 20 GB;不需要 GPU。
- 网络:服务器要能访问 OpenAI 接口;内网环境需要配置代理。
- 账号:一个可用的 API Key,且已经在控制台确认该模型可调用、额度正常。
分步骤部署
第 1 步:初始化项目与依赖
```bash
mkdir -p image-review/app && cd image-review
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install fastapi "uvicorn[standard]" openai pillow python-dotenv
pip freeze > requirements.txt
```
四个依赖分别负责:Web 服务、ASGI 服务器、调用分类器、图片降采样(大图直接上传容易超时)、读取 .env。pip freeze 输出的是你当前环境装到的版本,够用即可,具体版本以官方文档当前版本为准。
目录结构最终会是这样:
```
image-review/
├── app/
│ ├── settings.py
│ ├── classifier.py
│ ├── policy.py
│ ├── db.py
│ ├── pipeline.py
│ └── main.py
└── data/
├── review.db
└── uploads/
```
第 2 步:配置密钥与环境变量
新建 .env(不要提交到 Git,.gitignore 里加上 .env 和 data/):
```
OPENAI_API_KEY=sk-你的key
MODERATION_MODEL=按官方文档当前可用的审核模型标识填写
DB_PATH=./data/review.db
UPLOAD_DIR=./data/uploads
MAX_IMAGE_SIDE=1536
```
MAX_IMAGE_SIDE 是降采样后的最长边,控制在千级像素既不影响判断,又能显著缩短上传耗时。
app/settings.py:
```python
import os
from pathlib import Path
from dotenv import load_dotenv
load_dotenv()
OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
MODERATION_MODEL = os.environ["MODERATION_MODEL"]
DB_PATH = Path(os.environ.get("DB_PATH", "./data/review.db"))
UPLOAD_DIR = Path(os.environ.get("UPLOAD_DIR", "./data/uploads"))
MAX_IMAGE_SIDE = int(os.environ.get("MAX_IMAGE_SIDE", "1536"))
UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
DB_PATH.parent.mkdir(parents=True, exist_ok=True)
```
这一步在做什么:把“会变的东西”(模型名、路径、尺寸)从代码里抽出来,后面调阈值、换模型都只改配置。成功的标志是 python -c "import sys; sys.path.insert(0,'app'); import settings; print(settings.MODERATION_MODEL)" 能打印出模型标识,且 data/ 两个目录已自动创建。
第 3 步:封装分类器调用
app/classifier.py:
```python
import base64
import io
from openai import OpenAI
from PIL import Image
import settings
client = OpenAI(api_key=settings.OPENAI_API_KEY, timeout=20.0, max_retries=2)
def _to_jpeg_data_url(path: str) -> str:
"""统一转成 JPEG、限制最长边,返回 data URL。"""
img = Image.open(path)
img = img.convert("RGB")
img.thumbnail((settings.MAX_IMAGE_SIDE, settings.MAX_IMAGE_SIDE))
buf = io.BytesIO()
img.save(buf, format="JPEG", quality=85)
b64 = base64.b64encode(buf.getvalue()).decode()
return f"data:image/jpeg;base64,{b64}"
def _dump(obj) -> dict:
"""兼容不同 SDK 版本的响应对象。"""
if hasattr(obj, "model_dump"):
return obj.model_dump()
return dict(obj)
def classify_image(path: str) -> dict:
data_url = _to_jpeg_data_url(path)
resp = client.moderations.create(
model=settings.MODERATION_MODEL,
input=[{"type": "image_url", "image_url": {"url": data_url}}],
)
result = resp.results[0]
categories = _dump(result.categories)
scores = _dump(result.category_scores)
return {
"flagged": bool(result.flagged),
"hit_categories": [k for k, v in categories.items() if v],
"scores": scores,
}
```
三个要点:先转码再上传,避免 iPhone 的 HEIC、超大 PNG 直接打过去被判非法图片;超时 + 重试交给 SDK,别自己写循环;只取 category_scores,因为后面分级靠的是连续分数,flagged 只是模型给的粗判,不能当唯一依据。
如果你的账号没有可用的审核类接口,也可以改成调用支持图像输入的视觉模型,让它按你定义的类别输出结构化 JSON(例如 {"sexual": 0.1, "violence": 0.7}),只要保证 classify_image 返回同样的 scores 结构,后续步骤完全不用改。
第 4 步:阈值分级策略
这是整条链路真正决定体验的地方。原则是:不同类别用不同阈值,儿童相关的最严,血腥暴力中等,擦边类放宽但必须进复核。
app/policy.py:
```python
DEFAULT_POLICY = {"block": 0.85, "review": 0.50}
CATEGORY_POLICY = {
"sexual/minors": {"block": 0.10, "review": 0.03},
"sexual": {"block": 0.70, "review": 0.35},
"violence/graphic": {"block": 0.75, "review": 0.40},
"hate": {"block": 0.70, "review": 0.35},
"self-harm": {"block": 0.60, "review": 0.30},
}
def decide(scores: dict) -> dict:
hits = []
for cat, score in scores.items():
p = CATEGORY_POLICY.get(cat, DEFAULT_POLICY)
if score >= p["block"]:
hits.append((cat, score, "block"))
elif score >= p["review"]:
hits.append((cat, score, "review"))
if not hits:
return {"decision": "pass", "top_category": None, "top_score": 0.0}
hits.sort(key=lambda x: (x[2] != "block", -x[1]))
cat, score, level = hits[0]
return {
"decision": "block" if level == "block" else "review",
"top_category": cat,
"top_score": round(float(score), 4),
}
```
三档含义:block = 不展示、不提示具体原因;review = 暂不展示,进人工队列;pass = 正常展示。阈值不要拍脑袋:拿 500~2000 张有人工标注的历史图片跑一遍,看 review 档里的误拦比例和 pass 档的抽样漏放比例,先把 review 区间放宽,宁可多复核也别漏放,等有数据了再收紧 block。
第 5 步:建表与状态机
app/db.py:
```python
import sqlite3
from contextlib import contextmanager
import settings
SCHEMA = """
CREATE TABLE IF NOT EXISTS review_task (
id TEXT PRIMARY KEY,
object_key TEXT NOT NULL,
user_id TEXT,
status TEXT NOT NULL,
top_category TEXT,
top_score REAL,
priority REAL DEFAULT 0,
scores_json TEXT,
flags_json TEXT,
reviewer TEXT,
review_note TEXT,
created_at TEXT,
updated_at TEXT
);
CREATE INDEX IF NOT EXISTS idx_task_status ON review_task(status, priority DESC);
CREATE TABLE IF NOT EXISTS appeal (
id TEXT PRIMARY KEY,
task_id TEXT NOT NULL,
user_id TEXT,
reason TEXT,
status TEXT NOT NULL,
created_at TEXT,
handled_at TEXT
);
"""
def init_db():
with connect() as conn:
conn.executescript(SCHEMA)
@contextmanager
def connect():
conn = sqlite3.connect(settings.DB_PATH, timeout=10)
conn.row_factory = sqlite3.Row
conn.execute("PRAGMA journal_mode=WAL")
try:
yield conn
conn.commit()
finally:
conn.close()
```
状态机一共六个值:auto_pass / auto_block / queued / manual_pass / manual_block / appealed。人工复核只允许改 queued 和 auto_block 的任务,其他状态改不动——这个约束写在 SQL 的 WHERE 里,比在 Python 里 if 判断可靠。
第 6 步:流水线主流程
app/pipeline.py:
```python
import json
import uuid
from datetime import datetime, timezone
import classifier
import db
import policy
def now() -> str:
return datetime.now(timezone.utc).isoformat(timespec="seconds")
def submit(path: str, user_id: str | None = None) -> dict:
task_id = uuid.uuid4().hex
result = classifier.classify_image(path)
verdict = policy.decide(result["scores"])
status = {"block": "auto_block", "review": "queued"}.get(
verdict["decision"], "auto_pass"
)
with db.connect() as conn:
conn.execute(
"""INSERT INTO review_task
(id, object_key, user_id, status, top_category, top_score,
priority, scores_json, flags_json, created_at, updated_at)
VALUES (?,?,?,?,?,?,?,?,?,?,?)""",
(
task_id, path, user_id, status,
verdict["top_category"], verdict["top_score"],
verdict["top_score"],
json.dumps(result["scores"]), json.dumps(result["hit_categories"]),
now(), now(),
),
)
return {"task_id": task_id, "status": status, **verdict}
```
注意 priority 直接用了 top_score,所以复核队列天然是“越像违规排越前”,审核员打开列表先看到风险最高的。
第 7 步:暴露接口
app/main.py:
```python
import shutil
import uuid
import uvicorn
from fastapi import FastAPI, File, Form, HTTPException, UploadFile
from pydantic import BaseModel
import db
import pipeline
import settings
app = FastAPI(title="image-review")
ALLOWED = {".jpg", ".jpeg", ".png", ".webp", ".gif"}
@app.on_event("startup")
def startup():
db.init_db() # 新版 FastAPI 推荐改用 lifespan,以官方文档为准
@app.post("/images")
async def upload(file: UploadFile = File(...), user_id: str | None = Form(None)):
suffix = "." + (file.filename or "x.jpg").rsplit(".", 1)[-1].lower()
if suffix not in ALLOWED:
raise HTTPException(400, "unsupported file type")
local = settings.UPLOAD_DIR / f"{uuid.uuid4().hex}{suffix}"
with local.open("wb") as f:
shutil.copyfileobj(file.file, f)
return pipeline.submit(str(local), user_id)
@app.get("/review/queue")
def review_queue(limit: int = 20):
with db.connect() as conn:
rows = conn.execute(
"""SELECT id, top_category, top_score, created_at
FROM review_task WHERE status='queued'
ORDER BY priority DESC, created_at ASC LIMIT ?""",
(limit,),
).fetchall()
return [dict(r) for r in rows]
class ReviewAction(BaseModel):
decision: str # pass | block
reviewer: str
note: str | None = None
@app.post("/review/{task_id}")
def review(task_id: str, body: ReviewAction):
if body.decision not in {"pass", "block"}:
raise HTTPException(400, "decision must be pass or block")
status = "manual_pass" if body.decision == "pass" else "manual_block"
with db.connect() as conn:
cur = conn.execute(
"""UPDATE review_task
SET status=?, reviewer=?, review_note=?, updated_at=?
WHERE id=? AND status IN ('queued','auto_block')""",
(status, body.reviewer, body.note, pipeline.now(), task_id),
)
if cur.rowcount == 0:
raise HTTPException(409, "task not found or already handled")
return {"task_id": task_id, "status": status}
class AppealIn(BaseModel):
task_id: str
user_id: str | None = None
reason: str
@app.post("/appeals")
def create_appeal(body: AppealIn):
with db.connect() as conn:
row = conn.execute("SELECT id FROM review_task WHERE id=?", (body.task_id,)).fetchone()
if row is None:
raise HTTPException(404, "task not found")
appeal_id = uuid.uuid4().hex
conn.execute(
"""INSERT INTO appeal (id, task_id, user_id, reason, status, created_at)
VALUES (?,?,?,?, 'open', ?)""",
(appeal_id, body.task_id, body.user_id, body.reason, pipeline.now()),
)
conn.execute(
"UPDATE review_task SET status='appealed', updated_at=? WHERE id=?",
(pipeline.now(), body.task_id),
)
return {"appeal_id": appeal_id, "status": "open"}
@app.post("/appeals/{appeal_id}/reopen")
def reopen_appeal(appeal_id: str, reviewer: str):
"""申诉通过初审:任务回到人工复核队列,由另一人复审。"""
with db.connect() as conn:
row = conn.execute("SELECT task_id FROM appeal WHERE id=?", (appeal_id,)).fetchone()
if row is None:
raise HTTPException(404, "appeal not found")
conn.execute(
"UPDATE appeal SET status='accepted', handled_at=? WHERE id=?",
(pipeline.now(), appeal_id),
)
conn.execute(
"UPDATE review_task SET status='queued', priority=1.0, reviewer=?, updated_at=? WHERE id=?",
(reviewer, pipeline.now(), row["task_id"]),
)
return {"appeal_id": appeal_id, "status": "accepted"}
if __name__ == "__main__":
uvicorn.run("main:app", host="0.0.0.0", port=8000, workers=1)
```
两个设计细节:priority=1.0 让申诉任务插到复核队列最前面,用户体验上“申诉有人管”比“排队 8 小时”重要得多;workers=1 是配合 SQLite 的,单进程写库不会打架,横向扩容时再换 PostgreSQL。
第 8 步:启动服务
```bash
cd image-review
source .venv/bin/activate
cd app && python main.py
```
看到 Uvicorn running on http://0.0.0.0:8000 和 Application startup complete 即为启动成功。浏览器打开 http://127.0.0.1:8000/docs 能看到自动生成的接口文档。
验证部署是否成功
准备两张图:一张正常照片 ok.jpg,一张明显违规的测试图 bad.jpg。
```bash
1. 上传正常图,预期 status 为 auto_pass
curl -s -F "file=@ok.jpg" -F "user_id=u_1001" http://127.0.0.1:8000/images
2. 上传违规图,预期 status 为 auto_block
curl -s -F "file=@bad.jpg" http://127.0.0.1:8000/images
3. 查复核队列,预期返回 JSON 数组(没有待审任务时为空数组)
curl -s "http://127.0.0.1:8000/review/queue?limit=5"
4. 落库检查,预期三种状态都有计数
sqlite3 data/review.db "SELECT status, COUNT(*) FROM review_task GROUP BY status;"
```
再完整走一遍人工链路:
```bash
TASK=<第 3 步返回的 task_id>
预期返回 {"task_id":"...","status":"manual_block"}
curl -s -X POST http://127.0.0.1:8000/review/$TASK \
-H 'Content-Type: application/json' \
-d '{"decision":"block","reviewer":"alice","note":"含违规元素"}'
预期返回 {"appeal_id":"...","status":"open"}
curl -s -X POST http://127.0.0.1:8000/appeals \
-H 'Content-Type: application/json' \
-d '{"task_id":"'"$TASK"'","user_id":"u_1001","reason":"图片为艺术摄影作品"}'
预期任务状态回到 queued
sqlite3 data/review.db "SELECT id,status,reviewer FROM review_task WHERE id='$TASK';"
```
判断标准:① 上传接口在 2 秒内返回且带 task_id;② scores_json 里出现了非零类别分;③ 重复 POST 同一个 task_id 的复核接口返回 409 而不是又改一次;④ 申诉后状态确实变成 queued 且 priority 为 1.0。
常见报错与解决
1. openai.BadRequestError: Invalid image / unsupported image format
原因:图片是 HEIC、CMYK 色彩空间的 JPEG、动图首帧异常,或体积远超接口限制。
解决:确认代码走了 _to_jpeg_data_url 的转码分支;对超大图再降一档尺寸后重试。
```bash
python -c "from PIL import Image; Image.open('bad.jpg').convert('RGB').save('fixed.jpg', 'JPEG', quality=85)"
curl -s -F "file=@fixed.jpg" http://127.0.0.1:8000/images
```
2. openai.AuthenticationError (401) 或 RateLimitError (429)
原因:Key 未加载(.env 不在工作目录、变量名拼错)或并发过高触发限流。
解决:先确认变量可见,再给上传接口加一层并发限制,或把同步调用改成后台任务。
```bash
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(bool(os.environ.get('OPENAI_API_KEY')))"
输出 True 才算配置生效
```
3. APITimeoutError / ReadTimeout
原因:单图过大导致上传慢,或出口网络抖动。
解决:把 MAX_IMAGE_SIDE 调到 1024 重试;确认服务器能直连接口域名,内网需配置 HTTPS_PROXY。
```bash
curl -s -o /dev/null -w "%{http_code} %{time_total}s\n" https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
```
4. sqlite3.OperationalError: database is locked
原因:开了多个 uvicorn worker,或多台机器挂同一个 SQLite 文件。
解决:开发和小流量阶段保持 workers=1;需要多实例时改用 PostgreSQL,把 db.py 里的 sqlite3.connect 换成对应驱动,SQL 语句基本不用动。
```bash
临时释放锁并确认 WAL 已开启
sqlite3 data/review.db "PRAGMA journal_mode; PRAGMA wal_checkpoint(TRUNCATE);"
```
5. 所有 category_scores 都是 0,但图片明显有问题
原因:模型标识填错、回落到了纯文本模型,或图片被降采样到细节丢失。
解决:打印实际传入的 MODERATION_MODEL;把 MAX_IMAGE_SIDE 提到 1536 以上;用官方文档给出的示例图对照测试。
```bash
python -c "import sys; sys.path.insert(0,'app'); import settings; print(settings.MODERATION_MODEL)"
```
后续维护
备份:review.db 是唯一不可再生的数据(图片本身可以从 data/uploads 重建,但决策记录不能)。每天做一次热备,别直接 cp 正在写的库:
```bash
mkdir -p backups
sqlite3 data/review.db ".backup 'backups/review-$(date +%F).db'"
find backups -name "review-*.db" -mtime +30 -delete
```
appeal 表建议单独再导一份 CSV 到别处,申诉记录涉及用户权益,保留周期通常比业务数据长。
升级:升级 SDK 或换模型时,先切一版影子流量——同一批图片同时走新旧两套分类逻辑,只记录不生效,比对 decision 的差异率。差异率超过 10% 就不要直接上线,先看是阈值问题还是类别体系变了。生产环境固定 requirements.txt 里的版本,升级走“改文件 → 重启 → 观察一天”的节奏。
日志:每条任务打一行结构化日志,至少包含 task_id、user_id、status、top_category、top_score、耗时。用 logging 输出 JSON,方便后续按类别统计拦截率。
监控:盯四个指标——复核队列积压数量(超过 200 就该加人)、平均复核时长、自动拦截率(某天突然翻倍说明阈值或流量有问题)、申诉反转率(人工复审后改判的比例)。申诉反转率持续高于 20%,基本可以判定 block 阈值偏低了。
阈值校准:每两周抽一次数据,把 auto_pass 里随机抽 1%~5% 做人工复查,估算漏放率;把 queued 里被人工判为 pass 的样本收集起来,它们就是下一版阈值的上调依据。阈值是随内容和用户群漂移的,别指望定一次管一年。
容量:图片上传目录按天分文件夹(uploads/2025-01-01/xxx.jpg),方便整目录归档到对象存储;单机磁盘到 70% 就该配置清理策略,只保留任务表里状态为 manual_block 和 appealed 的原始图片,其余按 30 天滚动删除。
