maogeigei
6e4ce9441c
定性：素材载体切换（本地 md -> WeKnora 容器），非扩容；驱动方向由素材驱动改为方法驱动。
- 新建 references/接口调用/WeKnora_极致事件检索.md 调用契约：MCP hybrid_search（服务 weknora）/ kb_id 用库名禁写死 UUID / match_count=3 / vector_threshold=0.5 显式 / 不传 keyword_threshold / 零命中判据 success=true 且 data=null / 只读 chunk_metadata.answers[0] / 禁用 chat 与 agent_chat / 复筛<=2条每节点 / 取材不取形转译 / 降级矩阵 / 成本控制
- S7 布位表新增「候选创作方法」列（4->5 列）打通方法层（此前 05_极致事件 6 个方法文件在创作流程中 0 调用）
- S7 新增「极致触点素材检索」按需环节 + {material_content} 定死结构 + 极致触点机制自检（[期待A]-被X打破->[结果B]）；输入章节素材库改双层源（主源 WeKnora / 降级 md，md 永不删除）
- 6 个方法文件补「素材供给」块（极致标签 / 定库检索入口 / 问法②打破方式填法）
- SKILL.md MCP 依赖节增 WeKnora 检索层（含静默降级口径）；S7 小节补调用链；frontmatter updated_at
- 索引_知识素材库.md 修正 03/05/06/07/08/11 定性（实为字段结构模板而非素材库）；新增「接口调用」章节
- S9 输入增 {material_cards} + 新增台词毛边三档参考；S11 类1「爆点贯穿」升级为爆点溯源 4 判据，八类35项清单同步
- 根目录补 3 份方案/规范文档 + 2 份 09-23 WeKnora 文档；变更日志归档
147 lines
7.6 KiB
Markdown
147 lines
7.6 KiB
Markdown
# 极致事件素材库 · 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 | 次标签承载 | 若要按次标签圈定，需改为「按标签拆条目」或「标签名写入相似问（但关键词不参与，效果有限）」 |
|