item3 - 10 知识库检索

// 提供混合检索接口
@RestController
@RequestMapping("/api/v1/search")
public class SearchController {
  @Autowired
  private HybridSearchService hybridSearchService;

  /**
   * 混合检索接口
   * 
   * URL: /api/v1/search/hybrid
   * Method: GET
   * Parameters:
   *   - query: 搜索查询字符串（必需）
   *   - topK: 返回结果数量（可选，默认10）
   * 
   * 示例: /api/v1/search/hybrid?query=人工智能的发展&topK=10
   * 
   * Response:
   * [
   *   {
   *     "fileMd5": "abc123...",
   *     "chunkId": 1,
   *     "textContent": "人工智能是未来科技发展的核心方向。",
   *     "score": 0.92,
   *     "userId": "user123",
   *     "orgTag": "TECH_DEPT",
   *     "isPublic": true
   *   }
   * ]
   */
  @GetMapping("/hybrid")
  public Map<String, Object> hybridSearch(@RequestParam String query,
    @RequestParam(defaultValue = "10") int topK,
    @RequestAttribute(value = "userId", required = false) String userId) {
    LogUtils.PerformanceMonitor monitor = LogUtils.startPerformanceMonitor("HYBRID_SEARCH");
    try {
      LogUtils.logBusiness("HYBRID_SEARCH", userId != null ? userId : "anonymous", "开始混合检索: query=%s, topK=%d", query, topK);
      
      List<SearchResult> results;
      if (userId != null) {
          // 如果有用户ID，使用带权限的搜索
          results = hybridSearchService.searchWithPermission(query, userId, topK);
      } else {
          // 如果没有用户ID，使用普通搜索（仅公开内容）
          results = hybridSearchService.search(query, topK);
      }
      
      LogUtils.logUserOperation(userId != null ? userId : "anonymous", "HYBRID_SEARCH", "search_query", "SUCCESS");
      LogUtils.logBusiness("HYBRID_SEARCH", userId != null ? userId : "anonymous", "混合检索完成: 返回结果数量=%d", results.size());
      monitor.end("混合检索成功");
      
      // 构造统一响应结构
      Map<String, Object> responseBody = new HashMap<>(4);
      responseBody.put("code", 200);
      responseBody.put("message", "success");
      responseBody.put("data", results);
      
      return responseBody;
    } catch (Exception e) {
      LogUtils.logBusinessError("HYBRID_SEARCH", userId != null ? userId : "anonymous", 
              "混合检索失败: query=%s", e, query);
      monitor.end("混合检索失败: " + e.getMessage());
      
      // 构造错误响应结构，保持与前端解析一致
      Map<String, Object> errorBody = new HashMap<>(4);
      errorBody.put("code", 500);
      errorBody.put("message", e.getMessage());
      errorBody.put("data", Collections.emptyList());
      return errorBody;
    }
  }
}

/**
 * 使用文本匹配和向量相似度进行混合搜索，支持权限过滤
 * 该方法确保用户只能搜索其有权限访问的文档（自己的文档、公开文档、所属组织的文档）
 *
 * @param query  查询字符串
 * @param userId 用户ID
 * @param topK   返回结果数量
 * @return 搜索结果列表
 */
public List<SearchResult> searchWithPermission(String query, String userId, int topK) { ... }

// 获取用户有效的组织标签（包含层级关系）
List<String> userEffectiveTags = getUserEffectiveOrgTags(userId);
logger.debug("用户 {} 的有效组织标签: {}", userId, userEffectiveTags);

// 获取用户的数据库ID用于权限过滤
String userDbId = getUserDbId(userId);
logger.debug("用户 {} 的数据库ID: {}", userId, userDbId);

/**
 * 获取用户的有效组织标签（包含层级关系）
 */
private List<String> getUserEffectiveOrgTags(String userId) {
  logger.debug("获取用户有效组织标签，用户ID: {}", userId);
  try {
      // 获取用户名
      User user;
      try {
          Long userIdLong = Long.parseLong(userId);
          logger.debug("解析用户ID为Long: {}", userIdLong);
          user = userRepository.findById(userIdLong)
              .orElseThrow(() -> new CustomException("User not found with ID: " + userId, HttpStatus.NOT_FOUND));
          logger.debug("通过ID找到用户: {}", user.getUsername());
      } catch (NumberFormatException e) {
          // 如果userId不是数字格式，则假设它就是username
          logger.debug("用户ID不是数字格式，作为用户名查找: {}", userId);
          user = userRepository.findByUsername(userId)
              .orElseThrow(() -> new CustomException("User not found: " + userId, HttpStatus.NOT_FOUND));
          logger.debug("通过用户名找到用户: {}", user.getUsername());
      }
      
      // 通过orgTagCacheService获取用户的有效标签集合
      List<String> effectiveTags = orgTagCacheService.getUserEffectiveOrgTags(user.getUsername());
      logger.debug("用户 {} 的有效组织标签: {}", user.getUsername(), effectiveTags);
      return effectiveTags;
  } catch (Exception e) {
      logger.error("获取用户有效组织标签失败: {}", e.getMessage(), e);
      return Collections.emptyList(); // 返回空列表作为默认值
  }
}

/**
 * 获取用户的数据库ID用于权限过滤
 */
private String getUserDbId(String userId) {
  logger.debug("获取用户数据库ID，用户ID: {}", userId);
  try {
    // 获取用户名
    User user;
    try {
      Long userIdLong = Long.parseLong(userId);
      logger.debug("解析用户ID为Long: {}", userIdLong);
      user = userRepository.findById(userIdLong)
          .orElseThrow(() -> new CustomException("User not found with ID: " + userId, HttpStatus.NOT_FOUND));
      logger.debug("通过ID找到用户: {}", user.getUsername());
      return userIdLong.toString(); // 如果输入已经是数字ID，直接返回
    } catch (NumberFormatException e) {
      // 如果userId不是数字格式，则假设它就是username
      logger.debug("用户ID不是数字格式，作为用户名查找: {}", userId);
      user = userRepository.findByUsername(userId)
          .orElseThrow(() -> new CustomException("User not found: " + userId, HttpStatus.NOT_FOUND));
      logger.debug("通过用户名找到用户: {}, ID: {}", user.getUsername(), user.getId());
      return user.getId().toString(); // 返回用户的数据库ID
    }
  } catch (Exception e) {
    logger.error("获取用户数据库ID失败: {}", e.getMessage(), e);
    throw new RuntimeException("获取用户数据库ID失败", e);
  }
}

// 生成查询向量
final List<Float> queryVector = embedToVectorList(query);

// 如果向量生成失败，仅使用文本匹配
if (queryVector == null) {
  logger.warn("向量生成失败，仅使用文本匹配进行搜索");
  return textOnlySearchWithPermission(query, userDbId, userEffectiveTags, topK);
}

/**
 * 生成查询向量，返回 List<Float>，失败时返回 null
 */
private List<Float> embedToVectorList(String text) {
  try {
    List<float[]> vecs = embeddingClient.embed(List.of(text));
    if (vecs == null || vecs.isEmpty()) {
        logger.warn("生成的向量为空");
        return null;
    }
    float[] raw = vecs.get(0);
    List<Float> list = new ArrayList<>(raw.length);
    for (float v : raw) {
        list.add(v);
    }
    return list;
  } catch (Exception e) {
    logger.error("生成向量失败", e);
    return null;
  }
}

SearchResponse<EsDocument> response = esClient.search(s -> {
  s.index("knowledge_base");
  // KNN 召回
  int recallK = topK * 30; // KNN 召回窗口
  s.knn(kn -> kn
          .field("vector")
          .queryVector(queryVector)
          .k(recallK)
          .numCandidates(recallK)
  );
  // 必须命中关键词 + 权限过滤
  s.query(q -> q.bool(b -> b
          .must(mst -> mst.match(m -> m.field("textContent").query(query)))
          .filter(f -> f.bool(bf -> bf
                  // 条件1: 用户可访问自己的文档
                  .should(s1 -> s1.term(t -> t.field("userId").value(userDbId)))
                  // 条件2: 公开文档
                  .should(s2 -> s2.term(t -> t.field("public").value(true)))
                  // 条件3: 组织标签
                  .should(s3 -> {
                      if (userEffectiveTags.isEmpty()) {
                          return s3.matchNone(mn -> mn);
                      } else if (userEffectiveTags.size() == 1) {
                          return s3.term(t -> t.field("orgTag").value(userEffectiveTags.get(0)));
                      } else {
                          return s3.bool(inner -> {
                              userEffectiveTags.forEach(tag -> inner.should(sh2 -> sh2.term(t -> t.field("orgTag").value(tag))));
                              return inner;
                          });
                      }
                  })
          ))
  ));

  // 第二阶段 BM25 rescore
  s.rescore(r -> r
          .windowSize(recallK)
          .query(rq -> rq
                  .queryWeight(0.2d)               // 保留部分 KNN 分
                  .rescoreQueryWeight(1.0d)        // BM25 主导
                  .query(rqq -> rqq.match(m -> m
                          .field("textContent")
                          .query(query)
                          .operator(Operator.And)
                  ))
          )
  );
  s.size(topK);
  return s;
}, EsDocument.class);

logger.debug("Elasticsearch查询执行完成，命中数量: {}, 最大分数: {}", 
response.hits().total().value(), response.hits().maxScore());

List<SearchResult> results = response.hits().hits().stream()
  .map(hit -> {
      assert hit.source() != null;
      logger.debug("搜索结果 - 文件: {}, 块: {}, 分数: {}, 内容: {}", 
          hit.source().getFileMd5(), hit.source().getChunkId(), hit.score(), 
          hit.source().getTextContent().substring(0, Math.min(50, hit.source().getTextContent().length())));
      return new SearchResult(
              hit.source().getFileMd5(),
              hit.source().getChunkId(),
              hit.source().getTextContent(),
              hit.score(),
              hit.source().getUserId(),
              hit.source().getOrgTag(),
              hit.source().isPublic()
      );
  })
  .toList();

attachFileNames(results);
return results;

private void attachFileNames(List<SearchResult> results) {
  if (results == null || results.isEmpty()) {
    return;
  }
  try {
    // 收集所有唯一的 fileMd5
    Set<String> md5Set = results.stream()
            .map(SearchResult::getFileMd5)
            .collect(Collectors.toSet());
    List<FileUpload> uploads = fileUploadRepository.findByFileMd5In(new java.util.ArrayList<>(md5Set));
    Map<String, String> md5ToName = uploads.stream()
            .collect(Collectors.toMap(FileUpload::getFileMd5, FileUpload::getFileName));
    // 填充文件名
    results.forEach(r -> r.setFileName(md5ToName.get(r.getFileMd5())));
  } catch (Exception e) {
    logger.error("补充文件名失败", e);
  }
}

/**
 * 使用文本匹配和向量相似度进行混合搜索，支持权限过滤
 * 该方法确保用户只能搜索其有权限访问的文档（自己的文档、公开文档、所属组织的文档）
 *
 * @param query  查询字符串
 * @param userId 用户ID
 * @param topK   返回结果数量
 * @return 搜索结果列表
 */
public List<SearchResult> searchWithPermission(String query, String userId, int topK) {
  logger.debug("开始带权限搜索，查询: {}, 用户ID: {}", query, userId);
  
  try {
    // 获取用户有效的组织标签（包含层级关系）
    List<String> userEffectiveTags = getUserEffectiveOrgTags(userId);
    logger.debug("用户 {} 的有效组织标签: {}", userId, userEffectiveTags);

    // 获取用户的数据库ID用于权限过滤
    String userDbId = getUserDbId(userId);
    logger.debug("用户 {} 的数据库ID: {}", userId, userDbId);

    // 生成查询向量
    final List<Float> queryVector = embedToVectorList(query);

    // 如果向量生成失败，仅使用文本匹配
    if (queryVector == null) {
        logger.warn("向量生成失败，仅使用文本匹配进行搜索");
        return textOnlySearchWithPermission(query, userDbId, userEffectiveTags, topK);
    }

    logger.debug("向量生成成功，开始执行混合搜索 KNN");

    SearchResponse<EsDocument> response = esClient.search(s -> {
      s.index("knowledge_base");
      // KNN 召回
      int recallK = topK * 30; // KNN 召回窗口
      s.knn(kn -> kn
        .field("vector")
        .queryVector(queryVector)
        .k(recallK)
        .numCandidates(recallK)
      );
      // 必须命中关键词 + 权限过滤
      s.query(q -> q.bool(b -> b
        .must(mst -> mst.match(m -> m.field("textContent").query(query)))
        .filter(f -> f.bool(bf -> bf
          // 条件1: 用户可访问自己的文档
          .should(s1 -> s1.term(t -> t.field("userId").value(userDbId)))
          // 条件2: 公开文档
          .should(s2 -> s2.term(t -> t.field("public").value(true)))
          // 条件3: 组织标签
          .should(s3 -> {
              if (userEffectiveTags.isEmpty()) {
                  return s3.matchNone(mn -> mn);
              } else if (userEffectiveTags.size() == 1) {
                  return s3.term(t -> t.field("orgTag").value(userEffectiveTags.get(0)));
              } else {
                  return s3.bool(inner -> {
                      userEffectiveTags.forEach(tag -> inner.should(sh2 -> sh2.term(t -> t.field("orgTag").value(tag))));
                      return inner;
                  });
              }
          })
        ))
      ));

      // 第二阶段 BM25 rescore
      s.rescore(r -> r
              .windowSize(recallK)
              .query(rq -> rq
                      .queryWeight(0.2d)               // 保留部分 KNN 分
                      .rescoreQueryWeight(1.0d)        // BM25 主导
                      .query(rqq -> rqq.match(m -> m
                              .field("textContent")
                              .query(query)
                              .operator(Operator.And)
                      ))
              )
      );
      s.size(topK);
      return s;
    }, EsDocument.class);

    logger.debug("Elasticsearch查询执行完成，命中数量: {}, 最大分数: {}", 
        response.hits().total().value(), response.hits().maxScore());

    List<SearchResult> results = response.hits().hits().stream()
            .map(hit -> {
                assert hit.source() != null;
                logger.debug("搜索结果 - 文件: {}, 块: {}, 分数: {}, 内容: {}", 
                    hit.source().getFileMd5(), hit.source().getChunkId(), hit.score(), 
                    hit.source().getTextContent().substring(0, Math.min(50, hit.source().getTextContent().length())));
                return new SearchResult(
                        hit.source().getFileMd5(),
                        hit.source().getChunkId(),
                        hit.source().getTextContent(),
                        hit.score(),
                        hit.source().getUserId(),
                        hit.source().getOrgTag(),
                        hit.source().isPublic()
                );
            })
            .toList();

    logger.debug("返回搜索结果数量: {}", results.size());
    attachFileNames(results);
    return results;
  } catch (Exception e) {
      logger.error("带权限的搜索失败", e);
      // 发生异常时尝试使用纯文本搜索作为后备方案
      try {
          logger.info("尝试使用纯文本搜索作为后备方案");
          return textOnlySearchWithPermission(query, getUserDbId(userId), getUserEffectiveOrgTags(userId), topK);
      } catch (Exception fallbackError) {
          logger.error("后备搜索也失败", fallbackError);
          return Collections.emptyList();
      }
  }
}