Wiki

外观

自定义二级分类使用教程

约 4601 字大约 15 分钟

2025-11-15

教程简介

  • 本教程详细介绍 Symedia 的二级分类功能，帮助您实现精细化、自动化的影片管理。
  • 涵盖了从基础配置、必须/可选 (?) 匹配逻辑、Series 系列分类到 include_keywords 标签匹配的全部用法。

一. 基础概念

1. 什么是二级分类？

二级分类是在媒体库中按照特定规则对影片进行自动分类的功能。例如，将影片自动整理成如下结构:

电影/
├── 漫威系列/
│   ├── 钢铁侠系列/
│   │   ├── 钢铁侠 (2008)/
│   │   └── 钢铁侠2 (2010)/
│   └── 复仇者联盟系列/
├── 华语电影/
│   └── 让子弹飞 (2010)/
└── 欧美电影/
    └── 盗梦空间 (2010)/

2. 配置文件位置

配置文件路径: config/category.yaml

二. 配置文件结构

1. 基本格式

# 电影分类配置
movie:
  分类名称1:
    匹配条件1: "值"
    匹配条件2: "值"
  分类名称2:
    匹配条件: "值"

# 电视剧分类配置
tv:
  分类名称1:
    匹配条件: "值"

核心匹配原则

  • 分类名称: 即 文件夹的目录名称。
  • 顺序决定一切: 按 category.yaml 中的顺序从上到下匹配，匹配成功后立即停止。
  • 具体规则在前: 必须将最精确的规则（如 漫威系列）放在最宽泛的规则（如 欧美电影）之前。
  • 保底分类: 将一个空配置（如 其他电影:）放在最后，可以匹配所有未分类的影片。

2. 核心匹配逻辑: 必须 vs 可选

匹配逻辑分为两大类: 必须属性 (AND) 和 可选属性 (OR)，这是实现精细化分类的关键。

  1. 必须属性 (AND 逻辑)

    • 语法: 属性名前没有 ? 前缀。
    • 逻辑: 所有 必须属性 必须全部满足，才会匹配成功。

    配置示例 (必须)

    美国科幻片:
  genre_ids: "878" # 必须:科幻
  production_countries: "US" # 必须: 美国
  year: "2020-2025" # 必须: 2020-2025年
    • 匹配逻辑: 影片必须同时满足上述所有三个条件才能匹配。

  2. 可选属性 (OR 逻辑)

    • 语法: 在属性名前添加 ? 或 ? 前缀。
    • 逻辑: 至少满足一个 可选属性 即可。

    配置示例 (可选)

    亚洲电影:
  ?original_language: "zh,ja,ko" # 可选: 中文、日语或韩语
  ?origin_country: "CN,JP,KR" # 可选: 中日韩
    • 匹配逻辑: 影片只要满足任意一个条件（例如: 语言是 zh 或国家是 JP）即可匹配。

  3. 混合匹配 (AND + OR)

    • 最终逻辑: (所有“必须属性”全部满足) AND (至少一个“可选属性”被满足)

    匹配结果

    • ✅ 科幻片 + 英语 → 匹配 (必须满足 + 可选满足)
    • ✅ 科幻片 + 法国制作 → 匹配 (必须满足 + 可选满足)
    • ❌ 科幻片 + 中文 → 不匹配 (必须满足，但可选条件均不满足)
    • ❌ 剧情片 + 英语 → 不匹配 (必须条件不满足)

  4. Done

三. 匹配规则详解

1. 常用匹配字段

字段说明示例
genre_ids内容类型28 (动作), 16 (动画)
original_language原始语言zh,en,ja
production_countries制作国家（电影）US,CN,JP
origin_country制作国家（电视剧）US,CN,JP
keywords关键词（从标题匹配）漫威,复仇者
include_keywordsTMDB 标签关键词tokusatsu,superhero
year年份2020-2025
series_keywords系列关键词钢铁侠,蜘蛛侠
series_directors系列导演诺兰,斯皮尔伯格
series_actors系列演员汤姆·克鲁斯
?属性名可选匹配属性?original_language

2. 多值匹配

使用逗号分隔多个值:

华语电影:
  original_language: "zh,cn,bo,za" # 匹配中文、粤语、藏语、壮语

3. 操作符 (用于 genre_ids 等字段)

  1. 必须包含 (AND)

    • 语法: 属性值前添加 + 前缀。
    • 逻辑: 包含所有带 + 标记的 ID。

    + 号: 必须包含 (AND)

    儿童动画:
  genre_ids: "+16,+10751" # 必须同时是动画(16)和家庭(10751)

  2. 必须排除 (NOT)

    • 语法: 属性值前添加 - 前缀。
    • 逻辑: 排除所有带 - 标记的 ID。

    - 号: 必须排除 (NOT)

    纪录片:
  genre_ids: "99,-10402" # 是纪录片(99)，但不是音乐(10402)

  3. 混合匹配 (AND + NOT)

    • 最终逻辑: (所有 必须包含、必须排除 全部满足) AND (可以有 可选属性(OR) 被满足)。

    + 号: 必须包含 (AND)。 - 号: 必须排除 (NOT)。无前缀: 可有(OR)。

    动作冒险:
  genre_ids: "+28,12,14,-27" # 必须有动作(28)，可以有冒险(12)或奇幻(14)，但不能有恐怖(27)

  4. 年份范围

    匹配年份范围之间的。

    近期电影:
  year: "2020-2025" # 2020年到2025年之间

  5. Done

4. keywords vs include_keywords

重点区分: 标题匹配 vs 标签匹配

  1. keywords: 匹配 影片标题。

    • 优点: 简单直接，适合根据常见中文/英文标题分类，从影片标题中匹配关键词。
      漫威系列:
  keywords: "漫威,复仇者,钢铁侠" # 标题包含这些词

  2. include_keywords: 匹配 TMDB 数据库的 Keywords 标签。

    • 优点: 更专业、更精确，不受标题翻译影响。
    特摄片:
 include_keywords: "tokusatsu" (特摄片), "cyberpunk" (赛博朋克) # TMDB标签包含 tokusatsu, cyberpunk

四. 可选属性匹配（? 前缀）

1. 什么是可选属性匹配？

通过在属性名前添加 ? 或 ？ 前缀，可以灵活控制匹配逻辑:

  • 没有 ? 前缀 = 必须匹配（所有这类属性都要满足）
  • 有 ? 前缀 = 可选匹配（至少满足其中一个）

2. 匹配规则

最终匹配条件 = 必须属性全部满足 AND 可选属性至少满足一个

3. 使用场景

  1. 只有必须属性（全部都要满足）

    匹配结果: 必须 同时满足 所有三个条件。

    美国科幻片:
  genre_ids: "878" # 必须: 科幻
  production_countries: "US" # 必须: 美国
  year: "2020-2025" # 必须: 2020-2025年

  2. 只有可选属性（至少满足一个）

    匹配结果: 语言是中文，或者国家是 CN，满足 任意一个 即可。

    亚洲电影:
  ?original_language: "zh,ja,ko" # 可选: 中文、日语或韩语
  ?origin_country: "CN"

  3. 必须 + 可选（组合匹配）

    相关信息

    欧美科幻:
  genre_ids: "878" # 必须: 科幻
  ?original_language: "en,fr,de" # 可选: 英/法/德语任意一个
  ?production_countries: "US,GB" # 可选: 美国或英国任意一个

    匹配结果

    • ✅ 科幻片 + 英语 → 匹配（必须满足 + 可选满足）
    • ✅ 科幻片 + 法国制作 → 匹配（必须满足 + 可选满足）
    • ❌ 科幻片 + 中文 + 中国制作 → 不匹配（必须满足但可选都不满足）
    • ❌ 剧情片 + 英语 → 不匹配（必须不满足）

  4. Done

4. 实战示例

  1. 示例1: 精确分类

    精确分类

    近期欧美科幻:
  genre_ids: "878" # 必须: 科幻
  year: "2020-2025" # 必须: 近期

  2. 示例2: 广泛收集

    广泛收集

    热门动作片:
  genre_ids: "28" # 必须: 动作片
  ?keywords: "漫威,DC,速度与激情" # 可选: 这些关键词之一
  ?year: "2023-2025" # 可选: 或者是近期作品

  3. 示例3: 复杂组合

    复杂组合

    经典港片:
origin_country: "HK" # 必须: 香港
year: "1980-2000" # 必须: 1980-2000年
?genre_ids: "28,80,18" # 可选: 动作、犯罪或剧情之一
?keywords: "成龙,周星驰,刘德华" # 可选: 或这些明星之一

  4. Done

5. 使用技巧

  1. 技巧 1: 多个可选属性形成"或"关系

    只要满足任意一个可选条件即可。

    假期观影推荐:
  ?genre_ids: "35,10751" # 可选1: 喜剧或家庭
  ?keywords: "圣诞,新年" # 可选2: 或节日主题
  ?year: "2024-2025" # 可选3: 或最近新片

  2. 技巧 2: 必须条件缩小范围，可选条件扩展匹配

    只要满足任意一个可选条件即可。

    漫威英雄片:
  genre_ids: "+28" # 必须: 动作片
  production_countries: "US"
  ?keywords: "复仇者,钢铁侠,蜘蛛侠" # 可选: 漫威角色
  ?include_keywords: "marvel cinematic universe (mcu)" # 可选: 关键词带有漫威宇宙

  3. Done

五. Series 系列分类

1. 什么是 Series？

Series 属性用于在主分类下自动创建子分类，格式为: 分类名/系列名。例如:

  • 漫威系列/钢铁侠系列/
  • 漫威系列/复仇者联盟系列/

2. Series 属性类型

属性说明示例
series_keywords从标题匹配系列关键词钢铁侠,蜘蛛侠
series_directors从导演匹配系列诺兰,昆汀
series_actors从演员匹配系列汤姆·克鲁斯

重要特性: Series 属性只用于生成系列名，不参与匹配条件判断！

3. 使用方式

注意: series_keywords 匹配只影响系列名，不影响是否匹配该分类！

  1. 方式 1: 只有 Series 属性

    相关信息

    漫威系列:
  series_keywords: "钢铁侠,美国队长,雷神,复仇者联盟"

    效果:

    • 标题包含"钢铁侠" → 漫威系列/钢铁侠系列/
    • 标题包含"复仇者联盟" → 漫威系列/复仇者联盟系列/
    • 标题不包含任何关键词 → 不匹配

  2. 方式 2: 必须条件 + Series

    相关信息

    科幻系列:
  genre_ids: "878" # 必须: 科幻片
  production_countries: "US" # 必须: 美国
  series_keywords: "星球大战,星际迷航" # 系列名

    效果:

    • 美国科幻片 + 标题含"星球大战" → 科幻系列/星球大战系列/
    • 美国科幻片 + 标题不含关键词 → 科幻系列/
    • 中国科幻片 → 不匹配（必须条件不满足）

  3. 方式 3: 可选条件 + Series

    相关信息

    动作系列:
  genre_ids: "28" # 必须: 动作片
  ?keywords: "汽车,赛车" # 可选: 关键词
  series_keywords: "速度与激情,变形金刚" # 系列名

    效果:

    • 动作片 + 标题含"速度与激情" → 动作系列/速度与激情系列/
    • 动作片 + 标题含"汽车" → 动作系列/
    • 动作片（无特殊关键词）→ 动作系列/
    • 剧情片 + 标题含"速度与激情" → 不匹配（必须条件不满足）

  4. Done

六. 高级用法

1. 排除特定类型

剧情片:
  genre_ids: "18,-27,-16" # 剧情片，但不要恐怖片和动画

2. 多条件组合

亚洲动作片:
  genre_ids: "28" # 必须: 动作片
  origin_country: "CN,HK,TW,JP,KR,TH" # 必须: 亚洲国家
  year: "2020-2025" # 必须: 近期

3. 保底分类

放在最后，不配置任何条件:

其他电影:
  # 不配置条件，匹配所有前面未匹配的

或配置为空:

其他电影:

4. 导演/演员系列

诺兰作品:
  series_directors: "克里斯托弗·诺兰"

汤姆·克鲁斯电影:
  series_actors: "汤姆·克鲁斯"

5. 复杂的可选逻辑

假期观影推荐:
  ?genre_ids: "35,10751" # 可选1: 喜剧或家庭
  ?keywords: "圣诞,新年,假期" # 可选2: 节日关键词
  ?year: "2023-2025" # 可选3: 最近新片

6. 使用 TMDB 标签精确分类

利用 include_keywords 进行专业分类:

# 特摄片分类（假面骑士、奥特曼等）
特摄片:
  include_keywords: "tokusatsu,super sentai,kaiju"
  series_keywords: "假面骑士,奥特曼,超级战队,哥斯拉"

# 超级英雄电影（通过标签更精确）
超级英雄:
  include_keywords: "superhero,marvel cinematic universe,dc extended universe"

# 赛博朋克题材
赛博朋克:
  genre_ids: "878" # 必须: 科幻类型
  include_keywords: "cyberpunk,dystopia" # 必须: 赛博朋克标签

# 音乐传记片
音乐传记:
  include_keywords: "biography,music" # 必须: 传记+音乐标签
  genre_ids: "10402,36" # 必须: 音乐+历史类型

在 TMDB 网站上查看影片的 Keywords 标签，可以找到更多可用的标签词。

七. 实战示例

  1. 示例 1: 电影完整配置

  2. 示例 2: 电视剧完整配置

  3. Done

八. FAQ

Q1: 分类顺序重要吗？

A: 非常重要！ 程序会按配置顺序匹配，匹配成功后停止。

❌ 错误示例（宽泛的在前）:

movie:
  欧美电影: # 这个太宽泛，几乎匹配所有
  漫威系列: # 永远不会匹配到这里
    series_keywords: "复仇者联盟"

✅ 正确示例（具体的在前）:

movie:
  漫威系列: # 先匹配具体的
    series_keywords: "复仇者联盟"
  欧美电影: # 再匹配宽泛的

Q2: 怎么调试分类不生效？

A: 从哪几方面检查。

  1. 检查配置语法是否正确（YAML 格式）。
  2. 检查分类顺序（是否被前面的分类拦截）。
  3. 查看日志输出。
  4. 确认 TMDB 数据是否包含该字段。

Q3: 什么时候用必须属性，什么时候用可选属性？

A: 按需使用，看需要精确或广泛。

  • 必须属性（无 ? 前缀）: 需要精确分类时使用
    • 例如: 2020 年后的美国科幻片。
    • 所有条件都必须满足。
  • 可选属性（有 ? 前缀）: 需要广泛收集时使用
    • 例如: 漫威电影 或 DC 电影 或 2024 年新片。
    • 至少满足其中一个即可。

Q4: Series 属性如何工作？

A: Series 属性不参与匹配条件判断，只用于生成系列名。

动作系列:
  genre_ids: "28" # 必须: 动作片
  ?keywords: "爆炸" # 可选: 关键词
  series_keywords: "速度与激情" # 只生成系列名
  • 动作片 → 匹配 ✅
  • 动作片 + 标题含 爆炸 → 匹配 ✅
  • 标题含 速度与激情 但不是动作片 → 不匹配 ❌

Q5: 能否让 Series 也参与匹配判断？

A: 不能。这是设计决策。如果需要关键词参与判断，请使用 keywords 或 ?keywords:

动作系列:
  genre_ids: "28" # 必须: 动作片
  ?keywords: "速度与激情" # 可选: 关键词匹配

Q6: 怎么处理多语言标题？

A: keywords 和 series_keywords 从 TMDB 标题 匹配，使用本地化标题:

日本动画:
  genre_ids: "16"
  origin_country: "JP"
  series_keywords: "ワンピース,海贼王,航海王" # 多个译名

Q7: 年份范围的边界是包含还是排除？

A: 包含边界。"2020-2025" 包括 2020 和 2025 年。

Q8: keywords 和 include_keywords 有什么区别？

A: 匹配关键源不一样。

keywords: 从影片的标题中匹配关键词

  • 适用场景: 通过常见的中文/英文标题进行分类。
  • 例如: keywords: "漫威,复仇者" 会匹配标题包含这些词的影片。

include_keywords: 从 TMDB 数据库的Keywords 标签字段匹配

  • 适用场景: 需要更专业、精确的分类。
  • 例如: include_keywords: "tokusatsu" 匹配特摄类型的影片。
  • 优势: TMDB 的标签更标准化，不受标题翻译影响。

建议:

  • 对于常规分类，用 keywords 就够了。
  • 对于专业领域（特摄、赛博朋克等），用 include_keywords 更精确。
  • 可以同时使用两者进行组合匹配。

Q9: 如何查找可用的 TMDB Keywords？

A: 从 TDMB 官网进行查找。

  1. 访问 TMDB 网站（themoviedb.org）。
  2. 搜索你想分类的影片。
  3. 在影片页面找到 Keywords 部分。
  4. 复制相关的英文关键词到 include_keywords 配置中。

示例:

  • 搜索《假面骑士》→ 找到 Keywords: tokusatsu
  • 搜索《银翼杀手》→ 找到 Keywords: cyberpunk, dystopia

📚 参考字典

1. Genre IDs（内容类型）

电影类型

ID中文English
28动作Action
12冒险Adventure
16动画Animation
35喜剧Comedy
80犯罪Crime
99纪录Documentary
18剧情Drama
10751家庭Family
14奇幻Fantasy
36历史History
27恐怖Horror
10402音乐Music
9648悬疑Mystery
10749爱情Romance
878科幻Science Fiction
10770电视电影TV Movie
53惊悚Thriller
10752战争War
37西部Western

电视剧类型

ID说明
10759动作冒险
16动画
35喜剧
80犯罪
99纪录片
18剧情
10751家庭
10762儿童
9648悬疑
10763新闻
10764真人秀
10765科幻奇幻
10766肥皂剧
10767脱口秀
10768战争政治
37西部

2. Language Codes（语言代码）

代码语言代码语言
zh中文en英语
ja日语ko韩语
fr法语de德语
es西班牙语it意大利语
pt葡萄牙语ru俄语
ar阿拉伯语hi印地语
th泰语vi越南语
id印尼语tr土耳其语

3.Country Codes（国家代码）

代码国家/地区代码国家/地区
CN中国大陆HK中国香港
TW中国台湾MO中国澳门
US美国GB英国
JP日本KR韩国
FR法国DE德国
IT意大利ES西班牙
CA加拿大AU澳大利亚
IN印度TH泰国
SG新加坡MY马来西亚
RU俄罗斯BR巴西
MX墨西哥AR阿根廷

🎯 快速上手

  1. 复制模板

    复制示例配置到 config/category.yaml

  2. 测试简单配置

    movie:
  华语电影:
    original_language: "zh,cn"

  其他电影:

  3. 逐步完善

    根据实际需求，添加更多分类。

  4. 观察效果

    查看媒体库目录结构是否符合预期。

  5. Done

⚡ 总结

  • ✅ 分类按顺序匹配，具体的放前面
  • ✅ 没有 ? 前缀 = 必须全部满足（AND）
  • ✅ 有 ? 前缀 = 至少满足一个（OR）
  • ✅ Series 属性只生成系列名，不参与匹配判断
  • ✅ 使用操作符 + - 精确控制匹配
  • ✅ 保底分类放最后，配置为空即可
  • ✅ 多测试，查看日志确认效果

祝你使用愉快！如有问题，欢迎查看日志或提 issue。 🎉

版权归属：Symedia

许可证：署名 4.0 国际 (CC-BY-4.0)

Docker VersionDocker Pulls Copyright © 2024-2025 Symedia