用 wxPython + 通义千问 VL 打造一款“批量人物图像识别“桌面应用

关键词：wxPython、通义千问 Qwen-VL、SQLite、PyInstaller、多线程、提示词工程

前言

我希望解决一个日常痛点：本地有几千张人物照片，想批量打上"性别 / 国籍 / 年龄 / 发型 / 衣着 / 化妆 / 动作 / 姿势 / 全身或半身"等结构化标签，方便日后筛选与检索。

借助阿里云百炼平台的 通义千问 Qwen-VL-Max 多模态大模型，再用 wxPython 写一个原生桌面 GUI，把识别结果落进本地 SQLite，配合多线程并发与配置持久化，就能做出一个"开箱即用"的本地化工具。

本文完整讲清楚这个项目的设计要点和踩坑过程，所有代码均可复用。

效果截图（功能区）：

• 顶部：选择文件夹批量识别、停止、重新识别选中、关键字搜索
• 中部：性别 / 国籍 / 年龄区间 / 构图 / 化妆 等多维筛选
• 配置：API Key、模型名、并发数、保存配置
• 主区：左侧带缩略图的多列结果表，右侧大图预览 + 详细字段 + 原始 JSON
  “C:\\Users\\86182\\Desktop\\qwenDetectImage\\code.py”
  

一、技术选型

二、目录结构与"双形态路径定位"

工具要满足一个隐性需求：直接运行 .py 和打包成 exe 之后，配置文件 / 数据库都必须落在程序同目录，不能因为打包了就跑到 C:\\Users\\xxx\\AppData\\… 之类的奇怪地方。

只用一个小函数搞定：

def get_app_dir():
"""无论是直接运行 .py 还是 PyInstaller 打包后的 .exe，都定位到可执行文件同目录。"""
if getattr(sys, "frozen", False):
return Path(sys.executable).resolve().parent
return Path(__file__).resolve().parent

def get_config_path():
return get_app_dir() / "config.json"

def get_db_path():
return get_app_dir() / "photo_analysis.db"

sys.frozen 是 PyInstaller 在运行期注入的属性，借此区分两种形态。配置和 DB 的路径全部从 get_app_dir() 派生，这样：

• 开发期：code.py 同级写读
• 发布期：xxx.exe 同级写读

用户只需把 exe + config.json + photo_analysis.db 整个目录拷走即可迁移。

三、SQLite 表结构与字段去重

所有识别结果落到一张 analyses 表：

CREATE TABLE IF NOT EXISTS analyses (
id INTEGER PRIMARY KEY AUTOINCREMENT,
path TEXT NOT NULL UNIQUE,
filename TEXT NOT NULL,
analyzed_at TEXT NOT NULL,
width INTEGER, height INTEGER,
nationality TEXT, gender TEXT, hairstyle TEXT,
frame_type TEXT, makeup TEXT, clothing TEXT,
estimated_age TEXT, action TEXT, posture TEXT,
top_labels TEXT, notes TEXT, raw_result TEXT
)

两个细节：

写入用 upsert：

con.execute("""
INSERT INTO analyses (path, filename, analyzed_at, …) VALUES (?, ?, ?, …)
ON CONFLICT(path) DO UPDATE SET
analyzed_at=excluded.analyzed_at,
nationality=excluded.nationality,
…
""", (...))

自动迁移老表

迭代过程中字段调整过几次。为了避免老用户每次都手动删 DB，启动时做一次结构校验：

REQUIRED_COLUMNS = {"path", "filename", "analyzed_at", ...}

cols = {row[1] for row in con.execute("PRAGMA table_info(analyses)").fetchall()}
if not REQUIRED_COLUMNS.issubset(cols):
con.execute("DROP TABLE analyses")

简单粗暴但够用——结构变了就重建。

四、调用 Qwen-VL：OpenAI 兼容接口 + base64

阿里云百炼提供了 OpenAI 兼容的 endpoint，因此可以直接复用 openai SDK，只换 base_url：

def image_to_data_url(image_path):
path = Path(image_path)
mime_type = {
".jpg": "image/jpeg", ".jpeg": "image/jpeg",
".png": "image/png", ".webp": "image/webp", ".bmp": "image/bmp",
}.get(path.suffix.lower(), "image/jpeg")
data = base64.b64encode(path.read_bytes()).decode("utf-8")
return f"data:{mime_type};base64,{data}"

def call_qwen_api(api_key, model, image_path, system_prompt, prompt_template):
from openai import OpenAI
client = OpenAI(
api_key=api_key,
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
response = client.chat.completions.create(
model=model,
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": [
{"type": "image_url", "image_url": {"url": image_to_data_url(image_path)}},
{"type": "text", "text": prompt_template},
]},
],
temperature=0.1,
)
raw = response.choices[0].message.content
result = extract_json_from_text(raw)
if not result:
raise ValueError(f"模型返回内容不是可解析 JSON：\\n{raw}")
return sanitize_result(result)

要点：

• 图片 base64 内嵌为 data URL，无需上传到 OSS。
• temperature=0.1：识别任务追求稳定。
• 返回内容需要从可能带 Markdown 围栏的文本里抠 JSON，单独写了 extract_json_from_text。

extract_json_from_text：三段式兜底解析

def extract_json_from_text(text):
candidates = [text.strip()]
fenced = re.search(r"```(?:json)?\\s*(.*?)\\s*```", text, re.DOTALL | re.IGNORECASE)
if fenced: candidates.append(fenced.group(1).strip())
obj = re.search(r"\\{.*\\}", text, re.DOTALL)
if obj: candidates.append(obj.group(0).strip())
for c in candidates:
try:
v = json.loads(c)
if isinstance(v, dict): return v
except json.JSONDecodeError:
continue
return None

依次尝试：原文 → json围栏内容 → 第一个 {…} 块。能兼容 99% 的"模型不那么听话"的情况。

五、提示词工程：踩过的最大的坑

这是项目里最折腾的部分，值得单独讲。

翻车现场：所有图片返回完全相同的结果

第一版 prompt 我把字段说明写在 JSON 模板的"值"位置：

{
"nationality": "判断的国籍或地域，例如：中国、日本、韩国…",
"gender": "男 或 女",
…
}

结果：模型把字段说明文字原封不动当作值返回。

第二版我加了"具体示例"，比如：

{"nationality":"中国","gender":"女","hairstyle":"黑色长直发",…}

结果更糟：三张完全不同的图片返回了完全相同的 JSON——模型直接把示例值当成"标准答案"了。

解决方案：System Prompt 描述结构 + User Prompt 极简触发

这是参考了一个能正常工作的版本后顿悟的：

DEFAULT_SYSTEM_PROMPT = """你是一个专业的人物图像特征分析专家。请仔细观察提供的照片，并提取人物的特征。
如果某个特征无法从照片中确认，请将其值设置为"未知"。如果照片中没有人物，请在 additional_notes 中说明。
请严格遵循以下 JSON 结构，不要输出任何 Markdown 标记…：
{
"nationality": "人物国籍或种族特征（如：中国、日本、韩国、欧美、东南亚、非洲，或未知）",
"gender": "性别（男、女、未知）",
"hairstyle": "发型描述（如：黑色长直发、棕色短卷发、马尾辫、寸头、未知）",
…
}"""

DEFAULT_PROMPT_TEMPLATE = "请分析这张照片中的人物，并输出 JSON 结果。"

关键变化：

• 结构定义放进 system prompt——它对模型而言是"规则"，不是"用户问题"。
• user prompt 退化为一句简单触发语——模型不会把它当作"用户已经给出的样例答案"。
• 字段说明用括号备注，不要写"具体如…“或"举例如…”，避免模型抄说明。

防御层：sanitize_result 兜底

即便 prompt 调好，模型偶尔仍会泄漏说明文字。再加一层结果清洗：

LEAK_KEYWORDS = (
"字段含义", "候选词", "判断该人物的国籍",
"可搜索的中文标签", "0~1 的小数", "必须是整数", "字符串。",
)

def _clean_value(value, allowed=None):
text = str(value or "").strip()
if not text: return "未知"
if any(kw in text for kw in LEAK_KEYWORDS): return "未知"
if allowed is not None and text not in allowed:
for option in allowed:
if option != "未知" and option in text:
return option
return "未知"
return text

def sanitize_result(result):
cleaned = dict(result)
cleaned["gender"] = _clean_value(result.get("gender"), {"男", "女", "未知"})
cleaned["frame_type"] = _clean_value(result.get("frame_type"), {"全身", "半身", "特写", "未知"})
cleaned["makeup"] = _clean_value(result.get("makeup"), {"已化妆", "未化妆", "未知"})
...
return cleaned

枚举字段做受控匹配（gender ∈ {男,女,未知}），文本字段做关键字泄漏检测，识别"中招"立刻置为未知。

Prompt 版本号

prompt 已经迭代了 5 版。为了让用户保留的旧 config.json 自动升级，我加了 PROMPT_VERSION：

PROMPT_VERSION = 5

# load_config 里：
if int(data.get("prompt_version", 0)) < PROMPT_VERSION:
config["system_prompt"] = DEFAULT_SYSTEM_PROMPT
config["prompt_template"] = DEFAULT_PROMPT_TEMPLATE
config["prompt_version"] = PROMPT_VERSION

只要本地版本号低，就强制覆盖 prompt——避免老用户用着老 prompt 出错却完全摸不到头脑。

六、并发识别：跳过已识别 + ThreadPoolExecutor

批量识别如果串行调用，几百张照片要等几十分钟。但是直接 for img in images: call_api(img) 会浪费等待时间，因为单次 API RTT 通常 5–15 秒。

跳过已识别

def fetch_analyzed_paths(db_path):
with closing(sqlite3.connect(db_path)) as con:
rows = con.execute("SELECT path FROM analyses").fetchall()
return {row[0] for row in rows}

worker 里先做差集，节约 token：

images = find_image_files(self.current_folder)
done_paths = fetch_analyzed_paths(self.db_path)
pending = [p for p in images if str(p) not in done_paths]

多线程 + 增量回写 UI

API 调用是 I/O 等待，GIL 不构成瓶颈，用线程池足矣：

with ThreadPoolExecutor(max_workers=max_workers) as pool:
futures = {
pool.submit(self._process_one, img, api_key, model, sysp, userp): img
for img in pending
}
for future in as_completed(futures):
record = future.result()
wx.CallAfter(self._on_record_ready, record, done, len(pending))

并发数由界面 wx.SpinCtrl 配置（1–16，默认 4）。

SQLite 写入加锁

SQLite 默认每个连接只能在一个线程使用，并发写还容易触发 database is locked。封装一把互斥锁：

self._db_lock = threading.Lock()

def _process_one(self, image_path, api_key, model, sysp, userp):
width, height = get_image_size(image_path)
result = call_qwen_api(api_key, model, image_path, sysp, userp)
with self._db_lock:
upsert_analysis(self.db_path, image_path, result, width, height)
record = fetch_analysis_by_path(self.db_path, image_path)
return record

API 调用并行，DB 写入串行，简单可靠。

边识别边显示

每一张完成都通过 wx.CallAfter 回到主线程，把单条记录追加进 wx.ListCtrl：

def _on_record_ready(self, record, done, total):
path = record.get("path")
existing = self._path_to_row.get(path)
if existing is not None:
self.all_records[existing] = record
else:
self.all_records.append(record)
self._path_to_row[path] = len(self.all_records) – 1
if record_matches_filters(record, self._collect_filters()):
idx = next((i for i,r in enumerate(self.visible_records)
if r.get("path") == path), –1)
if idx >= 0:
self._update_list_row(idx, record)
else:
self._append_record_to_list(record)
self.SetStatusText(f"已识别 {done}/{total}：{Path(path).name}")

_path_to_row 这个 dict 用来 O(1) 判定路径是否已展示过——避免"重新识别选中"的图片在 UI 上重复出现。

七、UI 细节：缩略图列 + WebP 兼容

wx.ListCtrl 用缩略图

self.thumb_images = wx.ImageList(120, 120)
self.list = wx.ListCtrl(panel, style=wx.LC_REPORT | wx.BORDER_SUNKEN)
self.list.SetImageList(self.thumb_images, wx.IMAGE_LIST_SMALL)

for index, (name, width) in enumerate([
("缩略图", 130), ("文件名", 220), ("国籍", 90), ("性别", 60),
("年龄", 60), ("构图", 80), ("发型", 140), ("化妆", 90),
("衣着", 200), ("动作", 140), ("姿势", 140), ("尺寸", 90),
]):
self.list.InsertColumn(index, name, width=width)

每行的第 0 列绑定一个 wx.ImageList 索引，列表自然就显示出缩略图。

WebP 加载兜底

wx.Image 默认不支持 webp。直接 wx.Image("xxx.webp") 在 Windows 下会弹错误对话框。处理思路：先用 wx 试，失败再用 Pillow，最后转回 wx.Image。

def load_wx_image(image_path):
no_log = wx.LogNull() # 抑制弹错框
try:
image = wx.Image(str(image_path), wx.BITMAP_TYPE_ANY)
except Exception:
image = None
del no_log
if image is not None and image.IsOk() and image.GetWidth() > 0:
return image
try:
from PIL import Image
with Image.open(str(image_path)) as pil_image:
pil_image = pil_image.convert("RGB")
wx_image = wx.Image(pil_image.width, pil_image.height)
wx_image.SetData(pil_image.tobytes())
return wx_image
except Exception:
return None

wx.LogNull() 是 wx 的一个 RAII 风格的日志静默器，构造期间所有 wx 错误日志都不弹窗。

八、配置持久化：每次都保存

为了"操作简单"，几乎所有可设置的字段都自动保存：

def _collect_config(self):
self.config.update({
"api_key": self.txt_api_key.GetValue().strip(),
"model": self.txt_model.GetValue().strip() or "qwen-vl-max",
"max_workers": int(self.spin_workers.GetValue()),
"last_dir": self.current_folder,
"window_size": list(self.GetSize()),
"window_pos": list(self.GetPosition()),
"system_prompt": self.config.get("system_prompt", DEFAULT_SYSTEM_PROMPT),
"prompt_template":self.config.get("prompt_template", DEFAULT_PROMPT_TEMPLATE),
"prompt_version": PROMPT_VERSION,
"filters": self._collect_filters(),
})
return self.config

触发时机：

• 切换文件夹 / 应用筛选 / 关闭窗口 / 显式点"保存配置"

加载时合并默认值，避免新增字段时老配置文件缺 key 报错：

filters = DEFAULT_CONFIG["filters"].copy()
filters.update(data.get("filters", {}) or {})
config.update(data)
config["filters"] = filters

九、常见踩坑回顾

十、PyInstaller 打包

pip install pyinstaller pillow openai wxpython
pyinstaller –onefile –windowed –name qwenDetectImage code.py

参数解释：

• –onefile：单文件 exe
• –windowed：不弹黑色控制台
• –name：自定义生成名

生成的 dist/qwenDetectImage.exe 直接拷到任意目录，跟 config.json 和 photo_analysis.db 放一起就能用。get_app_dir() 会自动定位到 exe 所在目录。

十一、可改进方向

• 识别失败重试：现在失败就跳过，可加入指数退避重试。
• 批量重识别：多选一组列表项 → 清空 DB 行 → 走识别流程；当前已有"重新识别选中"按钮。
• 导出 Excel/CSV：方便给非技术同事用。
• 本地小模型蒸馏：高频字段（性别、构图）可以用 ResNet 之类做本地预过滤，云调用只跑细字段。
• 图片去重哈希：用 phash 防止两张视觉相同但路径不同的图被重复调用。

十二、完整代码结构速览

qwenDetectImage/
├─ code.py # 单文件实现，约 900 行
├─ config.json # 自动生成的用户配置
├─ photo_analysis.db # SQLite 库
└─ dist/qwenDetectImage.exe # PyInstaller 输出

模块拓扑：

[wx.Frame: IndexerFrame]
├─ load_config / save_config (JSON)
├─ init_database / upsert_analysis (SQLite)
├─ ThreadPoolExecutor (并发)
│ └─ call_qwen_api (OpenAI 兼容)
│ ├─ image_to_data_url
│ ├─ extract_json_from_text
│ └─ sanitize_result
└─ wx.ListCtrl + wx.ImageList (缩略图列表)

结语

这个工具最初只是"想给本地照片打标"，最终变成了一次很好的提示词工程实践——你会反复看到大模型把示例当作答案、把字段说明当作值。Prompt 的位置（system vs user）、措辞（描述 vs 命令）、是否含示例值，都会显著改变模型行为。再加上一层结果清洗（sanitize_result），能把鲁棒性提升一大截。

如果你也在做"大模型 + 本地数据"的桌面/工具型应用，希望本文中关于 路径定位、配置自治、SQLite 兜底迁移、wx + 多线程增量渲染、prompt 防泄漏 的经验对你有用。

完整代码已开源（如读者需要可在评论区索取仓库链接），欢迎 fork 与改造。

作者一句话：
模型不会读心，它只会读你写下的字。Prompt 写不好，再贵的模型也救不了你。