接口说明文档

本服务为资源搜索与推荐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。

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