用途
semantic-search-setup 用于为文档集合建立向量嵌入基础设施，并实现语义搜索。与关键词搜索（FTS5）不同，语义搜索在没有精确词匹配的情况下，也能找到概念上相似的内容。该技能适用于以下场景：为文档集合添加 AI 驱动的搜索、查找概念相关的文档、为 RAG 问答系统准备知识库、构建推荐系统、实现“更多类似内容”（more like this）功能。
主要能力
技能围绕 sentence-transformers 与 numpy 构建嵌入能力，并使用余弦相似度进行检索。提供的代码示例涵盖以下环节：
- 使用 SentenceTransformer 加载模型（如 all-MiniLM-L6-v2），通过 model.encode 生成归一化嵌入，并用 np.dot 计算相似度。
- 提供模型选型参考：all-MiniLM-L6-v2（384 维、速度快、质量好、通用）、all-mpnet-base-v2（768 维、速度中等、质量更好、更高精度）、bge-small-en-v1.5（384 维、速度快、质量好、多语言）、text-embedding-3-small（1536 维、API、质量极好、生产环境 OpenAI）。文档推荐在本地 CPU 场景使用 all-MiniLM-L6-v2。
- 数据库表设计：embeddings 表包含 id、chunk_id、embedding（BLOB）、model_name、dimension、created_at 字段，并建立 chunk_id 索引。
- EmbeddingGenerator 类：强制 CPU 模式，提供 embed_text、embed_batch、save_embedding 方法，嵌入以 float32 存储。
- 批量处理：generate_all_embeddings 只处理尚未生成嵌入的文本块，按批次生成并保存。
- 语义搜索：semantic_search 对查询生成嵌入，从数据库中读取所有嵌入，计算余弦相似度得分，按分数降序返回 top_k 结果，包含 chunk_id、score、text、filename、page。
- 后台服务脚本：embed-service.sh 提供 start、stop、status 命令，通过 PID 文件管理进程，日志写入 /tmp/embed.log。
- 状态监控：get_embedding_status 返回总文本块数、已嵌入数、剩余数和进度百分比。
使用方式
安装依赖：
pip install sentence-transformers numpy
# 或
uv pip install sentence-transformers numpy
示例运行命令：
# 生成嵌入
python embed.py --db knowledge.db --batch 100
# 作为后台服务运行
./embed-service.sh start
# 查看进度
./embed-service.sh status
# 搜索
python search.py "fatigue analysis requirements"
文档还提供了执行清单，依次包括：安装 sentence-transformers 和 numpy；根据用例选择合适的嵌入模型；在数据库中创建 embeddings 表；为所有文本块生成嵌入；用示例查询测试语义搜索；与关键词搜索（FTS5）比较结果；根据可用内存优化批次大小；设置后台服务以持续更新。
适用场景
为文档集合添加 AI 搜索、查找概念相关文档、为 RAG 问答系统准备知识库、构建推荐系统、实现“更多类似内容”功能。相关技能包括 knowledge-base-builder（先构建文档数据库）、rag-system-builder（在语义搜索之上添加 AI 问答）、pdf-text-extractor（从 PDF 提取文本）。
限制与错误处理
文档列出的常见错误及处理方式：CUDA 显存不足时通过设置 CUDA_VISIBLE_DEVICES="" 强制 CPU 模式；模型下载失败时检查网络连接并核对模型名称；numpy.frombuffer 维度不匹配通常因嵌入由不同模型生成，需要用一致的模型重新生成；sqlite3.OperationalError（database is locked）时使用 timeout=30 并分批提交；大批次导致内存问题时将 batch_size 降至 50 或更低。
性能指标（文档给出）：CPU 嵌入速度约 100 块/秒，GPU 约 500 块/秒，每个嵌入存储约 1.5KB（384 维），1 万个嵌入的搜索延迟低于 100ms，模型加载时间 2-5 秒。
文档建议的最佳实践包括：使用归一化嵌入（normalize_embeddings=True）；为稳定性强制 CPU 模式（CUDA_VISIBLE_DEVICES=""）；SQLite 使用 timeout=30；按 100-500 块分批处理；逐批保存以支持断点续跑；记录错误日志。关于收费、价格与商用授权，资料中暂未提供。