修复 metadata 结构问题并完善 README 文档

1. 修复了 comparison.py 中 metadata 结构问题，移除了手动添加的 database 字段，让 make_server() 自动处理数据库配置 2. 完善了 README.md 文档，添加了关于工具使用原则、参数说明、高级用法和模型选择的详细说明 3. 添加了首次使用时模型下载失败的解决方案说明
2025-10-23 22:02:52 +08:00
parent 04d1106e53
commit 5919119915
2 changed files with 137 additions and 26 deletions
--- a/README.md
+++ b/README.md
@@ -33,6 +33,118 @@ export HF_HUB_OFFLINE=1
 export HF_ENDPOINT=https://hf-mirror.com
 ```

+## 数据可视化工具
+
+项目包含一个强大的数据可视化工具 [comparison.py](file:///Users/lingyuzeng/project/embedding_atlas/src/visualization/comparison.py)，可以比较两个 CSV 文件中的数据并在 2D 空间中可视化。
+
+### 安装和首次使用注意事项
+
+首次运行时，系统需要下载 embedding 模型权重（如 `all-MiniLM-L6-v2`）。如果下载失败，请设置 Hugging Face 镜像：
+
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+```
+
+### 工具使用原则
+
+在使用该工具时，请遵循以下核心设计原则：
+
+1. 让 `make_server()` 自动处理数据库配置
+2. 使用完整的 `props` 格式提供前端所需的所有信息
+3. 避免手动添加可能与系统自动添加冲突的配置字段
+
+### 命令行使用方式
+
+```bash
+python src/visualization/comparison.py file1.csv file2.csv \
+  --column1 smiles --column2 smiles \
+  --label1 "Dataset A" --label2 "Dataset B" \
+  --interactive --port 5055
+```
+
+参数说明：
+- `file1.csv` 和 `file2.csv`：要比较的两个 CSV 文件
+- `--column1` 和 `--column2`：分别指定两个文件中用于生成 embedding 的列名
+- `--label1` 和 `--label2`：在可视化中显示的数据集标签
+- `--interactive`：启动交互式 Web 查看器
+- `--port`：指定 Web 服务器端口
+- `--model`：指定要使用的 embedding 模型（默认：`all-MiniLM-L6-v2`）
+- `--batch-size`：指定处理数据的批大小（默认：32）
+- `--output` 或 `-o`：指定输出图像文件路径（默认：`comparison_visualization.png`）
+- `--host`：指定 Web 服务器主机地址（默认：`0.0.0.0`）
+
+### Python API 调用方式
+
+工具也支持作为 Python 模块直接调用：
+
+```python
+from src.visualization.comparison import visualize_csv_comparison
+
+# 基本用法
+visualize_csv_comparison(
+    "file1.csv", 
+    "file2.csv",
+    column1="smiles",
+    column2="smiles",
+    launch_interactive=True,
+    port=5055
+)
+
+# 高级用法 - 自定义模型和参数
+visualize_csv_comparison(
+    "file1.csv",
+    "file2.csv",
+    column1="smiles",
+    column2="smiles",
+    model="sentence-transformers/all-mpnet-base-v2",  # 使用不同的模型
+    batch_size=16,  # 调整批处理大小
+    output_path="custom_output.png",  # 自定义输出路径
+    launch_interactive=True,
+    port=8080,  # 自定义端口
+    umap_args={  # 自定义 UMAP 参数
+        "n_neighbors": 20,
+        "min_dist": 0.2,
+        "metric": "cosine"
+    }
+)
+
+# 自定义 embedding 服务
+from src.visualization.comparison import create_embedding_service
+
+create_embedding_service(
+    ["text1", "text2", "text3"],  # 第一组文本数据
+    ["text4", "text5", "text6"],  # 第二组文本数据
+    labels=("Group A", "Group B"),
+    model="sentence-transformers/all-mpnet-base-v2",  # 指定模型
+    batch_size=16,  # 批处理大小
+    port=5055
+)
+```
+
+### 支持的模型
+
+工具支持任何兼容 Sentence Transformers 的模型，包括但不限于：
+
+- `all-MiniLM-L6-v2`（默认）
+- `all-mpnet-base-v2`
+- `all-distilroberta-v1`
+- `paraphrase-multilingual-MiniLM-L12-v2`
+
+### 高级功能
+
+1. **自定义 UMAP 参数**：
+   可以通过 `umap_args` 参数调整降维效果：
+   ```python
+   umap_args = {
+       "n_neighbors": 15,      # 邻居数量
+       "min_dist": 0.1,        # 最小距离
+       "metric": "cosine"      # 距离度量
+   }
+   ```
+
+2. **批处理优化**：
+   对于大型数据集，可以通过调整 `batch_size` 参数来平衡内存使用和处理速度。
+
 ## 会话编排服务（FastAPI / MCP）

 使用 `uv run embedding-backend-api` 可以启动一个同时兼容 FastAPI 与 FastMCP 的后端服务。该服务监听 `/sessions` 路径，负责按需拉起 `embedding-atlas` 容器并在 10 小时后自动清理。
@@ -45,7 +157,7 @@ uv run embedding-backend-mcp

 ### REST API 用法

-```bash
+```
 curl -X POST http://localhost:9000/sessions \
  -H 'Content-Type: application/json' \
  -d '{
@@ -79,7 +191,7 @@ curl http://localhost:9000/sessions

 示例请求：

-```bash
+```
 curl -X POST http://localhost:9000/sessions \
  -H 'Content-Type: application/json' \
  -d '{
@@ -97,7 +209,7 @@ curl -X POST http://localhost:9000/sessions \

 无查询参数，返回当前所有会话的列表：

-```json
+```
 {
  "sessions": [
    {
@@ -121,7 +233,7 @@ curl -X POST http://localhost:9000/sessions \

 根目录的 `fastmcp.json` 示例可直接将本项目注册为 MCP 工具：

-```bash
+```
 uv run embedding-backend-mcp
 ```

@@ -129,14 +241,14 @@ FastMCP 客户端加载该配置后，可用标准 MCP 协议转发同一套 RES

 ## 命令行生成嵌入可视化交互

-```bash
+```
 uv run embedding-atlas data/drugbank_pre_filtered_mordred_qed_id_selfies.csv --text smiles
 uv run embedding-atlas data/drugbank_pre_filtered_mordred_qed_id_selfies.csv --export-application data/my_visualization.zip
 ```

 `embedding-atlas` 更多用法示例：

-```bash
+```
 # 本地文件
 embedding-atlas dataset.parquet
 # Hugging Face 数据集
@@ -153,7 +265,7 @@ embedding-atlas dataset.parquet --x projection_x --y projection_y

 ### Python API使用方法

-```python
+```
 from script.visualize_csv_comparison import visualize_csv_comparison, create_embedding_service

 # 比较两个CSV文件
@@ -190,7 +302,7 @@ create_embedding_service(

 ### 命令行使用方法

-```bash
+```
 # 基本用法
 python script/visualize_csv_comparison.py file1.csv file2.csv

@@ -226,7 +338,7 @@ python script/visualize_csv_comparison.py file1.csv file2.csv \

 ## 划分 MolGen 第一轮微调数据集

-```bash
+```
 uv run python script/split_drugbank.py \
  --in-csv data/drugbank_pre_filtered_mordred_qed_id_selfies.csv \
  --out-dir splits_v2 --seed 20250922 \
@@ -241,13 +353,13 @@ uv run python script/split_drugbank.py \

 合并数据集：

-```bash
+```
 uv run python script/merge_splits.py --input-dir splits_v2/ --output data/drugbank_split_merge.csv
 ```

 可视化：

-```bash
+```
 uv run embedding-atlas data/drugbank_split_merge.csv --text smiles
 ```