AI 教程
🔍

AI 搜索

MacCMS LA 内置 AI 智能搜索,访客和管理员都可以使用自然语言同时检索本地 CMS 数据库和已配置的外部资源站。结果按语义排序,而不是简单的关键词匹配,对视频、影视、文章等大型站点尤其有用。

功能特性

  • CMS 数据库搜索 —— 对本地视频、文章、专题、播放器等数据进行语义搜索。
  • 外部资源搜索 —— 在一个入口同时查询已对接的资源库 / 采集站。
🧠

工作原理

系统 → AI 搜索配置 启用后,前台每次搜索都会经过 3 段式流水线。每段都有独立缓存,因此重复查询几乎不消耗额外资源。

  1. 1查询扩展

    LLM 会把原始查询扩展为最多 N 条更利于检索的变体(扩展词数量,默认 4),包括同义词、年份、类型标签等。

  2. 2混合关键词召回

    所有变体会并行查询启用模块(视频 / 文章 / 漫画 / 专题 / 演员 / 角色 / 剧情 / 网址),结合 FULLTEXT 与标签匹配。

  3. 3语义重排序(Embedding)

    可选。候选结果使用 Embedding 与原始问题计算余弦相似度后重排,再合并为统一排序的清单。

📋

前置条件

  • 一个可用的 AI 服务 API Key(兼容 OpenAI 协议即可,例如 OpenAI、DeepSeek 或本地的 Ollama 服务)。
  • 如需启用外部搜索,请先在 采集 → 资源库 中添加好资源站。
1

第 1 步 — 配置 AI 服务商

打开 系统 → AI 搜索配置。AI 搜索需要一个兼容 OpenAI 协议的端点,需提供 POST /v1/chat/completions(若启用语义重排,还需 /v1/embeddings)。填入 服务商模型API 地址API Key

🅾️OpenAI

服务商 openai,模型 gpt-4o-mini,API 地址 https://api.openai.com/v1。到 platform.openai.com 申请 API Key。

🐳DeepSeek

服务商 openai(兼容),模型 deepseek-chat,API 地址 https://api.deepseek.com/v1。比 OpenAI 便宜,检索效果相当。

🦙Ollama(本地部署)

服务商 openai(兼容),模型 qwen2.5:7b,API 地址 http://127.0.0.1:11434/v1。零成本但需要至少 8 GB GPU/内存。

💡建议:把 响应语言 设为 自动(跟随问题语言),让 AI 回答自动跟随访客输入语言。
2

第 2 步 — 启用 AI 搜索并选择模块

打开 启用 AI 搜索,然后在 启用模块 中勾选需要参与 AI 搜索的内容类型:

  • 视频 (vod)文章 (art)漫画 (manga)专题 (topic) —— 主要内容模块。
  • 演员 (actor)角色 (role)剧情 (plot) —— 影视类扩展元数据,影视站点很有用。
  • 网址 (website) —— 网址导航模块,仅在你启用了它时再开启。
3

第 3 步 — 调优检索

这些选项控制 LLM 产生多少查询变体,以及对上游服务的等待时长:

  • 扩展词数量(默认 4,范围 1–12)—— LLM 为每次查询生成的变体数量。数值越大命中越多,但 Token 成本也更高。
  • 最小查询长度(默认 2)—— 短于此长度的查询会跳过 AI 流水线,回退到普通 MySQL 搜索。
  • 超时(秒)(默认 12)—— 单次上游请求的预算;网络较慢时调低,可让搜索体感更顺畅。
4

第 4 步 — 配置外部资源

同一个页面包含两类互补的外部能力:外部资源链接(在每条结果旁推荐外站 URL)与 外部数据源平台(内置 TMDB / 豆瓣 / IMDb 等元数据源,用于丰富答案)。可以只开其一,也可全开。

  1. a
    外部资源链接 区域,打开 启用外部资源链接。设置 外部链接数量(1–10,默认 3)—— 单次回答最多附带几条建议链接。
  2. b
    外部站点白名单 填入英文逗号分隔的域名列表,例如 wikipedia.org,imdb.com,douban.com。只有白名单内的站点会被展示。
  3. c
    向下滚动到 外部数据源平台 并打开。决定是否启用 在线实时检索检索缓存,或两者都开 —— 推荐 live + cache 组合。
  4. d
    设置 缓存有效期(秒)(默认 600)、合并结果上限(单次回答允许加入多少外部条目)以及 离线同步间隔(秒) 用于定时喂数。
  5. e
    按需启用各服务商:TMDB(需 API Key,影视类推荐)、豆瓣IMDbAniList(漫画,无需 Key)、Google Books(需 Books API Key)。
📄配置示例

下面是保存表单后 MacCMS 实际写入的 ai_search 数组。后台 UI 与直接修改配置文件的结果完全一致。

{
  "ai_search": {
    "enabled": "1",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "response_language": "auto",
    "api_base": "https://api.openai.com/v1",
    "api_key": "sk-***",
    "timeout": "12",
    "max_terms": "4",
    "min_query_len": "2",
    "module": {
      "vod": "1", "art": "1", "manga": "0", "topic": "1",
      "actor": "0", "role": "0", "plot": "0", "website": "0"
    },
    "external_enabled": "1",
    "external_max_links": "3",
    "external_domains": "wikipedia.org,imdb.com,douban.com",
    "semantic_enabled": "1",
    "embedding_model": "text-embedding-3-small",
    "semantic_weight": "0.45",
    "semantic_candidates": "40",
    "rate_limit_enabled": "1",
    "rate_limit_window": "60",
    "rate_limit_max": "20",
    "max_question_chars": "800",
    "debug_log": "0"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
json
💡提示:TMDB / 豆瓣 / IMDb 接口受上游限流影响 —— 生产环境建议开启 检索缓存,TTL 设为 1 小时以上。
📚

配置参数说明

系统 → AI 搜索配置 中所有选项与下方表格一一对应。默认值已经适合大多数站点 —— 没有实际问题不建议盲调。

选项默认值说明
ai_search.enabled1AI 搜索功能的总开关。
ai_search.provideropenai服务商,一般填 openai 或任意兼容 OpenAI 协议的值。
ai_search.modelgpt-4o-mini用于扩展查询的对话补全模型。
ai_search.api_basehttps://api.openai.com/v1兼容 OpenAI 协议的接口地址。
ai_search.timeout12单次请求上游服务的超时时间(秒)。
ai_search.max_terms4每个查询由 LLM 生成的变体数量(范围 1–12)。
ai_search.min_query_len2短于此长度的查询会回退到普通 MySQL 搜索。
ai_search.module{ vod: 1, art: 1, ... }按模块开关:vod / art / manga / topic / actor / role / plot / website
ai_search.external_enabled0在结果旁展示白名单内的外部链接建议。
ai_search.external_domains以英文逗号分隔的域名白名单,例如 wikipedia.org,imdb.com,douban.com
ai_search.semantic_enabled0用 Embedding 余弦相似度对关键词召回结果做重排。
ai_search.semantic_weight0.45关键词分数与向量分数的融合比例(0…1)。
💬

使用方式

访客在搜索框输入自然语言(例如:“一部 2024 年关于时间循环的科幻片”),系统会对查询进行改写,然后对本地数据库和外部资源进行混合检索,返回统一排序的结果。管理员也可以在后台列表页通过同样的方式快速定位条目。

🛠️

常见问题

搜索没有任何结果
请确认 启用 AI 搜索 已开启、至少勾选了一个模块、保存的 API Key 有效,并且上游服务可访问。可以打开 调试日志(最后一项开关)查看失败请求。
外部结果一直不出现
要看到外站推荐链接,必须同时开启 启用外部资源链接 并设置至少一个白名单域名。若要让答案有元数据增强,还需开启 外部数据源平台 与至少一个服务商(TMDB / 豆瓣 / IMDb / AniList / Google Books)。
前台搜索框没有 AI 标识
先清理系统缓存并强制刷新。若仍不显示,可能是模板覆盖了搜索框 —— 切换回官方模板或合并最新的 search.tpl
Token 费用偏高
扩展词数量 调到 2、使用更便宜的模型(gpt-4o-mini / deepseek-chat),并把 Embedding 模型 切换为 text-embedding-3-small。开启 访问频率限制 可以遏制恶意刷量。
💡

实用建议

💡搜索场景建议选用较小的模型(例如 gpt-4o-mini / deepseek-chat),以降低延迟和成本,效果通常已经足够。
💡如果没有结果,请检查资源库是否可访问、API Key 是否仍有可用配额。
Scroll Top