mirror of
https://github.com/MemeMeow-Studio/MemeMeow.git
synced 2026-10-17 04:41:01 +08:00
infstellar
5ecda39843
- Implement tests for the ImageProcessingWorker to validate task deduplication and policy interactions. - Create tests for operation policy to ensure proper grant handling and error responses. - Add tests for reverse image provider response structure to validate empty and malformed results. - Develop comprehensive tests for scope resolution and service validation to ensure correct behavior in various scenarios.
66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
# 图片处理与搜索向量迁移
|
|
|
|
本文说明现有图片如何进入逐图处理链，以及搜索从旧的全库 `cache_generation` 切换到
|
|
单图文本 embedding 的运维边界。迁移工具只接受服务端数据库和配置，不把全库图片 ID
|
|
放进任务 payload，也不把 provider secret 写入参数、日志或结果。
|
|
|
|
## 前置条件
|
|
|
|
- 使用项目的 `uv` 环境，并连接可用的 PostgreSQL/pgvector 数据库。
|
|
- 目标 `scope_id` 已存在，且维护者已确认该 scope 的图片根和 embedding 配置可用。
|
|
- 迁移前保留数据库备份；迁移不会删除旧 generation、旧向量或图片文件。
|
|
|
|
## 分页回填
|
|
|
|
先只创建逐图 job，适合检查规模和处理队列：
|
|
|
|
```bash
|
|
uv run python scripts/backfill_image_processing.py \
|
|
--scope-id local --page-size 100 --seed-only
|
|
```
|
|
|
|
默认模式会在分页 seed 的同时为可索引语境生成单图文本向量：
|
|
|
|
```bash
|
|
uv run python scripts/backfill_image_processing.py \
|
|
--scope-id local --page-size 100
|
|
```
|
|
|
|
脚本按 `(storage_key, meme_id)` keyset 分页，每页处理后持久化进度；重复执行会复用同一
|
|
图片版本的 job 和向量，不需要也不允许构造包含全库 ID 的单个任务。当前 scope 中有存储
|
|
操作处于 `prepared` 或 `file_applied` 的图片会暂时跳过，避免把未完成的文件副作用当作
|
|
迁移事实。
|
|
|
|
## 搜索来源切换
|
|
|
|
迁移开始时服务端创建新的 `SearchMigrationState` epoch，并冻结可验证的旧 generation
|
|
引用。回填期间一次查询只使用旧 generation 的逐条校验结果；不会把旧 generation 和
|
|
新单图向量混在同一次查询中。每条旧记录都必须匹配当前 scope、图片 SHA、metadata hash、
|
|
模型、维度、语境状态和可访问的业务存储键。
|
|
|
|
确认所有图片都成功回填后，才使用显式切换：
|
|
|
|
```bash
|
|
uv run python scripts/backfill_image_processing.py \
|
|
--scope-id local --page-size 100 --switch
|
|
```
|
|
|
|
只有本次运行没有失败、处理数量完整且不是 `--seed-only` 时才会切换到
|
|
`incremental_only`。失败或数量不完整不会切换来源；修复配置或图片后重新执行即可。
|
|
切换后日常搜索只读取当前 scope 中与图片 SHA、metadata hash 和 embedding 模型匹配的
|
|
单图向量，旧 generation 仍保留供审计或受控回滚检查。
|
|
|
|
## 失败、未知执行与回滚
|
|
|
|
图片处理阶段的外部执行结果无法确认时以 `unknown_execution` 收束，不会因为迁移重启而
|
|
自动重放 Agent 或 provider 调用。通过处理任务页面或受控 API 显式重试会创建新的 job
|
|
revision 和必要的叶子 Task；旧任务、attempt 和 operation 事实保留。
|
|
|
|
回滚时先停止新 job 的认领和迁移命令，保留新表、向量、job 和迁移 epoch。只有在确认旧
|
|
generation 仍与当前图片和语境逐条匹配后，才允许由部署方执行受控回滚；不要手工删除表、
|
|
清空迁移状态或把旧 generation 重新标记为当前来源。没有可验证旧来源时，应保持搜索未就绪，
|
|
而不是返回可能过期的结果。
|
|
|
|
当前环境未提供可用 PostgreSQL/Docker，因此本地验收覆盖了脚本参数、分页逻辑和契约测试，
|
|
真实数据库建表、双 scope 外键以及生产量级回填仍需在 staging 数据库执行。
|