# 项目说明文档

## 目录

1.  [util\_old.py](#util_oldpy)
2.  [utils.py](#utilspy)
3.  [search\_ui.py](#search_uipy)
4.  [main.py](#mainpy)
5.  [search\_plus.py](#search_pluspy)
6.  [search\_queries.py](#search_queriespy)
7.  [search\_ui\_v2.py](#search_ui_v2py)

---

## 1. `util_old.py` <a name="util_oldpy"></a>

该文件包含一些用于网络爬取、文件处理和数据保存的实用函数。

### 主要功能

1.  **`fetch_documents(ip_address, dataset_id, api_key)`**:
    -   从指定的 API 端点获取文档数据。
    -   使用 `requests` 库发送 HTTP GET 请求。
    -   处理 HTTP 错误和其它异常。
    -   返回 JSON 格式的响应数据。
2.  **`is_file(url)`**:
    -   检查给定的 URL 是否指向一个文件（基于文件扩展名）。
    -   使用预定义的文件扩展名集合 `file_extensions` 进行判断。
3.  **`is_webpage(url)`**:
    -   检查给定的 URL 是否指向一个网页。
    -   通过检查 `Content-Type` 头是否包含 `text/html` 来判断。
4.  **`can_crawl_webpage(url)`**:
    -   判断一个网页是否适合爬取。
    -   使用 `BeautifulSoup` 解析网页内容。
    -   检查否存在大量 JavaScript 代码、页面内容是否主要是乱码或图片、以及是否存在 `meta robots` 标签阻止爬取。
    -   使用 `langdetect` 库检测页面语言是否为中文。
5.  **`is_cosmetic_related(snippet)`**:
    -   检查给定的文本片段是否与化妆品相关。
    -   使用预定义的关键词列表进行判断。
6.  **`parse_search(result)`**:
    -   解析搜索结果，判断链接类型（文件、网页或未知类型）。
    -   根据链接类型返回相应的描述字符串。
7.  **`save_webpage_content(url, engine, search_id, output_dir, pool)`**:
    -   保存网页内容到本地文件，并将相关信息记录到数据库。
    -   使用 `BeautifulSoup` 提取网页文本内容。
    -   检查网页是否已保存，避免重复保存。
8.  **`download_file(url, engine, search_id, output_dir, pool)`**:
    -   下载文件到本地，并将相关信息记录到数据库。
    -   检查文件是否已下载，避免重复下载。
9.  **`save_non_crawlable(url, engine, search_id, pool)`**:
    -   将无法爬取的链接保存到数据库的黑名单中。
    -   避免重复保存。
10. **`get_blacklist(pool)`**:
    -   从数据库中获取黑名单列表。
11. **`libreoffice_to_pdf(file_path, output_dir)`**:
    -   使用 LibreOffice 将文件转换为 PDF 格式。
    -   处理文件不存在和转换失败的情况。
12. **`pdf_to_images(pdf_path, output_dir)`**:
    -   将 PDF 文件逐页转换为图像。
    -   使用 `pdf2image` 库进行转换。
    -   强制清理每页处理后的内存。
13. **`process_files(base_dir)`**:
    -   遍历指定目录下的所有文件，处理 PPT/PPTX、XLS/XLSX、DOC/DOCX 和 PDF 文件。
    -   将这些文件转换为 PDF 格式，并将 PDF 文件转换为图像。

### 依赖库

-   `bs4` (BeautifulSoup4)
-   `os`
-   `gc`
-   `requests`
-   `langdetect`
-   `langchain_core`
-   `langchain.text_splitter`
-   `pdf2image`
-   `typing`

---

## 2. `utils.py` <a name="utilspy"></a>

该文件包含一些用于判断 URL 类型和内容是否相关的实用函数。

### 主要功能

1.  **`is_file(url)`**:
    -   检查给定的 URL 是否指向一个文件（基于文件扩展名）。
    -   使用预定义的文件扩展名集合 `file_extensions` 进行判断。
2.  **`is_webpage(url)`**:
    -   检查给定的 URL 是否指向一个网页。
    -   通过检查 `Content-Type` 头是否包含 `text/html` 来判断。
3.  **`can_crawl_webpage(url)`**:
    -   判断一个网页是否适合爬取。
    -   使用 `BeautifulSoup` 解析网页内容。
    -   检查是否存在 `meta robots` 标签阻止爬取。
4.  **`is_cosmetic_related(snippet)`**:
    -   检查给定的文本片段是否与化妆品相关。
    -   使用预定义的关键词列表进行判断。
5.  **`parse_search(result)`**:
    -   解析搜索结果，判断链接类型（文件、网页或未知类型）。
    -   根据链接类型返回相应的描述字符串。

### 依赖库

-   `bs4` (BeautifulSoup4)
-   `requests`

---

## 3. `search_ui.py` <a name="search_uipy"></a>

该文件使用 Gradio 库创建一个 Web UI，用于执行多搜索引擎聚合搜索。

### 主要功能

1.  **`SearchUI` 类**:
    -   `__init__`: 初始化 API 密钥。
    -   `parse_google_results(results)`: 解析 Google 搜索结果，提取标题、链接、摘要和位置信息。
    -   `parse_bing_results(results)`: 解析 Bing 搜索结果，提取标题、链接、摘要和位置信息。
    -   `parse_baidu_results(results)`: 解析百度搜索结果，提取标题、链接、摘要和位置信息，并处理百度特有的 `answer_box`。
    -   `format_results(results)`: 将解析后的搜索结果格式化为 Markdown 文本。
    -   `search_all_engines(query)`: 在 Google、Bing 和 Baidu 三个搜索引擎中执行搜索，并返回格式化后的结果。
2.  **`create_ui()` 函数**:
    -   创建 `SearchUI` 实例。
    -   定义自义 CSS 样式，用于美化 UI。
    -   使用 Gradio 创建 Web UI，包括搜索输入框、搜索按钮、加载动画和搜索结果展示区域。
    -   定义搜索事件处理函数，用于在搜索时显示加载动画，并在搜索完成后更新搜索结果。

### 依赖库

-   `gradio`
-   `json`
-   `typing`
-   `requests`

---

## 4. `main.py` <a name="mainpy"></a>

该文件使用 FastAPI 创建一个 API，用于处理搜索请求和批量搜索请求。

### 主要功能

1.  **数据库连接配置**:
    -   定义数据库连接参数。
2.  **API 端点**:
    -   `/search/`: 接收单个搜索请求，并返回搜索结果。
    -   `/batch_search/`: 接收批量搜索请求，并返回搜索结果。
3.  **数据模型**:
    -   `SearchRequest`: 定义单个搜索请求的数据模型。
    -   `SearchResult`: 定义单个搜索结果的数据模型。
    -   `BatchSearchRequest`: 定义批量搜索请求的数据模型。
    -   `SearchResultItem`: 定义批量搜索结果中单个搜索结果的数据模型。
    -   `BatchSearchResponse`: 定义批量搜索响应的数据模型。
4.  **`fetch_all_content(query)`**:
    -   从数据库中获取与查询相关的已保存网页内容。
5.  **`save_user_query(query, result_count)`**:
    -   将用户查询记录保存到数据。
6.  **`search(request)`**:
    -   接收单个搜索请求，首先尝试从数据库获取结果，如果数据库中没有结果，则调用 `search_plus` 模块进行搜索。
    -   保存用户查询记录。
7.  **`batch_search(request)`**:
    -   接收批量搜索请求，并使用 SerpAPI 在 Google、Bing 和 Baidu 中执行搜索。
    -   返回包含所有搜索结果的响应。

### 依赖库

-   `fastapi`
-   `pydantic`
-   `aiomysql`
-   `requests`
-   `search_plus`
-   `datetime`
-   `json`

---

## 5. `search_plus.py` <a name="search_pluspy"></a>

该文件包含用于执行搜索并将结果保存到数据库的函数。

### 主要功能

1.  **数据库连接配置**:
    -   定义数据库连接参数。
2.  **`search_and_save(query)`**:
    -   在 Google、Bing 和 Baidu 三个搜索引擎中执行搜索。
    -   将搜索结果以 JSON 字符串的形式保存到数据库的 `web_search_results` 表中。
3.  **`main(queries)`**:
    -   接收一个查询列表，并对每个查询调用 `search_and_save` 函数。

### 依赖库

-   `fastapi`
-   `pydantic`
-   `databases`
-   `requests`
-   `json`
-   `datetime`

---

## 6. `search_queries.py` <a name="search_queriespy"></a>

该文件用于定时执行搜索任务。

### 主要功能

-   **定时执行**:
    -   该脚本配置为通过 Ubuntu 系统的定时任务 (crontab) 在每周日 0 点定时执行。它从数据库中读取预定义的查询列表，并使用 `search_plus.py` 中的 `main` 函数执行搜索，并将结果保存到数据库。  **设置方法见下文 "Crontab 设置说明" 部分。**

### 依赖库

-   `aiomysql`
-   `search_plus`
-   `datetime`

---

## Crontab 设置说明

1. **打开 crontab 编辑器:** 使用命令 `crontab -e` 打开 crontab 编辑器。  如果这是你第一次使用 crontab，系统会询问你使用哪个编辑器 (例如 vim 或 nano)。

2. **添加定时任务:**  在编辑器中添加以下一行，以在每周日 0 点执行 `search_queries.py` 脚本：
   ```bash
   0 0 * * 0 /usr/bin/python3 /path/to/your/search_queries.py  # 请替换 /path/to/your/ 为你的脚本实际路径   ```

   *   `0 0 * * 0`:  表示每天的 0 分 0 秒，每周日执行 (0 代表星期日)。  你可以根据需要修改这个时间表达式。  更多关于 crontab 时间表达式的资料，请参考 `man 5 crontab`。
   *   `/usr/bin/python3`:  指定 Python3 解释器。  如果你的 Python3 解释器不在这个路径，请修改为正确的路径。
   *   `/path/to/your/search_queries.py`:  替换为 `search_queries.py` 脚本的完整路径。

3. **保存并退出:** 保存 crontab 文件并退出编辑器。

4. **查看 crontab 设置:** 使用命令 `crontab -l` 查看当前已设置的 crontab 任务。 你应该能够看到你刚刚添加的那一行。

5. **验证定时任务:**  为了验证定时任务是否正确设置，你可以尝试在 `search_queries.py` 脚本中添加日志记录功能，例如使用 `logging` 模块记录执行时间和相关信息。  然后，你可以等待到下一个星期日 0 点，查看日志文件，确认脚本是否被正确执行。  如果脚本没有执行，请检查脚本路径、Python 解释器路径以及 crontab 时间表达式是否正确。  你也可以使用 `tail -f /path/to/your/logfile` 实时监控日志文件。

---

## 7. `search_ui_v2.py` <a name="search_ui_v2py"></a>

该文件使用 Gradio 库创建一个 Web UI，用于执行多搜索引擎聚合搜索，并提供更高级的功能。

### 主要功能

1.  **`SearchUI` 类**:
    -   `__init__`: 初始化 API 密钥。
    -   `parse_google_results(results)`: 解析 Google 搜索结果，提取标题、链接、摘要和位置信息。
    -   `parse_bing_results(results)`: 解析 Bing 搜索结果，提取标题、链接、摘要和位置信息。
    -   `parse_baidu_results(results)`: 解析百度搜索结果，提取标题、链接、摘要和位置信息，并处理百度特有的 `answer_box`。
    -   `format_results(results)`: 将解析后的搜索结果格式化为 Markdown 文本。
    -   `search_all_engines(query)`: 在 Google、Bing 和 Baidu 三个搜索引擎中执行搜索，并返回格式化后的结果。
    -   `save_search_results(query, results)`: 将搜索结果保存到数据库。
2.  **`create_ui()` 函数**:
    -   创建 `SearchUI` 实例。
    -   定义自义 CSS 样式，用于美化 UI。
    -   使用 Gradio 创建 Web UI，包括搜索输入框、搜索按钮、加载动画、搜索结果展示区域和保存搜索结果的选项。
    -   定义搜索事件处理函数，用于在搜索时显示加载动画，并在搜索完成后更新搜索结果。
    -   定义保存搜索结果的事件处理函数，用于将搜索结果保存到数据库。

### 界面结构

1. **标题:** 显示"九鑫多搜索引擎聚合搜索"。
2. **搜索输入框:** 一个文本框，用于输入搜索关键词。
3. **搜索按钮:** 一个按钮，点击后开始搜索。
4. **加载动画:** 搜索过程中显示一个GIF动画，提示用户正在等待结果。搜索完成后自动隐藏。
5. **搜索结果展示区域:** 分为三个部分，分别显示Google、Bing和百度搜索结果。每个部分都以HTML卡片的形式展示搜索结果，包含标题、链接和摘要。点击卡片中的链接会在新标签页打开搜索结果页面。每个搜索引擎的结果区域都有各自的边框颜色，方便区分。

### 操作方法

1. **输入关键词:** 在搜索输入框中输入你想要搜索的内容。
2. **点击搜索:** 点击"搜索"按钮。此时加载动画会显示。
3. **查看结果:** 搜索完成后，加载动画会消失，Google、Bing和百度的搜索结果会分别显示在各自的区域内。每个搜索结果以卡片形式呈现，点击卡片即可打开对应的链接。

### 功能说明

该UI使用SerpAPI接口在Google、Bing和百度三个搜索引擎上进行搜索。它会解析搜索结果，并以用户友好的方式展示。界面使用了自定义CSS样式，使界面更美观易用。程序还包含错误处理机制，如果搜索过程中出现错误，会显示相应的错误信息。

总而言之，这是一个功能完善、界面友好的多搜索引擎聚合搜索工具。用户只需输入关键词并点击搜索按钮，即可快速获得来自三个不同搜索引擎的搜索结果。

### 依赖库

-   `gradio`
-   `json`
-   `typing`
-   `requests`
-   `aiomysql`