跳到主内容
快讯直播
AI智模界
教程

用图像分类器搭一条可上线的审核流水线

适用场景

你有一个用户会自行上传图片的产品(头像、二手交易图、评论配图、社区发帖),需要在图片进到前台展示之前,判断它是否包含违规内容,并对边界样本安排人工复核、对用户申诉留痕。这套方案把“调用分类器 → 按分数分级 → 自动放行/自动拦截/进入人工队列 → 申诉回查”串成一条可落地的服务,适合 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 天滚动删除。

AI 生成本文由 AI 基于公开信息自动生成,仅供参考。