| name | resmax-embedding |
| description | 在 GPU 服务器上为 accepted_index.csv 构建或刷新论文 embedding 缓存,供 resmax-survey 的语义检索使用。 |
resmax-embedding
何时使用
用于构建或刷新 paper_database/embedding_cache/qwen3_8b.npz。上游是 resmax-database,下游是 resmax-survey。
前置条件
paper_database/accepted_index.csv 已由 resmax-database 规范化。
.localconfig/server.env 配置了 RESMAX_SSH_HOST 等远程 GPU 参数。
- 生产前先确认 GPU 空闲,不盲目启动长任务。
最小流程
SKILL_ROOT=.agents/skills/resmax-embedding
source .localconfig/server.env
ssh "$RESMAX_SSH_HOST" nvidia-smi
rsync -avz $SKILL_ROOT/scripts/ "$RESMAX_SSH_HOST:$RESMAX_SSH_REMOTE_DIR/scripts/"
rsync -avz paper_database/accepted_index.csv "$RESMAX_SSH_HOST:$RESMAX_SSH_REMOTE_DIR/accepted_index.csv"
ssh "$RESMAX_SSH_HOST" "source $RESMAX_SSH_CONDA_INIT && conda activate $RESMAX_SSH_CONDA_ENV && \
cd $RESMAX_SSH_REMOTE_DIR && HF_HUB_OFFLINE=1 python3 scripts/build_cache_multigpu.py \
--accepted accepted_index.csv \
--out .embedding_cache/qwen3_8b.npz \
--gpus 0,1,2,3"
rsync -avz "$RESMAX_SSH_HOST:$RESMAX_SSH_REMOTE_DIR/.embedding_cache/qwen3_8b.npz" \
paper_database/embedding_cache/qwen3_8b.npz
python3 .agents/skills/resmax-database/scripts/normalize_database.py \
--csv paper_database/accepted_index.csv \
--manifest paper_database/manifest.json
python3 .agents/skills/resmax-database/scripts/validate_database.py \
--csv paper_database/accepted_index.csv \
--cache paper_database/embedding_cache/qwen3_8b.npz \
--manifest paper_database/manifest.json
执行注意
- 如果
RESMAX_SSH_REMOTE_DIR 以 ~ 开头,远程 ssh 命令中不要把它整体包进引号;cd $RESMAX_SSH_REMOTE_DIR 可由远程 shell 展开,cd "$RESMAX_SSH_REMOTE_DIR" 会创建或访问字面量 ~/... 路径。
- 如果本地
accepted_index.csv 已经通过 validate_database.py,拉回缓存后优先用 normalize_database.py --skip-normalize 刷新 manifest;普通 normalize 会刷新时间戳字段,可能让缓存 meta 中的 accepted_csv_sha256 再次落后。
build_cache_multigpu.py 必须在没有新增 paper_id 时仍能重写 .npz metadata;否则 CSV 内容变化但 paper_id 集合不变时,缓存会保持旧 accepted_csv_sha256。
缓存契约
.npz 必须包含:
embeddings: float32 [N, D]
paper_ids: safe string dtype,不允许 object dtype / pickle-only
meta: JSON 字符串,至少包含 model_name、dimension、count、accepted_csv_sha256
默认目标是覆盖所有 queryable rows:paper_id 非空且摘要不是空值/占位符。旧缓存如果需要 allow_pickle=True 读取,应视为需要重建。
参考资料
- 旧完整手册:
references/legacy_full_manual.md
- 远程配置说明:仓库根目录
SECRETS.md 和 .localconfig/README.md