knowledge_search/api

特征搜索API服务

概述

这是一个FastAPI服务，复用阶段3-7的完整流程，提供搜索和评估功能。

安装依赖

pip install -r requirements.txt

配置环境变量

export OPENROUTER_API_KEY='your-api-key'
export API_HOST='0.0.0.0'  # 可选，默认0.0.0.0
export API_PORT='8000'     # 可选，默认8000

启动服务

python api/main.py

或者使用uvicorn直接启动：

uvicorn api.search_service:app --host 0.0.0.0 --port 8000

API文档

启动服务后，访问以下地址查看自动生成的API文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

API端点

POST /what/search

执行搜索和评估

请求体：

{
  "original_target": "原始目标名称",
  "persona_features": [
    {
      "persona_feature_name": "人设特征名称1"
    },
    {
      "persona_feature_name": "人设特征名称2"
    },
    {
      "persona_feature_name": "人设特征名称3"
    }
  ],
  "candidate_words": ["候选词1", "候选词2", "候选词3"]
}

响应：

{
  "original_target": "原始目标名称",
  "search_results": [
    {
      "search_word": "搜索词",
      "comprehensive_score": 0.85,
      "comprehensive_score_detail": {
        "N": 20,
        "M": 5,
        "total_contribution": 4.25,
        "P": 0.2125
      },
      "matched_notes": [
        {
          "note_id": "帖子ID",
          "note_title": "帖子标题",
          "evaluation_score": 0.9,
          "max_similarity": 0.95,
          "contribution": 0.855,
          "note_data": {
            // 完整的搜索结果信息
          }
        }
      ]
    }
  ]
}

说明：

• 只返回综合得分P > 0的搜索结果
• matched_notes包含完整的帖子信息（note_data字段）

GET /health

健康检查端点

响应：

{
  "status": "healthy",
  "pipeline_initialized": true
}

使用示例

使用curl

curl -X POST "http://localhost:8000/what/search" \
  -H "Content-Type: application/json" \
  -d '{
    "original_target": "墨镜",
    "persona_features": [
      {"persona_feature_name": "时尚达人"},
      {"persona_feature_name": "潮流穿搭"},
      {"persona_feature_name": "配饰搭配"}
    ],
    "candidate_words": ["太阳镜", "墨镜", "遮阳", "时尚", "潮流"]
  }'

使用Python

import requests

url = "http://localhost:8000/search"
data = {
    "original_target": "墨镜",
    "persona_features": [
        {"persona_feature_name": "时尚达人"},
        {"persona_feature_name": "潮流穿搭"},
        {"persona_feature_name": "配饰搭配"}
    ],
    "candidate_words": ["太阳镜", "墨镜", "遮阳", "时尚", "潮流"]
}

response = requests.post(url, json=data)
result = response.json()
print(result)

注意事项

1. 不修改现有代码：API服务独立实现，不修改src/pipeline/feature_search_pipeline.py中的阶段1-2
2. 本地测试不受影响：现有的main.py和run_full_pipeline方法保持不变
3. 临时文件：服务会在临时目录中创建文件，服务关闭时会自动清理
4. 综合得分P：只返回综合得分P > 0的搜索结果

配置选项

可以通过环境变量配置以下选项：

• OPENROUTER_API_KEY: OpenRouter API密钥（必需）
• API_HOST: API服务主机地址（默认：0.0.0.0）
• API_PORT: API服务端口（默认：8000）
• SEARCH_MAX_WORKERS: 搜索并发数（默认：3）
• EVALUATION_MAX_WORKERS: 评估并发数（默认：10）
• EVALUATION_MAX_NOTES_PER_QUERY: 每个搜索词评估的最大帖子数（默认：20）
• DEEP_ANALYSIS_MAX_WORKERS: 深度解构并发数（默认：5）
• DEEP_ANALYSIS_MIN_SCORE: 深度解构最低分数阈值（默认：0.8）
• SIMILARITY_WEIGHT_EMBEDDING: 相似度分析向量模型权重（默认：0.5）
• SIMILARITY_WEIGHT_SEMANTIC: 相似度分析LLM模型权重（默认：0.5）
• SIMILARITY_MAX_WORKERS: 相似度分析并发数（默认：5）
• MAX_CANDIDATES: 参与组合的最大候选词数（默认：20）
• MAX_COMBO_LENGTH: 最大组合词数（默认：3）
• QUERY_GENERATION_MAX_WORKERS: Query生成并发数（默认：8）

错误处理

API会返回适当的HTTP状态码：

• 200: 成功
• 400: 请求参数错误
• 500: 内部服务器错误
• 503: 服务不可用（Pipeline未初始化）

日志

服务会输出详细的日志信息，包括：

• 请求处理过程
• 各阶段执行状态
• 错误信息

日志级别可以通过Python的logging模块配置。