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.
3.3 KiB
图片处理与搜索向量迁移
本文说明现有图片如何进入逐图处理链，以及搜索从旧的全库 cache_generation 切换到
单图文本 embedding 的运维边界。迁移工具只接受服务端数据库和配置，不把全库图片 ID
放进任务 payload，也不把 provider secret 写入参数、日志或结果。
前置条件
- 使用项目的
uv环境，并连接可用的 PostgreSQL/pgvector 数据库。 - 目标
scope_id已存在，且维护者已确认该 scope 的图片根和 embedding 配置可用。 - 迁移前保留数据库备份；迁移不会删除旧 generation、旧向量或图片文件。
分页回填
先只创建逐图 job，适合检查规模和处理队列：
uv run python scripts/backfill_image_processing.py \
--scope-id local --page-size 100 --seed-only
默认模式会在分页 seed 的同时为可索引语境生成单图文本向量：
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、
模型、维度、语境状态和可访问的业务存储键。
确认所有图片都成功回填后，才使用显式切换：
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 数据库执行。