# 特征搜索API服务

## 概述

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

## 安装依赖

```bash
pip install -r requirements.txt
```

## 配置环境变量

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

## 启动服务

```bash
python api/main.py
```

或者使用uvicorn直接启动：

```bash
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

执行搜索和评估

**请求体：**

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

**响应：**

```json
{
  "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

健康检查端点

**响应：**

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

## 使用示例

### 使用curl

```bash
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

```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模块配置。