接口说明文档

本服务为资源搜索与推荐API，所有接口均支持Postman测试。每个接口均包含功能说明、请求方式、参数、返回值、详细Postman测试方法，并补充了核心逻辑和原理说明。

1. 搜索接口

  • 接口功能：根据关键词、分类、标签等条件搜索资源。
  • 核心逻辑与原理：
    • 支持关键词分词、拼音、语义扩展（包括自定义语义映射和Word2Vec相似词扩展）。
    • 支持多字段（标题、内容、分类、标签）模糊匹配。
    • 相关性打分综合考虑精确匹配、分词、拼音、标签、描述、分类等多种因素。
    • 支持多种排序方式（热度、时间、相似度等）。
  • 请求方式：POST
  • URL：/search
  • 请求参数： | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------- | ---- | -------------------------------------- | | keyword | string | 是 | 搜索关键词 | | sort_by | string | 否 | 排序方式（downloads、similarity等） | | category | string | 否 | 分类名 | | search_mode | string | 否 | 搜索模式（title、title_desc、all等） | | tags | array | 否 | 标签数组 |
  • 返回说明：
    • results: 资源列表，每项包含id、title、category、heat、created_at等字段。

Postman测试方法：

  1. 新建POST请求，URL填http://127.0.0.1:5000/search
  2. Body选择raw，类型JSON，内容示例：
    {
  "keyword": "电影",
  "sort_by": "downloads"
}
  3. 点击Send，查看返回结果。

2. 标签推荐接口

  • 接口功能：根据用户兴趣标签推荐相关资源。
  • 核心逻辑与原理：
    • 首先根据用户兴趣标签（user_tags表+tags表）查找相关资源。
    • 若无结果，则用标签名模糊匹配资源标题和内容。
    • 推荐结果按相关性和热度排序。
  • 请求方式：POST
  • URL：/recommend_tags
  • 请求参数： | 参数名 | 类型 | 必填 | 说明 | | -------- | ------- | ---- | -------------- | | user_id | string | 是 | 用户ID | | tags | array | 否 | 用户关注标签 |
  • 返回说明：
    • recommendations: 推荐资源列表。

Postman测试方法：

  1. 新建POST请求，URL填http://127.0.0.1:5000/recommend_tags
  2. Body选择raw，类型JSON，内容示例：
    {
  "user_id": "1",
  "tags": ["动作", "科幻"]
}
  3. 点击Send，查看推荐结果。

3. 用户兴趣标签管理接口

  • 接口功能：管理用户兴趣标签（增删查）。
  • 核心逻辑与原理：
    • 用户标签数据存储在 user_tags 表，通过 tag_id 关联 tags 表，所有操作均以标签名为主。
    • 支持添加、删除、查询用户兴趣标签。
  • 请求方式：POST/GET/DELETE
  • URL：/user_tags 或 /tags
  • 请求参数：
    • POST/DELETE： | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | -------- | | user_id | string | 是 | 用户ID | | tags | array | 是 | 标签数组 |
    • GET： | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | -------- | | user_id | string | 是 | 用户ID |
  • 返回说明：
    • tags: 用户当前兴趣标签列表。

Postman测试方法：

  • 添加标签（POST）：
    1. 新建POST请求，URL填http://127.0.0.1:5000/user_tags
    2. Body选择raw，类型JSON：
      {
  "user_id": "1",
  "tags": ["动作", "科幻"]
}
    3. Send。
  • 查询标签（GET）：
    1. 新建GET请求，URL填http://127.0.0.1:5000/user_tags?user_id=1
    2. Send。
  • 删除标签（DELETE）：
    1. 新建DELETE请求，URL填http://127.0.0.1:5000/user_tags
    2. Body选择raw，类型JSON：
      {
  "user_id": "1",
  "tags": ["动作", "科幻"]
}
    3. Send。

4. 协同过滤推荐接口

  • 接口功能：基于用户行为的个性化推荐。
  • 核心逻辑与原理：
    • 基于 behaviors 表的用户行为（type='favorite' 或 'view'）构建用户-物品矩阵。
    • 计算用户与其他用户的兴趣重叠度（Jaccard相似度=交集/并集），找出最相似的用户。
    • 推荐这些相似用户收藏/浏览过、但当前用户未看过的帖子。
    • 若用户行为数据不足或无相似用户，则推荐全站热门资源。
  • 请求方式：POST
  • URL：/user_based_recommend
  • 请求参数： | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | ------------ | | user_id | string | 是 | 用户ID | | top_n | int | 否 | 推荐数量 |
  • 返回说明：
    • recommendations: 推荐资源列表。

Postman测试方法：

  1. 新建POST请求，URL填http://127.0.0.1:5000/user_based_recommend
  2. Body选择raw，类型JSON：
    {
  "user_id": "1",
  "top_n": 3
}
  3. Send。

5. Word2Vec状态检查接口

  • 接口功能：检查Word2Vec模型加载状态。
  • 核心逻辑与原理：
    • 检查Word2Vec模型是否加载成功，返回词汇量、向量维度、部分词的相似词等信息。
  • 请求方式：GET
  • URL：/word2vec_status
  • 返回说明：
    • enabled, initialized, vocab_size, vector_size, test_results等。

Postman测试方法：

  1. 新建GET请求，URL填http://127.0.0.1:5000/word2vec_status
  2. Send。

6. 调试接口

  • 接口功能：数据库调试与数据检查。
  • 核心逻辑与原理：
    • 通过多种SQL查询，辅助开发者调试数据库内容和搜索命中情况。
  • 请求方式：POST
  • URL：/debug_search
  • 请求参数： | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | -------- | | keyword | string | 是 | 关键词 |
  • 返回说明：
    • 各类调试用的数据库查询结果。

Postman测试方法：

  1. 新建POST请求，URL填http://127.0.0.1:5000/debug_search
  2. Body选择raw，类型JSON：
    {
  "keyword": "电影"
}
  3. Send。

如需补充其它接口或参数说明，随时联系！