CLAUDE.md 15 KB
CLAUDE.md
项目概述
这是一个基于LLM的智能搜索系统，用于小红书内容搜索场景。系统通过多阶段处理流程（7个步骤），从原始特征出发，自动生成、评估和执行搜索任务。核心功能包括特征匹配、关联分析、智能搜索词生成、并发搜索执行、LLM评估、深度解构和相似度分析。
概念定义
核心术语
- 选题点：帖子中灵感点列表下的名称、目的点列表下的名称、关键点列表下的名称
- 人设特征/分类：作者多个帖子的聚合结果，在输入文件"匹配人设结果"结构下，命名是"人设特征名称"，相似度得分是指这些选题点和人设各个特征点的匹配度
- 候选词：相似度 ≥ 0.8 的��设特征名称，或符合条件的帖子点名称
- Base Word：中心词，用于组织和生成搜索词的基础词汇
- 完全匹配：LLM评估得分 ≥ 0.8 的搜索结果
维度分类
- 灵感点：全新内容、共性差异、共性内容（实质/形式/意图）
- 目的点：用户目的和意图
- 关键点：关键特征和要素
数据流程与结构
流程概览
输入: how.json
↓
步骤1: 特征筛选 → filtered_features.json
↓
步骤2: 候选词提取 → candidate_words.json
↓
步骤3: 搜索词生成(LLM) → search_queries_evaluated.json
↓
步骤4: 执行搜索(小红书API) → search_results.json
↓
步骤5: 结果评估(LLM两层过滤) → evaluated_results.json
↓
步骤6: 深度解构(可选) → deep_analysis_results.json
↓
步骤7: 相似度分析(可选) → similarity_analysis_results.json
↓
可视化: HTML交互式界面
输入数据结构: how.json
位置: input/posts/{post_id}_how.json
核心字段:
{
"帖子id": "690d977d0000000007036331",
"帖子详情": {
"link": "https://www.xiaohongshu.com/explore/...",
"title": "帖子标题",
"body_text": "帖子正文",
"images": ["图片URL1", "图片URL2"],
"like_count": 7428,
"collect_count": 368,
"channel_account_name": "作者名称"
},
"解构结果": {
"灵感点列表": [
{
"ID": "inspiration_1",
"名称": "猫咪考试祝福",
"类型": "实质",
"描述": "详细描述...",
"置信度": 0.95,
"匹配人设结果": [
{
"人设特征名称": "鼓励式猫咪表情包",
"人设特征层级": "灵感点",
"特征类型": "标签", // 或 "分类"
"特征分类": ["表情包素材", "日常生活演绎", "实质"],
"相似度": 0.5339,
"说明": "相似度计算说明..."
}
]
}
],
"目的点列表": [...],
"关键点列表": [...]
}
}
步骤1输出: filtered_features.json
筛选条件: 0.5 ≤ 最高相似度 < 0.8
[
{
"原始特征名称": "猫咪考试祝福",
"来源层级": "灵感点列表",
"权重": 1.0,
"所属点名称": "猫咪考试祝福",
"最高匹配信息": {
"人设特征名称": "鼓励式猫咪表情包",
"人设特征层级": "灵感点",
"特征类型": "标签",
"相似度": 0.5339,
"是分类": false,
"所属分类路径": "表情包素材/日常生活演绎/实质"
},
"top3匹配信息": [...]
}
]
步骤2输出: candidate_words.json
候选词来源:
- 人设候选词: 相似度 ≥ 0.8 的人设特征
- 帖子候选词: 点名称（该点最高相似度 ≥ 0.8）
[
{
"原始特征名称": "猫咪考试祝福",
"来源层级": "灵感点列表",
"高相似度候选_按base_word": {
"鼓励式猫咪表情包": [
{
"候选词": "鼓励式猫咪表情包",
"候选词类型": "persona", // 或 "post"
"相似度": 0.85,
"特征类型": "标签",
"人设特征层级": "灵感点",
"来源层级": "persona",
"来源路径": "表情包素材/日常生活演绎/实质",
"来源原始特征": "猫咪考试祝福"
}
]
}
}
]
步骤3输出: search_queries_evaluated.json
生成方式: LLM基于中心词(base_word)和候选词生成搜索词
[
{
"原始特征名称": "猫咪考试祝福",
"组合评估结果_分组": [
{
"base_word": "鼓励式猫咪表情包",
"base_word_similarity": 0.5339,
"base_word_info": {...},
"top10_searches": [
{
"search_word": "鼓励式猫咪表情包 考试祝福",
"score": 0.92,
"reasoning": "组合词很好地结合了中心词和候选词...",
"source_word": "鼓励式猫咪表情包",
"original_feature": "猫咪考试祝福"
}
],
"available_words": ["鼓励式猫咪表情包", "考试祝福", ...]
}
]
}
]
步骤4输出: search_results.json
数据来源: 小红书搜索API
[
{
"原始特征名称": "猫咪考试祝福",
"组合评估结果_分组": [
{
"base_word": "鼓励式猫咪表情包",
"top10_searches": [
{
"search_word": "鼓励式猫咪表情包 考试祝福",
"search_result": {
"data": {
"data": [
{
"id": "note_id_123",
"note_card": {
"display_title": "考试祝福表情包",
"type": "normal", // 或 "video"
"image_list": ["http://..."],
"user": {
"nickname": "用户昵称",
"user_id": "..."
},
"interact_info": {
"liked_count": "1234",
"collected_count": "56"
}
}
}
]
}
},
"search_metadata": {
"searched_at": "2025-01-01T12:00:00",
"status": "success",
"note_count": 20
}
}
]
}
]
}
]
步骤5输出: evaluated_results.json
评估机制: LLM两层过滤
- 第一层: 过滤与Query无关的结果
- 第二层: 评估与目标特征的匹配度
[
{
"原始特征名称": "猫咪考试祝福",
"组合评估结果_分组": [
{
"base_word": "鼓励式猫咪表情包",
"top10_searches": [
{
"search_word": "鼓励式猫咪表情包 考试祝福",
"search_result": {...},
"evaluation_with_filter": {
"total_notes": 20,
"filtered_count": 5, // 第一层过滤: 与Query无关
"evaluated_count": 15, // 第二层评估数量
"statistics": {
"完全匹配(0.8-1.0)": 8,
"相似匹配(0.6-0.79)": 4,
"弱相似(0.5-0.59)": 2,
"无匹配(≤0.4)": 1
},
"notes_evaluation": [
{
"note_index": 0,
"note_id": "note_id_123",
"Query相关性": "相关", // 或 "不相关"
"Query相关性说明": "...",
"综合得分": 0.85,
"评分说明": "...",
"关键匹配点": ["考试祝福", "猫咪表情包"]
}
]
}
}
]
}
]
}
]
步骤6输出: deep_analysis_results.json (可选)
触发条件: 评估得分 ≥ min_score (默认0.8) 且评估类型为"完全匹配"
{
"metadata": {
"stage": "deconstruction",
"post_id": "690d977d0000000007036331",
"total_matched_notes": 50,
"processed_notes": 45,
"success_count": 40,
"min_score_threshold": 0.8,
"created_at": "2025-01-01T12:00:00"
},
"results": [
{
"note_id": "note_id_123",
"search_word": "鼓励式猫咪表情包 考试祝福",
"original_feature": "猫咪考试祝福",
"evaluation_score": 0.85,
"evaluation_type": "完全匹配",
"key_matching_points": ["考试祝福", "猫咪表情包"],
"inspiration_features": [
{
"feature_name": "考试祝福主题",
"dimension": "灵感点-全新内容",
"dimension_detail": "实质",
"weight": 0.8,
"source_index": 0,
"source_candidate_number": 1
}
],
"purpose_features": [...],
"key_point_features": [...],
"api_response": {
"result": {
"data": {
"三点解构": {
"灵感点": {
"全新内容": [...],
"共性差异": [...],
"共性内容": [...]
},
"目的点": {...},
"关键点": {...}
}
}
}
}
}
]
}
步骤7输出: similarity_analysis_results.json (可选)
计算公式:
- 混合相似度 = weight_embedding × embedding_score + weight_semantic × semantic_score
- 综合得分P = Σ(评估分 × 最高相似度) / 总帖子数
{
"metadata": {
"stage": "similarity_analysis",
"weight_embedding": 0.5,
"weight_semantic": 0.5,
"min_similarity": 0.0,
"created_at": "2025-01-01T12:00:00"
},
"results": [
{
"note_id": "note_id_123",
"original_feature": "猫咪考试祝福",
"features_similarity": [
{
"feature_name": "考试祝福主题",
"dimension": "灵感点-全新内容",
"dimension_detail": "实质",
"weight": 0.8,
"similarity_score": 0.75,
"similarity_breakdown": {
"embedding_score": 0.80, // 向量模型
"semantic_score": 0.70, // LLM模型
"weighted_score": 0.75 // 加权平均
},
"original_feature": "猫咪考试祝福"
}
],
"statistics": {
"total_features": 5,
"avg_similarity": 0.72,
"max_similarity": 0.85,
"min_similarity": 0.60
}
}
],
"综合得分P": 0.78 // 可选，需要启用 calculate_comprehensive_score
}
项目架构
目录结构
optimization/
├── lib/ # 核心功能库
│ ├── client.py # API客户端
│ ├── data_loader.py # 数据加载
│ ├── match_analyzer.py # 匹配分析
│ ├── relation_analyzer.py # 关联分析
│ ├── semantic_similarity.py # 语义相似度
│ ├── hybrid_similarity.py # 混合相似度(向量+LLM)
│ └── utils.py # 工具函数
├── src/ # 主要源代码
│ ├── pipeline/ # 流程控制
│ ├── analyzers/ # 分析器(解构/相似度)
│ ├── evaluators/ # 评估器(LLM)
│ ├── clients/ # API客户端
│ └── visualizers/ # 可视化生成器
├── input/posts/ # 输入数据 (*_how.json)
├── output_v2/ # 输出结果
├── visualization/ # 可视化HTML文件
├── cache/search/ # 搜索缓存
└── logs/ # 日志文件
核心模块职责
数据处理流程:
EnhancedSearchV2(src/pipeline/feature_search_pipeline.py) - 主流程控制器LLMEvaluator(src/evaluators/llm_evaluator.py) - 搜索词生成和结果评估PostDeconstructionAnalyzer(src/analyzers/) - 深度解构分析SimilarityAnalyzer(src/analyzers/) - 相似度分析XiaohongshuSearch(src/clients/) - 小红书搜索API客户端OpenRouterClient(src/clients/) - LLM API客户端
可视化模块:
deconstruction_visualizer.py- 整合可视化（搜索+评估+解构+相似度）
运行模式
基础模式 (步骤1-4)
python3 main.py --mode basic
标准模式 (步骤1-5，默认)
python3 main.py --mode standard
完整模式 (步骤1-7)
python3 main.py --mode full
自定义控制
python3 main.py \
--enable-evaluation \
--enable-deep-analysis \
--deep-analysis-min-score 0.9 \
--enable-similarity \
--similarity-weight-embedding 0.6
关键配置参数
搜索相关
top_n: 每个特征取评分最高的N个搜索词 (默认10)max_total_searches: 全局最大搜索次数max_searches_per_feature: 每个特征的最大搜索次数search_max_workers: 搜索并发数 (默认3)
评估相关
enable_evaluation: 是否启用结果评估evaluation_max_workers: 评估并发数 (默认10)evaluation_max_notes_per_query: 每个搜索最多评估的帖子数 (默认20)
解构相关
enable_deep_analysis: 是否启用深度解构deep_analysis_min_score: 最低分数阈值 (默认0.8)deep_analysis_max_workers: 解构并发数 (默认5)deep_analysis_api_url: 解构API地址
相似度相关
enable_similarity: 是否启用相似度分析similarity_weight_embedding: 向量模型权重 (默认0.5)similarity_weight_semantic: LLM模型权重 (默认0.5)similarity_min_similarity: 最小相似度阈值 (默认0.0)calculate_comprehensive_score: 是否计算综合得分P
严格约束
代码修改规范
- Prompt保护: 重构或修改功能代码过程中不要修改任何的原始prompt，如需修改，必须确认授权
- 可视化更新: 如果涉及可视化的修改，修改完后直接open打开验证效果
- 数据结构保持: 修改代码时必须保持各环节的数据结构兼容性，避免破坏数据流转
- 并发控制: 注意并发数限制，避免API限流
调试指南
- 应用日志:
logs/app.log - 中间结果:
output_v2/*.json(各步骤的输出文件) - 缓存位置:
cache/search/*.json(搜索结果缓存) - 可视化输出:
visualization/*.html
常见问题
- API超时: 检查网络和API配置，调整重试策略
- 相似度计算异常: 检查embedding模型可用性
- LLM评估失败: 检查OpenRouter API密钥和模型可用性
- 搜索结果为空: 检查搜索词是否合理，API是否正常
- 解构失败: 检查解构API地址和帖子ID有效性
数据访问模式
可视化数据访问路径
搜索结果可视化:
- 统计数据: 遍历所有
组合评估结果_分组→top10_searches→evaluation_with_filter - 左侧导航:
data[featureIdx]['组合评估结果_分组'][groupIdx]['top10_searches'] - 右侧结果:
search_result.data.data[noteIdx] - 评估详情:
noteEvaluations["featureIdx-groupIdx-swIdx-noteIdx"]
解构结果可视化:
- 评估数据:
evaluated_data[featureIdx]['组合评估结果_分组'][groupIdx]['top10_searches'][swIdx] - 解构数据:
deconstruction_mapping[note_id](通过note_id关联) - 相似度数据:
similarity_mapping[note_id](通过note_id关联) - 特征信息:
all_features[feature_name](从how.json提取)
数据关联关系
- 主键标识符:
note_id(帖子唯一ID) - 评估结果 → 解构结果: 通过
note_id匹配 - 评估结果 → 相似度结果: 通过
note_id匹配 - How文件 → 评估结果: 通过
原始特征名称匹配