how

人设数据索引构建工具

本目录包含三个索引构建脚本，用于从人设数据和 what 解构结果中构建不同维度的索引，方便快速查询和分析。

---

快速开始

一键构建所有索引

# 构建所有三个索引文件
python build_category_index.py --persona-dir data/阿里多多酱/out/人设_1110
python build_point_to_note_index.py --what-dir data/阿里多多酱/out/人设_1110/what解构结果
python build_note_to_all_index.py --persona-dir data/阿里多多酱/out/人设_1110

---

索引文件说明

1. 分类索引_完整.json

脚本: build_category_index.py

用途: 按分类维度组织帖子（灵感分类、目的分类、关键点分类）

数据来源:

• 灵感分类：来自 人设.json
• 目的分类：来自 what解构结果/
• 关键点分类：来自 what解构结果/

结构:

{
  "灵感分类": {
    "职场疲惫共鸣": {
      "分类层级": "二级分类",
      "分类名称": "职场疲惫共鸣",
      "分类定义": "关于工作压力、倦怠及身份认同的普遍情绪宣泄。",
      "分类路径": [
        {"视角名称": "灵感触发源", "视角描述": "..."},
        {"分类名称": "个人感受与思考", "分类定义": "..."},
        {"分类名称": "职场疲惫共鸣", "分类定义": "..."}
      ],
      "帖子ID列表": ["68d1ebb8...", "68d00894..."],
      "帖子详情列表": [{...}, {...}]
    }
  },
  "目的分类": {...},
  "关键点分类": {...}
}

使用场景:

• 查看某个分类下的所有帖子
• 了解分类的层级结构和定义
• 按分类维度分析内容

统计:

• 灵感分类：15 个
• 目的分类：45 个
• 关键点分类：60 个

---

2. 点到帖子映射.json

脚本: build_point_to_note_index.py

用途: 按具体点组织帖子，提供双向映射（点→帖子，帖子→点）

数据来源: 全部来自 what解构结果/

结构:

{
  "点到帖子映射": {
    "灵感点": {
      "职场投入产出不平衡": {
        "灵感点": "职场投入产出不平衡",
        "维度": "职场观察",
        "描述": "观察到职场中普遍存在的现象...",
        "帖子ID列表": ["68d00894..."],
        "帖子详情列表": [{...}]
      }
    },
    "目的点": {...},
    "关键点": {...}
  },
  "帖子到点映射": {
    "68d00894...": {
      "灵感点列表": [
        {
          "灵感点": "职场投入产出不平衡",
          "来源字段": "共性差异",
          "维度": "职场观察",
          "描述": "..."
        }
      ],
      "目的点列表": [...],
      "关键点列表": [...],
      "帖子详情": {...}
    }
  }
}

使用场景:

• 查看某个具体灵感点/目的点/关键点的所有帖子
• 反查：某个帖子有哪些点
• 分析点与帖子的关联关系

统计:

• 灵感点：46 个（关联 20 个帖子）
• 目的点：45 个（关联 19 个帖子）
• 关键点：60 个（关联 19 个帖子）
• 平均每个帖子：2.3 个灵感点、2.2 个目的点、3.2 个关键点

---

3. 帖子到分类和点映射.json

脚本: build_note_to_all_index.py

用途: 按帖子ID组织，包含每个帖子的完整信息（分类 + 点 + 详情）

数据来源:

• 分类信息：来自 人设.json
• 点信息：来自 what解构结果/
• 帖子详情：通过详情接口获取

结构:

{
  "68d00894...": {
    "帖子ID": "68d00894...",
    "所属分类": [
      {
        "分类类型": "灵感分类",
        "视角名称": "灵感触发源",
        "一级分类": "个人感受与思考",
        "二级分类": "职场疲惫共鸣",
        "分类定义": "..."
      }
    ],
    "灵感点列表": [
      {
        "灵感点": "职场投入产出不平衡",
        "来源字段": "共性差异",
        "维度": "职场观察",
        "描述": "..."
      }
    ],
    "目的点列表": [...],
    "关键点列表": [...],
    "帖子详情": {
      "channel_content_id": "68d00894...",
      "title": "上班要显贵 就不能太基础",
      "body_text": "...",
      "like_count": 768,
      "images": [...],
      "content_type": "normal",
      "publish_time": "2025-09-22 10:01:05"
    }
  }
}

使用场景:

• 通过帖子ID快速获取完整信息
• 查看某个帖子属于哪些分类
• 查看某个帖子有哪些点
• 一站式获取帖子的所有元数据

统计:

• 帖子总数：20
• 有分类信息的帖子：17 个
• 有灵感点信息的帖子：20 个
• 有目的点信息的帖子：19 个
• 有关键点信息的帖子：19 个
• 平均每个帖子：2.0 个分类、2.3 个灵感点、2.2 个目的点、3.2 个关键点

---

使用指南

脚本 1: build_category_index.py

构建按分类维度组织的索引。

基本使用:

python build_category_index.py --persona-dir data/阿里多多酱/out/人设_1110

参数说明:

• --persona-dir: 人设目录路径（必填）
• --output: 输出文件路径（可选，默认: {persona_dir}/分类索引_完整.json）
• --no-details: 不获取帖子详情（可选，只构建索引结构）

示例:

# 基本使用（包含帖子详情）
python build_category_index.py --persona-dir data/阿里多多酱/out/人设_1110

# 只构建索引结构，不获取详情（速度快）
python build_category_index.py --persona-dir data/阿里多多酱/out/人设_1110 --no-details

# 自定义输出文件
python build_category_index.py --persona-dir data/阿里多多酱/out/人设_1110 --output my_index.json

---

脚本 2: build_point_to_note_index.py

构建点到帖子的双向映射索引。

基本使用:

python build_point_to_note_index.py --what-dir data/阿里多多酱/out/人设_1110/what解构结果

参数说明:

• --what-dir: what解构结果目录路径（必填）
• --output: 输出文件路径（可选，默认: {what_dir}/../点到帖子映射.json）
• --no-details: 不获取帖子详情（可选）

示例:

# 基本使用
python build_point_to_note_index.py --what-dir data/阿里多多酱/out/人设_1110/what解构结果

# 只构建索引结构
python build_point_to_note_index.py --what-dir data/阿里多多酱/out/人设_1110/what解构结果 --no-details

# 自定义输出文件
python build_point_to_note_index.py --what-dir data/阿里多多酱/out/人设_1110/what解构结果 --output custom.json

---

脚本 3: build_note_to_all_index.py

构建帖子ID到分类和点的完整映射。

基本使用:

python build_note_to_all_index.py --persona-dir data/阿里多多酱/out/人设_1110

参数说明:

• --persona-dir: 人设目录路径（必填）
• --output: 输出文件路径（可选，默认: {persona_dir}/帖子到分类和点映射.json）
• --no-details: 不获取帖子详情（可选）

示例:

# 基本使用
python build_note_to_all_index.py --persona-dir data/阿里多多酱/out/人设_1110

# 只构建索引结构
python build_note_to_all_index.py --persona-dir data/阿里多多酱/out/人设_1110 --no-details

# 自定义输出文件
python build_note_to_all_index.py --persona-dir data/阿里多多酱/out/人设_1110 --output custom.json

---

查询场景对比

查询需求	使用哪个索引	示例查询
查看某个分类下的所有帖子	分类索引_完整.json	"职场疲惫共鸣"分类有哪些帖子？
查看某个具体点的所有帖子	点到帖子映射.json → 点到帖子映射	"职场投入产出不平衡"这个灵感点有哪些帖子？
查看某个帖子的所有分类	帖子到分类和点映射.json	帖子 68d00894 属于哪些分类？
查看某个帖子的所有点	帖子到分类和点映射.json	帖子 68d00894 有哪些灵感点/目的点/关键点？
反查：帖子有哪些点	点到帖子映射.json → 帖子到点映射	帖子 68d00894 有哪些点？
获取帖子的完整信息	帖子到分类和点映射.json	帖子 68d00894 的详情、分类、点是什么？

---

数据流程图

人设.json
  ↓
build_category_index.py  →  分类索引_完整.json
  (灵感分类)

what解构结果/
  ↓
build_category_index.py  →  分类索引_完整.json
  (目的分类 + 关键点分类)
  ↓
build_point_to_note_index.py  →  点到帖子映射.json
  (灵感点 + 目的点 + 关键点)

人设.json + what解构结果/
  ↓
build_note_to_all_index.py  →  帖子到分类和点映射.json
  (完整映射)

---

核心特性

1. 自动缓存

所有脚本都会利用帖子详情的缓存机制：

• 已获取过的帖子详情会自动使用缓存
• 只有新帖子才会调用详情接口
• 大大提升重复运行的速度

2. 数据去重

• 帖子ID自动去重
• 图片URL自动去重（保持顺序）
• 确保数据一致性

3. Null处理

• 不存在的字段统一使用 null（而非空字符串或 0）
• 保持数据结构的一致性和可靠性

4. 时间格式化

• 自动将时间戳转换为可读格式
• publish_timestamp: 毫秒时间戳
• publish_time: "YYYY-MM-DD HH:MM:SS"

5. 内容类型判断

• 根据 video 字段自动判断
• 有视频: content_type = "video"
• 无视频: content_type = "normal"

---

常见问题

Q1: 三个索引文件有什么区别？

A: 它们从不同维度组织相同的数据：

• 分类索引: 按分类维度（灵感/目的/关键点分类）
• 点到帖子映射: 按具体点（具体的灵感点/目的点/关键点）
• 帖子到分类和点映射: 按帖子ID（一站式获取所有信息）

Q2: 为什么需要三个不同的索引？

A: 不同的查询场景需要不同的数据组织方式：

• 分析分类 → 用分类索引
• 分析具体点 → 用点到帖子映射
• 查看帖子完整信息 → 用帖子到分类和点映射

Q3: 如何更新索引？

A: 重新运行对应的脚本即可：

# 更新所有索引
python build_category_index.py --persona-dir data/阿里多多酱/out/人设_1110
python build_point_to_note_index.py --what-dir data/阿里多多酱/out/人设_1110/what解构结果
python build_note_to_all_index.py --persona-dir data/阿里多多酱/out/人设_1110

Q4: --no-details 什么时候使用？

A: 适用于以下场景：

• 只需要索引结构，不需要帖子详情
• 快速验证索引构建是否正确
• 减少API调用（开发测试时）

Q5: 帖子详情从哪里来？

A: 通过 script.detail.get_xiaohongshu_detail() 接口获取：

• 自动使用缓存（如果已获取过）
• 自动保存到 data/detail/xiaohongshu_detail/{note_id}/
• 包含 raw 和 clean 两种格式

---

技术细节

数据来源

数据类型	来源文件	提取字段
灵感分类	人设.json	灵感点列表 → 模式列表 → 二级细分
目的分类	what解构结果/*.json	三点解构.目的点.main_purpose / secondary_purposes
关键点分类	what解构结果/*.json	三点解构.关键点.key_points
具体灵感点	what解构结果/*.json	三点解构.灵感点.{全新内容,共性差异,共性内容}
具体目的点	what解构结果/*.json	三点解构.目的点.main_purpose / secondary_purposes
具体关键点	what解构结果/*.json	三点解构.关键点.key_points
帖子详情	详情接口	get_xiaohongshu_detail(note_id)

依赖

from script.detail import get_xiaohongshu_detail

确保 script/detail/ 模块可用。

---

输出文件位置

默认输出位置：

data/阿里多多酱/out/人设_1110/
├── 人设.json                    # 输入
├── what解构结果/                 # 输入
├── 分类索引_完整.json            # 输出1
├── 点到帖子映射.json             # 输出2
└── 帖子到分类和点映射.json       # 输出3

---

版本历史

• v1.0 (2025-11-13): 初始版本
  • 支持三种索引构建
  • 自动获取帖子详情
  • 支持缓存机制

---

相关文档

• 搜索模块 README
• 详情模块 README