# 极致事件素材库 · WeKnora 容器交付说明 V1.0

> 一句话：容器已建好，11 张卡全部灌入并验证可检索。**唯一必须记住的参数是 `vector_threshold = 0.5`** —— 不传它（默认 0.7）口语问法几乎召不回来。
> 日期：2026-09-23 ｜ 环境：本机 WeKnora 0.8.0（Docker，`localhost:31607`）
> 配套脚本：`tools/weknora-fit/5_build_event_lib.py`（建库+灌卡）、`6_threshold.py`（阈值扫描）

---

## 一、容器信息

| 项 | 值 |
|:--|:--|
| 库名 | **MCN极致事件素材库** |
| 库 ID | `e6772e41-7b72-499d-b46c-e5ca7c9d1740` |
| 类型 | **FAQ 型**（`type=faq`，一条目 = 一分块，不走文档分块器） |
| embedding | `03f0cf45-38dd-4330-aed9-38e394e66160`（BAAI/bge-m3，remote） |
| summary | `a2de7804-1a1b-4940-800a-bf877f64b5be`（glm-5.3-flash） |
| 索引策略 | `vector=true` / `keyword=true` / `graph=false` / `wiki=false` |
| faq_config | `index_mode=question_answer`、`question_index_mode=combined` |
| 条目数 | **11**（导入 11 / 成功 11 / 失败 0） |
| 地址 | `http://127.0.0.1:31607` ｜ 鉴权头 `X-API-Key` |

> ⚠️ 建库时三件事必须一起给：`type=faq` + `embedding_model_id` + `indexing_strategy{vector,keyword}`。缺 embedding → 导入卡在 `processing/0%` 且 error 字段为空；缺 indexing_strategy → **入库 100% 成功但检索永远返回空**（静默失败）。

---

## 二、库内 11 条条目

| # | 事件卡 | 主标签（tag_name） | 答案长度 | 相似问 | 反例问 |
|:--:|:--|:--|:--:|:--:|:--:|
| 100000017 | 高温实物证言 · 手机壳被晒化 | 反常识 | 678 字 | 4 | 2 |
| 100000018 | 沙疗活埋 · 从挑战者到沙漠「炮塔」 | 反差 | 679 字 | 4 | 2 |
| 100000019 | 番茄牛腩（红烧牛腩） | 食材极致 | 978 字 | 4 | 2 |
| 100000020 | 蒜香辣鸡爪 | 难度极限 | 969 字 | 4 | 2 |
| 100000021 | 皮蛋炒饭 | 难度极限 | 955 字 | 4 | 2 |
| 100000022 | 「随地大小睡」 | 反常识 | 623 字 | 4 | 2 |
| 100000023 | 浴室盲拍 · 只拍门，只听惨叫 | 自嘲反差 | 621 字 | 4 | 2 |
| 100000024 | 「雷霆发型」怼脸 | 反差 | 576 字 | 4 | 2 |
| 100000025 | 端着饭追过 5 个空间 | 反差 | 677 字 | 4 | 2 |
| 100000026 | 「我还给你带瓶水」的预判 | 预见式服务 | 654 字 | 4 | 2 |
| 100000027 | 一阵凉风，执念光速漂移 | 反差 | 609 字 | 4 | 2 |

**标签分布**：反差 4 ｜ 反常识 2 ｜ 难度极限 2 ｜ 自嘲反差 1 ｜ 食材极致 1 ｜ 预见式服务 1（全部为 **12 维词表原样值**，无自造词）

**标签 seq_id**（标签优先检索要用）：反差 `10000009` ｜ 反常识 `10000010` ｜ 自嘲反差 `10000011` ｜ 难度极限 `10000012` ｜ 预见式服务 `10000013` ｜ 食材极致 `10000014`

---

## 三、检索参数（本轮最重要的发现）

### 3.1 默认阈值 0.7 让口语问法基本召不回来

`SearchFAQEntries` 里 `if req.VectorThreshold <= 0: VectorThreshold = 0.7` —— **0.7 是硬编码默认值**，且 FAQ 检索恒为 `DisableKeywordsMatch: true`（**纯向量，关键词完全不参与**）。

阈值扫描（33 个探针 × 7 档阈值，脚本 `6_threshold.py`）：

| 探针组 | 条数 | 0.7（默认） | **0.5** | 0.45 | 0.4 |
|:--|:--:|:--:|:--:|:--:|:--:|
| A 标准问原句 | 11 | 11 命中（各 1 条） | **11/11，top1 全对** | 同 | 同 |
| B 相似问原句 | 11 | 8 命中 / 3 条 0 | **11/11，top1 全对** | 同 | 同 |
| **C 未登录新口语问法** | 11 | **仅 1/11** | **11/11，top1 全对** | 11/11（召回满 5 条） | 同 |

> C 组才是 S7 的实际使用方式（说人话去要素材）。**0.7 下 10 条召不回来；0.5 下 11 条全中且 top1 就是期望的那张卡。**

### 3.2 推荐参数

| 场景 | 参数 |
|:--|:--|
| 常规检索 | `vector_threshold = 0.5`，`match_count = 3~5` |
| 要更多候选 | `vector_threshold = 0.45`（召回更满，top1 不变） |
| 圈定标签范围 | 加 `first_priority_tag_ids: [seq_id]`（0.5 阈值下工作正常，见 §3.3） |

### 3.3 标签优先检索实测（阈值 0.5）

| 标签（seq_id） | 限定后命中 | 库内该标签条目数 |
|:--|:--:|:--:|
| 反差(10000009) | 4 | 4 ✅ |
| 反常识(10000010) | 2 | 2 ✅ |
| 难度极限(10000012) | 2 | 2 ✅ |
| 自嘲反差(10000011) | 1 | 1 ✅ |
| 预见式服务(10000013) | 1 | 1 ✅ |
| 食材极致(10000014) | 1 | 1 ✅ |

> 0.7 阈值下这 6 项**全部返回 0** —— 说明标签优先的失败也不是标签机制的问题，同样是阈值。

---

## 四、调用方式

**只能用 HTTP API** —— MCP 通道暴露 40+ 工具但没有 FAQ / Tag 工具（`hybrid_search` 也不带 `tag_ids`）。

```python
import requests
BASE = "http://127.0.0.1:31607/api/v1"
H = {"X-API-Key": "<key>", "Content-Type": "application/json"}
KB = "e6772e41-7b72-499d-b46c-e5ca7c9d1740"

r = requests.post(f"{BASE}/knowledge-bases/{KB}/faq/search", headers=H, timeout=60, json={
    "query_text": "找一条反差感强的事件，人物前面很狂、后面被打脸",
    "match_count": 5,
    "vector_threshold": 0.5,          # ← 必须显式传，默认 0.7 召不回
    # "first_priority_tag_ids": [10000009],   # 可选：圈定「反差」范围
})
for e in r.json()["data"]:
    print(round(e["score"], 4), e["tag_name"], e["answers"][0][:60])
```

**调用注意（踩坑记录）**：
1. `dry_run` 是**异步任务且占用导入通道** —— 紧接正式导入会 `400 已有导入任务进行中`。
2. 沙箱内 `curl localhost` 必须 `--noproxy '*'`，否则代理返回 502。
3. 导入是异步任务，要轮询 `/faq/import/progress/{task_id}` 等 `completed`。

---

## 五、字段映射（卡片 → FAQ 条目）

| 卡片字段 / 结构 | FAQ 条目字段 | 说明 |
|:--|:--|:--|
| 主检索意图（本轮设计） | `standard_question` | 一句话「我要什么素材」 |
| 其他问法（4 条/卡） | `similar_questions` | **唯一召回杠杆**（关键词不参与检索） |
| 不该命中的边界（2 条/卡） | `negative_questions` | 不入索引，用于界定 |
| **整张卡正文** | `answers[0]` | 不切分，576–978 字完整保留（原子性） |
| 主标签（12 维之一） | `tag_name` | 条目唯一标签，用于圈定范围 |

---

## 六、已知限制（如实说明）

| # | 限制 | 影响 |
|:--:|:--|:--|
| 1 | **条目单标签** | 次标签（如 T1 的 `视觉冲击`）只存在于答案正文，`tag_name` 只能是主标签 → 按次标签圈定做不到 |
| 2 | **关键词完全不参与检索** | 相似问里塞的「反常识 实物证言 手机壳晒化」这类关键词串**无效**；召回全靠向量语义 |
| 3 | `CustomMetadata` 不参与过滤 | 「铺垫量级=短 且 极致类型=反转」这类多字段硬过滤做不到 |
| 4 | **T3「石榴籽」未入库** | 按 4.4 条款属情绪效果、不设标签，故无卡无条目（正确行为，非遗漏） |
| 5 | 阈值 0.5 是**11 条样本的经验值** | 扩样本后需复扫（脚本可复用） |
| 6 | `MCN极致事件素材库` 与 `mcnvideoprompt` **互相独立** | 未混库；本轮未碰 `mcnvideoprompt` |

---

## 七、待定（需你决策）

| # | 事项 | 说明 |
|:--:|:--|:--|
| 1 | **技能是否接入** | 是否在 `7_生成短视频大纲.md` 的极致触点布位处加「素材检索入口（WeKnora FAQ 库，阈值 0.5）」——动了就是技能文件变更，需你确认 |
| 2 | 扩样本 | 33 条热门清单里还剩约 28 条未提炼；扩量后建议复扫阈值 |
| 3 | 次标签承载 | 若要按次标签圈定，需改为「按标签拆条目」或「标签名写入相似问（但关键词不参与，效果有限）」 |