feat: implement POST /assets/smart-match endpoint #1242

Merged

auto-approve-bot merged 5 commits from feat/smart-match-assets into develop 2026-08-05 09:51:01 +08:00

Conversation 5 Commits 5 Files Changed 9

+1623 -6

xiaoxia commented 2026-08-05 08:20:40 +08:00

Owner

Copy Link

Copy Source

Summary

实现 POST /assets/smart-match 端点，提供统一智能选素材 API。

Changes

New: packages/domain/smart_match.py

统一智能选素材算法，合并 3 套重叠的选素材逻辑（_helpers / generation_tasks / auto_clip_service）：

• 多维度加权评分：质量分(40%) + 时长适配(30%) + 新鲜度(20%) + 未使用偏好(10%)
• 时长分桶均衡：short(<10s) / medium(10-30s) / long(>30s) 轮流选取，避免同质化
• 可扩展：后续接入 AI 模型只需替换 score_asset()

New: POST /assets/smart-match

• Request: { "library_id": "xxx", "limit": 10, "kind": "video" }
• Response: { "items": [{ "asset": {...}, "score": 85.5, "breakdown": {...} }], "total_candidates": 50 }
• 权限校验：验证用户对项目 + 素材库的访问权限

Tests

• 33 个新增单测（算法 28 + 端点 5）
• 全量测试 13832 passed, 0 failed

API Contract

// POST /assets/smart-match
// Request
{
  "library_id": "string (required)",
  "limit": "int (optional, 1-200)",
  "kind": "video|image|audio (optional)"
}

// Response
{
  "items": [
    {
      "asset": { /* full AssetResponse */ },
      "score": 85.5,
      "breakdown": { "quality": 36.0, "duration": 30.0, "recency": 18.5, "unused": 1.0 }
    }
  ],
  "total_candidates": 50
}

## Summary 实现 `POST /assets/smart-match` 端点，提供统一智能选素材 API。 ## Changes ### New: `packages/domain/smart_match.py` 统一智能选素材算法，合并 3 套重叠的选素材逻辑（_helpers / generation_tasks / auto_clip_service）： - **多维度加权评分**：质量分(40%) + 时长适配(30%) + 新鲜度(20%) + 未使用偏好(10%) - **时长分桶均衡**：short(<10s) / medium(10-30s) / long(>30s) 轮流选取，避免同质化 - **可扩展**：后续接入 AI 模型只需替换 `score_asset()` ### New: `POST /assets/smart-match` - Request: `{ "library_id": "xxx", "limit": 10, "kind": "video" }` - Response: `{ "items": [{ "asset": {...}, "score": 85.5, "breakdown": {...} }], "total_candidates": 50 }` - 权限校验：验证用户对项目 + 素材库的访问权限 ### Tests - 33 个新增单测（算法 28 + 端点 5） - 全量测试 13832 passed, 0 failed ## API Contract ```json // POST /assets/smart-match // Request { "library_id": "string (required)", "limit": "int (optional, 1-200)", "kind": "video|image|audio (optional)" } // Response { "items": [ { "asset": { /* full AssetResponse */ }, "score": 85.5, "breakdown": { "quality": 36.0, "duration": 30.0, "recency": 18.5, "unused": 1.0 } } ], "total_candidates": 50 } ```

xiaoxia added 1 commit 2026-08-05 08:20:40 +08:00

feat: implement POST /assets/smart-match endpoint ... f86498b702

- New unified smart asset selection algorithm (packages/domain/smart_match.py)
  - Multi-dimensional scoring: quality(40%) + duration(30%) + recency(20%) + unused(10%)
  - Duration diversity: balanced selection across short/medium/long buckets
  - Replaces 3 overlapping selection logics (_helpers/generation_tasks/auto_clip_service)
- New API endpoint: POST /assets/smart-match
  - Request: { library_id, limit?, kind? }
  - Response: { items: [{ asset, score, breakdown }], total_candidates }
- 33 unit tests covering algorithm + endpoint
- Full test suite: 13832 passed, 0 failed

gitea-actions bot commented 2026-08-05 08:22:07 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

auto-approve-bot added 1 commit 2026-08-05 08:22:45 +08:00

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

auto-approve-bot approved these changes 2026-08-05 08:30:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-05 08:30:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia referenced this issue from a commit 2026-08-05 09:26:19 +08:00

fix: total_candidates 按 kind 过滤后再统计，修复前后端候选数不一致

xiaoxia added 1 commit 2026-08-05 09:26:19 +08:00

fix: total_candidates 按 kind 过滤后再统计，修复前后端候选数不一致 ... 3c86b89d7f

- API 层先按 request.kind 过滤素材，再计算 total_candidates
- smart_select_assets 调用时 kind=None 避免重复过滤
- 新增 test_kind_filter_video_total_candidates 验证 kind 过滤后总数正确
- 修复 #1242 AI Code Review 阻塞问题

xiaoxia added 1 commit 2026-08-05 09:37:56 +08:00

fix: AI Code Review 阻塞问题修复 ... 21dc361cdd

- API层改用DB查询按kind过滤(find_by_library_and_file_type)，避免内存过滤性能问题
- score_asset中int()转换增加try/except，防止脏数据ValueError
- 新增test_dirty_metadata_use_count_string_does_not_crash验证异常处理
- Stub增加find_by_library_and_file_type方法支持kind过滤测试

xiaoxia force-pushed feat/smart-match-assets from d26a97e004 to 21dc361cdd 2026-08-05 09:37:56 +08:00 Compare

auto-approve-bot added 1 commit 2026-08-05 09:40:47 +08:00

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

auto-approve-bot commented 2026-08-05 09:42:39 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

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

📊 审查概览

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

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

无

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

1. [packages/domain/smart_match.py: 多处] 建议使用常量替代魔法数字

   • 具体内容：在 score_asset 函数中，权重系数（如 0.4, 0.3）和衰减因子（如 -0.05, -0.02）直接硬编码在计算逻辑中。建议将这些数值提取为模块级的常量（如 WEIGHT_QUALITY = 0.4, DECAY_FACTOR_RECENCY = -0.05），以提高代码可读性和后续调参的便利性。

2. [packages/domain/smart_match.py: 36] 建议优化类型提示

   • 具体内容：SmartMatchResult 和 score_asset 等函数中使用了 asset: Any。虽然这提供了灵活性，但会导致 IDE 无法进行属性补全和静态类型检查。建议定义一个 Protocol 或直接使用具体的 Asset 类（如果循环依赖允许），明确指出 asset 必须具备 quality_score, duration, created_at 等属性。

3. [apps/api/app/api/routes/assets.py: 537] 性能优化建议

   • 具体内容：在 smart_match_assets 接口中，limit=10000 意味着可能一次性将 10,000 个 Asset 对象加载到内存中进行 Python 端的评分和排序。对于大型素材库，这可能会导致较高的内存占用和 GC 压力。建议评估是否可以通过数据库层面的计算（Window Functions等）进行预筛选，或者在文档中明确标注该接口的内存开销预期。

✅ 良好实践

• 参数校验完善：SmartMatchRequest Schema 中对 limit 做了 le=200 的限制，对 kind 做了正则校验，有效防止了恶意请求或参数溢出。
• 权限检查：在 smart_match_assets 接口入口处正确调用了 check_project_access，确保了数据访问的安全性。
• 空值处理：在 score_asset 中对 quality_score, duration, created_at 等可能为 None 的字段做了完善的兜底处理，避免了 NPE。
• 多样性算法：_diversity_select 实现了基于分桶的均衡选取策略，有效避免了返回结果过于单一（如全是长视频），提升了智能匹配的实用性。

---

✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能无明显瓶颈

---

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

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：通过 - 建议级问题数量：3 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 1. **[packages/domain/smart_match.py: 多处] 建议使用常量替代魔法数字** - 具体内容：在 `score_asset` 函数中，权重系数（如 `0.4`, `0.3`）和衰减因子（如 `-0.05`, `-0.02`）直接硬编码在计算逻辑中。建议将这些数值提取为模块级的常量（如 `WEIGHT_QUALITY = 0.4`, `DECAY_FACTOR_RECENCY = -0.05`），以提高代码可读性和后续调参的便利性。 2. **[packages/domain/smart_match.py: 36] 建议优化类型提示** - 具体内容：`SmartMatchResult` 和 `score_asset` 等函数中使用了 `asset: Any`。虽然这提供了灵活性，但会导致 IDE 无法进行属性补全和静态类型检查。建议定义一个 `Protocol` 或直接使用具体的 Asset 类（如果循环依赖允许），明确指出 asset 必须具备 `quality_score`, `duration`, `created_at` 等属性。 3. **[apps/api/app/api/routes/assets.py: 537] 性能优化建议** - 具体内容：在 `smart_match_assets` 接口中，`limit=10000` 意味着可能一次性将 10,000 个 Asset 对象加载到内存中进行 Python 端的评分和排序。对于大型素材库，这可能会导致较高的内存占用和 GC 压力。建议评估是否可以通过数据库层面的计算（Window Functions等）进行预筛选，或者在文档中明确标注该接口的内存开销预期。 ### ✅ 良好实践 - **参数校验完善**：`SmartMatchRequest` Schema 中对 `limit` 做了 `le=200` 的限制，对 `kind` 做了正则校验，有效防止了恶意请求或参数溢出。 - **权限检查**：在 `smart_match_assets` 接口入口处正确调用了 `check_project_access`，确保了数据访问的安全性。 - **空值处理**：在 `score_asset` 中对 `quality_score`, `duration`, `created_at` 等可能为 None 的字段做了完善的兜底处理，避免了 NPE。 - **多样性算法**：`_diversity_select` 实现了基于分桶的均衡选取策略，有效避免了返回结果过于单一（如全是长视频），提升了智能匹配的实用性。 --- ✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能无明显瓶颈 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-05 01:42:39 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot merged commit e27a48f0e0 into develop 2026-08-05 09:51:01 +08:00

auto-approve-bot deleted branch feat/smart-match-assets 2026-08-05 09:51:01 +08:00

gitea-actions bot commented 2026-08-05 09:51:50 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

xiaoxia referenced this pull request 2026-08-05 11:13:44 +08:00

refactor: 统一智能选素材逻辑，迁移 generation_tasks smart 模式到 smart_match #1243

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#1242