feat: 片段重复率控制（受控复用+15%双闸门+批量plan独立）与素材余量四字段 #1549

Merged

xiaoxia merged 6 commits from feat/segment-duplication-control into develop 2026-08-30 07:36:33 +08:00

Conversation 5 Commits 6 Files Changed 17

+1966 -255

xiaoxia commented 2026-08-30 02:11:02 +08:00

Owner

Copy Link

Copy Source

背景

目标：任意两条成片画面重复率 ≤15%。此前自动轮回机制会清空历史区间并无限复用，且 MediaKit 智能选片不避让历史区间、批量生成多条视频共用同一 plan/clips，导致成片间画面重复。

Task G：片段重复率控制

1. MediaKit 智能选片避让历史区间

• 历史已用区间并入 _recommended_time_conflicts 冲突检查，边缘间隙 SEGMENT_EDGE_GAP=0.3s（与随机选片同口径）
• 撞历史区间时放弃推荐、保留原起点（不再把片段挪到已用画面上）

2. 自动轮回 → 受控复用

• 历史区间永不自动清空（reset 仅保留运维入口）
• metadata schema 升级：used_time_ranges: [{start, end, plan_id, created_at, use_count=1, last_used_at}]
• 100 次随机选点失败后，复用 last_used_at 最老且 use_count < MAX_RANGE_USE_COUNT(=3) 的区间；复用判定在 record_used_segments 内部（重叠率 ≥60% 累加 use_count）
• 15% 双闸门：
  • 分配闸门：为下一片段选素材时，若该素材在本成片中 reused/assigned > REUSE_RATIO_LIMIT(0.15) 则停止分配该素材
  • 回调内预判：复用发生在 calc 内部回调中，回调按 (reused+clip)/(assigned+clip) > limit 预判拒绝（返回 None），拦住「导致超限的那次复用」
• 复用回调返回 None 时 _calc_random_start_time 直接返回 None（删除末尾/0.0 重叠降级，避免放回已用画面）；无回调旧路径保留末尾降级（向后兼容）
• from-assets 轮询：calc 移进轮询循环，返回 None 时切换下一素材；全部素材超限 → 400「素材可切区间不足，请补充新素材」

3. 批量 N 条视频片段独立（合并 Issue #1282）

• count>1 时第 2 条起 clone_plan_for_variant 克隆独立 plan（新 plan_id、独立 clips、独立随机起点），禁止共用 source_edit_plan_id/clips
• 预览 enqueue 前同样克隆独立变体 plan；克隆失败降级退回源 plan（warning 不阻断）

Task H：素材余量透出与已用尽素材排除

• AssetResponse 新增四字段：used_duration / available_duration / used_ratio（float|None）、usable（bool，默认 True）
• 语义：
  • used_duration = 历史区间合并后总时长（秒，封顶 total）
  • available_duration = total - used_duration
  • used_ratio = used_duration / total（0~1）
  • usable=false：扩边（0.3s）后无 ≥3s 空闲段（零重复可切区间耗尽）且所有历史区间 use_count 均达上限 3
• 非视频/无时长/计算异常 → 三个字段 None + usable=True，对前端零影响（字段缺失按可用处理）
• GET /assets 列表与 GET /assets/{id} 详情统一经 _to_asset_response 一处注入
• POST /assets/smart-match 结果层过滤 usable=false 素材（评分逻辑不动）
• from-assets 对已用尽素材天然兜底：find_reusable_range 返 None → calc 返 None → 轮询跳过 → 全失败 400（防并发）

配置常量（tracker 模块）

常量	值	含义
REUSE_RATIO_LIMIT	0.15	单条成片复用画面占比上限
SEGMENT_EDGE_GAP	0.3s	历史区间边缘避让间隙
MAX_RANGE_USE_COUNT	3	单区间最多复用次数（第 4 次拒绝）
_MIN_FREE_CLIP_DURATION	3.0s	判定可用的最小空闲段

测试

• 新增：test_mediakit_conflicts.py（10，撞历史不挪点/冲突检测）、test_clone_plan_variant.py（7，批量3条plan独立区间互不相同）、test_asset_availability.py（23，余量四字段/smart-match过滤）
• 更新：tracker 21 用例（含第4次复用拒绝）、clips 路由（零时长跳过/混合池/15%闸门/None轮询）、mediakit 旧断言适配扩边语义
• 全量 unit：13910 passed, 8 skipped, 0 failed

前端配合（另 PR）

素材库卡片余量角标：红「已用尽」/ 红「即将用尽」(used_ratio≥0.85) / 橙「已用 xx%」(≥0.5)；Step2 过滤 usable=false；字段缺失按可用处理。

Closes #1282

## 背景 目标：任意两条成片画面重复率 ≤15%。此前自动轮回机制会清空历史区间并无限复用，且 MediaKit 智能选片不避让历史区间、批量生成多条视频共用同一 plan/clips，导致成片间画面重复。 ## Task G：片段重复率控制 ### 1. MediaKit 智能选片避让历史区间 - 历史已用区间并入 `_recommended_time_conflicts` 冲突检查，边缘间隙 `SEGMENT_EDGE_GAP=0.3s`（与随机选片同口径） - 撞历史区间时**放弃推荐、保留原起点**（不再把片段挪到已用画面上） ### 2. 自动轮回 → 受控复用 - 历史区间**永不自动清空**（reset 仅保留运维入口） - metadata schema 升级：`used_time_ranges: [{start, end, plan_id, created_at, use_count=1, last_used_at}]` - 100 次随机选点失败后，复用 `last_used_at` 最老且 `use_count < MAX_RANGE_USE_COUNT(=3)` 的区间；复用判定在 record_used_segments 内部（重叠率 ≥60% 累加 use_count） - **15% 双闸门**： - 分配闸门：为下一片段选素材时，若该素材在本成片中 `reused/assigned > REUSE_RATIO_LIMIT(0.15)` 则停止分配该素材 - 回调内预判：复用发生在 calc 内部回调中，回调按 `(reused+clip)/(assigned+clip) > limit` 预判拒绝（返回 None），拦住「导致超限的那次复用」 - 复用回调返回 None 时 `_calc_random_start_time` 直接返回 None（删除末尾/0.0 重叠降级，避免放回已用画面）；无回调旧路径保留末尾降级（向后兼容） - from-assets 轮询：calc 移进轮询循环，返回 None 时切换下一素材；全部素材超限 → **400「素材可切区间不足，请补充新素材」** ### 3. 批量 N 条视频片段独立（合并 Issue #1282） - `count>1` 时第 2 条起 `clone_plan_for_variant` 克隆独立 plan（新 plan_id、独立 clips、独立随机起点），禁止共用 source_edit_plan_id/clips - 预览 enqueue 前同样克隆独立变体 plan；克隆失败降级退回源 plan（warning 不阻断） ## Task H：素材余量透出与已用尽素材排除 - `AssetResponse` 新增四字段：`used_duration` / `available_duration` / `used_ratio`（float|None）、`usable`（bool，默认 True） - 语义： - `used_duration` = 历史区间合并后总时长（秒，封顶 total） - `available_duration` = total - used_duration - `used_ratio` = used_duration / total（0~1） - `usable=false`：扩边（0.3s）后无 ≥3s 空闲段（零重复可切区间耗尽）**且**所有历史区间 use_count 均达上限 3 - 非视频/无时长/计算异常 → 三个字段 None + usable=True，**对前端零影响**（字段缺失按可用处理） - `GET /assets` 列表与 `GET /assets/{id}` 详情统一经 `_to_asset_response` 一处注入 - `POST /assets/smart-match` 结果层过滤 usable=false 素材（评分逻辑不动） - from-assets 对已用尽素材天然兜底：find_reusable_range 返 None → calc 返 None → 轮询跳过 → 全失败 400（防并发） ## 配置常量（tracker 模块） | 常量 | 值 | 含义 | |---|---|---| | REUSE_RATIO_LIMIT | 0.15 | 单条成片复用画面占比上限 | | SEGMENT_EDGE_GAP | 0.3s | 历史区间边缘避让间隙 | | MAX_RANGE_USE_COUNT | 3 | 单区间最多复用次数（第 4 次拒绝） | | _MIN_FREE_CLIP_DURATION | 3.0s | 判定可用的最小空闲段 | ## 测试 - 新增：test_mediakit_conflicts.py（10，撞历史不挪点/冲突检测）、test_clone_plan_variant.py（7，批量3条plan独立区间互不相同）、test_asset_availability.py（23，余量四字段/smart-match过滤） - 更新：tracker 21 用例（含第4次复用拒绝）、clips 路由（零时长跳过/混合池/15%闸门/None轮询）、mediakit 旧断言适配扩边语义 - **全量 unit：13910 passed, 8 skipped, 0 failed** ## 前端配合（另 PR） 素材库卡片余量角标：红「已用尽」/ 红「即将用尽」(used_ratio≥0.85) / 橙「已用 xx%」(≥0.5)；Step2 过滤 usable=false；字段缺失按可用处理。 Closes #1282

xiaoxia added 1 commit 2026-08-30 02:11:02 +08:00

feat(segments): 片段重复率控制（受控复用+15%闸门）与素材余量四字段 ... e33502956c

Task G：任意两条成片画面重复率 ≤15%
- MediaKit 智能选片避让历史区间：历史区间并入冲突检查、0.3s 边缘间隙、
  撞历史时放弃推荐保留原起点（不再挪到已用画面）
- 自动轮回改造为受控复用：历史永不自动清空；used_time_ranges 增加
  use_count/last_used_at；100 次随机失败后复用 last_used_at 最老且
  use_count<3 的区间；单条成片复用占比 >15% 时该素材停止分配（分配闸门 +
  复用回调内预判双闸门）；全部素材超限返回 400「素材可切区间不足，请补充新素材」
- 复用回调返回 None 时 calc 直接返回 None（删除末尾/0.0 重叠降级），
  from-assets 轮询内 calc 失败切换下一素材
- 批量 N 条视频片段独立：count>1 时克隆独立 plan，禁止共用
  source_edit_plan_id/clips（合并 Issue #1282）；预览同样克隆独立变体
- 常量：REUSE_RATIO_LIMIT=0.15 / SEGMENT_EDGE_GAP=0.3 / MAX_RANGE_USE_COUNT=3

Task H：素材余量透出与已用尽素材排除
- GET /assets 列表与详情响应附加 used_duration/available_duration/
  used_ratio/usable 四字段（非视频/无时长/异常时 None + usable=True，零影响）
- usable=false：零重复可切区间已耗尽（扩边后无 ≥3s 空闲段）且所有历史
  区间 use_count 均达上限
- smart-match 结果层过滤 usable=false 素材（评分逻辑不动）
- from-assets 对已用尽素材天然兜底：calc 返回 None → 轮询跳过 →
  全部素材用尽时 400

测试：新增 test_mediakit_conflicts(10)/test_clone_plan_variant(7)/
test_asset_availability(23)，更新 tracker/clips/mediakit 既有用例；
全量 unit 13910 passed

gitea-actions bot commented 2026-08-30 02:14:36 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1549
预览链接	https://pr-1549.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1549 | | 预览链接 | [https://pr-1549.preview.xiaoxiajianji.com](https://pr-1549.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot added 1 commit 2026-08-30 02:16:27 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 7cb36a5c3d

xiaoxia added 1 commit 2026-08-30 02:33:21 +08:00

fix(segments): AI Review 阻塞项修复 — 记录写入行级锁 + 克隆失败不降级共用 ... b2a334f99b

- record_used_segments 读取 AssetModel 加 with_for_update() 行级锁，
  序列化并发事务对 classification_result 的读-改-写，杜绝区间记录丢失更新
  （SQLite 下 with_for_update 为 no-op）
- 批量生成：变体 plan 克隆前置到任务创建之前，全部成功才建任务（无脏数据）；
  克隆含 1 次重试抗 DB 抖动，仍失败则 500 中断，不再静默退回共用源 plan
- 预览生成：克隆失败标记任务 failed 并返回 500，不再退回原 plan
  （两条修复共同保证批量/多预览视频内容不重复的业务约束）
- 测试：FakeSession 支持 with_for_update；预览相关测试 mock EditPlanService
  或显式置空 source_edit_plan_id；zip 加 strict（B905）

auto-approve-bot added 1 commit 2026-08-30 02:38:44 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] b2d4589949

auto-approve-bot commented 2026-08-30 02:42:34 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：否
• 阻塞级问题数量：0 个

📊 审查概览

• 整体评价：通过
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

无

💡 改进建议（不阻塞合并）

1. [apps/api/app/api/routes/assets.py: 591-603] 潜在的 N+1 查询性能风险

   • 具体内容：在 smart_match_assets 函数中，代码遍历 results 列表并对每个元素调用 compute_asset_availability(r.asset)。如果 compute_asset_availability 内部涉及数据库查询（例如查询该素材的历史使用片段），且 results 列表较长，这将导致 N+1 查询问题，显著降低接口响应速度。
   • 修改建议：建议检查 compute_asset_availability 的实现。如果涉及 DB 查询，考虑在循环外批量获取所有相关素材的元数据或使用信息，然后批量计算，或者限制单次返回的 results 数量。

2. [apps/api/app/api/routes/templates_editor/clips.py: 866] 浮点数精度风险

   • 具体内容：代码使用 set(other_segments) | set(historical_segments.get(asset_id, [])) 对时间段进行去重。时间段由浮点数元组 (float, float) 组成。由于浮点数精度问题（如 0.1 + 0.2 != 0.3），数学上相等的时间点可能被视为不同，导致去重失败或冲突检测不准确。
   • 修改建议：虽然代码中多处使用了 round(..., 1)，降低了风险，但在处理集合操作时，建议将时间转换为整数（如毫秒）或确定精度的字符串后再进行集合操作，以确保去重的准确性。

✅ 良好实践

1. [apps/api/app/api/routes/generation_tasks.py] 采用“预克隆”策略处理批量生成任务。在创建任务之前先完成所有 Plan 的克隆，确保了操作的原子性，避免了部分任务创建成功导致的数据不一致或脏数据问题。
2. [apps/api/app/api/routes/templates_editor/clips.py] 引入受控复用机制（make_reuse_callback）和复用比率限制（REUSE_RATIO_LIMIT），有效防止了素材过度复用导致的视频内容重复问题，逻辑设计较为严谨。
3. [apps/api/app/api/routes/assets.py] 在 _asset_availability_fields 中增加了异常捕获和降级处理，当计算失败时默认返回 usable=True，保证了素材列表接口的可用性不被下游计算错误阻断，且保留了日志记录便于排查。

---

✅ 格式检查通过 | ✅ 逻辑审查通过 | ⚠️ 建议关注性能

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-29 18:42:33 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：通过 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 1. **[apps/api/app/api/routes/assets.py: 591-603] 潜在的 N+1 查询性能风险** - 具体内容：在 `smart_match_assets` 函数中，代码遍历 `results` 列表并对每个元素调用 `compute_asset_availability(r.asset)`。如果 `compute_asset_availability` 内部涉及数据库查询（例如查询该素材的历史使用片段），且 `results` 列表较长，这将导致 N+1 查询问题，显著降低接口响应速度。 - 修改建议：建议检查 `compute_asset_availability` 的实现。如果涉及 DB 查询，考虑在循环外批量获取所有相关素材的元数据或使用信息，然后批量计算，或者限制单次返回的 `results` 数量。 2. **[apps/api/app/api/routes/templates_editor/clips.py: 866] 浮点数精度风险** - 具体内容：代码使用 `set(other_segments) | set(historical_segments.get(asset_id, []))` 对时间段进行去重。时间段由浮点数元组 `(float, float)` 组成。由于浮点数精度问题（如 `0.1 + 0.2 != 0.3`），数学上相等的时间点可能被视为不同，导致去重失败或冲突检测不准确。 - 修改建议：虽然代码中多处使用了 `round(..., 1)`，降低了风险，但在处理集合操作时，建议将时间转换为整数（如毫秒）或确定精度的字符串后再进行集合操作，以确保去重的准确性。 ### ✅ 良好实践 1. **[apps/api/app/api/routes/generation_tasks.py]** 采用“预克隆”策略处理批量生成任务。在创建任务之前先完成所有 Plan 的克隆，确保了操作的原子性，避免了部分任务创建成功导致的数据不一致或脏数据问题。 2. **[apps/api/app/api/routes/templates_editor/clips.py]** 引入受控复用机制（`make_reuse_callback`）和复用比率限制（`REUSE_RATIO_LIMIT`），有效防止了素材过度复用导致的视频内容重复问题，逻辑设计较为严谨。 3. **[apps/api/app/api/routes/assets.py]** 在 `_asset_availability_fields` 中增加了异常捕获和降级处理，当计算失败时默认返回 `usable=True`，保证了素材列表接口的可用性不被下游计算错误阻断，且保留了日志记录便于排查。 --- ✅ 格式检查通过 | ✅ 逻辑审查通过 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-29 18:42:33 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot approved these changes 2026-08-30 02:45:31 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-30 02:45:31 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia added 1 commit 2026-08-30 07:14:18 +08:00

fix(segments): AI Review 二轮修复 — 批量无源plan索引守卫 + 区间set精度归一化 ... 78e9463825

- [阻塞] count>1 但 source_edit_plan_id 为空时 variant_plan_ids 为空列表，
  循环 task_index>0 直接索引 variant_plan_ids[task_index-1] 抛 IndexError
  导致批量创建崩溃；加非空守卫，无源 plan 时各任务走自身随机选片
  （新增回归测试 test_batch_no_plan_guard：还原守卫即红、修复后绿）
- [建议] MediaKit 历史区间 set 去重前 round(3) 归一化浮点精度，避免
  1.0 与 1.0000000001 被误判为不同区间
- [建议] smart-match 循环调用 compute_asset_availability 为纯函数
  （只读 model 内存字段、无 DB 查询），无 N+1 问题，无需修改

auto-approve-bot added 1 commit 2026-08-30 07:22:04 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 8c760d4a2d

xiaoxia merged commit 3acdb8b729 into develop 2026-08-30 07:36:33 +08:00

gitea-actions bot commented 2026-08-30 07:42:25 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1549 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1549 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

xiaoxia referenced this pull request 2026-08-30 08:03:07 +08:00

fix: 素材余量四字段兼容 Asset 领域实体（真实接口恒为 None 修复） #1550

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1549